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

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

  1. On your home page, under Administration, select Open admin, then select Applications in the admin menu.
  2. 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).
  3. Select Create application.

Tell Sovrain about the service provider

With the SP’s metadata

  1. Open the Service Provider tab.
  2. Under Metadata source, select Import metadata….
  3. 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.
  4. 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

  1. Open the Service Provider tab.
  2. Under Endpoints & identity, replace Entity ID with the SP’s entity ID.
  3. 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.
  4. If the SP signs its requests, under SP trust certificates select Add certificate, choose Use SIGNING or SIGNING_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

  1. Open the Identity Provider tab.
  2. Under IdP metadata, copy Metadata URL into the SP, or select Download XML and upload the file there.
  3. 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 firstName to givenName.

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.

  1. Open the Access & diagnostics tab.
  2. 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

  1. 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.
  2. Sign in to the application as a member of the group you added.
  3. 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.

  1. On the Service Provider tab, turn on Allow IdP-initiated SSO.
  2. Leave App launcher URL empty: the tile then signs people straight in.
  3. 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

  1. Make sure the SP’s RSA certificate is listed under SP trust certificates with Use set to ENCRYPTION or SIGNING_ENCRYPTION.
  2. On the Access & diagnostics tab, under Encryption, turn on Enable assertion encryption for this application and choose What to encrypt. ASSERTION is the safest choice; many SPs do not accept the other two.

If the SP supports Single Logout

  1. On the Sign-out tab, turn on Enable Single Logout for this application.
  2. Fill in SP SLO URL and choose Binding.

All four signing options start on. See About sessions and sign-out.