Definition

1. Definition

Use the information in the following table to configure settings that dictate the behavior of how resources are accessed. This method is similar to the IBM Security Verify Access Definition, but with more configuration settings that are introduced in IBM Security Verify Access OIDC Provider.

NameDescriptionValid ValueMandatoryDefault
idDefinition IDstringNo (Required for DCR flows)
nameDefinition NamestringNo (Required for DCR flows)
grant_typesSupported grant types.string[]Yes
access_policy_idAccess Policy Rule ID.stringNo
pre_mappingrule_idPre-Token mapping rule ID.stringNo
post_mappingrule_idPost-Token mapping rule ID.stringNo
ropc_mappingrule_idROPC-mapping rule ID.stringNo
base_urlBase url of the endpoints.valid url string, example: https://www.idp.com/isvaopYes
mtls_base_urlBase url of the MTLS endpoints.valid url string, example: https://www.idp-mtls.com/isvaopNo
mtls_certificate_header_nameHTTP header name that contains MTLS certificate.string, example: X-Client-CertificateNo
token_settingsToken Settings
featuresFeature Flags
backchannel_settingsBackchannel Settings
attribute_mapAttribute mapping to resolve claims.map of string -> string
metadataname-value pair to override metadata informationmap of string -> any
request_objectJWT-Secured Authorization Request Settings
dpop_max_lifetimeLifetime of DPoP proof JWT in seconds.integerNo

1.1. Token Settings

NameDescriptionValid ValueMandatoryDefault
issuerOP's issuer URI.valid url stringYes
signing_algSigning algorithm for ID token generated.stringYes
signing_keystoreSigning keystore name.stringYes
signing_keylabelSigning key label.stringYes
encryption_algKey encryption algorithm for ID token generated.stringNo
encryption_encContent encryption algorithm for ID token generated.stringNo
authorization_code_lifetimeLifetime of authorization code.integerNo300s
access_token_lifetimeLifetime of access token.integerNo7200s
id_token_lifetimeLifetime of id_token.integerNo3600s
refresh_token_lifetimeLifetime of refresh token.integerNo64800s

1.2. Features Flags

NameDescriptionValid ValueMandatoryDefault
enable_fault_toleranceEnable multiple refresh tokens for fault tolerance.BooleanNoNo
consent_promptPrompt for consent vs auto-consent.ALWAYS_PROMPT, NEVER_PROMPT, PROMPT_ONCE_AND_REMEMBERNoALWAYS_PROMPT
fapi_compliantWhether to enforce all the FAPI checks.BooleanNoNo
enforce_parAccept only authorized request using push authorize.BooleanNoNo
prefer_claims_at_userinfoThis is introduced to address this requirement (https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.4). When it is set to true and an OAuth/OIDC flow generates access token, instead of returning the requested claims in the id_token, the claims are returned only at /userinfo endpoint; unless such claims are essential to be returned in id_token.BooleanNoNo

1.3. Backchannel Settings

These settings are related to Client-Initiated Backchannel Authentication (CIBA).

NameDescriptionValid ValueMandatoryDefault
default_expiryThe default CIBA session lifetime in seconds.integerNo900s
maximum_expiryMaximum CIBA session lifetime in seconds.integerNo1800s
polling_intervalPolling interval value that is communicated to the relying party.integerNo5s
notifyuser_mappingrule_idMapping rule ID that is run when the user is notified.stringNonotifyuser
checkstatus_mappingrule_idMapping rule ID that is run when the authentication status is checked.stringNocheckstatus
user_code_supportWhether this CIBA implementation supports user_code. This information is published in .well-known endpoint.BooleanNofalse

1.4. JWT Secured Authorization Request Settings

These settings are related to JWT-Secured Authorization Request(JAR).

NameDescriptionValid ValueMandatoryDefault
lifetimeThe maximum lifetime of the incoming request-JWT in seconds.integerNo
require_expiryBoolean flag to check if the request-JWT contains a exp claimBooleanNofalse
only_request_object_paramsBoolean flag to enforce the request-JWT to contain all the request parameters.BooleanNofalse
enforce_single_usageBoolean flag to enforce single use of a request-JWT.BooleanNofalse

1.5. Device flow settings

These settings are Device Authorization Grant.

NameDescriptionValid ValueMandatoryDefault
device_flow_polling_interval_in_secsPolling interval in secondsintegerNo5
device_flow_codelifetime_in_secsValidity of the device code in secondsintegerNo300
device_flow_usercode_lengthLength of the user code. Has to be set of a value greater than 6integerNo6
device_flow_usercode_charsetCharacter set for user code, should be characters that are unique and greater that the code lengthstringNoABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789
enforce_clientauth_device_authorizeTo enforce client authentication at the device authorization endpointbooleanNotrue

definition:
  id: 1                                                     # Definition ID
  name: OIDC Definition                                     # Definition Name
  grant_types:                                              # Supported grant types.
    - authorization_code
    - implicit
    - password
    - client_credentials
    - 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
  access_policy_id: 1                                       # Access Policy Rule ID.
  pre_mappingrule_id: isvaop_pretoken                       # Pre-Token mapping rule ID.
  post_mappingrule_id: isvaop_posttoken                     # Post-Token mapping rule ID.
  ropc_mappingrule_id: ropc                                 # ROPC mapping rule ID.
  base_url: https://isvaop.ibm.com:445                      # Base url of the endpoints.
  mtls_base_url: https://isvaop.ibm.com:445                 # Base url of the MTLS endpoints.
  mtls_certificate_header_name: x-client-certificate        # HTTP header name that contains MTLS certificate.
  features:                                                 # Features Flags
    enable_fault_tolerance: false                           # Enable multiple refresh token for fault tolerance.
    consent_prompt: ALWAYS_PROMPT                           # Prompt for consent. ALWAYS_PROMPT, NEVER_PROMPT, PROMPT_ONCE_AND_REMEMBER
    fapi_compliant: false                                   # Whether to enforce all the FAPI checks.
    enforce_par: false                                      # Only accept authorize request using push authorize.
    prefer_claims_at_userinfo: true                         # This is introduced to address this requirement (https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.4). When it is set to true and an OAuth/OIDC flow generates access token, instead of returning the requested claims in the id_token, the claims are returned only at /userinfo endpoint; unless such claims are essential to be returned in id_token.
  token_settings:                                           # Token Settings
    issuer: https://isvaop.ibm.com                          # OP's issuer URI.
    signing_alg: PS512                                      # Signing algorithm for ID token generated.
    signing_keystore: rt_profile_keys                       # Signing keystore name.
    signing_keylabel: rsa256                                # Signing key label.
    encryption_alg: none                                    # Key encryption algorithm for ID token generated.
    encryption_enc: none                                    # Content encryption algorithm for ID token generated.
    authorization_code_lifetime: 300                        # Lifetime of authorization code.
    access_token_lifetime: 7200                             # Lifetime of access token.
    id_token_lifetime: 3600                                 # Lifetime of id_token.
    refresh_token_lifetime: 64800                           # Lifetime of refresh token.
  backchannel_settings:                                     # Backchannel Settings
    default_expiry: 900                                     # The default CIBA session lifetime in seconds. If not specified, it is set to 900 seconds.
    maximum_expiry: 1800                                    # Maximum CIBA session lifetime in seconds. If not specified, it is set to 1800 seconds.
    polling_interval: 5                                     # Polling interval value that will be communicated to the relying party. Default is 5 seconds.
    notifyuser_mappingrule_id: notifyuser                   # Mapping rule ID that will be executed when notifying the user. Default is `notifyuser`.
    checkstatus_mappingrule_id: checkstatus                 # Mapping rule ID that will be executed when checking authentication status. Default is `checkstatus`.
    user_code_support: false                                # Whether this CIBA implementation supports user_code. This information will be published in `.well-known` endpoint.
  attribute_map:                                            # Attribute mapping to resolve claims. also refer to attributesources.yml
    name: display_name
    age: age
    website: website
  metadata:                                                 # name-value pair to override metadata information
    claims_supported:
      - iss
      - name
      - displayName
  dpop_max_lifetime: 3600                                   # Lifetime of DPoP proof JWT. 
  request_object:
    lifetime: 3600                                          # Lifetime of the incoming JWT-Secured Authorization Request.
    require_expiry: true                                    # Boolean flag to check if the JWT-Secured Authorization Request contains a exp claim.
    only_request_object_params: false                       # Boolean flag to enforce the JWT-Secured Authorization Request to contain all the request parameters.
    enforce_single_usage: false                             # Boolean flag to enforce single use of a JWT-Secured Authorization Request.
  device_flow_settings:
    device_flow_polling_interval_in_secs: 8                 # Polling interval in seconds
    device_flow_codelifetime_in_sec: 200                    # Lifetime seconds for device_code
    device_flow_usercode_length: 7                          # User code length
    device_flow_usercode_charset: 'ABCDEF1234'              # User code character set
    enforce_clientauth_device_authorize: true               # Boolean flag to enforce client authentication at device authorization