How-to guide
Connect a SAML app
Register a SAML service provider, exchange metadata, handle the signed-request requirement and give a group access.
This guide connects an application that signs people in with SAML 2.0, so that your people use their Sovrain account to sign in to it. In SAML terms Sovrain is the identity provider (IdP) and the application is the service provider (SP). You need access to the application’s own SAML or SSO settings as well.
Before you start
From the application’s SAML settings, find either:
- its metadata: a URL or an XML file; or
- the values one by one: its entity ID (also called audience URI or identifier), its ACS URL (also called reply URL or single sign-on URL), and its signing certificate if it signs its requests.
A new SAML application starts with a placeholder entity ID, urn:idp:app:<slug>, and requires the SP to sign its
sign-in requests; the steps below deal with both. Its other defaults are listed in
Application settings › SAML.
Create the application
- On your home page, under Administration, select Open admin, then select Applications in the admin menu.
- Select Add application and fill in:
- Application name: what your people see, for example
Expenses; - Slug: a short lower-case name, for example
expenses. It becomes part of the SAML addresses; - Application type: SAML 2.0 (SSO).
- Application name: what your people see, for example
- Select Create application.
Tell Sovrain about the service provider
With the SP’s metadata
- Open the Service Provider tab.
- Under Metadata source, select Import metadata….
- Choose the Source:
- Metadata URL: paste the HTTPS address. Tick Auto-refresh from this URL daily if the SP changes its metadata, for example when it renews its certificate;
- Upload XML file;
- Paste XML.
- Select Import.
Sovrain fills in Entity ID, the ACS URLs, the SP trust certificates and, if present, the SP’s sign-out address. Sovrain accepts unsigned metadata, so import it only from a source you trust.
By hand
- Open the Service Provider tab.
- Under Endpoints & identity, replace Entity ID with the SP’s entity ID.
- Under ACS URLs, select Add ACS URL. Set Binding to HTTP-POST, paste the SP’s ACS URL into Location, and select Add URL. Sovrain delivers sign-ins with HTTP-POST only.
- If the SP signs its requests, under SP trust certificates select Add certificate, choose Use
SIGNINGorSIGNING_ENCRYPTION, paste the certificate into Certificate (PEM) and select Add.
Deal with signed requests
New SAML applications require the SP to sign its sign-in requests (AuthnRequests). Until Sovrain has the SP’s signing certificate, every sign-in that starts at the application fails with an error page.
Do one of these:
- give Sovrain the SP’s certificate, either through its metadata or under SP trust certificates; or
- if the SP does not sign its requests, turn off Require signed AuthnRequest from the SP under Endpoints & identity.
Tell the service provider about Sovrain
- Open the Identity Provider tab.
- Under IdP metadata, copy Metadata URL into the SP, or select Download XML and upload the file there.
- If the SP wants single values instead, copy Identity provider entity ID (for example
https://acme.sovrain.net/saml/expenses) and Identity provider single sign-on URL. For the certificate, go to Signing keys and use Copy certificate or Download certificate on the active key.
Choose what the SP receives
Open the Subject & attributes tab.
- Under Subject (NameID), pick the Source attribute and Format the SP expects. With the source
email, only a verified address is sent; people without one cannot sign in to this application. - Under Attribute mapping, select Add mapping for each attribute the SP needs, for example
firstNametogivenName.
Sovrain sends the role attribute on its own when group access gives roles; see
Send roles to apps. Sovrain sends no groups attribute. More in
Map claims and attributes.
Let people in
Only members of the groups listed under Group access can sign in to the application.
- Open the Access & diagnostics tab.
- Under Group access, select Add group, choose a group, for example
Engineering, and select Add.
Put the application on your people’s home page
On the Service Provider tab, under App launcher, fill in App launcher URL with the SP’s sign-on page. The tile on the home page then sends people to the application, which asks Sovrain to sign them in.
Test it
- On the Access & diagnostics tab, under Test SSO & recent activity, select Run test SSO. It signs and checks a sample assertion with the active key. It does not sign anyone in.
- Sign in to the application as a member of the group you added.
- Look at Recent activity on the same tab. See Find out why someone cannot sign in to an app.
If you want people to start at the Sovrain tile
Some SPs accept sign-ins that start at the identity provider.
- On the Service Provider tab, turn on Allow IdP-initiated SSO.
- Leave App launcher URL empty: the tile then signs people straight in.
- If the SP needs to know where to land people, fill in Default RelayState, up to 80 bytes.
If the SP needs something else signed
Under What gets signed on the Identity Provider tab, choose Response or Both instead of Assertion.
If the SP expects a different two-step signal
Under Two-step sign-in signal (AuthnContextClassRef) on the Identity Provider tab, choose what the SP expects: REFEDS MFA (the default), Microsoft or Password only.
If the SP wants encrypted assertions
- Make sure the SP’s RSA certificate is listed under SP trust certificates with Use set to
ENCRYPTIONorSIGNING_ENCRYPTION. - On the Access & diagnostics tab, under Encryption, turn on Enable assertion encryption for this
application and choose What to encrypt.
ASSERTIONis the safest choice; many SPs do not accept the other two.
If the SP supports Single Logout
- On the Sign-out tab, turn on Enable Single Logout for this application.
- Fill in SP SLO URL and choose Binding.
All four signing options start on. See About sessions and sign-out.
Related
- Add sign-in with SAML, for developers of the application.
- SAML for what Sovrain sends and accepts.
- Rotate signing keys.
- Provision accounts with SCIM, to create accounts in the same application.