Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

Web clients

Web clients API

search

Web clients API

The web client API allows the creation of new web clients via a REST API. It can be used in scripts to add many clients at the same time, or to edit or delete web clients.

All endpoints are protected with an API client using either the Client Secret Basic or PrivateKeyJWT authentication method. It requires an API client with the onegini_api_config (Config API) scope.

Web client API endpoints

List web clients

This returns a list of all web clients.

  • Endpoint: /api/v1/configuration/web-clients
  • Method: GET

Request parameters:

Param Required Description
page no Results are limited to 100 entries. Page number defaults to 0.

Example request:

GET /api/v1/configuration/web-clients HTTP/1.1
Host: onegini.example.com

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   "result":[
      {
         "name":"web client 1",
         "client_id":"365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B",
         "client_authentication_method": "CLIENT_SECRET_BASIC",
         "grant_types":[
            "AUTHORIZATION_CODE"
         ],
         "access_token_format":"JWT",
         "redirect_url":"https://example.com/redirect",
         "additional_redirect_urls":[
            "https://example.com/redirect",
            "https://example.net/redirect"
         ],
         "access_grant_expires_in":30,
         "access_token_expires_in":3600,
         "additional_audiences":[],
         "refresh_token_enabled":true,
         "simultaneous_sessions_allowed":true,
         "max_simultaneous_sessions":25,
         "default_scopes":[
            "address",
            "email"
         ],
         "additional_scopes":[
            "phone"
         ],
         "identity_provider_id":"123-123",
         "additional_identity_provider_ids":["123-124", "123-125"],
         "legacy_group_permissions_enabled": false,
         "template_set":"template1",
         "consent_disabled":true
      },
      {
        ... more clients ...
      }
   ]
}

In the event of an error, one of the generic error codes is returned.

Create web client

This creates a new web client.

  • Endpoint: /api/v1/configuration/web-clients
  • Method: POST

JSON body parameters:

Param Required Example Description
name yes "myWebClient" Custom client name
client_id yes "F167433E63CE8BD874D7…" Unique Identifier for a client
client_authentication_method no "CLIENT_SECRET_BASIC" The authentication method that must be used for this client. Allowed values: CLIENT_SECRET_BASIC, PKCE, PRIVATE_KEY_JWT, and PUBLIC. If no method is specified and the DEVICE_CODE grant type is enabled, it defaults to PUBLIC. Otherwise it defaults to CLIENT_SECRET_BASIC.
client_secret depends "AF33E2BF29C54A4639AB…" Client secret (not returned on GET). Required when client_authentication_method is CLIENT_SECRET_BASIC or when the client_authentication_method is not specified.
hashed_client_secret depends "$bcrypt$c=12$T/jBeKR…" A hashed version of the secret using the PHC format (not returned on GET). For more information, see the web client migration page.
public_jwk depends EC or RSA public key Plain public key for private key JWT authentication in the Elliptic Curve (min P-256) or RSA (min 2048, max 4096 key length) x509 format. The OneWelcome Identity Platform favours jwks_uri if provided over statically defined JWK.
jwks_uri depends "https://authorization-server/jwks" URI of the JWKS endpoint with public keys for private key JWT authentication.
grant_types yes ["CLIENT_CREDENTIALS"] Set of grant types. Allowed values: AUTHORIZATION_CODE, CLIENT_CREDENTIALS, PASSWORD, IMPLICIT, and DEVICE_CODE. When client_authentication_method is PKCE the only allowed value is AUTHORIZATION_CODE.
access_token_format no "OPAQUE" Format of the Access Token. Allowed values: OPAQUE (random string) or JWT (JSON Web Token). Defaults to OPAQUE when omitted. The JWT access token contains the user identifier for AUTHORIZATION_CODE grant types.
redirect_url yes "https://example.com/redirect" A URL to which the browser is redirected after successfully obtaining an access grant. Required for the AUTHORIZATION_CODE grant type.
additional_redirect_urls no ["https://example.org/redirect"] Additional URLs that the user can be redirected to after successfully obtaining an access grant.
device_verification_uri no "https://example.com/device" A URI to which the user is redirected by the device to complete the authorization flow. It is used for the DEVICE_CODE grant type with in-app authorization. It is expected that the user manually enters the user code.
device_verification_uri_complete no "https://example.com/device?code={user_code}" A URI to which the user is redirected by the device to complete the authorization flow. It is used for the DEVICE_CODE grant type with in-app authorization. The URI contains the {user_code} placeholder, which is replaced with the actual user code.
access_grant_expires_in yes 30 The number of seconds that an access grant is valid. Required forAUTHORIZATION_CODE grant type.
access_token_expires_in yes 900 The number of seconds that an access token is valid. Required for AUTHORIZATION_CODE and CLIENT_CREDENTIALS grant types.
resource_gateway_ids no ["resource_gateway_1"] An array with the client_ids of existing clients that act as a resource gateway. It is used to populate the aud claim in a JWT access token.
additional_audiences no ["aud2", "https://example.com"] An array of case-sensitive strings that identifies the audience of the issued access token, other than the resource gateways. It is used to populate the aud claim in a JWT access token.
refresh_token_enabled no true Issue refresh tokens
refresh_token_expires_in no 7200 Limits the time that refresh tokens can be used to obtain a new access token and refresh token. It is calculated from the refresh token issued time. Omit the field for unlimited validity. When providing a value, refresh_token_enabled must be true.
max_refresh_token_validity no 86400 The overall refresh token lifetime starting from the initial refresh token creation. This setting ensures that a stolen refresh token cannot be used indefinitely. Omit the field for unlimited validity. When providing a value, refresh_token_enabled must be true.
simultaneous_sessions_allowed no true Allow users to establish multiple sessions at the same time
max_simultaneous_sessions no 25 Limits the number of sessions when simultaneous sessions are allowed. The value must be between two and 25 (inclusive). Defaults to 25 when omitted and simultaneous_sessions_allowed is true.
default_scopes no ["profile"] Default scopes are automatically assigned if a client does not request any scopes. If you want an authorization request to fail when no scopes are requested, leave this empty.
additional_scopes no ["address", "email"] Additional scopes that can be requested by a client during an authorization request. The default scopes can also be requested by a client during the authorization request.
identity_provider_id no "123-123" The identifier of an existing identity provider that you want to be the primary or default for this client. If none is specified in the request, this is used.
additional_identity_provider_ids no ["123-124", "123-125"] Identifiers of additional existing identity providers that can be specified in the request.
template_set no "template1" Identifier of an existing template set
consent_disabled no false When consent is skipped, the user is not asked for consent in the authorization flow. The value must be true when grant_types contains PASSWORD.
open_id_connect no See table below JSON object for OpenID Connect configuration. Required when default_scopes or additional_scopes contain openid.
legacy_group_permissions_enabled no false By default, the latest version of the DABP report is returned in claims. Set this flag value to true to use legacy version 1 of this report.
web_hook_ids no [“customize-token-webhook”] Set of integrated web hook IDs.

The following parameters are a part of the open_id_connect object.

Param Required Example Description
expiration_time_seconds depends 3600 The number of seconds that an ID token is valid. It is used to calculate the exp expiration date claim in the ID token. Required when default_scopes or additional_scopes contains openid.
additional_audiences no ["https://resource.example.com"] An array of case-sensitive strings that identifies who is the audience of the issued ID token. It is used to populate the aud claim in the ID token in combination with the client_id that is always included.
delete_tokens_on_logout no Enables or disables the deletion of access tokens and refresh tokens when the end-session endpoint is called. It is advised to use this when using the PKCE client authentication method.
post_logout_redirect_url no "https://redirect.example.com" This is the primary or default post-logout URL. The user is redirected to this URL if no other URL is specified in the end-session request.
additional_post_logout_redirect_urls no ["https://redirect.example.com", "https://postlogout.example.com"] An array of additional post-logout redirect URLs. This array contains the potential URLs that could be specified to be redirected to as part of the end-session request.
front_channel_logout_url no "https://front-channel-logout.example.com" A URL that is reachable on the relying party that invalidates the session. This is triggered after a successful logout via the end-session page.
id_token_encryption_enabled no Enabling or disabling ID token encryption
id_token_encryption_method depends "A256GCM" Encryption method used to encrypt the ID token. Required when id_token_encryption_enabled is true. Allowed values: A128GCM, A192GCM, A256GCM, A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
id_token_jwks_uri depends "https://example.com/jwks.json" JSON Web Key Set (JWKS) endpoint that contains the JSON Web Keys (JWK) used to encrypt the ID token. Required when id_token_encryption_enabled is true.

Example request:

POST /api/v1/configuration/web-clients HTTP/1.1
Host: onegini.example.com
Content-Type: application/json
{
  "name": "web client 1",
  "client_id": "365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B",
  "client_secret": "919724DAE12CAB220407C34EDAE8438CEAE965CD0F8AD033A743C1F4BB4B15C4",
  "client_authentication_method": "CLIENT_SECRET_BASIC",
  "grant_types": [
    "AUTHORIZATION_CODE",
    "CLIENT_CREDENTIALS"
  ],
  "access_token_format": "JWT",
  "redirect_url": "https://example.com/redirect",
  "additional_redirect_urls": [
    "https://example.org/redirect",
    "https://example.net/redirect"
  ],
  "access_grant_expires_in": 30,
  "access_token_expires_in": 3600,
  "refresh_token_enabled": true,
  "simultaneous_sessions_allowed": true,
  "max_simultaneous_sessions": 25,
  "default_scopes": [
    "address",
    "email"
  ],
  "additional_scopes": [
    "phone",
    "openid"
  ],
  "identity_provider_id": "123-123",
  "consent_disabled": true,
  "legacy_group_permissions_enabled": true,
  "open_id_connect": {
    "expiration_time_seconds": 3600,
    "post_logout_redirect_url": "https://redirect.example.com"
  }
}

Example success response:

HTTP/1.1 201 CREATED
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Location: /api/v1/configuration/web-clients/365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B

The success response body is empty.

In the event of an error, one of the generic error codes is returned.

Read web client

This returns one web client.

  • Endpoint: /api/v1/configuration/web-clients/{client_id}
  • Method: GET

Path parameters:

Param Required Description
client_id yes Unique identifier of the web client.

Example request:

GET /api/v1/configuration/web-clients/365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B HTTP/1.1
Host: onegini.example.com

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   "name":"web client 1",
   "client_id":"365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B",
   "client_authentication_method": "CLIENT_SECRET_BASIC",
   "grant_types":[
      "AUTHORIZATION_CODE"
   ],
   "access_token_format":"JWT",
   "redirect_url":"https://example.com/redirect",
   "additional_redirect_urls":[
      "https://example.org/redirect",
      "https://example.net/redirect"
   ],
   "access_grant_expires_in":30,
   "access_token_expires_in":3600,
   "additional_audiences":[],
   "refresh_token_enabled":true,
   "simultaneous_sessions_allowed":true,
   "default_scopes":[
      "address",
      "email"
   ],
   "additional_scopes":[
      "phone"
   ],
   "identity_provider_id":"123-123",
   "additional_identity_provider_ids":["123-124", "123-125"],
   "template_set":"template1",
   "consent_disabled":true,
  "legacy_group_permissions_enabled": true
}

Update web client

Some fields can be updated after creating a web client.

  • Endpoint: /api/v1/configuration/web-clients/{client_id}
  • Method: PATCH

Path parameters:

Param Required Description
client_id yes Unique identifier of the web client

JSON body parameters:

Only the fields that are sent in the request are changed.

Param Required Example Description
name no "My web portal" Client name
client_authentication_method no "CLIENT_SECRET_BASIC" The authentication method that must be used for this client. Allowed values: CLIENT_SECRET_BASIC, PKCE, PRIVATE_KEY_JWT and PUBLIC.
client_secret no "AF33E2BF29C54A4639AB…" Client secret (not returned on GET)
hashed_client_secret no "$bcrypt$c=12$T/jBeKR…" A hashed version of the secret using the PHC format (not returned on GET). For more information, see the web client migration page.
public_jwk depends EC or RAS public key Plain public key for private key JWT authentication in the Elliptic Curve (min P-256) or RSA (min 2048, max 4096 key length) x509 format. The the OneWelcome Identity Platform favours jwks_uri, if provided, over statically defined JWK.
jwks_uri depends "https://authorization-server/jwks" URI of the JWKS endpoint with public keys for private key JWT authentication.
grant_types no ["CLIENT_CREDENTIALS"] Set of grant types. Allowed values: AUTHORIZATION_CODE, CLIENT_CREDENTIALS, PASSWORD, IMPLICIT, and DEVICE_CODE. When client_authentication_method is PKCE, the only allowed value is AUTHORIZATION_CODE.
access_token_format no "OPAQUE" Format of the access token. Allowed values: OPAQUE (random string), JWT (JSON Web Token). The JWT access token contains the user identifier for the AUTHORIZATION_CODE grant type.
redirect_url no "https://example.com/redirect" A URL to which the browser is redirected after successfully obtaining an access grant. Used with the AUTHORIZATION_CODE grant type.
additional_redirect_urls no ["https://example.org/redirect"] Additional URLs that the user can be redirected to after successfully obtaining an access grant.
access_grant_expires_in no 30 The number of seconds that an access grant is valid. Used with the AUTHORIZATION_CODE grant type.
access_token_expires_in no 3600 The number of seconds that an access token is valid. Used with grant types AUTHORIZATION_CODE, CLIENT_CREDENTIALS.
resource_gateway_ids no ["resource_gateway_1"] An array with client_ids of existing clients that act as a resource gateway. It is used to populate the aud claim in a JWT access token.
additional_audiences no ["aud2", "https://example.com"] An array of case-sensitive strings that identifies the audience of the issued access token other than the resource gateways. It is used to populate the aud claim in a JWT access token.
refresh_token_enabled no true Issue refresh tokens
refresh_token_expires_in no 7200 The number of seconds that a refresh token is valid.
max_refresh_token_validity no 86400 The overall refresh token lifetime starting from the initial refresh token creation. This setting ensures that a stolen refresh token cannot be used indefinitely.
simultaneous_sessions_allowed no true Allow users to establish multiple sessions at the same time
max_simultaneous_sessions no 25 Limits the number of sessions when simultaneous sessions are allowed. Value must be between two and 25 (inclusive). Defaults to 25 when omitted and simultaneous_sessions_allowed is true.
default_scopes no ["profile"] Default scopes are the scopes that are automatically assigned if a client does not request any scopes. If you want an authorization request to fail when no scopes are requested, leave this empty.
additional_scopes no ["address", "email"] Additional scopes that can be requested by a client during an authorization request. The default scopes can also be requested by a client during the authorization request.
identity_provider_id no "123-123" The identifier of an existing identity provider that you want to be the primary or default for this client.
additional_identity_provider_ids no ["123-124", "123-125"] Identifiers of additional existing identity providers that are able to be specified in the request.
template_set no "template1" Identifier of an existing template set
consent_disabled no false When consent is skipped, the user is not asked for consent in the authorization flow
open_id_connect no See table below JSON object for OpenID Connect configuration. Required when openid is added to default_scopes or additional_scopes.
legacy_group_permissions_enabled no false By default, the latest version of the DABP report is returned in claims. Set this flag value to true to use legacy version 1 of this report.
web_hook_ids no [“customize-token-webhook”] Set of integrated web hook IDs.

The following parameters are a part of the open_id_connect object.

Param Required Example Description
expiration_time_seconds depends 3600 The number of seconds that an ID token is valid. It is used to calculate the exp expiration date claim in the ID token. Required when openid is added to default_scopes or additional_scopes.
additional_audiences no ["https://resource.example.com"] An array of case-sensitive strings that identifies who is the audience of the issued ID token. It is used to populate the aud claim in the ID token in combination with the client_id that is always included.
delete_tokens_on_logout no Enables or disables the deletion of access tokens and refresh tokens when the end-session endpoint is called. It is advised to use this when using the client authentication method PKCE.
post_logout_redirect_url no "https://redirect.example.com" This is the primary or default post-logout URL. The user is redirected to this URL if no other URL is specified in the end-session request.
additional_post_logout_redirect_urls no ["https://redirect.example.com", "https://postlogout.example.com"] An array of additional post-logout redirect URLs. This array contains the potential URLs that could be specified to be redirected to as part of the end-session request.
front_channel_logout_url no "https://front-channel-logout.example.com" A URL reachable on the relying party that invalidates the session. This is triggered after a successful logout via the end-session page.
id_token_encryption_enabled no Enabling or disabling ID token encryption
id_token_encryption_method depends "A256GCM" Encryption method used to encrypt the ID token. Required when id_token_encryption_enabled is changed to true. Allowed values: A128GCM, A192GCM, A256GCM, A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
id_token_jwks_uri depends "https://example.com/jwks.json" JSON Web Key Set (JWKS) endpoint that contains the JSON Web Keys (JWK) used to encrypt the ID token. Required when id_token_encryption_enabled is changed to true.

Example request:

PATCH /api/v1/configuration/web-clients/F167433E63CE8BD874D7 HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

{
  "scopes": ["address", "email", "phone"]
}

Example success response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

The success response body is empty.

In the event of an error, one of the generic error codes is returned.

Delete web client

This removes a web client.

  • Endpoint: /api/v1/configuration/web-clients/{client_id}
  • Method: DELETE

Path parameters:

Param Required Description
client_id yes Unique identifier of the web client

Example request:

DELETE /api/v1/configuration/web-clients/365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B HTTP/1.1
Host: onegini.example.com

Example success response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

Error codes

One of the following responses is returned, containing a JSON object with an error code, a message, and details about the error.

HTTP status Error code Message
400 invalid_request One or more parameters is missing or incorrect. The details contain the missing or incorrect parameters.
401 unauthorized Provide valid credentials to get access to the API
403 forbidden Operation is not allowed for the current user
404 not_found Web Client configuration cannot be found for this client_id
409 conflict The Client ID already exists

Limitations

Some fields are references to other parts in the configuration of the OneWelcome Identity Platform. This API can only refer to existing identifiers for the following:

  • Resource gateways
  • Identity providers (both primary and additional)
  • Scopes (both default and additional)
  • Template set

When an unknown identifier is passed, this API returns an HTTP status code 400 with the invalid_request error code.

On this page