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:

NameData typeDescriptionMandatoryDefault
client_idstringClient identifier.Yes
client_secretstringClient 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_namestringName of the client.Yes
client_id_issued_attimestampTimestamp (in seconds) from when the client is created.No
enabledbooleanSet to true to enable this clientYes
grant_typesstring arrayGrant type that the client is allowed to use at the token endpoint.Yes
response_typesstring arrayResponse type that the client is allowed to use at the authorization endpoint.Yes
redirect_urisstring arrayRedirection URI strings for use in redirect-based flows such as the authorization code and implicit flows.Yes
request_urisstring arrayRequest URIs that are pre-registered by the Relying Party for use at the OIDC Provider.Yes
scopesstring arrayA list of scope values that the client can use when it requests access tokens.No
jwks_uristringURL string that references the client's JSON Web Key (JWK) set document that contains the client's public keys.No
id_token_signed_response_algstringJWS 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.ymlNo
id_token_encrypted_response_algstringJWE alg algorithm for encrypting the ID Token that is issued to the Client.No
id_token_encrypted_response_encstringJWE enc algorithm for encrypting the ID Token that is issued to the Client.No
userinfo_signed_response_algstringJWS alg algorithm for signing UserInfo Responses.No
userinfo_encrypted_response_algstringJWE alg algorithm for encrypting UserInfo Responses.No
userinfo_encrypted_response_encstringJWE enc algorithm for encrypting UserInfo Responses.No
request_object_signing_algstringJWS alg algorithm that must be used for signing Request Objects sent to the OIDC Provider.No
request_object_encryption_algstringJWE alg algorithm the Relying Party is declaring that it may use for encrypting Request Objects sent to the OIDC Provider.No
request_object_encryption_encstringJWE enc algorithm the Relying Party is declaring that it might use for encrypting Request Objects sent to the OIDC Provider.No
token_endpoint_auth_methodstringRequested authentication method for the backend endpoints (token, introspect, revoke).Yes
token_endpoint_auth_signing_algstringJWS 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_jtiBooleanWhen 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_dnstringExpected subject distinguished name of the certificate that the OAuth client uses in mutual-TLS authentication.No
tls_client_auth_san_dnsstringExpected DNS name SAN entry in the certificate that the OAuth client uses in mutual-TLS authentication.No
tls_client_auth_san_emailstringExpected RFC822 name SAN entry in the certificate that the OAuth client uses in mutual-TLS authentication.No
tls_client_auth_san_ipstringExpected IP address SAN entry in the certificate that the OAuth client uses in mutual-TLS authentication.No
tls_client_auth_san_uristringExpected URI SAN entry in the certificate that the OAuth client uses in mutual-TLS authentication.No
tls_client_certificate_bound_access_tokensBooleanIndicates the client's intention to use mutual-TLS client certificate-bound access tokens. The default value is false.No
require_pushed_authorization_requestsBooleanIndicates the client's intention to enforce usage of push authorization request (PAR) to trigger authorize flow.No
require_pkceBooleanIndicates the client's intention to enforce usage of proof-key for code exchange.No
backchannel_token_delivery_modestringBackchannel token delivery mode. One of the following values: poll or pingNo
backchannel_user_code_parameterbooleanBoolean 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 trueNofalse
backchannel_client_notification_endpointstringREQUIRED 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_tokensbooleanBoolean value specifying whether to adds the jkt claim to the cnf claim in the access token.No
dpop_signing_algstringExpected JWS alg algorithm for signed the DPoP proof JWT. Optional.No
dpop_single_use_jtibooleanWhen set to true the DPoP proof JWT should contain a unique identifier in the jti claim which cannot be re-used.No
response_modesstring arrayThis parameter informs the authorization server of the allowed list of modes that the client expects for the authorization response .No
token_exchange_settingsobjectToken exchange configuration.
extensionobjectOther information of the client that does not fit the above metadata.

The following table lists the token exchange configuration parameters:

NameData typeDescriptionMandatoryDefault
client_groupsstring arrayThe 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_typesstring arrayThis 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_typesstring arrayThis parameter indicates the list of requested token types supported for token exchange.No
supported_actor_token_typesstring arrayThis 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:

NameData typeDescriptionMandatoryDefault
company_namestringCompany name that is associated with this Client.No
company_urlstringCompany URL that is associated with this Client.No
emailstringEmail address that is associated with this Client.No
phonestringPhone number that is associated with this Client.No
contact_personstringContact person that is associated with this Client.No
contact_typestringContact type that is associated with this Client.No
otherInfostringOther information associated with this Client.No
encryptKeystringKey label of the signer key that is used to encrypt ID token.No
encryptDBstringKeystore of the signer key that is used to encrypt ID token.No

For dynamic client:

NameData typeDescriptionMandatoryDefault
contactsstring arrayEmail addresses of people responsible for the Client.No
logo_uristringURL that references a logo for the Client application.No
client_uristringURL of the home page of the Client.No
policy_uristringURL that the Relying Party Client provides to the user to read about how the profile data is used.No
tos_uristringURL 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
  - urn:ietf:params:oauth:grant-type:device_code
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