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

How-to guide

Connect an OpenID Connect app

Register an app, add its redirect URI, give a group access and copy the client settings.

This guide connects an application that signs people in with OpenID Connect (OIDC), so that your people use their Sovrain account to sign in to it. You need access to the application’s own SSO or OIDC settings as well.

Before you start

From the application’s documentation or settings page, find:

  • its redirect URI, also called callback URL or reply URL, for example https://wiki.acme.example/oauth/callback;
  • whether it runs on a server and can keep a secret (a confidential client), or runs in the browser or on a phone (a public client);
  • whether it sends PKCE. Most current libraries do.

A new OIDC application starts as a confidential client with no secret and without the groups scope; the steps below deal with both. Its other defaults are listed in Application settings › Relying Party (RP).

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 Team Wiki;
    • Slug: a short lower-case name, for example portal;
    • Application type: OpenID Connect (SSO). This cannot be changed later.
  3. Select Create application.

The application’s page opens with its client ID under the name.

Add the redirect URI

  1. Open the Relying Party (RP) tab.
  2. Under Redirect URIs, select Add redirect URI, paste the application’s redirect URI and select Add.

Sovrain compares redirect URIs exactly: no wildcards, no prefixes, path and query included. A URI must use https; plain http is accepted only for localhost, 127.0.0.1 and [::1]. Until one URI is listed, Sovrain refuses every sign-in to the application. Add one row for each address the application uses.

Give the application its client settings

  1. Under Client registration, next to Client secret, select Generate. Copy the secret straight into the application: Sovrain keeps only a hash and shows the secret once.
  2. Copy Client ID into the application.
  3. Under Our endpoints, copy Discovery URL, for example https://acme.sovrain.net/.well-known/openid-configuration, into the application. If it asks for single endpoints instead, copy Issuer, Authorization, Token, Userinfo and JWKS from the same card.
  4. In the application, set the scopes to openid profile email, or to the scopes you allow in the next section.

The application can send the secret either in the HTTP Basic header or in the form body.

Check scopes and options

Under Scopes & options:

  • Tick groups if the application needs to know the user’s groups or roles. An application that asks for a scope that is not ticked gets an error at sign-in.
  • Leave Require PKCE on unless the application cannot send PKCE.
  • Turn on Allow refresh tokens only if the application needs to stay signed in without the browser.

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.

To give the group a role in the application, see Send roles to apps.

Put the application on your people’s home page

OpenID Connect sign-in always starts at the application, so the application has no tile on the Sovrain home page until you give it an address.

  1. Open the App identity tab.
  2. Fill in App launcher URL, for example https://wiki.acme.example.

Test it

  1. On the Access & diagnostics tab, under Diagnostics & activity, select Test sign-in. It checks that Sovrain can sign a token the application can verify. 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. A failed sign-in shows what went wrong and, often, a line starting with Fix:. See Find out why someone cannot sign in to an app.

If the application is a public client

Use this for single-page apps and mobile apps, which cannot keep a secret. A mobile app needs an https redirect URI (a universal or app link) or a loopback address; custom schemes such as com.acme.app:/cb are refused.

  1. On the Relying Party (RP) tab, under Client registration, set Client type to PUBLIC.
  2. Confirm Switch to PUBLIC.

The secret is discarded and PKCE stays required for good: a public client proves itself with PKCE alone.

If the application cannot send PKCE

Turn off Require PKCE under Scopes & options. This is possible only for a confidential client. Sovrain accepts only the S256 PKCE method.

If you need a new client secret

  1. Under Client registration, select Rotate.
  2. Confirm Generate new secret.
  3. Copy the new secret into the application at once.

The old secret stops working the moment the new one exists, so the application cannot sign anyone in until you paste the replacement.

If the application should be told when people sign out

Sign-out is on by default. On the Sign-out tab:

  • fill in Back-channel logout URI so that Sovrain tells the application, server to server, when a session ends;
  • or fill in Front-channel logout URI, which the browser loads in a hidden frame;
  • under Post-logout redirect URIs, add the addresses the application may send people to after signing out. They are matched exactly, like redirect URIs.

See About sessions and sign-out.