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" }
]
}
| Field | Values | Default for a new application |
|---|---|---|
entity_id | The service provider’s entity ID | urn:idp:app:<slug> |
require_signed_authn_request | boolean | true |
allow_idp_initiated | boolean | false |
default_relay_state | string or null, at most 80 bytes | null |
nameid_source | A built-in attribute or an attribute of the bank | email |
nameid_format | Full URN | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
sign_scope | ASSERTION, RESPONSE, BOTH | ASSERTION |
mfa_context_class | REFEDS_MFA, MICROSOFT_MULTIPLE_AUTHN, PASSWORD_PROTECTED_TRANSPORT | REFEDS_MFA |
encryption.enabled | boolean | false |
encryption.scope | ASSERTION, NAMEID, ATTRIBUTES or null | null |
encryption.key_transport | RSA_OAEP_SHA256, RSA_OAEP_MGF1P or null | null |
encryption.data_algorithm | AES_128_GCM, AES_192_GCM, AES_256_GCM, AES_128_CBC, AES_256_CBC or null | null |
slo.enabled | boolean | false |
slo.sp_url | string or null | null |
slo.sp_binding | HTTP_REDIRECT, HTTP_POST or null | null |
slo.sign_logout_request, slo.sign_logout_response, slo.require_signed_logout_request, slo.require_signed_logout_response | boolean | true |
metadata.source_type | url, file, xml, manual or null | null |
metadata.auto_refresh | boolean | false |
metadata.last_refresh_status | string or null; starts with FAILED: after a failed refresh | null |
acs[].binding | HTTP_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[].source | metadata or manual | |
signing_keys[].status | active, next, retired | one active RSA-2048 / SHA-256 key |
signing_keys[].algorithm | JCA-style algorithm name, for example SHA256withRSA, SHA256withECDSA | |
sp_certificates[].use | SIGNING, ENCRYPTION, SIGNING_ENCRYPTION | none |
sp_certificates[].source | metadata_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
| Field | Type | Required | Notes |
|---|---|---|---|
entity_id | string | yes | Unique in the organization |
require_signed_authn_request | boolean | no | Left out: false |
allow_idp_initiated | boolean | no | Left out: false |
default_relay_state | string | no | At 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
| Field | Type | Required | Notes |
|---|---|---|---|
sign_scope | string | yes | ASSERTION, RESPONSE or BOTH |
Change the two-step sign-in signal
PUT /api/v1/apps/{slug}/saml/mfa-context-class
| Field | Type | Required | Notes |
|---|---|---|---|
mfa_context_class | string | yes | REFEDS_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
| Field | Type | Required | Notes |
|---|---|---|---|
nameid_source | string | yes | id, 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_format | string | yes | Full 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
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | no | Left out: false |
sp_url | string | when enabled | An absolute http or https URL |
sp_binding | string | no | HTTP_REDIRECT or HTTP_POST |
sign_logout_request | boolean | no | Left out: false |
sign_logout_response | boolean | no | Left out: false |
require_signed_logout_request | boolean | no | Left out: false |
require_signed_logout_response | boolean | no | Left 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
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | no | Left out: false |
scope | string | no | ASSERTION, NAMEID or ATTRIBUTES. With enabled: true and no scope, nothing is encrypted. |
key_transport | string | yes | RSA_OAEP_SHA256 or RSA_OAEP_MGF1P, also when turning encryption off |
data_algorithm | string | yes | AES_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
| Field | Type | Required | Notes |
|---|---|---|---|
index | number | no | Default 0. Unique in the application. |
binding | string | yes | HTTP_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. |
location | string | yes | The 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
| Field | Type | Required | Notes |
|---|---|---|---|
url | string | one of url, xml | An https URL. Used when both are sent. |
xml | string | one of url, xml | The metadata document |
auto_refresh | boolean | no | Refresh 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
| Field | Type | Required | Notes |
|---|---|---|---|
source | string | yes | A built-in attribute or an attribute of the bank |
saml_name | string | yes | The 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
| Field | Type | Required | Notes |
|---|---|---|---|
algorithm | string | yes | RSA_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
| Field | Type | Required | Notes |
|---|---|---|---|
use | string | yes | SIGNING, ENCRYPTION or SIGNING_ENCRYPTION |
pem | string | yes | An X.509 certificate in PEM |
note | string | no |
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.