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

How-to guide

Configure apps with the Admin API

Create an OpenID Connect or SAML app, set it up and give groups access to it, from a script.

This guide registers an application in Sovrain from a script, for example to set up the same app in several organizations or to keep its settings in version control. It covers an OpenID Connect app, a SAML app and the groups that may sign in. The Admin API lives at https://acme.sovrain.net/api/v1 and takes and returns JSON.

Before you start

  • Get an Admin API token with the scopes apps:read, apps:write and groups:read. apps:write can also replace a client secret, which breaks a running app until it gets the new one; keep the token for setup scripts only.
  • Choose the app’s slug, for example portal. It identifies the app in the API and in its addresses. The rules are in Applications › Create an application.

In the examples, $TOKEN holds the access token:

API=https://acme.sovrain.net/api/v1
AUTH="Authorization: Bearer $TOKEN"
JSON="Content-Type: application/json"

Create the application

  1. Check whether the app exists:

    curl "$API/apps/portal" -H "$AUTH"
    

    404 means it does not; any other answer shows the app as it is, and you can skip to the protocol settings. Creating an app with a slug in use is refused with 422 and Slug already in use: portal.

  2. Create it with the type it signs in with, OIDC or SAML, in upper case:

    curl "$API/apps" -H "$AUTH" -H "$JSON" -d '{"type":"OIDC","name":"Portal","slug":"portal"}'
    

    Sovrain answers 201 with the application. An OIDC app cannot become SAML later, or the other way round, so choose carefully.

If the app signs in with OpenID Connect

  1. Set the scopes and options. The call replaces all four settings, and a boolean you leave out becomes false:

    curl -X PUT "$API/apps/portal/oidc/settings" -H "$AUTH" -H "$JSON" \
      -d '{"scopes":["openid","profile","email","groups"],"require_pkce":true,"allow_refresh_tokens":true}'
    

    The first call to any /oidc endpoint creates the client. The answer contains its client_id. Include groups if the app reads groups or roles.

  2. If the app runs in the browser or on a phone and cannot keep a secret, make it a public client:

    curl -X PUT "$API/apps/portal/oidc/client-type" -H "$AUTH" -H "$JSON" -d '{"client_type":"PUBLIC"}'
    
  3. Add each redirect URI. Sign-in is refused until the app has one:

    curl "$API/apps/portal/oidc/redirect-uris" -H "$AUTH" -H "$JSON" \
      -d '{"uri":"https://portal.acme.example/callback"}'
    

    A URI that is already registered is refused with 422, so compare with redirect_uris in GET $API/apps/portal/oidc first. The rules a URI must follow are in OpenID Connect › Redirect URI rules.

  4. For a confidential client, generate the secret once:

    curl -X POST "$API/apps/portal/oidc/secret" -H "$AUTH"
    

    The answer holds client_id and client_secret. Store the secret in the app’s configuration straight away; Sovrain never shows it again. Every call makes a new secret and the old one stops working at once, so call it only when has_secret is false or when you mean to replace the secret.

  5. If the app should hear about sign-out, turn it on with its back-channel address:

    curl -X PUT "$API/apps/portal/oidc/logout" -H "$AUTH" -H "$JSON" \
      -d '{"enabled":true,"backchannel_uri":"https://portal.acme.example/logout/backchannel"}'
    

    The address must be https and reachable from the internet. See End your app’s session when people sign out elsewhere.

Give the app the issuer https://acme.sovrain.net, the client_id and, for a confidential client, the secret. Its OpenID Connect library finds the rest at https://acme.sovrain.net/.well-known/openid-configuration. Then add sign-in to the app.

If the app signs in with SAML

A new SAML app already has a signing key and the defaults listed in Application settings › SAML. It requires signed requests, so SP-initiated sign-in is refused until the app has a certificate from the service provider.

  1. If the service provider publishes metadata, import it. Sovrain takes the entity ID, the ACS endpoints, the certificates and the Single Logout address from it:

    curl "$API/apps/portal/saml/metadata" -H "$AUTH" -H "$JSON" \
      -d '{"url":"https://portal.acme.example/saml/metadata","auto_refresh":true}'
    

    With auto_refresh, Sovrain fetches the URL again every day. Without a URL, send the document as xml instead.

  2. If there is no metadata, set the same things one by one:

    curl -X PUT "$API/apps/portal/saml/sp" -H "$AUTH" -H "$JSON" \
      -d '{"entity_id":"https://portal.acme.example/saml/metadata","require_signed_authn_request":true}'
    
    curl "$API/apps/portal/saml/acs" -H "$AUTH" -H "$JSON" \
      -d '{"index":0,"binding":"HTTP_POST","location":"https://portal.acme.example/saml/acs"}'
    
    curl "$API/apps/portal/saml/sp-certificates" -H "$AUTH" -H "$JSON" \
      -d "$(jq -n --rawfile pem sp.pem '{use:"SIGNING",pem:$pem}')"
    

    PUT …/saml/sp replaces the whole setting: leaving out require_signed_authn_request turns the requirement off, and leaving out allow_idp_initiated turns IdP-initiated sign-in off.

  3. If the service provider expects another subject than the email address, change it:

    curl -X PUT "$API/apps/portal/saml/subject" -H "$AUTH" -H "$JSON" \
      -d '{"nameid_source":"login","nameid_format":"urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"}'
    

    Sovrain does not check these values when it saves them. An unknown source makes every sign-in to the app fail.

  4. Add an attribute mapping for each attribute the service provider reads:

    curl "$API/apps/portal/saml/mappings" -H "$AUTH" -H "$JSON" -d '{"source":"firstName","saml_name":"givenName"}'
    

    A name that is already mapped is refused with 422, so compare with mappings in GET $API/apps/portal/saml first.

Give the service provider Sovrain’s metadata address, https://acme.sovrain.net/saml/portal/metadata. Then add sign-in to the app.

Give groups access

  1. Find the group’s id:

    curl "$API/groups" -H "$AUTH"
    
  2. Give the group access, with a role if the app uses one:

    curl -X PUT "$API/apps/portal/groups/v6BQgJN59SryMvGUwk7jUP" -H "$AUTH" -H "$JSON" -d '{"role":"editor"}'
    

    Sovrain answers 204, and the call is safe to repeat. Sending it again without a role clears the role the group had. The role reaches the app as the role claim (OpenID Connect, with the groups scope) or attribute (SAML).

  3. Check the result in access of GET $API/apps/portal.

To take access away, call DELETE $API/apps/portal/groups/{groupId}; a group without access answers 422.

If the app also takes accounts over SCIM

Create it as SAML with "provisioning": true, or as SCIM if it does not sign in through Sovrain. Then:

  1. Save the app’s SCIM base URL and token and test them in one call:

    curl "$API/apps/portal/scim/test" -H "$AUTH" -H "$JSON" \
      -d '{"base_url":"https://portal.acme.example/scim/v2","token":"…"}'
    

    The answer is 200 even when the test fails; go on only when status is ok.

  2. Choose whom to send. The scope starts empty, so nobody is sent until you set it:

    curl -X PUT "$API/apps/portal/scim/scope" -H "$AUTH" -H "$JSON" \
      -d '{"groups":[{"id":"v6BQgJN59SryMvGUwk7jUP"}]}'
    

    Add ?dry_run=true to see first how many accounts would be created or removed.

  3. Turn provisioning on:

    curl -X PUT "$API/apps/portal/scim" -H "$AUTH" -H "$JSON" -d '{"enabled":true}'
    

Do not send PUT …/scim/provisioning with false: it deletes the connection with its mapping and scope. Every SCIM call: SCIM provisioning.