Provider Configuration

Provider configuration

Every IBM Security Verify Access OIDC Provider container represents one OIDC Provider (OP), which in IBM Security Verify Access one API Protection Definition.

The following text describes the configuration that is needed in order for the provider to function properly.

The following example shows the provider configuration.

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: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/isvaop               # 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.
    enable_dynamic_registration: true                       # Enable dynamic registration endpoint.
    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    
jwks:                                                       # JSON Web Key Set (JWKS) Settings
  signing_keystore: rt_profile_keys                         # Keystore name containing keys related to JWT signing/signature validation.
  encryption_keystore: rt_profile_keys                      # Keystore name containing keys related to JWT encryption/decryption.
authentication:                                             # Authentication Settings
  endpoint: https://isvaop.ibm.com:445/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:password
                                                            # Endpoint to redirect when authentication is required. This is mandatory when `grant_types` contains `authorization_code` or `implicit`
  callback_param_name: Target                               # Parameter name to specify the callback target URI. If it is not specified, the default callback param name is `Target`.
  subject_attribute_name: uid                               # Name of the user or credential attribute that will be used to populate the `sub`. If it is not specified, the default attribute is `uid`.
template_macros:                                            # Template Macros
  user_macros:                                              # List of authenticated user claims to be made available.
    - name
    - family_name
    - given_name
    - display_name
  request_macros:                                           # List of request parameter to be made available.
    - authorization_details
    - claims
    - user_code
    - state
    - binding_message
ssl:
  certificate:                                              # The default SSL connection certificate array.
    - ks:rt_profile_keys                                    # The default SSL keystore to be used for SSL connections. ks: indicates keystore.
  disable_hostname_verification: false                      # The SSL connection validates the hostname.
javascript:                                                 # Javascript Settings
  timeout: 0                                                # Maximum execution time for a script in ms. Set to 0 for unlimited execution time.
  max_load: 16                                              # Maximum number of v8 engine spawned.
  max_ctx_in_isolate: 50                                    # Maximum reuse of v8 engine before recreated. Set to 0 to disable.
  use_pool: false                                           # If true, run in `pool` mode, otherwise run in `worker` mode.
logging:                                                    # Logging Settings
  level: finest                                             # Logging level setting. If the level is not set or invalid, `info` will be used. `panic`, `fatal`, `error`, `warn`, `warning` (alias of `warn`), `info`, `debug`, `fine`(alias of `debug`), `trace`, `finest` (alias of `trace`)
server:
  ssl:
    key: ks:https_keys/httpserverkey                       # Name of the keystore/key for the ISVAOP HTTPS server.
    certificate: ks:https_keys/httpservercert              # Name of the keystore/certificate for the ISVAOP HTTPS server.
    ca:
      - ks:https_keys/httpserverca                         # Name of the keystore/CA for the ISVAOP HTTPS server.
dynamic_registration:
  recipe: FAPI_UK-OB                                        # Security profile to use, option Default, FAPI_DEFAULT, FAPI_UK-OB, FAPI_AU-CDR
  mappingrule_id: dcr                                       # Dynamic registration mapping rule ID.
  software_statement_validation:                            # Software statement validation settings.
    jwks_uri: http://172.16.123.1:3000/jwks/obdirectory     # Jwks URI containing the public key required to validate the software statement signature.
    signing_algs:                                           # Accepted signing algorithms.
      - ES256
  registration_endpoint_authentication:                     # Authentication settings for POST operation.
    require_mtls: true                                      # Specifies whether the endpoint requires MTLS.
    require_bearer_token: true                              # Specifies whether the endpoint requires bearer token.
    require_software_statement: false                       # Specifies whether the endpoint requires software statement.
    allow_custom_client_creds: true                         # Only for POST. Specifies whether to accept client_id/client_secret in the POST payload.
  management_endpoint_authentication:                       # Authentication settings for PUT/GET/DELETE operations.
    require_mtls: false                                     # Specifies whether the endpoint requires MTLS.
    require_bearer_token: true                              # Specifies whether the endpoint requires bearer token.
    require_software_statement: false                       # Specifies whether the endpoint requires software statement. This is only applicable for PUT operation.
  registration_access_token:                                # Registration access token settings.
    generate: true                                          # Specifies whether to produce registration access token as part of POST/PUT/GET operations.
    lifetime: 86400                                         # Specifies the lifetime of the registration access token.
    scopes:                                                 # Specify the scopes required by the access token. All scopes specified here are mandatory. Unauthorized if any scope is not present in the access token.
      - cdr:registration
secrets:
  obf_key: "ENC:iUt+3MzCntxSL2FPTUuJqER79UaiRSApMz3cbgJm4yzuiv6H7KN8ADsamX6+Qre1oTsATjnb1bJ0Lmi7WWfxWeGT477yqqvgVayFlCDIFzZeNkdINjASfTE3B+/3Sm9YjIYuWtZdySiXeydhJXSiOGU9osdA9g2BZXR4eMrXNutCuaSvFH6MY+TyOH5q15vy6vEWOebJQHrnug0A8rN6NF8G8XaxCe/+yqH57jJpdhm0N7iUydIYOBOQ1wDgCc8nRMWkQqlkcRhDZvLLAIlhoshYvo06ubyryt8/vv/0AvTLq9AIiQoL8CtYLr+SNZlzWe4CnHYZdO9S+AIrUOVORw=="
  enc_key: "@keys/private.pem"

Detailed configuration and explanation of each stanza shown in the provider configuration is provided in the following topics:

  1. definition
  2. jwks
  3. authentication
  4. template_macros
  5. ssl
  6. javascript
  7. logging
  8. server
  9. dynamic_registration
  10. secrets