Configuring JWT Bearer grant type

Overview

JSON Web Token (JWTs) is a JSON-based security token encoding that enables sharing of identity and security data between independent security domains. The JSON Web Token profile for OAuth 2.0 Client Authentication and Authorization Grants is the specification that defines the use of JWT Bearer token as a means for requesting an OAuth 2.0 access token as well as client authentication.

The assertion for ISVAOP needs to have the following claims

Claim name	Description	Example value
sub	The subject of the JWT	peter
aud	The intended audience of the JWT, it should be the authorization servers token endpoint	https://www.myidp.ibm.com/isvaop/oauth2/token
iss	The entity that issues the JWT	https://www.myidp.ibm.com/
jti	A unique identifier for the JWT, it prevents replay attack	eec0ab20-c6d2-11ee-ba30-e3acce745120
exp	When the JWT expires	1707432574

Configuring provider.yml

The definition configuration defines a new grant_type urn:ietf:params:oauth:grant-type:jwt-bearer.

# Copyright contributors to the IBM Security Verify Access OIDC Provider Resources project
version: 24.08
logging:
  level: debug
definition:
  id: 1
  name: OIDC Definition
  grant_types:
    - authorization_code
    - password
    - client_credentials
    - implicit
    - refresh_token
    - urn:ietf:params:oauth:grant-type:token-exchange    
    - urn:ietf:params:oauth:grant-type:jwt-bearer 
  pre_mappingrule_id: isvaop_pretoken                       # Pre-Token mapping rule ID.
  post_mappingrule_id: isvaop_posttoken  
  base_url: https://isvaop.ibm.com:445/isvaop
  token_settings:                                           # Token Settings
    issuer: https://isvaop.ibm.com                          # OP's issuer URI.
    signing_alg: PS256                                      # Signing algorithm for ID token generated.
    signing_keystore: isvaop_signing                        # Signing keystore name.
    signing_keylabel: jwtsigning                            # Signing key label.
  attribute_map:                                            # Attribute mapping to resolve claims. also refer to attributesources.yml
    surname: surname  
server:
  ssl:
    key: ks:isvaop_keys/httpserverkey
    certificate: ks:isvaop_keys/httpservercert
jwks:
  signing_keystore: isvaop_signing
secrets:
  obf_key: "ENC:iUt+3MzCntxSL2FPTUuJqER79UaiRSApMz3cbgJm4yzuiv6H7KN8ADsamX6+Qre1oTsATjnb1bJ0Lmi7WWfxWeGT477yqqvgVayFlCDIFzZeNkdINjASfTE3B+/3Sm9YjIYuWtZdySiXeydhJXSiOGU9osdA9g2BZXR4eMrXNutCuaSvFH6MY+TyOH5q15vy6vEWOebJQHrnug0A8rN6NF8G8XaxCe/+yqH57jJpdhm0N7iUydIYOBOQ1wDgCc8nRMWkQqlkcRhDZvLLAIlhoshYvo06ubyryt8/vv/0AvTLq9AIiQoL8CtYLr+SNZlzWe4CnHYZdO9S+AIrUOVORw=="
  enc_key: "@keys/private.pem"

Configuring a confidential client

Enable a new grant type called urn:ietf:params:oauth:grant-type:jwt-bearer.
Since it is a confidential client set token_endpoint_auth_method to client_secret_post.

# Copyright contributors to the IBM Security Verify Access OIDC Provider Resources project
clients:  
  - client_id: client01jwtbearerconf
    client_secret: "OBF:U2FsdGVkX19iBhlwc53QkybjO6RjFHhSbz4VRudYHA="                                            # Client secret that is used for client authentication and/or JWT signing/encryption. `OBF:` indicates obfuscated string.
    client_name: client01jwtbearerconf                                                                              # 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                                                    
    id_token_signed_response_alg: PS512                                                                         
    token_endpoint_auth_method: client_secret_post                                                               
    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
      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

Generating assertion

The assertion can be generated using jwt.io
A JSON representation of the token

  {
    "sub": "peter",
    "aud": "https://isvaop.ibm.com:445/isvaop/oauth2/token",
    "jti": "f6272a30-bf1e-11ee-bac7-27cfsa56458c",
    "iss": "https://www.ibm.com",
    "iat": 1706585019,
    "exp": 1706585619
  }

The token has to be signed and the client jwks_uri should contain public key to verify the token.

JWT Bearer request example

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=client01jwtbearerconf' \
--data-urlencode 'client_secret=asfasdfawqdewq' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
--data-urlencode 'assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6Imp3dCIsImtpZCI6Imp3dGJlYXJlciJ9.eyJzdWIiOiJwZXRlciIsImF1ZCI6Imh0dHBzOi8vd3d3Lm15aWRwLmlibS5jb20vaXN2YW9wL29hdXRoMi90b2tlbiIsImp0aSI6ImY2MjcyYTMwLWJmMWUtMTFlZS1iYWM3LTI3YzYzNTI2NDU4YyIsImlzcyI6Imh0dHBzOi8vd3d3LmlibS5jb20iLCJpYXQiOjE3MDY1ODUwMTksImV4cCI6MTcwNjU4NTYxOX0.GnPhvx9MjafK3OTBmazbNuBBI5zJH5CEeephxwUD9lG3FnsCCU4x6H42Svr1NZ5APOhhCGmVJg7byG8OB159uHUMeo96suUttLDgnbawJSfwr7kmGYhWtIiWBTDQi_YGX0jR9Nsn33nn2OVnDbWRDE7c6Qxav06hbp3TWCsqR8l8_0aQJAV4OV2TXFXtyLjNfUxP43nphOlaNpSSvzEvpcpXKfKqsFgMnY_BR12p4qIBLSWRXpYOQTJLj66jvaPccQ8MtJEgOCertWctCIn5inl48_Rw5LLVc6J9MZAxBHnxQkfsHNs0OTEOsTZEBFZVFvMWb0Ajv2TQcxUPEZNE6xvy7DYW2qHfWkrh5yctu4-WgIgoz3yhuU3CR_JwMoBrwo6F4qyVnIhFHpUt5JQ-RdKTuZUwIIrISFHwelzRr_g_B884vP-K5Fb_pg5F7nJHQHXpfed5CIxLdPiM8vYkwXGRXJpj7HksYCmbr_akiupbpnG7hmvnEcBeuV8Y4Td-8eF_qetRGkOWCNJ2C9j48BIoAC0gSmzYn_mH4maMMh2TXlNHHFNT6wkNS2JDCJlMb5WwZ-4KWXx2VgRdbwp8HtPupGxuYdhGluGmWLo1uqZuNpbFS5LnqBAa3YrfBmkjRAnWuGTeSPe3rnyZ8VqUltWAeRRTRA_3_S3EY42IlS0'

Client authentication is set to client_secret_post, hence client_id and client_secret are sent in the post payload.

Configuring a public client

Enable a new grant type called urn:ietf:params:oauth:grant-type:jwt-bearer.
Since it is a public client set token_endpoint_auth_method to none and remove the client_secret entry.

# Copyright contributors to the IBM Security Verify Access OIDC Provider Resources project
clients:  
  - client_id: client01jwtbearer
    client_secret:                                           # Client secret that is used for client authentication and/or JWT signing/encryption. `OBF:` indicates obfuscated string.
    client_name: client01jwtbearer                                                                 # 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                                                    
    id_token_signed_response_alg: PS512                                                                         
    token_endpoint_auth_method: none                                                               
    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
      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

Generating assertion

The assertion can be generated using jwt.io
A JSON representation of the token

  {
    "sub": "peter",
    "aud": "https://isvaop.ibm.com:445/isvaop/oauth2/token",
    "jti": "f6272a30-bf1e-11ee-bac7-27c63526458c",
    "iss": "https://www.ibm.com",
    "iat": 1706585019,
    "exp": 1706585619
  }

The token has to be signed and the client jwks_uri should contain public key to verify the token.

JWT Bearer request example

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=client01jwtbearer' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
--data-urlencode 'assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6Imp3dCIsImtpZCI6Imp3dGJlYXJlciJ9.eyJzdWIiOiJwZXRlciIsImF1ZCI6Imh0dHBzOi8vd3d3Lm15aWRwLmlibS5jb20vaXN2YW9wL29hdXRoMi90b2tlbiIsImp0aSI6ImY2MjcyYTMwLWJmMWUtMTFlZS1iYWM3LTI3YzYzNTI2NDU4YyIsImlzcyI6Imh0dHBzOi8vd3d3LmlibS5jb20iLCJpYXQiOjE3MDY1ODUwMTksImV4cCI6MTcwNjU4NTYxOX0.GnPhvx9MjafK3OTBmazbNuBBI5zJH5CEeephxwUD9lG3FnsCCU4x6H42Svr1NZ5APOhhCGmVJg7byG8OB159uHUMeo96suUttLDgnbawJSfwr7kmGYhWtIiWBTDQi_YGX0jR9Nsn33nn2OVnDbWRDE7c6Qxav06hbp3TWCsqR8l8_0aQJAV4OV2TXFXtyLjNfUxP43nphOlaNpSSvzEvpcpXKfKqsFgMnY_BR12p4qIBLSWRXpYOQTJLj66jvaPccQ8MtJEgOCertWctCIn5inl48_Rw5LLVc6J9MZAxBHnxQkfsHNs0OTEOsTZEBFZVFvMWb0Ajv2TQcxUPEZNE6xvy7DYW2qHfWkrh5yctu4-WgIgoz3yhuU3CR_JwMoBrwo6F4qyVnIhFHpUt5JQ-RdKTuZUwIIrISFHwelzRr_g_B884vP-K5Fb_pg5F7nJHQHXpfed5CIxLdPiM8vYkwXGRXJpj7HksYCmbr_akiupbpnG7hmvnEcBeuV8Y4Td-8eF_qetRGkOWCNJ2C9j48BIoAC0gSmzYn_mH4maMMh2TXlNHHFNT6wkNS2JDCJlMb5WwZ-4KWXx2VgRdbwp8HtPupGxuYdhGluGmWLo1uqZuNpbFS5LnqBAa3YrfBmkjRAnWuGTeSPe3rnyZ8VqUltWAeRRTRA_3_S3EY42IlS0'

📘
Note
The specification states "Authentication of the client is optional, "client_id" is only needed when a form of client authentication that relies on the parameter is used"

To achieve the above scenario, in ISVAOP the iss claim in the assertion is read as the client_id and static and dynamic client are looked up with the matching client_id.
If found the client configuration is used to validate the assertion signature, else an error is thrown.

JWT Bearer request example without client_id

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
--data-urlencode 'assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6Imp3dCIsImtpZCI6Imp3dGJlYXJlciJ9.eyJzdWIiOiJwZXRlciIsImF1ZCI6Imh0dHBzOi8vd3d3Lm15aWRwLmlibS5jb20vaXN2YW9wL29hdXRoMi90b2tlbiIsImp0aSI6ImY2MjcyYTMwLWJmMWUtMTFlZS1iYWM3LTI3YzYzNTI2NDU4YyIsImlzcyI6Imh0dHBzOi8vd3d3LmlibS5jb20iLCJpYXQiOjE3MDY1ODUwMTksImV4cCI6MTcwNjU4NTYxOX0.GnPhvx9MjafK3OTBmazbNuBBI5zJH5CEeephxwUD9lG3FnsCCU4x6H42Svr1NZ5APOhhCGmVJg7byG8OB159uHUMeo96suUttLDgnbawJSfwr7kmGYhWtIiWBTDQi_YGX0jR9Nsn33nn2OVnDbWRDE7c6Qxav06hbp3TWCsqR8l8_0aQJAV4OV2TXFXtyLjNfUxP43nphOlaNpSSvzEvpcpXKfKqsFgMnY_BR12p4qIBLSWRXpYOQTJLj66jvaPccQ8MtJEgOCertWctCIn5inl48_Rw5LLVc6J9MZAxBHnxQkfsHNs0OTEOsTZEBFZVFvMWb0Ajv2TQcxUPEZNE6xvy7DYW2qHfWkrh5yctu4-WgIgoz3yhuU3CR_JwMoBrwo6F4qyVnIhFHpUt5JQ-RdKTuZUwIIrISFHwelzRr_g_B884vP-K5Fb_pg5F7nJHQHXpfed5CIxLdPiM8vYkwXGRXJpj7HksYCmbr_akiupbpnG7hmvnEcBeuV8Y4Td-8eF_qetRGkOWCNJ2C9j48BIoAC0gSmzYn_mH4maMMh2TXlNHHFNT6wkNS2JDCJlMb5WwZ-4KWXx2VgRdbwp8HtPupGxuYdhGluGmWLo1uqZuNpbFS5LnqBAa3YrfBmkjRAnWuGTeSPe3rnyZ8VqUltWAeRRTRA_3_S3EY42IlS0'

A client identifier with https://www.ibm.com is looked up in the above scenario.

Overview

Configuring provider.yml

Configuring a confidential client

Generating assertion

JWT Bearer request example

Configuring a public client

Generating assertion

JWT Bearer request example

📘Note

JWT Bearer request example without client_id

📘
Note