Sovrain
  1. Documentation
  2. Identity provider
  3. For developers
  4. Admin API

Reference

OpenID Connect clients

Admin API endpoints for an application's OpenID Connect client - settings, secret, redirect URIs, sign-out and claims.

Endpoints under https://acme.sovrain.net/api/v1/apps/{slug}/oidc, for applications of type OIDC. Authentication, conventions and the error format are on Admin API. How the client behaves at sign-in: OpenID Connect.

Scope: apps:read for GET, apps:write for every other call. Every write answers 200 with the client object, except where noted.

The client is created by the first call to any of these endpoints, including GET. Call them only for applications of type OIDC: on another type they create a client that sign-in never uses.

The client object

{
  "client_id": "TdAtCYictm7inke6XQkeED",
  "client_type": "confidential",
  "has_secret": true,
  "scopes": ["openid", "profile", "email", "groups"],
  "require_consent": false,
  "require_pkce": true,
  "allow_refresh_tokens": true,
  "logout_enabled": true,
  "backchannel_logout_uri": null,
  "frontchannel_logout_uri": "https://portal.acme.example/logout/frontchannel",
  "redirect_uris": [
    { "id": 2, "uri": "https://portal.acme.example/callback" }
  ],
  "post_logout_redirect_uris": [
    { "id": 1, "uri": "https://portal.acme.example/signed-out" }
  ],
  "claims": [
    { "id": 1, "source": "login", "claim_name": "username", "scope": "profile" }
  ]
}
FieldTypeDefault for a new clientNotes
client_idstringrandom22 characters. Never changes.
client_typestringconfidentialconfidential or public, in lower case
has_secretbooleanfalseWhether a secret has been generated. The secret itself is never returned again.
scopesarrayopenid, profile, emailThe scopes the application may request
require_consentbooleanfalseAsk the user before the first sign-in
require_pkcebooleantrueAlways true for a public client
allow_refresh_tokensbooleanfalse
logout_enabledbooleantrueWhether the application takes part in sign-out
backchannel_logout_uristring or nullnull
frontchannel_logout_uristring or nullnull
redirect_urisarrayemptyEach {id, uri}. Sign-in is refused while the list is empty.
post_logout_redirect_urisarrayemptyEach {id, uri}
claimsarrayemptyCustom claims, each {id, source, claim_name, scope}

Get the client

GET /api/v1/apps/{slug}/oidc

Response 200: the client object.

Change scopes and options

PUT /api/v1/apps/{slug}/oidc/settings

This call replaces all four settings. A boolean left out becomes false; scopes left out becomes ["openid"].

FieldTypeRequiredNotes
scopesarray of stringsnoOnly openid, profile, email and groups are kept; others are dropped. openid is always added.
require_consentbooleanno
require_pkcebooleannoIgnored for a public client, which always requires PKCE
allow_refresh_tokensbooleanno
{
  "scopes": ["openid", "profile", "email", "groups"],
  "require_consent": false,
  "require_pkce": true,
  "allow_refresh_tokens": true
}

Change the client type

PUT /api/v1/apps/{slug}/oidc/client-type

FieldTypeRequiredNotes
client_typestringyesCONFIDENTIAL or PUBLIC, in upper case

Changing the type deletes the current secret. Changing to PUBLIC sets require_pkce to true.

Errors: 400 invalid_request for a lower-case or unknown value.

Generate a client secret

POST /api/v1/apps/{slug}/oidc/secret

No body. Creates a new secret and answers it once. The previous secret stops working at once. Sovrain keeps only a SHA-256 hash of the secret.

Response 200, with Cache-Control: no-store:

{
  "client_id": "TdAtCYictm7inke6XQkeED",
  "client_secret": "<44-character secret>"
}

Errors:

StatuserrorWhen
422refusedA public client has no secret; cannot generate a secret

Add a redirect URI

POST /api/v1/apps/{slug}/oidc/redirect-uris

FieldTypeRequiredNotes
uristringyesRules: Redirect URI rules
{ "uri": "https://portal.acme.example/callback" }

Errors:

StatuserrorWhen
422refusedRedirect URI already registered: https://portal.acme.example/callback
422refusedRedirect URI must be absolute and include a host: com.acme.app:/cb
422refusedRedirect URI must not contain a fragment — a fragment never reaches the server
422refusedOther breaches of the rules, each with its own text

Remove a redirect URI

DELETE /api/v1/apps/{slug}/oidc/redirect-uris/{uriId}

Errors:

StatuserrorWhen
400invalid_requesturiId is not a number
422refusedUnknown redirect URI: id=99999

Add a post-logout redirect URI

POST /api/v1/apps/{slug}/oidc/post-logout-uris

FieldTypeRequiredNotes
uristringyesThe same rules as redirect URIs

Remove a post-logout redirect URI

DELETE /api/v1/apps/{slug}/oidc/post-logout-uris/{uriId}

Errors as for redirect URIs.

Change sign-out

PUT /api/v1/apps/{slug}/oidc/logout

FieldTypeRequiredNotes
enabledbooleannoLeft out: false, so {} turns sign-out off. An empty body answers 400 invalid_request.
backchannel_uristringnoLeft out: unchanged. "": cleared. Must be an https address that Sovrain can reach on the public internet.
frontchannel_uristringnoLeft out: unchanged. "": cleared. The redirect URI rules apply.

The three parts are saved one after another, in the order of the table. When a URI is refused, the parts before it stay saved.

{
  "enabled": true,
  "frontchannel_uri": "https://portal.acme.example/logout/frontchannel"
}

Errors:

StatuserrorWhen
422refusedBack-channel logout URI rejected — URL host resolves to a non-routable address (10.0.0.5): 10.0.0.5

Add a custom claim

POST /api/v1/apps/{slug}/oidc/claims

FieldTypeRequiredNotes
sourcestringyesA built-in attribute (id, externalId, login, email, firstName, lastName) or an attribute of the bank, with exact case
claim_namestringyesA letter, then up to 63 of A-Z a-z 0-9 _ . -. Not one of the reserved claim names. Unique in the client.
scopestringyesprofile, email or groups. The claim is sent only when this scope is granted.
{ "source": "login", "claim_name": "username", "scope": "profile" }

Errors:

StatuserrorWhen
422refusedThe claim name email is reserved: it already means something in every token we issue.
422refusedA claim must be released by one of profile, email, groups, not openid. The openid scope is always granted, so a claim on it would bypass consent.
422refusedUnknown source attribute: nope
422refusedAn invalid claim name, or a claim name the client already has

Remove a custom claim

DELETE /api/v1/apps/{slug}/oidc/claims/{mappingId}

Errors: 422 refused for an unknown id.

Disconnect everyone

POST /api/v1/apps/{slug}/oidc/disconnect-everyone

No body. Response 204.

Deletes every user’s consent and every refresh token of the client, closes the client’s sessions and sends back-channel logout. The admin pages call this Revoke for everyone.