Client Configuration

Clients

The clients directory represent IBM Security Verify Access static clients. Dynamic clients are retrieved directly from the runtime database.
It is designed to use the client metadata names that are defined by specification. So, whether it is a static or dynamic client, the metadata names are the same.

📘
Note
There may be information that does not match client metadata, this information can be represented by the extension section

The following table lists the top-level metadata that are supported:

Name	Data type	Description	Mandatory	Default
client_id	string	Client identifier.	Yes
client_secret	string	Client secret that is used for client authentication, and JWT signing and encryption. It is recommended to be an obfuscated string. The obfuscation key is read from the provider configuration secrets stanza.	Yes
client_name	string	Name of the client.	Yes
client_id_issued_at	timestamp	Timestamp (in seconds) from when the client is created.	No
enabled	boolean	Set to `true` to enable this client	Yes
grant_types	string array	Grant type that the client is allowed to use at the token endpoint.	Yes
response_types	string array	Response type that the client is allowed to use at the authorization endpoint.	Yes
redirect_uris	string array	Redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows.	Yes
request_uris	string array	Request URIs that are pre-registered by the Relying Party for use at the OIDC Provider.	Yes
scopes	string array	A list of scope values that the client can use when it requests access tokens.		No
jwks_uri	string	URL string that references the client's JSON Web Key (JWK) set document that contains the client's public keys.	No
id_token_signed_response_alg	string	JWS `alg` algorithm for signing the ID Token that is issued to the Client. Optional. If present it shall be always the same as the token_settings.signing_alg value set in provider.yml	No
id_token_encrypted_response_alg	string	JWE `alg` algorithm for encrypting the ID Token that is issued to the Client.	No
id_token_encrypted_response_enc	string	JWE `enc` algorithm for encrypting the ID Token that is issued to the Client.	No
userinfo_signed_response_alg	string	JWS `alg` algorithm for signing UserInfo Responses.	No
userinfo_encrypted_response_alg	string	JWE `alg` algorithm for encrypting UserInfo Responses.	No
userinfo_encrypted_response_enc	string	JWE `enc` algorithm for encrypting UserInfo Responses.	No
request_object_signing_alg	string	JWS `alg` algorithm that must be used for signing Request Objects sent to the OIDC Provider.	No
request_object_encryption_alg	string	JWE `alg` algorithm the Relying Party is declaring that it may use for encrypting Request Objects sent to the OIDC Provider.	No
request_object_encryption_enc	string	JWE `enc` algorithm the Relying Party is declaring that it might use for encrypting Request Objects sent to the OIDC Provider.	No
token_endpoint_auth_method	string	Requested authentication method for the backend endpoints (token, introspect, revoke).	Yes
token_endpoint_auth_signing_alg	string	JWS `alg` algorithm that must be used for signing the JWT that is used to authenticate the Client at the Token Endpoint for the `private_key_jwt` authentication methods.	No
token_endpoint_auth_single_use_jti	Boolean	When set to `true` and client assertion is used as the method to perform client authentication, the client assertion cannot be reused.	No
tls_client_auth_subject_dn	string	Expected subject distinguished name of the certificate that the OAuth client uses in mutual-TLS authentication.	No
tls_client_auth_san_dns	string	Expected DNS name SAN entry in the certificate that the OAuth client uses in mutual-TLS authentication.	No
tls_client_auth_san_email	string	Expected RFC822 name SAN entry in the certificate that the OAuth client uses in mutual-TLS authentication.	No
tls_client_auth_san_ip	string	Expected IP address SAN entry in the certificate that the OAuth client uses in mutual-TLS authentication.	No
tls_client_auth_san_uri	string	Expected URI SAN entry in the certificate that the OAuth client uses in mutual-TLS authentication.	No
tls_client_certificate_bound_access_tokens	Boolean	Indicates the client's intention to use mutual-TLS client certificate-bound access tokens. The default value is `false`.	No
require_pushed_authorization_requests	Boolean	Indicates the client's intention to enforce usage of push authorization request (PAR) to trigger authorize flow.	No
require_pkce	Boolean	Indicates the client's intention to enforce usage of proof-key for code exchange.	No
backchannel_token_delivery_mode	string	Backchannel token delivery mode. One of the following values: `poll` or `ping`	No
backchannel_user_code_parameter	boolean	Boolean value specifying whether the Client supports the user_code parameter. If omitted, the default value is `false`. This parameter only applies when definition.backchannel_settings.user_code_support in provider.yml is set to `true`	No	`false`
backchannel_client_notification_endpoint	string	REQUIRED if the token delivery mode is set to `ping`. This is the endpoint to which the ISVA OP will post a notification after a successful or failed end-user authentication. It MUST be an HTTPS URL.	No
dpop_bound_access_tokens	boolean	Boolean value specifying whether to adds the `jkt` claim to the `cnf` claim in the access token.	No
dpop_signing_alg	string	Expected JWS `alg` algorithm for signed the DPoP proof JWT. Optional.	No
dpop_single_use_jti	boolean	When set to `true` the DPoP proof JWT should contain a unique identifier in the `jti` claim which cannot be re-used.	No
response_modes	string array	This parameter informs the authorization server of the allowed list of modes that the client expects for the authorization response .	No
token_exchange_settings	object	Token exchange configuration.
extension	object	Other information of the client that does not fit the above metadata.

The following table lists the token exchange configuration parameters:

Name	Data type	Description	Mandatory
client_groups	string array	The list of OpenID Connect client groups. Client groups is a way tagging clients. Tokens generated by a client can be used as the subject token for token exchange with another client using the same tag. If this list is empty, any client can use the tokens generated from this client as the subject token for token exchange.	No
supported_subject_token_types	string array	This parameter indicates the list of subject token types supported for token exchange. A subject token represents the identity of the party on behalf of whom the token is being requested.	No
supported_requested_token_types	string array	This parameter indicates the list of requested token types supported for token exchange.	No
supported_actor_token_types	string array	This parameter indicates the list of actor token types supported for token exchange. An actor token represents the identity of the party to whom the access rights of the issued token are being delegated.	No

The following nonexhaustive list of information goes to the extension:

For static client:

Name	Data type	Description	Mandatory
company_name	string	Company name that is associated with this Client.	No
company_url	string	Company URL that is associated with this Client.	No
email	string	Email address that is associated with this Client.	No
phone	string	Phone number that is associated with this Client.	No
contact_person	string	Contact person that is associated with this Client.	No
contact_type	string	Contact type that is associated with this Client.	No
otherInfo	string	Other information associated with this Client.	No
encryptKey	string	Key label of the signer key that is used to encrypt ID token.	No
encryptDB	string	Keystore of the signer key that is used to encrypt ID token.	No

For dynamic client:

Name	Data type	Description	Mandatory
contacts	string array	Email addresses of people responsible for the Client.	No
logo_uri	string	URL that references a logo for the Client application.	No
client_uri	string	URL of the home page of the Client.	No
policy_uri	string	URL that the Relying Party Client provides to the user to read about how the profile data is used.	No
tos_uri	string	URL that the Relying Party Client provides to the user to read about the Relying Party's terms of service.	No

client_id: clientTemplateWithComments                                                                       # Client identifier
client_secret: "OBF:U2FsdGVkX19iBhlwc53QkybjO6RjFHhSbz4VRudYHA="                                            # Client secret that is used for client authentication and/or JWT signing/encryption. `OBF:` indicates obfuscated string.
client_name: Client Template with Comments                                                                  # Name of the client.
client_id_issued_at: 1642399207                                                                             # Timestamp (in seconds) from when the client is created.
enabled: true                                                                                               # Set to `true` to enable this client
grant_types:                                                                                                # Grant type that the client is allowed to use at the token endpoint.
  - authorization_code
  - password
  - client_credentials
  - implicit
  - refresh_token
  - urn:openid:params:grant-type:ciba
  - urn:ietf:params:oauth:grant-type:token-exchange 
  - urn:ietf:params:oauth:grant-type:jwt-bearer
response_types:                                                                                             # Response type that the client is allowed to use at the authorization endpoint.
  - code id_token
  - code
  - code token
  - none
  - code token id_token
redirect_uris:                                                                                              # Redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows.
  - https://www.rp.com/redirect
request_uris:                                                                                               # Request URIs that are pre-registered by the Relying Party for use at the OIDC Provider.
  - https://www.rp.com/request/test.jwt
scopes:                                                                                                     # A list of scope values that the client can use when requesting access tokens.
  - cdr:registration
  - openid
  - profile
jwks_uri: https://www.rp.com/oidc/endpoint/default/jwks                                                     # URL string referencing the client's JSON Web Key (JWK) set document, that contains the client's public keys.
id_token_signed_response_alg: PS512                                                                         # JWS alg algorithm for signing the ID Token that is issued to the Client. Optional. If present it shall be always the same as the token_settings.signing_alg value set in provider.yml
id_token_encrypted_response_alg: none                                                                       # JWE alg algorithm for encrypting the ID Token that is issued to the Client. Optional, default is `none`.
id_token_encrypted_response_enc: none                                                                       # JWE enc algorithm for encrypting the ID Token that is issued to the Client. Optional, default is `none`.
userinfo_signed_response_alg: none                                                                          # JWS alg algorithm for signing UserInfo Responses.
userinfo_encrypted_response_alg: none                                                                       # JWE alg algorithm for encrypting UserInfo Responses. Optional, default is `none`.
userinfo_encrypted_response_enc: none                                                                       # JWE enc algorithm for encrypting UserInfo Responses. Optional, default is `none`.
request_object_signing_alg: PS256                                                                           # JWS alg algorithm that MUST be used for signing Request Objects sent to the OIDC Provider.
request_object_encryption_alg: none                                                                         # JWE alg algorithm the Relying Party is declaring that it may use for encrypting Request Objects sent to the OIDC Provider.
request_object_encryption_enc: none                                                                         # JWE enc algorithm the Relying Party is declaring that it might use for encrypting Request Objects sent to the OIDC Provider.
token_endpoint_auth_method: tls_client_auth                                                                 # Requested authentication method for the backend endpoints (token, introspect, revoke).
# token_endpoint_auth_signing_alg: RS384                                                                    # JWS alg algorithm that **must** be used for signing the JWT that is used to authenticate the Client at the Token Endpoint for the `private_key_jwt` authentication methods.
token_endpoint_auth_single_use_jti: false                                                                   # When set to `true` and client assertion is used as the method to perform client authentication, the client assertion cannot be reused.
tls_client_auth_subject_dn: CN=clientTemplateWithComments,OU=security,O=IBM,L=singapore,ST=singapore,C=SG   # Expected subject distinguished name of the certificate that the OAuth client uses in mutual-TLS authentication.
# tls_client_auth_san_dns: www.rp.com                                                                       # Expected DNS name SAN entry in the certificate that the OAuth client uses in mutual-TLS authentication.
# tls_client_auth_san_email: [email protected]                                                              # Expected RFC822 name SAN entry in the certificate that the OAuth client uses in mutual-TLS authentication.
# tls_client_auth_san_ip: 1.2.3.4                                                                           # Expected IP address SAN entry in the certificate that the OAuth client uses in mutual-TLS authentication.
# tls_client_auth_san_uri: https://www.rp.com                                                               # Expected URI SAN entry in the certificate that the OAuth client uses in mutual-TLS authentication.
tls_client_certificate_bound_access_tokens: false                                                           # Indicates the client's intention to use mutual-TLS client certificate-bound access tokens. The default value is `false`.
require_pushed_authorization_requests: false                                                                # Indicates the client's intention to enforce usage of push authorization request (PAR) to trigger authorize flow.
require_pkce: true                                                                                          # Indicates the client's intention to enforce usage of proof-key for code exchange.
backchannel_token_delivery_mode: poll                                                                       # Backchannel token delivery mode. One of the following values: `poll` or `ping`
backchannel_user_code_parameter: false                                                                      # Boolean value specifying whether the Client supports the user_code parameter. If omitted, the default value is `false`. This parameter only applies when definition.backchannel_settings.user_code_support in provider.yml is set to `true`
# backchannel_client_notification_endpoint: http://www.rp.com/auth/notification                             # REQUIRED if the token delivery mode is set to `ping`. This is the endpoint to which the ISVA OP will post a notification after a successful or failed end-user authentication. It MUST be an HTTPS URL.
dpop_bound_access_tokens: true                                                                              # Boolean value specifying whether to adds the `jkt` claim to the `cnf` claim in the access token.     
dpop_signing_alg: PS256                                                                                     # Expected JWS `alg` algorithm for signed the DPoP proof JWT.
dpop_single_use_jti: false                                                                                  # When set to `true` the DPoP proof JWT should contain a unique identifier in the `jti` claim which cannot be re-used.
response_modes:                                                                                             # This parameter informs the authorization server of the allowed list of response_modes that the client expects for the authorization response.
  - query
  - fragment
  - form_post
  - query.jwt
  - fragment.jwt
  - form_post.jwt
  - jwt 
token_exchange_settings: 
  client_groups:
    - benefits
    - insurance
  supported_subject_token_types:
    - urn:ietf:params:oauth:token-type:access_token
    - urn:ietf:params:oauth:token-type:refresh_token
    - urn:ietf:params:oauth:token-type:id_token
  supported_actor_token_types:
    - urn:ietf:params:oauth:token-type:access_token
    - urn:ietf:params:oauth:token-type:refresh_token
    - urn:ietf:params:oauth:token-type:id_token
    - urn:x-oath:params:oauth:token-type:device-secret
  supported_requested_token_types: 
    - urn:ietf:params:oauth:token-type:access_token
    - urn:ietf:params:oauth:token-type:refresh_token
    - urn:ietf:params:oauth:token-type:id_token
extension:                                                                                                  # Other information of the client that does not fit the above metadata.
  email: [email protected]
  contact_type: ADMINISTRATOR
  company_name: IBM
  encryptDB: rt_encrypt
  encryptKey: rsa

Clients

📘Note

📘
Note