Ga naar inhoud
buildinglinksbuildinglinks

Test an identity provider link

POST
/api/v1/settings/idp/test
curl --request POST \
  --url https://example.com/api/v1/settings/idp/test \
  --header 'Content-Type: application/json' \
  --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E \
  --data '{ "issuer": "example", "internal_url": "example", "client_id": "example", "client_secret": "example", "role_claim": "example", "role_mapping": { "additionalProperty": [ "example" ] }, "offline_access": true }'

Checks a link without saving it: the discovery document, that the provider calls itself by the issuer, its signing keys, and that it accepts the client id and secret (a client credentials request whose token is not used). Without a client secret the stored one is tested. ends_sessions says whether saving it would end the current sessions, the caller’s own too. What needs a browser, such as the redirect URI, is not tested.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

The link with the participant’s OpenID Connect provider.

object
issuer
required

Issuer as seen by browsers (and as it appears in iss).

string
internal_url

Optional base URL used for back-channel calls (discovery, token) when the IdP is reachable under a different name from the server.

string | null
client_id
required
string
client_secret

Write only: never returned.

string | null
role_claim

Dotted path to the roles claim, e.g. realm_access.roles or groups.

string
role_mapping

App role → IdP role names that grant it.

object
key
additional properties
Array<string>
offline_access

Ask for offline_access: an IdP such as Entra ID only gives a refresh token with it. Keycloak gives one without, bound to its session; with it, an offline token that outlives a logout.

boolean

Example generated

{
  "issuer": "example",
  "internal_url": "example",
  "client_id": "example",
  "client_secret": "example",
  "role_claim": "example",
  "role_mapping": {
    "additionalProperty": [
      "example"
    ]
  },
  "offline_access": true
}

Responses

Section titled “Responses”

200

Section titled “200”

OK.

Media typeapplication/json

POST /api/v1/settings/idp/test.

object
ok
required

No check failed: the link may be saved.

boolean
checks
required
Array<object>

One check of [check].

object
id
required

discovery, issuer, keys or client.

string
status
required

ok, warning (could not be checked fully; saving is allowed), failed (saving is refused) or skipped (an earlier check failed).

string
detail
required

What was found, for people.

string
ends_sessions
required

Saving ends the sessions of the current IdP, the caller’s own too: the issuer or the client changes.

boolean

Example generated

{
  "ok": true,
  "checks": [
    {
      "id": "example",
      "status": "example",
      "detail": "example"
    }
  ],
  "ends_sessions": true
}

400

Section titled “400”

Issuer or client id missing.

Media typeapplication/json

The body of every failed call to a management API.

object
error
required
object
code
required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string
message
required

For people; may change between versions.

string

Example 

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}

401

Section titled “401”

No valid session, DPoP-bound token or API key.

Media typeapplication/json

The body of every failed call to a management API.

object
error
required
object
code
required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string
message
required

For people; may change between versions.

string

Example 

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}

403

Section titled “403”

The caller lacks the role this operation needs; or a change with the session cookie came from a page of another site (cross_site_request, decisions #83).

Media typeapplication/json

The body of every failed call to a management API.

object
error
required
object
code
required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string
message
required

For people; may change between versions.

string

Example 

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}