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:writeandgroups:read.apps:writecan 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
Check whether the app exists:
curl "$API/apps/portal" -H "$AUTH"404means 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 with422andSlug already in use: portal.Create it with the type it signs in with,
OIDCorSAML, in upper case:curl "$API/apps" -H "$AUTH" -H "$JSON" -d '{"type":"OIDC","name":"Portal","slug":"portal"}'Sovrain answers
201with the application. AnOIDCapp cannot becomeSAMLlater, or the other way round, so choose carefully.
If the app signs in with OpenID Connect
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
/oidcendpoint creates the client. The answer contains itsclient_id. Includegroupsif the app reads groups or roles.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"}'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 withredirect_urisinGET $API/apps/portal/oidcfirst. The rules a URI must follow are in OpenID Connect › Redirect URI rules.For a confidential client, generate the secret once:
curl -X POST "$API/apps/portal/oidc/secret" -H "$AUTH"The answer holds
client_idandclient_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 whenhas_secretisfalseor when you mean to replace the secret.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
httpsand 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.
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 asxmlinstead.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/spreplaces the whole setting: leaving outrequire_signed_authn_requestturns the requirement off, and leaving outallow_idp_initiatedturns IdP-initiated sign-in off.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.
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 withmappingsinGET $API/apps/portal/samlfirst.
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
Find the group’s
id:curl "$API/groups" -H "$AUTH"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 theroleclaim (OpenID Connect, with thegroupsscope) or attribute (SAML).Check the result in
accessofGET $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:
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
200even when the test fails; go on only whenstatusisok.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=trueto see first how many accounts would be created or removed.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.
Related
- Automate onboarding with the Admin API, to put people into the group.
- Connect an OpenID Connect app and Connect a SAML app, for the same tasks in the admin pages.
- Every endpoint, field and error: Applications, OpenID Connect clients and SAML configuration.