Sovrain
  1. Documentation
  2. Identity provider
  3. For developers
  4. Admin API

Reference

SAML configuration

Admin API endpoints for an application's SAML setup - service provider, signing, encryption, ACS, metadata, mappings, keys and certificates.

Endpoints under https://acme.sovrain.net/api/v1/apps/{slug}/saml, for applications of type SAML. Authentication, conventions and the error format are on Admin API. How Sovrain behaves as a SAML identity provider: SAML.

Scope: apps:read for GET /saml and GET …/certificate, apps:write for every other call. Every write answers 200 with the whole SAML object, deletes included.

An application without a SAML configuration answers 422 refused, for example Application 4 has no SAML configuration; the text differs between endpoints.

The SAML object

{
  "entity_id": "https://wiki.acme.example/saml/metadata",
  "require_signed_authn_request": true,
  "allow_idp_initiated": true,
  "default_relay_state": "/start",
  "nameid_source": "email",
  "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "sign_scope": "ASSERTION",
  "mfa_context_class": "REFEDS_MFA",
  "encryption": {
    "enabled": false,
    "scope": null,
    "key_transport": null,
    "data_algorithm": null
  },
  "slo": {
    "enabled": true,
    "sp_url": "https://wiki.acme.example/saml/slo",
    "sp_binding": "HTTP_REDIRECT",
    "sign_logout_request": true,
    "sign_logout_response": true,
    "require_signed_logout_request": true,
    "require_signed_logout_response": true
  },
  "metadata": {
    "source_type": null,
    "url": null,
    "auto_refresh": false,
    "last_refreshed_at": null,
    "last_refresh_status": null
  },
  "acs": [
    {
      "id": 1,
      "index": 0,
      "binding": "HTTP_POST",
      "location": "https://wiki.acme.example/saml/acs",
      "source": "manual",
      "default": true
    }
  ],
  "signing_keys": [
    {
      "id": 3,
      "status": "active",
      "algorithm": "SHA256withRSA",
      "fingerprint": "de:38:bf:79:…:ed:d6",
      "valid_from": "2026-11-17T09:55:12.371481913Z",
      "valid_to": "2028-11-16T09:55:12.371481913Z"
    }
  ],
  "sp_certificates": [
    {
      "id": 1,
      "use": "SIGNING",
      "fingerprint": "3e:b5:cc:88:…:3f:59",
      "algorithm": "RSA",
      "valid_from": "2026-11-17T09:54:04Z",
      "valid_to": "2027-11-17T09:54:04Z",
      "source": "manual",
      "note": "Wiki SP signing",
      "dropped_from_metadata_at": null
    }
  ],
  "mappings": [
    { "id": 1, "source": "firstName", "saml_name": "givenName" }
  ]
}
FieldValuesDefault for a new application
entity_idThe service provider’s entity IDurn:idp:app:<slug>
require_signed_authn_requestbooleantrue
allow_idp_initiatedbooleanfalse
default_relay_statestring or null, at most 80 bytesnull
nameid_sourceA built-in attribute or an attribute of the bankemail
nameid_formatFull URNurn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
sign_scopeASSERTION, RESPONSE, BOTHASSERTION
mfa_context_classREFEDS_MFA, MICROSOFT_MULTIPLE_AUTHN, PASSWORD_PROTECTED_TRANSPORTREFEDS_MFA
encryption.enabledbooleanfalse
encryption.scopeASSERTION, NAMEID, ATTRIBUTES or nullnull
encryption.key_transportRSA_OAEP_SHA256, RSA_OAEP_MGF1P or nullnull
encryption.data_algorithmAES_128_GCM, AES_192_GCM, AES_256_GCM, AES_128_CBC, AES_256_CBC or nullnull
slo.enabledbooleanfalse
slo.sp_urlstring or nullnull
slo.sp_bindingHTTP_REDIRECT, HTTP_POST or nullnull
slo.sign_logout_request, slo.sign_logout_response, slo.require_signed_logout_request, slo.require_signed_logout_responsebooleantrue
metadata.source_typeurl, file, xml, manual or nullnull
metadata.auto_refreshbooleanfalse
metadata.last_refresh_statusstring or null; starts with FAILED: after a failed refreshnull
acs[].bindingHTTP_POST (HTTP_ARTIFACT rows can exist; SP-initiated sign-in never uses them, but IdP-initiated sign-in uses the default or first endpoint whatever its binding)no ACS
acs[].sourcemetadata or manual
signing_keys[].statusactive, next, retiredone active RSA-2048 / SHA-256 key
signing_keys[].algorithmJCA-style algorithm name, for example SHA256withRSA, SHA256withECDSA
sp_certificates[].useSIGNING, ENCRYPTION, SIGNING_ENCRYPTIONnone
sp_certificates[].sourcemetadata_url, metadata_file, manual

Fingerprints are SHA-256 in lower-case hexadecimal, bytes separated by :.

Get the SAML configuration

GET /api/v1/apps/{slug}/saml

Response 200: the SAML object.

Change the service provider

PUT /api/v1/apps/{slug}/saml/sp

FieldTypeRequiredNotes
entity_idstringyesUnique in the organization
require_signed_authn_requestbooleannoLeft out: false
allow_idp_initiatedbooleannoLeft out: false
default_relay_statestringnoAt most 80 bytes. Left out: none.
{
  "entity_id": "https://wiki.acme.example/saml/metadata",
  "require_signed_authn_request": true,
  "allow_idp_initiated": true,
  "default_relay_state": "/start"
}

Errors: 400 without entity_id; 422 for a relay state over 80 bytes; 500 for an entity ID that another application of the organization already uses.

Change what gets signed

PUT /api/v1/apps/{slug}/saml/sign-scope

FieldTypeRequiredNotes
sign_scopestringyesASSERTION, RESPONSE or BOTH

Change the two-step sign-in signal

PUT /api/v1/apps/{slug}/saml/mfa-context-class

FieldTypeRequiredNotes
mfa_context_classstringyesREFEDS_MFA (https://refeds.org/profile/mfa), MICROSOFT_MULTIPLE_AUTHN (http://schemas.microsoft.com/claims/multipleauthn) or PASSWORD_PROTECTED_TRANSPORT

Change the subject

PUT /api/v1/apps/{slug}/saml/subject

FieldTypeRequiredNotes
nameid_sourcestringyesid, externalId, login, email, firstName, lastName or an attribute of the bank. Not checked when saved: an unknown source makes every sign-in to the application fail.
nameid_formatstringyesFull URN, for example urn:oasis:names:tc:SAML:2.0:nameid-format:persistent. Not checked when saved.
{
  "nameid_source": "login",
  "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
}

Change Single Logout

PUT /api/v1/apps/{slug}/saml/slo

FieldTypeRequiredNotes
enabledbooleannoLeft out: false
sp_urlstringwhen enabledAn absolute http or https URL
sp_bindingstringnoHTTP_REDIRECT or HTTP_POST
sign_logout_requestbooleannoLeft out: false
sign_logout_responsebooleannoLeft out: false
require_signed_logout_requestbooleannoLeft out: false
require_signed_logout_responsebooleannoLeft out: false

The four signing flags are true for a new application. Send them as true to keep them on.

Change encryption

PUT /api/v1/apps/{slug}/saml/encryption

FieldTypeRequiredNotes
enabledbooleannoLeft out: false
scopestringnoASSERTION, NAMEID or ATTRIBUTES. With enabled: true and no scope, nothing is encrypted.
key_transportstringyesRSA_OAEP_SHA256 or RSA_OAEP_MGF1P, also when turning encryption off
data_algorithmstringyesAES_128_GCM, AES_192_GCM, AES_256_GCM, AES_128_CBC or AES_256_CBC, also when turning encryption off

Saving does not check that the application has an encryption certificate; without one, sign-in fails.

{
  "enabled": true,
  "scope": "ASSERTION",
  "key_transport": "RSA_OAEP_SHA256",
  "data_algorithm": "AES_256_GCM"
}

Errors: 400 with Send 'key_transport' or Send 'data_algorithm'.

Add an ACS endpoint

POST /api/v1/apps/{slug}/saml/acs

FieldTypeRequiredNotes
indexnumbernoDefault 0. Unique in the application.
bindingstringyesHTTP_POST. HTTP_ARTIFACT is accepted, never used for SP-initiated sign-in, and used by IdP-initiated sign-in when it is the default or first endpoint.
locationstringyesThe URL. Not checked.

The new endpoint is never the default.

{ "index": 0, "binding": "HTTP_POST", "location": "https://wiki.acme.example/saml/acs" }

Errors: 422 refused with ACS index already in use: 1.

Remove an ACS endpoint

DELETE /api/v1/apps/{slug}/saml/acs/{acsId}

Errors: 422 refused for an unknown id.

Make an ACS endpoint the default

POST /api/v1/apps/{slug}/saml/acs/{acsId}/default

No body.

Import service provider metadata

POST /api/v1/apps/{slug}/saml/metadata

FieldTypeRequiredNotes
urlstringone of url, xmlAn https URL. Used when both are sent.
xmlstringone of url, xmlThe metadata document
auto_refreshbooleannoRefresh from url every day at 04:00 UTC. Default false.

What an import reads: SAML › Service provider metadata. Uploading a file works in the admin pages only.

Errors: 422 refused with Send either 'url' or 'xml' to import metadata, or with the reason the document could not be fetched or read.

Refresh metadata now

POST /api/v1/apps/{slug}/saml/metadata/refresh

No body. Fetches the stored URL again.

Errors: 422 refused when no URL is stored (No metadata URL stored for appId=5) or when the refresh fails. A failure is also saved in metadata.last_refresh_status.

Add an attribute mapping

POST /api/v1/apps/{slug}/saml/mappings

FieldTypeRequiredNotes
sourcestringyesA built-in attribute or an attribute of the bank
saml_namestringyesThe attribute name in the assertion. Unique in the application. Not actor.
{ "source": "firstName", "saml_name": "givenName" }

Errors: 422 refused, for example The SAML attribute name actor is reserved: it names who signs in for the owner of a shared account., an unknown source, or a name already mapped.

Remove an attribute mapping

DELETE /api/v1/apps/{slug}/saml/mappings/{mappingId}

Generate a signing key

POST /api/v1/apps/{slug}/saml/signing-keys

FieldTypeRequiredNotes
algorithmstringyesRSA_2048_SHA256, RSA_2048_SHA512, ECDSA_P256_SHA256, ECDSA_P384_SHA384 or ECDSA_P521_SHA512

Creates a key with status next, published in the IdP metadata but not yet signing. Its self-signed certificate is valid for 730 days. Only one next key can exist at a time.

RSA_2048_SHA1 is accepted by the request reader but always refused: Self-signed certificate generation failed for portal: RSA signing with SHA-1 is not available: generate a SHA-256 signing key.

Promote a signing key

POST /api/v1/apps/{slug}/saml/signing-keys/{keyId}/promote

The next key becomes active; the previous active key becomes retired.

Deactivate a signing key

POST /api/v1/apps/{slug}/saml/signing-keys/{keyId}/deactivate

The active key becomes retired and the next key becomes active.

Errors: 422 refused with Cannot deactivate the only signing key: generate a next key first, then deactivate.

Discard a signing key

POST /api/v1/apps/{slug}/saml/signing-keys/{keyId}/discard

Deletes a next key.

Download a signing certificate

GET /api/v1/apps/{slug}/saml/signing-keys/{keyId}/certificate

Scope: apps:read

Response 200, Content-Type: application/x-pem-file, the certificate in PEM:

-----BEGIN CERTIFICATE-----
MIICpzCCAY+gAwIBAgIJAKttV0tx0Z9dMA0GCSqGSIb3DQEBCwUA…
-----END CERTIFICATE-----

Add a service provider certificate

POST /api/v1/apps/{slug}/saml/sp-certificates

FieldTypeRequiredNotes
usestringyesSIGNING, ENCRYPTION or SIGNING_ENCRYPTION
pemstringyesAn X.509 certificate in PEM
notestringno

Errors: 422 refused with Not a valid PEM X.509 certificate; 500 for a certificate the application already has.

Remove a service provider certificate

DELETE /api/v1/apps/{slug}/saml/sp-certificates/{certId}

Keep a service provider certificate

POST /api/v1/apps/{slug}/saml/sp-certificates/{certId}/keep

Turns a certificate that disappeared from the metadata into a manual one, so it is trusted again and not deleted.