Sovrain
  1. Documentation
  2. Identity provider

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:

ItemValue
IdP entity IDhttps://acme.sovrain.net/saml/portal
IdP metadatahttps://acme.sovrain.net/saml/portal/metadata
Single sign-on servicehttps://acme.sovrain.net/saml/portal/sso (HTTP-Redirect and HTTP-POST)
Single Logout servicehttps://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.

MethodPathPurpose
GET/saml/{slug}/metadataIdP metadata, Content-Type: application/samlmetadata+xml. Public. 404 for an unknown or non-SAML application.
GET/saml/{slug}/ssoAuthnRequest, HTTP-Redirect binding
POST/saml/{slug}/ssoAuthnRequest, HTTP-POST binding
GET, POST/saml/{slug}/logoutLogoutRequest 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:

  • EntityDescriptor with the IdP entity ID;
  • IDPSSODescriptor with WantAuthnRequestsSigned set from Require signed AuthnRequest from the SP, and protocolSupportEnumeration="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;
  • SingleLogoutService for HTTP-Redirect and HTTP-POST, only when Single Logout is turned on;
  • one NameIDFormat: the format set for the application;
  • SingleSignOnService for 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

ItemRule
EncodingBase64; HTTP-Redirect also DEFLATE. At most 64 KiB encoded and 128 KiB inflated.
QueryA parameter repeated, or a parameter name containing % or +, is refused
XMLUTF-8 only. No DOCTYPE, external entities or processing instructions. At most 64 levels deep, 100,000 elements, 128 attributes on an element.
ReadID, IssueInstant, Issuer, Destination, AssertionConsumerServiceURL or AssertionConsumerServiceIndex, ForceAuthn, IsPassive, RequestedAuthnContext
IgnoredNameIDPolicy, ProtocolBinding, AttributeConsumingServiceIndex, Scoping, Subject, Conditions

Checks

CheckRule
IssuerEquals the application’s SP entity ID
DestinationRequired when signed requests are required. When present, equals the SSO URL.
IssueInstantWithin 5 minutes of Sovrain’s clock
SignatureRequired 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.
ACSNot both a URL and an index
ReplayEach 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

OptionBehaviour
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
RequestedAuthnContextHonoured 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

FailureAnswer
The request is invalid, unsigned when a signature is required, replayed, or names an unknown ACSAn error page on Sovrain (400), nothing sent to the service provider
The application is disabled, or the person’s groups give no accessA SAML Response to the ACS with status Responder / RequestDenied
The NameID source value is empty, for example an unverified emailResponder / AuthnFailed
IsPassive and a page would be neededResponder / NoPassive
The requested authentication context cannot be metResponder / 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. RelayState is the application’s Default RelayState (at most 80 bytes).
  • Refusals are pages on Sovrain.

The response

ElementValue
Response/@ID_ followed by 32 hexadecimal characters
Response/@DestinationThe ACS URL
IssuerThe IdP entity ID
StatusSuccess
Subject/NameIDSee NameID
SubjectConfirmationbearer, with Recipient = ACS URL, InResponseTo = request ID, NotOnOrAfter = now + 5 minutes
ConditionsNotBefore = now − 30 seconds, NotOnOrAfter = now + 5 minutes, AudienceRestriction = the SP entity ID
AuthnStatementAuthnInstant = when the person signed in, SessionIndex = stable for the Sovrain session. No SessionNotOnOrAfter.
AuthnContextClassRefSee AuthnContextClassRef
AttributeStatementSee Attributes

RelayState sent by the service provider is returned unchanged.

Signing

ItemValue
What is signedWhat gets signed: the assertion (default), the response, or both
SignatureEnveloped, exclusive canonicalization, the certificate in KeyInfo
Key algorithmsRSA-2048 with SHA-256 (default) or SHA-512; ECDSA P-256 with SHA-256, P-384 with SHA-384, P-521 with SHA-512
KeysOne 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 statesnext (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:

ItemValues
What is encryptedThe assertion (EncryptedAssertion), the NameID (EncryptedID) or the attributes (EncryptedAttribute)
Data encryptionAES-256-GCM (default), AES-192-GCM, AES-128-GCM; AES-256-CBC and AES-128-CBC (legacy)
Key transportRSA-OAEP with SHA-256 and MGF1-SHA-256 (http://www.w3.org/2009/xmlenc11#rsa-oaep, default); RSA-OAEP-MGF1P with SHA-1 (legacy)
CertificateAn 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 LogoutRequest goes 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 request ID.
  • 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 Success with a nested PartialLogout status.
  • The LogoutResponse goes 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 LogoutRequest carries the NameID with the format and value sent at sign-in. SessionIndex is included only for sessions of a delegated sign-in.
  • The application’s LogoutResponse must carry InResponseTo equal 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.

ItemRule
SizeAt most 2 MiB
URLhttps only, a public address, no redirects, 10-second timeout
SignatureOptional. 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 IDThe first EntityDescriptor is used. Its entity ID must not be used by another application of the organization.
ACSEndpoints with the HTTP-POST or HTTP-Artifact binding. An endpoint without index refuses the import.
CertificatesEvery KeyDescriptor. Without use, the certificate is SIGNING_ENCRYPTION.
Single LogoutHTTP-Redirect preferred over HTTP-POST; SOAP ignored. Sets the SP Single Logout URL but does not turn Single Logout on.
RefreshDaily 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 groups attribute.
  • Back-channel (SOAP) Single Logout.