Mutual TLS Sender Constrained Tokens

Mutual TLS Sender Constrained Tokens are tokens that are bound to the underlying mutual TLS connection between the client and the authorization server. The TLS session is established by the Mutual TLS Client Authentication as part of a OAuth 2.0 workflow. After a successful client authentication the authorization server will encode the thumbprint (hash) of the client certificate in the Introspection Response (when using opaque tokens).

Prerequisites

Set up ISVAOP
Run the OAuth and OpenID Connect Provider wizard in ISVA.
Set up an application or relying party that supports authorization code flow with mTLS.

Configuring ISVAOP

Configuring provider.yml

The mtls_certificate_header_name is configured to match the Web reverse proxy crendential attribute.

# Copyright contributors to the IBM Security Verify Access OIDC Provider Resources project
logging:
  level: debug
definition:
  id: 1
  name: OIDC Definition
  grant_types:
    - authorization_code
  base_url: https://isvaop.ibm.com:445/isvaop
  mtls_certificate_header_name: x-client-certificate        # Web reverse proxy credential name that contains the certificate for mtls.
  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.
    access_token_type: jwt                                  # Indicates the access token format.
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"

Read more about key management to be able to create a jwtsigning key to sign the id_token, and to create https_keys to configure server node.
secrets node defines secret data which can be used to obfuscate or encrypt entries within the YAML configuration documents. Read more about geerating the obf_key and enc_key in the document.

Configuring the static client which uses tls_client_auth and tls_client_certificate_bound_access_tokens

The token_endpoint_auth_method is configured to enforce MTLS as the authentication method at the token endpoint, tls_client_auth_subject_dn enforces the incoming client certificate's subject_dn matches the configuration and tls_client_certificate_bound_access_tokens enforces the resulting access token will be bound to the certificate by the means of confirmation claim.

# Copyright contributors to the IBM Security Verify Access OIDC Provider Resources project
client_id: client_mtls
client_secret: "OBF:U2FsdGVkX1989Y/UBwz1BNPbIkv0hgBTcoynJtlRt56hu3TGX+5Kdi4TJ6MLMYtO" # ahwoaor82noawasg is the secret in clear text. This value will not be used.
client_name: "AuthorizationCode with mTLS"
enabled: true
redirect_uris:
  - https://www.mysp.ibm.com/isam/sps/oidc/rp/isamrp/redirect/partner
grant_types:
  - authorization_code
response_types:
  - code
token_endpoint_auth_method: tls_client_auth                 
tls_client_auth_subject_dn: CN=client_mtls,O=ACME,C=US
tls_client_certificate_bound_access_tokens: true

Configuring the static client which uses private_key_jwt and tls_client_certificate_bound_access_tokens

The token_endpoint_auth_method is configured to enforce private_key_jwt as the authentication method at the token endpoint, tls_client_auth_subject_dn enforces the incoming client certificate's subject_dn matches the configuration and tls_client_certificate_bound_access_tokens enforces the resulting access token will be bound to the certificate by the means of confirmation claim. The token_endpoint_auth_signing_alg enforces the signature algorithm of the JWT. The jwks_uri references the client's JSON Web Key (JWK) set document that contains the clients public key.

# Copyright contributors to the IBM Security Verify Access OIDC Provider Resources project
client_id: client_private_key_jwt
client_secret: "OBF:U2FsdGVkX1989Y/UBwz1BNPbIkv0hgBTcoynJtlRt56hu3TGX+5Kdi4TJ6MLMYtO" # ahwoaor82noawasg is the secret in clear text. This value will not be used.
client_name: "AuthorizationCode with private_key_jwt"
enabled: true
redirect_uris:
  - https://www.mysp.ibm.com/isam/sps/oidc/rp/isamrp/redirect/partner
grant_types:
  - authorization_code
response_types:
  - code
token_endpoint_auth_method: private_key_jwt
token_endpoint_auth_signing_alg: PS256
tls_client_auth_subject_dn: CN=client_mtls,O=ACME,C=US
tls_client_certificate_bound_access_tokens: true
jwks_uri: https://www.acme.com/oidc/jwks

Demonstrating Proof-of-Possession (DPoP)

DPoP provides a mechanism for a client to get sender-constrained OAuth tokens by providing a proof-of-possession of a public/private key pair. The specification is in draft status: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-11

Prerequisites

Set up ISVAOP
Set up an application or relying party that supports demonstrating proof-of-possession (DPoP) flow.

Configuring ISVAOP

In provider.yml, under definition, set the acceptable maximum lifetime of DPoP proof. If not specified, the default is 1800 seconds.
```
# Copyright contributors to the IBM Security Verify Access OIDC Provider Resources project
definition:
  dpop_max_lifetime: 1800
```

Create a new static client configuration client_dpop.yml and copy the following content.
The dpop_bound_access_tokens enforces that a DPoP JWT proof exists and the resulting access_token contains a cnf claim called jkt, dpop_signing_alg enforces the signature algorithm of the DPoP JWT.

# Copyright contributors to the IBM Security Verify Access OIDC Provider Resources project
client_id: client_dpop
client_secret: "OBF:U2FsdGVkX1989Y/UBwz1BNPbIkv0hgBTcoynJtlRt56hu3TGX+5Kdi4TJ6MLMYtO" # ahwoaor82noawasg
client_name: Client DPoP
enabled: true
redirect_uris:
  - https://www.acme.com
grant_types:
  - authorization_code
  - password
  - refresh_token
response_types:
  - code
token_endpoint_auth_method: client_secret_post
dpop_bound_access_tokens: true
dpop_signing_alg: PS256
dpop_single_use_jti: false