Skip to content

Latest commit

 

History

History
99 lines (77 loc) · 6.58 KB

README.md

File metadata and controls

99 lines (77 loc) · 6.58 KB
Raw

Enabling mutual TLS with Holder of Key verification

The Transaction Security section of the Consumer Data Standards mandates that mutual TLS (mTLS) be used in conjuction with the Holder of Key (HoK) mechanism on certain endpoints.

When mutual TLS is used by the client on the connection to the token endpoint, the authorization server is able to bind the issued access token to the client certificate. When the client makes a request to a protected resource, it MUST be made over a mutually authenticated TLS connection using the same certificate that was used for mutual TLS at the token endpoint.

This Apigee CDS reference implementation of CDS can be optionally configured to enforce mTLS with HoK verification.

Prerequisites

Apigee supports mTLS by configuring a virtual host. A virtual host can be configured to either not require mTLS or to always require mTLS. Since the CDS standards mandate a mixture of TLS and mTLS endpoints, a second virtual host must be created and configured to require mTLS. In order to create a new virtual host you will need:

  • An Apigee paid account. Free trial accounts do not allow creation of new virtual hosts
  • A host alias that can be associated with the virtual host. You must own the domain name specified in the host alas.
  • A DNS entry and CNAME record for the host alias. The CNAME record must be associated with <APIGEE_ORG>-<APIGEE_ENV>.apigee.net. See About host aliases and DNS names for more details.
  • A server certificate (PEM or PKCS12/PFX file) and key (PEM or PKCS12/PFX file) associated with the hostname. Wildcards are allowed in the certificate SAN or CN

See Requirements for configuring a virtual host for the Cloud for more details on these prerequisites.

Steps

1. Create the virtual host

1.a. Create a keystore named CDS-Keystore
1.b. Create an alias CDS-DataHolderCertificate in the keystore and upload your certificate
1.c. Create a reference to the CDS-Keystore keystore, named CDS-KeystoreRef
1.d) Create a truststore, named CDS-Truststore
1.e) Create an alias CDS-TestClient in the truststore and add a client certificate

Any client certificate will do, as long as it the same that will be used when sending requests to endpoints where mTLS with HoK is enforced. The installation script creates a test client certificate and stores it in setup/certs/CDSTestApp.crt

1.f) Create a reference to the CDS-Truststore, named CDS-TruststoreRef
1.g) Create a virtual host named secure-mtls

Use the Apigee API to create it.

export MTLS_HOSTNAME=<Fully qualified host alias - Do not include protocol> # For example: export MTLS_HOSTNAME=secure-cds.apac-hybrid.s.apigee.com

curl --request POST -u $APIGEE_USER:$APIGEE_PASSWORD https://api.enterprise.apigee.com/v1/o/$APIGEE_ORG/e/$APIGEE_ENV/virtualhosts \
--header 'Content-Type: application/json' \
--data-raw '{ 
    "description": "Virtual Host used for MTLS with Holder of Key verification", 
    "hostAliases": [ 
        "'$MTLS_HOSTNAME'" 
    ], 
    "interfaces": [], 
    "listenOptions": [], 
    "name": "secure-mtls", 
    "port": "443", 
    "retryOptions": [], 
    "sSLInfo": { 
        "ciphers": [], 
        "clientAuthEnabled": "true", 
        "enabled": "true", 
        "ignoreValidationErrors": false, 
        "keyAlias": "CDS-DataHolderCertificate", 
        "keyStore": "ref://CDS-KeystoreRef", 
        "protocols": [], 
        "trustStore": "ref://CDS-TruststoreRef" 
    }, 
    "useBuiltInFreeTrialCert": false, 
    "propagateTLSInformation": { 
        "connectionProperties": true, 
        "clientProperties": true 
    } 
}'

2. Add a KVM entry to store the fully qualified host alias

This entry is used in the OIDC Configuration End Point. The oidc proxy extracts this value from an entry associated with the key HOK_mtlsHostname in a KVM named CDSConfig

apigeetool addEntryToKVM -u $APIGEE_USER -p $APIGEE_PASSWORD -o $APIGEE_ORG -e $APIGEE_ENV \
 --mapName CDSConfig --entryName HOK_mtlsHostname --entryValue https://$MTLS_HOSTNAME

3. Modify proxies to also use the new virtual host

The following proxies need to use the new virtual host:

  • oidc
  • mock-oidc
  • CDS-ConsentMgmtWithKVM
  • Any banking proxy (Currently CDS-Accounts and CDS-Transactions)
  • CDS-DynamicClientRegistration

For each of these proxies, execute the following steps:

  • In the Apigee UI, click on the proxy and then click on the Develop tab
  • Select ProxyEndpoints -> default, uncomment the following XML element: <VirtualHost>secure-mtls</VirtualHost> , and save.

The reference implementation is now configured to use mTLS with HoK.

The Postman collection includes a folder for testing HoK verification.

Using mTLS with HoK verification in a production environment

Note that the above proxies still accept one-way TLS connections, which is fine for testing purposes, but shouldn't be the case in a production environment. In production, no banking proxy (Currently CDS-Accounts and CDS-Transactions) should use the secure virtualhost, only secure-mtls.

However, oidc, mock-oidc, CDS-ConsentMgmtWithKVM, and CDS-DynamicClientRegistration apiproxies have a mixture of one way TLS and mTLS endpoints, so these proxies should still use both endpoints.

You will need to edit the verify-mtls-and-hok shared flow to remove the dummy condition which prevents the enforcement of mTLS on the endpoints that should only accept mTLS.

Finally, you will also need to add the CDR Register certificate to the CDS-Truststore, so that client certificates issued by this authority will be accepted.