Securing APIs with Certificate Bound Access Tokens

While OAuth 2.0 relies on bearer tokens for securing access to protected resources, bearer tokens require Transport Layer Security between an OAuth client and the resource server when presenting the access token to get access to a resource. In this security model, it is crucial to prevent access token leakage. Therefore, access token storage and transfer have to be done with care.

WSO2 API-M supports certificate bound JWT (access token) validation only. To generate certificate bound JWTs, the IDP of your choice should provide support. API-M Gateway will then validate the JWT tokens generated by the IDP. The JWT should include the transport certificate thumbprint under the cnf claim, as per the specification provided in RFC8705.

APIs in WSO2 API Manager can be secured using Certificate Bound Access Tokens, also known as Holder of Key Tokens. The following section explains as to how the APIs in WSO2 API Manager can be secured using Certificate Bound Access Tokens.

Import client certificate to the truststore

Follow the steps given below to import the CA-signed public key certificate into API Manager's default truststore (client-truststore.jks).

  1. Get a copy of the client-truststore.jks file from the <API-M_HOME>/repository/resources/security/ directory.

  2. Export the public key from your .jks file using the following command.

    keytool -export -alias certalias -keystore newkeystore.jks -file <public key name>.pem

  3. Import the public key you extracted in the previous step to the client-truststore.jks file using the following command.

    keytool -import -alias certalias -file <public key name>.pem -keystore client-truststore.jks -storepass wso2carbon

    Note

    wso2carbon is the keystore password of the default client-truststore.jks file.

Enable the Certificate Bound Access Token

  1. Open the <API-M_HOME>/repository/conf/deployment.toml file.

  2. Configure the enable_outbound_auth_header under the [apim.oauth_config] configuration.

    [apim.oauth_config]
enable_certificate_bound_access_token = <true|false>
    [apim.oauth_config]
enable_certificate_bound_access_token = true

  3. Restart the server if it is already running.

Create an API secured with OAuth 2.0

  1. Sign in to the Publisher.

    https://<hostname>:9443/publisher

  2. Create an API.

Invoke an API secured with Certificate Bound Access Token using Postman

Import the certificate and private key to Postman.

  1. Navigate to the certificates tab in Postman settings.

    Add the certificate to Postman

  2. Add the certificate and private key.

    Provide certificate and private key

  3. Set the Certificate Bound Access Token as the Bearer token.

    The token comprises of client certificate thumbprint as the cnf claim.

    "cnf", "{"x5t#S256": "9a0c3570ac7392bee14a408ecb38978852a86d38cbc087feeeeaab2c9a07b9f1"}"

  4. Invoke the API from Postman.

Validate Certificate Bound Access Tokens when SSL is terminated by the Load Balancer or Reverse Proxy

When the SSL termination of API requests takes place at the Load Balancer or Reverse Proxy, the following prerequisites need to be met by the Load Balancer.

  • Terminate the mutual SSL connection from the client.

  • Pass the client SSL certificate to the Gateway in an HTTP Header.

    For more information, see the Nginx documentation.

Using MTLS Header to invoke APIs secured with Certificate Bound Access Tokens

By default, the WSO2 API Manager retrieves the client certificate from the X-WSO2-CLIENT-CERTIFICATE HTTP header.

Follow the instructions below to change the header:

  1. Navigate to the <API-M_HOME>/repository/conf/deployment.toml file.

  2. Configure the certificate_header under the [apimgt.mutual_ssl] configuration.

     [apimgt.mutual_ssl]
 certificate_header = "<Header Name>"
 # This property needs to be true if the MutualSSL connection is established between the load balancer and the Gateway.
 enable_client_validation = false
 #This property needs to be true if the certificate should be decoded when it is passed from the load balancer to the Gateway.
 client_certificate_encode = false
     [apimgt.mutual_ssl]
 certificate_header = "SSL-CLIENT-CERT"
 enable_client_validation = false
 client_certificate_encode = false

  3. Start the server.

  4. Invoke the API with the custom header.

    curl -k --location -X GET "<API_URL>" -H  "accept: application/json" -H  "Authorization: Bearer <access-token>" -H "<MTSL_Header_name>:<Certificate_Key>"

Note

The Certificate Bound Access Token validation flow described above uses the Nginx load balancer. When using a different Elastic Load Balancer (ELB) to configure the MTSL with SSL termination, make sure to refer the service provider's documentation and the feature catalog to do the necessary configurations.

Top