Reference
SAML
Entity IDs, endpoints, bindings, request checks, assertions, signing, encryption, Single Logout and metadata of Sovrain as a SAML 2.0 identity provider.
Sovrain is a SAML 2.0 identity provider. Each SAML application of an organization has its own IdP entity ID, endpoints and signing keys. The NameID and attributes Sovrain sends are on Claims and attributes. The settings of a SAML application are on Application settings.
Entity ID and endpoints
For an application with the slug portal in the organization acme:
| Item | Value |
|---|---|
| IdP entity ID | https://acme.sovrain.net/saml/portal |
| IdP metadata | https://acme.sovrain.net/saml/portal/metadata |
| Single sign-on service | https://acme.sovrain.net/saml/portal/sso (HTTP-Redirect and HTTP-POST) |
| Single Logout service | https://acme.sovrain.net/saml/portal/logout (HTTP-Redirect and HTTP-POST) |
With a primary custom domain, every value uses that domain instead of acme.sovrain.net, for example
https://login.acme.example/saml/portal. Changing the primary domain, or the application’s slug, changes the entity ID
and every endpoint.
| Method | Path | Purpose |
|---|---|---|
| GET | /saml/{slug}/metadata | IdP metadata, Content-Type: application/samlmetadata+xml. Public. 404 for an unknown or non-SAML application. |
| GET | /saml/{slug}/sso | AuthnRequest, HTTP-Redirect binding |
| POST | /saml/{slug}/sso | AuthnRequest, HTTP-POST binding |
| GET, POST | /saml/{slug}/logout | LogoutRequest from the service provider, or its LogoutResponse during a Sovrain sign-out |
Limits: 300 requests per minute per client IP address on sso and logout; a POST body of at most 256 KiB.
IdP metadata
The metadata document contains, in this order:
EntityDescriptorwith the IdP entity ID;IDPSSODescriptorwithWantAuthnRequestsSignedset from Require signed AuthnRequest from the SP, andprotocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol";- a
KeyDescriptor use="signing"for the active signing key, then one for the next key while one is staged; SingleLogoutServicefor HTTP-Redirect and HTTP-POST, only when Single Logout is turned on;- one
NameIDFormat: the format set for the application; SingleSignOnServicefor HTTP-Redirect and HTTP-POST.
The metadata is not signed. It has no encryption key, no Organization, no ContactPerson, and no validUntil or
cacheDuration.
SP-initiated sign-in
Reading the request
| Item | Rule |
|---|---|
| Encoding | Base64; HTTP-Redirect also DEFLATE. At most 64 KiB encoded and 128 KiB inflated. |
| Query | A parameter repeated, or a parameter name containing % or +, is refused |
| XML | UTF-8 only. No DOCTYPE, external entities or processing instructions. At most 64 levels deep, 100,000 elements, 128 attributes on an element. |
| Read | ID, IssueInstant, Issuer, Destination, AssertionConsumerServiceURL or AssertionConsumerServiceIndex, ForceAuthn, IsPassive, RequestedAuthnContext |
| Ignored | NameIDPolicy, ProtocolBinding, AttributeConsumingServiceIndex, Scoping, Subject, Conditions |
Checks
| Check | Rule |
|---|---|
Issuer | Equals the application’s SP entity ID |
Destination | Required when signed requests are required. When present, equals the SSO URL. |
IssueInstant | Within 5 minutes of Sovrain’s clock |
| Signature | Required by default (Require signed AuthnRequest from the SP). Either the query signature of HTTP-Redirect or an embedded XML signature, made with a certificate in the application’s SP trust certificates. |
| ACS | Not both a URL and an index |
| Replay | Each request ID is accepted once; IDs are remembered for 10 minutes |
New SAML applications require signed requests. Until an SP certificate is added, by metadata import or by hand, every SP-initiated sign-in is refused, unless the requirement is turned off.
Assertion consumer service
- Only registered ACS endpoints with the HTTP-POST binding are used.
- The endpoint is chosen by the request’s URL (exact match), else by its index, else the default endpoint.
- The response is always delivered by a page that posts a form to the ACS automatically.
Options in the request
| Option | Behaviour |
|---|---|
ForceAuthn="true" | The person signs in again. The existing session is kept until the new sign-in replaces it. Skipped when the session is newer than the request. |
IsPassive="true" | When any page would be needed (sign-in, second step, account choice), the answer is the status NoPassive |
RequestedAuthnContext | Honoured with the comparisons exact (default), minimum, maximum and better, at most 16 references. Password level: PasswordProtectedTransport, Password, the SAML 1.0 and AD FS password classes, REFEDS SFA. Two-step level: https://refeds.org/profile/mfa, http://schemas.microsoft.com/claims/multipleauthn. A two-step level requires a second step; an impossible request is answered with NoAuthnContext. |
Failures
| Failure | Answer |
|---|---|
| The request is invalid, unsigned when a signature is required, replayed, or names an unknown ACS | An error page on Sovrain (400), nothing sent to the service provider |
| The application is disabled, or the person’s groups give no access | A SAML Response to the ACS with status Responder / RequestDenied |
| The NameID source value is empty, for example an unverified email | Responder / AuthnFailed |
IsPassive and a page would be needed | Responder / NoPassive |
| The requested authentication context cannot be met | Responder / NoAuthnContext |
IdP-initiated sign-in
- Requires Allow IdP-initiated SSO on the application.
- Starts from the application’s tile on the person’s home page.
- Posts to the default ACS endpoint; without a default, to the first ACS endpoint.
- The response has no
InResponseTo.RelayStateis the application’s Default RelayState (at most 80 bytes). - Refusals are pages on Sovrain.
The response
| Element | Value |
|---|---|
Response/@ID | _ followed by 32 hexadecimal characters |
Response/@Destination | The ACS URL |
Issuer | The IdP entity ID |
Status | Success |
Subject/NameID | See NameID |
SubjectConfirmation | bearer, with Recipient = ACS URL, InResponseTo = request ID, NotOnOrAfter = now + 5 minutes |
Conditions | NotBefore = now − 30 seconds, NotOnOrAfter = now + 5 minutes, AudienceRestriction = the SP entity ID |
AuthnStatement | AuthnInstant = when the person signed in, SessionIndex = stable for the Sovrain session. No SessionNotOnOrAfter. |
AuthnContextClassRef | See AuthnContextClassRef |
AttributeStatement | See Attributes |
RelayState sent by the service provider is returned unchanged.
Signing
| Item | Value |
|---|---|
| What is signed | What gets signed: the assertion (default), the response, or both |
| Signature | Enveloped, exclusive canonicalization, the certificate in KeyInfo |
| Key algorithms | RSA-2048 with SHA-256 (default) or SHA-512; ECDSA P-256 with SHA-256, P-384 with SHA-384, P-521 with SHA-512 |
| Keys | One set per application. Self-signed certificate with CN=<slug>, valid for 730 days. The end date is not enforced, and keys are not rotated automatically. |
| Key states | next (published in metadata, not signing), active (signing), retired (listed only) |
The algorithm RSA-2048 · SHA-1 is listed but cannot be generated. Choose another algorithm.
Signatures from the service provider
- Checked only against certificates in the application’s SP trust certificates.
- Accepted: RSA keys of at least 2048 bits with SHA-256, SHA-384 or SHA-512, and ECDSA keys.
- Refused: SHA-1. Only exclusive canonicalization, with an optional enveloped-signature transform.
- A certificate that disappears from refreshed metadata is no longer trusted from that moment. It is deleted 7 days later, unless an admin selects Keep.
Encryption
Off by default. When on:
| Item | Values |
|---|---|
| What is encrypted | The assertion (EncryptedAssertion), the NameID (EncryptedID) or the attributes (EncryptedAttribute) |
| Data encryption | AES-256-GCM (default), AES-192-GCM, AES-128-GCM; AES-256-CBC and AES-128-CBC (legacy) |
| Key transport | RSA-OAEP with SHA-256 and MGF1-SHA-256 (http://www.w3.org/2009/xmlenc11#rsa-oaep, default); RSA-OAEP-MGF1P with SHA-1 (legacy) |
| Certificate | An RSA certificate of the service provider with the use ENCRYPTION, else one with SIGNING_ENCRYPTION. Without one, the sign-in fails with an error page. |
RelayState
A RelayState from the service provider is returned unchanged; Sovrain does not limit its length. When the person
must first sign in, the return address including RelayState must fit in 6 KiB.
Single Logout
Off by default. Turned on per application with an SP Single Logout URL and binding (HTTP-Redirect or HTTP-POST).
Logout started by the service provider
- The
LogoutRequestgoes to/saml/{slug}/logout, by HTTP-Redirect or HTTP-POST. - Checks:
Issuer,Destination(required when a signature is required),IssueInstant, the signature (required by default: Require signed LogoutRequest), single use of the requestID. - With signature checking on, the person’s Sovrain session in that browser ends. With it off, only the person’s sessions at this application are marked ended.
- Sovrain does not pass the logout on to other applications. When the person has sessions at other applications
with Single Logout, the answer is
Successwith a nestedPartialLogoutstatus. - The
LogoutResponsegoes to the application’s configured SP Single Logout URL and binding, not to the address or binding of the request. - Errors show a page on Sovrain.
Logout started by Sovrain
- Triggered by Sign out, by the confirmation of an OpenID Connect sign-out and by Disconnect on Profile › Applications. Admin actions do not trigger it.
- The browser visits each application in turn (front channel only).
- It covers every session of the person at every application with Single Logout, from any browser.
- The
LogoutRequestcarries the NameID with the format and value sent at sign-in.SessionIndexis included only for sessions of a delegated sign-in. - The application’s
LogoutResponsemust carryInResponseToequal to the request. The whole sequence expires after 30 minutes. - Sessions are recorded for Single Logout only if Single Logout was on when the person signed in.
Service provider metadata
An admin imports the service provider’s metadata from a URL, an uploaded file (admin pages only) or pasted XML.
| Item | Rule |
|---|---|
| Size | At most 2 MiB |
| URL | https only, a public address, no redirects, 10-second timeout |
| Signature | Optional. When present, it must cover the root element. The first import trusts the document’s own certificate; later imports must verify against a certificate already trusted. |
| Entity ID | The first EntityDescriptor is used. Its entity ID must not be used by another application of the organization. |
| ACS | Endpoints with the HTTP-POST or HTTP-Artifact binding. An endpoint without index refuses the import. |
| Certificates | Every KeyDescriptor. Without use, the certificate is SIGNING_ENCRYPTION. |
| Single Logout | HTTP-Redirect preferred over HTTP-POST; SOAP ignored. Sets the SP Single Logout URL but does not turn Single Logout on. |
| Refresh | Daily at 04:00 UTC, only for a URL source with Auto-refresh from this URL daily ticked |
Not supported
- Bindings: HTTP-Artifact (ACS rows can be imported or added; SP-initiated sign-in never uses them, IdP-initiated sign-in posts to the default or first endpoint whatever its binding), SOAP, PAOS / ECP.
NameIDPolicy; a real transient NameID;SessionNotOnOrAfter.- Signed IdP metadata; an encryption key in the IdP metadata.
- SHA-1 signatures in either direction; RSA PKCS#1 v1.5 key transport. DSA, Ed25519 and RSA-PSS certificates can be stored but are not used.
- A
groupsattribute. - Back-channel (SOAP) Single Logout.