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" }
]
}
| Field | Type | Default for a new client | Notes |
|---|---|---|---|
client_id | string | random | 22 characters. Never changes. |
client_type | string | confidential | confidential or public, in lower case |
has_secret | boolean | false | Whether a secret has been generated. The secret itself is never returned again. |
scopes | array | openid, profile, email | The scopes the application may request |
require_consent | boolean | false | Ask the user before the first sign-in |
require_pkce | boolean | true | Always true for a public client |
allow_refresh_tokens | boolean | false | |
logout_enabled | boolean | true | Whether the application takes part in sign-out |
backchannel_logout_uri | string or null | null | |
frontchannel_logout_uri | string or null | null | |
redirect_uris | array | empty | Each {id, uri}. Sign-in is refused while the list is empty. |
post_logout_redirect_uris | array | empty | Each {id, uri} |
claims | array | empty | Custom 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"].
| Field | Type | Required | Notes |
|---|---|---|---|
scopes | array of strings | no | Only openid, profile, email and groups are kept; others are dropped. openid is always added. |
require_consent | boolean | no | |
require_pkce | boolean | no | Ignored for a public client, which always requires PKCE |
allow_refresh_tokens | boolean | no |
{
"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
| Field | Type | Required | Notes |
|---|---|---|---|
client_type | string | yes | CONFIDENTIAL 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:
| Status | error | When |
|---|---|---|
| 422 | refused | A public client has no secret; cannot generate a secret |
Add a redirect URI
POST /api/v1/apps/{slug}/oidc/redirect-uris
| Field | Type | Required | Notes |
|---|---|---|---|
uri | string | yes | Rules: Redirect URI rules |
{ "uri": "https://portal.acme.example/callback" }
Errors:
| Status | error | When |
|---|---|---|
| 422 | refused | Redirect URI already registered: https://portal.acme.example/callback |
| 422 | refused | Redirect URI must be absolute and include a host: com.acme.app:/cb |
| 422 | refused | Redirect URI must not contain a fragment — a fragment never reaches the server |
| 422 | refused | Other breaches of the rules, each with its own text |
Remove a redirect URI
DELETE /api/v1/apps/{slug}/oidc/redirect-uris/{uriId}
Errors:
| Status | error | When |
|---|---|---|
| 400 | invalid_request | uriId is not a number |
| 422 | refused | Unknown redirect URI: id=99999 |
Add a post-logout redirect URI
POST /api/v1/apps/{slug}/oidc/post-logout-uris
| Field | Type | Required | Notes |
|---|---|---|---|
uri | string | yes | The 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
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | no | Left out: false, so {} turns sign-out off. An empty body answers 400 invalid_request. |
backchannel_uri | string | no | Left out: unchanged. "": cleared. Must be an https address that Sovrain can reach on the public internet. |
frontchannel_uri | string | no | Left 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:
| Status | error | When |
|---|---|---|
| 422 | refused | Back-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
| Field | Type | Required | Notes |
|---|---|---|---|
source | string | yes | A built-in attribute (id, externalId, login, email, firstName, lastName) or an attribute of the bank, with exact case |
claim_name | string | yes | A letter, then up to 63 of A-Z a-z 0-9 _ . -. Not one of the reserved claim names. Unique in the client. |
scope | string | yes | profile, email or groups. The claim is sent only when this scope is granted. |
{ "source": "login", "claim_name": "username", "scope": "profile" }
Errors:
| Status | error | When |
|---|---|---|
| 422 | refused | The claim name email is reserved: it already means something in every token we issue. |
| 422 | refused | A 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. |
| 422 | refused | Unknown source attribute: nope |
| 422 | refused | An 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.