Skip to main content

Access Control (REST) API - OIDC Clients

This section includes REST APIs for working with Access Control OIDC (OpenID Connect) Client tasks.

Get All OIDC Clients - GET /OIDCClients

Get details of all OIDC (OpenID Connect) clients.

Notice

The ‘Manage Clients’ permission is required to execute this API.

Usage:

  1. GET /OIDCClients and get details of all OIDC clients

  2. PUT /OIDCClients/{id} and update OIDC client details

URL

/cxrestapi/auth/OIDCClients

Method:

GET

Media Type (header):

Authorization: Bearer <access token value>

Accept: application/json;v=1.0

Parameters

None

Success Response:

Code: 200 Success

Error Response:

Code: 401 Unauthorized

Code: 403 Forbidden

Sample Response:

{
  "id": 4,
  "updateAccessTokenClaimsOnRefresh": false,
  "accessTokenType": 0,
  "includeJwtId": false,
  "alwaysIncludeUserClaimsInIdToken": false,
  "clientId": "resource_owner_sast_client",
  "clientName": "Cx Sast Resource Owner Client",
  "allowOfflineAccess": true,
  "clientSecrets": [
    "7PXDgKOvDnF+YLUEpZ02brsgAAfeyld6n2D/qd4UunM="
  ],
  "allowedGrantTypes": [
    "password"
  ],
  "allowedScopes": [
    "sast_api",
    "access_control_api",
    "offline_access"
  ],
  "enabled": true,
  "requireClientSecret": true,
  "redirectUris": [],
  "postLogoutRedirectUris": [],
  "frontChannelLogoutUri": null,
  "frontChannelLogoutSessionRequired": true,
  "backChannelLogoutUri": null,
  "backChannelLogoutSessionRequired": true,
  "identityTokenLifetime": 300,
  "accessTokenLifetime": 3600,
  "authorizationCodeLifetime": 300,
  "absoluteRefreshTokenLifetime": 2592000,
  "slidingRefreshTokenLifetime": 1296000,
  "refreshTokenUsage": 1,
  "refreshTokenExpiration": 1,
  "allowedCorsOrigins": [],
  "allowAccessTokensViaBrowser": false,
  "claims": [],
  "clientClaimsPrefix": ""
}

Notes:

Retrieves details of all OIDC clients. If the request fails, it returns an error response.

Create New OIDC Client - POST /OIDCClients

Create a new OIDC client.

Notice

The ‘Manage Clients’ permission is required to execute this API.

Usage:

  1. POST /OIDCClients and create a new OIDC client

  2. GET /OIDCClients/{id} and get details of an OIDC client

URL

/cxrestapi/auth/OIDCClients

Method:

POST

Media Type (header):

Authorization: Bearer <access token value>

Content-Type: application/json;v=1.0

Parameters

createClientViewModel=[body]: Specifies the OIDC client details

updateAccessTokenClaimsOnRefresh=[boolean] - Whether the access token should be updated on a refresh token request (true/false)

accessTokenType=[integer] - Whether the access token is a reference token or a self-contained JWT token. Default=Jwt

includeJwtId=[boolean] - Whether JWT access tokens should have an embedded unique Id (true/false)

alwaysIncludeUserClaimsInIdToken=[boolean] - When requesting both an Id token and access token, should the user claims always be added to the Id token instead of requiring the client to use the userinfo endpoint (true/false). Default=false

clientId=[string] – Client Id

clientName=[string] – Client display name

allowOfflineAccess=[boolean] - Whether this client can request refresh tokens (true/false)

clientSecrets=[string] - Credentials to access the token endpoint

allowedGrantTypes=[string] - Grant types the client is allowed to use. Grant types are a way to specify how a client wants to interact with IdentityServer. Allowed values: "client_credentials","implicit","authorization_code","hybrid", “password”

allowedScopes=[boolean] - By default a client has no access to any resources. Specify the allowed resources by adding the corresponding scopes names

enabled=[string] – Whether the client is enabled (true/false). Default=true

requireClientSecret=[boolean] - Whether this client needs a secret to request tokens from the token endpoint (true/false). Default=true

redirectUris=[string] - Specifies the allowed URIs to return tokens or authorization codes to. This is a required field for “implict” and “authorization_code” grant types.

postLogoutRedirectUris=[string] - Allowed URIs to redirect to after logout

frontChannelLogoutUri=[string] - Logout URI at client for HTTP based front-channel logout

frontChannelLogoutSessionRequired=[string] - Whether the user’s session Id should be sent to the FrontChannelLogoutUri (true/false). Default=true

backChannelLogoutUri=[string] - Logout URI at client for HTTP based back-channel logout

backChannelLogoutSessionRequired=[string] - Whether the user’s session Id should be sent in the request to the BackChannelLogoutUri (true/false). Default=true

identityTokenLifetime=[integer] – Timeframe to identity token (in seconds). Default: 300 seconds/5 minutes

accessTokenLifetime=[integer] - Timeframe of access token (in seconds). Default: 3600 seconds/1 hour)

authorizationCodeLifetime=[integer] Timeframe of authorization code (in seconds). Default: 300 seconds/5 minutes)

absoluteRefreshTokenLifetime=[integer] - Maximum timeframe of a refresh token (in seconds). Default: 2592000 seconds/30 days

slidingRefreshTokenLifetime=[integer] - Sliding timeframe of a refresh token (in seconds). Default=1296000 seconds/15 days

refreshTokenUsage=[integer] – Refresh token usage: ReUse = 0, the refresh token handle will stay the same when refreshing tokens, OneTime = 1, the refresh token handle will be updated when refreshing tokens

refreshTokenExpiration=[integer] – Refresh token expiration: Absolute = 0, the refresh token will expire on a fixed point in time (specified by the AbsoluteRefreshTokenLifetime), Sliding = 1, when refreshing the token, the lifetime of the refresh token will be renewed(by the amount specified in SlidingRefreshTokenLifetime). The timeframe will not exceed AbsoluteRefreshTokenLifetime

allowedCorsOrigins=[string] - If specified, will be used by the default CORS policy service implementations (In-Memory and EF) to build a CORS policy for JavaScript clients. This is a required field for “implict” grant type

allowAccessTokensViaBrowser=[string] - Whether this client is allowed to receive access tokens via the browser. This is useful to harden flows that allow multiple response types (e.g., by disallowing a hybrid flow client that is supposed to use code id_token to add the token response type and thus leaking the token to the browser (true/false).

claims=[uniqueItems]: type=[string], value=[string] - Allows settings claims for the client (true/false ). This will be included in the access token.

clientClaimsPrefix=[string] - The prefix of client claim types.

Notice

In order to retrieve additional information about the available endpoint-scopes, refer to: ‘http://<server-name/ip>:<port>/cxrestapi/auth/identity/.well-known/openid-configuration’ or click on the discovery document link in your swagger instance.

Success Response:

Code: 201 Success (returns location of the created OIDC client in the response header)

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Sample Response:

no content

Notes:

Returns the location of the created OIDC client in the response header. If the request fails, it returns an error response.

Get OIDC Client by Id - GET /OIDCClients/{id}

Gets details of an OIDC client according to OIDC client Id.

Notice

The ‘Manage Clients’ permission is required to execute this API.

Usage:

  1. POST /OIDCClients and create a new OIDC client

  2. GET /OIDCClients/{id} and get details of an OIDC client

URL

/cxrestapi/auth/OIDCClients/{id}

Method:

GET

Media Type (header):

Authorization: Bearer <access token value>

Accept: application/json;v=1.0

Parameters

Required:

id=[integer] - Unique Id of the OIDC client

Success Response:

Code: 200 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not Found

Sample Response:

{
  "id": 4,
  "updateAccessTokenClaimsOnRefresh": false,
  "accessTokenType": 0,
  "includeJwtId": false,
  "alwaysIncludeUserClaimsInIdToken": false,
  "clientId": "resource_owner_sast_client",
  "clientName": "Cx Sast Resource Owner Client",
  "allowOfflineAccess": true,
  "clientSecrets": [
    "7PXDgKOvDnF+YLUEpZ02brsgAAfeyld6n2D/qd4UunM="
  ],
  "allowedGrantTypes": [
    "password"
  ],
  "allowedScopes": [
    "sast_api",
    "access_control_api",
    "offline_access"
  ],
  "enabled": true,
  "requireClientSecret": true,
  "redirectUris": [],
  "postLogoutRedirectUris": [],
  "frontChannelLogoutUri": null,
  "frontChannelLogoutSessionRequired": true,
  "backChannelLogoutUri": null,
  "backChannelLogoutSessionRequired": true,
  "identityTokenLifetime": 300,
  "accessTokenLifetime": 3600,
  "authorizationCodeLifetime": 300,
  "absoluteRefreshTokenLifetime": 2592000,
  "slidingRefreshTokenLifetime": 1296000,
  "refreshTokenUsage": 1,
  "refreshTokenExpiration": 1,
  "allowedCorsOrigins": [],
  "allowAccessTokensViaBrowser": false,
  "claims": [],
  "clientClaimsPrefix": ""
}

Notes:

Retrieves details of the OIDC client according to OIDC client Id. If the request fails, it returns an error response.

Update an OIDC Client - PUT /OIDCClients/{id}

Update the OIDC client details according to OIDC Client Id.

Notice

The ‘Manage Clients’ permission is required to execute this API.

Usage:

  1. GET /OIDCClients/{id} and get details of an OIDC client

  2. PUT /OIDCClients/{id} and update the OIDC client details

URL

/cxrestapi/auth/OIDCClients/{id}

Method:

PUT

Media Type (header):

Authorization: Bearer <access token value>

Content-Type: application/json;v=1.0

Parameters

Required:

id=[integer] - Unique Id of the OIDC client

updateClientModel=[body]: Specifies the OIDC client details to update

clientId=[string] – Client Id

clientName=[string] – Client display name

allowOfflineAccess=[boolean] - Whether this client can request refresh tokens (true, false)

clientSecrets=[string] - Credentials to access the token endpoint

allowedGrantTypes=[string] - Grant types the client is allowed to use ("client_credentials","implicit","authorization_code","hybrid", "password")

allowedScopes=[string] - Scopes the client is allowed to use (access_control_api)

enabled=[boolean] - Whether client is enabled (true, false)

requireClientSecret=[boolean] - Whether this client needs a secret to request tokens from the token endpoint (true, false)

redirectUris=[string] - Allowed URIs to return tokens or authorization codes to. This is a required field for “implict” and “authorization_code” grant types

postLogoutRedirectUris=[string] - Allowed URIs to redirect to after logout

frontChannelLogoutUri=[string] - Logout URI at client for HTTP based front-channel logout.

frontChannelLogoutSessionRequired=[boolean] - Whether the user’s session Id should be sent to the FrontChannelLogoutUri (true, false)

backChannelLogoutUri=[string] - Logout URI at client for HTTP based back-channel logout.

backChannelLogoutSessionRequired=[boolean] – Whether the user’s session Id should be sent in the request to the BackChannelLogoutUri (true, false)

identityTokenLifetime=[integer] - Timeframe to identity token (in seconds). Default: 300 seconds/5 minutes

accessTokenLifetime=[integer] – Timeframe of access token (in seconds). Default: 3600 seconds/1 hour

authorizationCodeLifetime=[integer] - Timeframe of authorization code (in seconds). Default: 300 seconds/5 minutes

absoluteRefreshTokenLifetime=[integer] - Maximum timeframe of a refresh token (in seconds). Default: 2592000 seconds/30 days

slidingRefreshTokenLifetime=[integer] - Sliding timeframe of a refresh token (in seconds). Defaults: 1296000 seconds/15 days

refreshTokenUsage=[integer] – Refresh token usage: ReUse = 0, the refresh token handle will stay the same when refreshing tokens, OneTime = 1, the refresh token handle will be updated when refreshing tokens

refreshTokenExpiration=[integer] – Refresh token expiration: Absolute = 0, the refresh token will expire on a fixed point in time (specified by the AbsoluteRefreshTokenLifetime), Sliding = 1, when refreshing the token, the lifetime of the refresh token will be renewed(by the amount specified in SlidingRefreshTokenLifetime). The timeframe will not exceed AbsoluteRefreshTokenLifetime

allowedCorsOrigins=[string] - If specified, will be used by the default CORS policy service implementations (In-Memory and EF) to build a CORS policy for JavaScript clients. This is a required field for “implict” grant type

allowAccessTokensViaBrowser=[string] - Whether this client is allowed to receive access tokens via the browser. This is useful to harden flows that allow multiple response types (e.g., by disallowing a hybrid flow client that is supposed to use code id_token to add the token response type and thus leaking the token to the browser (true/false).

claims=[uniqueItems]: type=[string], value=[string] - Allows settings claims for the client (true/false ). This will be included in the access token.

clientClaimsPrefix=[string] - The prefix of client claim types.

Success Response:

Code: 204 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not found

Sample Response:

no content

Notes:

Updates the OIDC client details according to OIDC client Id and defined parameters. Once the request is successful, it does not return any content. If the request fails, it returns an error response.

Delete an OIDC Client - DELETE /OIDCClients/{id}

Delete an OIDC client according to OIDC Client Id.

Notice

The ‘Manage Clients’ permission is required to execute this API.

Usage:

  1. GET /OIDCClients and get details of all OIDC clients

  2. DELETE /OIDCClients/{id} and delete the OIDC client

URL

/cxrestapi/auth/OIDCClients/{id}

Method:

DELETE

Media Type (header):

Authorization: Bearer <access token value>

Content-Type: application/json;v=1.0

Parameters

Required:

id=[integer] - Unique Id of the OIDC client

Success Response:

Code: 204 Returns no content

Error Response:

Code: 400 Returns error messages

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Client not found

Sample Response:

no content

Notes:

Deletes the OIDC client details according to OIDC client Id. Once the request is successful, it does not return any content. If the request fails, it returns an error response.

In this section: