Sovrain
  1. Documentation
  2. Identity provider
  3. For developers

How-to guide

Add sign-in with SAML to your app

Connect your service provider to Sovrain, send signed AuthnRequests and validate the assertions that come back.

This guide connects an application that acts as a SAML 2.0 service provider (SP) to Sovrain, so people sign in with their Sovrain account. In the examples the app’s slug in Sovrain is portal.

Before you start

Ask an admin to connect your app as a SAML app and to give at least one group access to it. You and the admin exchange these values:

From Sovrain (Identity Provider tab)Example
Metadata URLhttps://acme.sovrain.net/saml/portal/metadata
Identity provider entity IDhttps://acme.sovrain.net/saml/portal
Identity provider single sign-on URLhttps://acme.sovrain.net/saml/portal/sso (HTTP-Redirect and HTTP-POST)
From your app (Service Provider tab)Example
Your SP metadata, by URL or as XML, for Import metadata…https://wiki.acme.example/saml/metadata
or, by hand: your Entity IDhttps://wiki.acme.example/saml
your ACS URL, with the HTTP-POST binding, under ACS URLshttps://wiki.acme.example/saml/acs
your signing certificate, under SP trust certificatesPEM

The IdP entity ID is different for every app, so do not reuse one app’s Sovrain settings for another.

Connect the two sides

  1. Load Sovrain’s metadata into your SP from the Metadata URL. The metadata is not signed, so fetch it over https. It lists the active signing certificate and, during a key change, the next one; trust every certificate it lists, and refresh the metadata now and then so that a key change does not break sign-in.
  2. Give the admin your SP metadata. Sovrain takes your entity ID, your ACS endpoints and your certificates from it. If you give the values by hand instead, make sure the admin replaces the placeholder entity ID urn:idp:app:portal with yours.
  3. Agree on the NameID. By default Sovrain sends the person’s verified email address with the format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. If your app needs a stable identifier, ask the admin to set Source attribute under Subject (NameID) to a value that does not change. Sovrain ignores the NameIDPolicy of your request.

Send the sign-in request

Sovrain requires signed AuthnRequests by default (Require signed AuthnRequest from the SP). Send each request like this:

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                    ID="_8f3c2a7e5b1d4c9a" Version="2.0" IssueInstant="2026-11-17T10:00:00Z"
                    Destination="https://acme.sovrain.net/saml/portal/sso"
                    AssertionConsumerServiceURL="https://wiki.acme.example/saml/acs">
  <saml:Issuer>https://wiki.acme.example/saml</saml:Issuer>
</samlp:AuthnRequest>
  • Issuer is your entity ID exactly.
  • Destination is the single sign-on URL. It is required when the request is signed.
  • ID is new for every request: Sovrain accepts each ID once.
  • IssueInstant is within 5 minutes of Sovrain’s clock.
  • AssertionConsumerServiceURL matches a registered ACS URL exactly. You can send AssertionConsumerServiceIndex instead, or neither to use the default ACS, but not both.
  • Sign with RSA of at least 2048 bits and SHA-256, SHA-384 or SHA-512, or with ECDSA, using exclusive canonicalization. SHA-1 signatures are refused. With the HTTP-Redirect binding, sign the query string; with HTTP-POST, embed the signature.

If the request is malformed, unsigned, replayed or names an unknown ACS URL, Sovrain shows an error page and does not send the person back to your app.

Validate the response

Sovrain always delivers the response to your ACS URL with an auto-submitting HTTP-POST form.

  1. Check the signature against a certificate from Sovrain’s metadata. By default Sovrain signs the assertion; the admin can switch What gets signed to the response or both, so validate whichever you agreed on.
  2. Check the Status is Success.
  3. Check that Issuer is the IdP entity ID, Destination and Recipient are your ACS URL, InResponseTo is the ID of your request, and Audience is your entity ID.
  4. Check the time window: NotBefore is 30 seconds before issue and NotOnOrAfter is 5 minutes after.
  5. Read the person from NameID and the attributes. Attributes use the basic name format and carry single string values, except role, which has one value per role. Empty values are not sent. There is no groups attribute; see Read groups and roles in your app.

The assertion has a SessionIndex but no SessionNotOnOrAfter, so your app decides how long its own session lasts.

When Sovrain accepted the request but cannot sign the person in, the response has a Responder status with one of these second-level codes:

StatusCause
RequestDeniedThe app is disabled, or the person is in no group with access
AuthnFailedThe NameID source has no value for this person, for example an unverified email address
NoPassiveIsPassive="true" and Sovrain would have to show a page
NoAuthnContextThe requested authentication context cannot be met

Variants

  • If people should be able to start from their Sovrain home page, ask the admin to turn on Allow IdP-initiated SSO. Your SP then receives responses without InResponseTo, with the admin’s default RelayState, and must accept them.
  • If you want the assertion encrypted, give the admin an RSA certificate for encryption. Sovrain encrypts with AES-GCM (or AES-CBC as a legacy option) and RSA-OAEP.
  • If you need a fresh sign-in, set ForceAuthn="true".
  • If you need a second step, see Require two-step sign-in from your app.
  • For Single Logout, see Sign people out from your app and End your app’s session when people sign out elsewhere.

Sovrain does not support the HTTP-Artifact binding, SOAP or ECP, signed IdP metadata, or SHA-1 signatures in either direction. All SAML details: SAML.