[RFC-8705] - OAuth 2.0 Mutual-TLS

Background

• Describe certificate-bound access and refresh tokens using mutual Transport Layer Security with X.509 certificates
• Client provided a mechanism for authentication to the authorization server using mutual TLS
  • self-signed certificates or public key infrastructure (PKI)
• Ensuring that such an access token presented to it was issued to the client presenting the token.

https://www.rfc-editor.org/rfc/rfc8705

Terminology

• Client presents its X.509 certificate and proves possession of the corresponding private key to a server when negotiating a TLS session
• Requires that the client send the Certificate and CertificateVerify messages during the handshake and for the server to verify the CertificateVerify and Finished messages

Difference Between TLS and MTLS

TLS

https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/

MTLS

https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/

Mutual TLS for OAuth Client Authentication (Two ways)

In order to utilize TLS for OAuth client authentication, the TLS connection between the client and the authorization server MUST have been established or re-established with mutual-TLS X.509 certificate authentication

Prerequisites

• client MUST include the client_id parameter (Section 2.2 of OAuth 2.0 [RFC6749])
  • authorization server to easily identify the client independently from the content of the certificate
• The authorization server MUST enforce the binding between client and certificate
• Authorization server returns a normal OAuth 2.0 error response per Section 5.2 of [RFC6749]
  • when no certificate is presented
  • when presented certificate does not match which is expected for the given client_id

PKI Mutual-TLS Method

https://www.csoonline.com/article/3400836/what-is-pki-and-how-it-secures-just-about-everything-online.html

• relies on a validated certificate chain [RFC5280] and a single subject distinguished name (DN) or a single subject alternative name (SAN) to authenticate the client
• Only one subject name value of any type is used for each client.
• The TLS handshake is utilized to validate the client's possession of the private key
• how to check a certificate's revocation status is a deployment decision at the discretion of the authorization server.
• Client registration metadata
  • Client using the tls_client_auth authentication method MUST use exactly one of the below metadata parameters

Registration Metadata

Self-Signed Certificate Mutual-TLS Method

• self_signed_tls_client_auth
• Client Registration Metadata

Mutual-TLS Client Certificate-Bound Access Tokens

• The authorization server is able to bind the issued access token to the client certificate
• such as embedding the certificate hash in the issued access token directly using the syntax described in Section 3.1
• through token introspection as described in Section 3.2
  • Binding the access token to the client certificate

Binding the access token to the client certificate in that fashion has the benefit of decoupling that binding from the client's authentication with the authorization server,

Access Token

• the access token itself cannot be used as input to the decision of whether or not to request mutual TLS
  • because it is "Application Data"
  • only exchanged after TLS handshake

Resource server

• mutual TLS is to be used for some or all resource accesses
• those requests MUST be made over a mutually authenticated TLS connection using the same certificate that was used for mutual TLS at the token endpoint
• client certificate used for mutual TLS and MUST verify that the certificate matches the certificate associated with the access token
  • if they dont match the resource access attempt MUST be rejected with an error
    • per [RFC6750], using an HTTP 401 status code and the invalid_token error code.

JWT Certificate Thumbprint Confirmation Method

• certificate hash information SHOULD be represented using the x5t#S256 confirmation
• base64url-encoded [RFC4648] SHA-256 [SHS] hash
• base64url-encoded value MUST omit all trailing pad '=' characters and MUST NOT include any line breaks, whitespace, or other additional characters.

  {
    "iss": "<https://server.example.com>",
    "sub": "ty.webb@example.com",
    "exp": 1493726400,
    "nbf": 1493722800,
    "cnf":{
      "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
    }
  }

Confirmation Method for Token Introspection

• The hash is conveyed using the same cnf with x5t#S256 member structure as the certificate SHA-256 thumbprint
• The protected resource compares that certificate hash to a hash of the client certificate used for mutual-TLS authentication and rejects the request if they do not match

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "active": true,
    "iss": "<https://server.example.com>",
    "sub": "ty.webb@example.com",
    "exp": 1493726400,
    "nbf": 1493722800,
    "cnf":{
      "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
    }
  }

Server.js

const https = require('https');
const fs = require('fs');
const express = require('express')

const app = express()

const RouteMap = {
  '/auth/integration': {
    mtls: true
  },

  '/auth': {
    mtls: false
  }
}
const clientAuthMiddleware = () => (req, res, next) => {
  const isMTLS= RouteMap[req.url] && RouteMap[req.url].mtls;

  if (isMTLS && !req.client.authorized) {
    return res.status(401).send('Invalid client certificate authentication.');
  }
  return next();
};
app.use(clientAuthMiddleware());
app.get('/auth/integration', (req,
                              res) => {
  return res.send('Hello World I`m auth with MTLS');
})

app.get('/auth', (req, res, next) => {
  return res.send('Hello World I`m auth without mtls');
});

const options = {
  key: fs.readFileSync('./server.key.pem'),
  cert: fs.readFileSync('./server.crt'),
  passphrase:'test',
  requestCert: true,
  rejectUnauthorized: false,
  ca: [fs.readFileSync('./client.crt')]
};

https.createServer(options, app).listen(8000, () => {
  console.log('server listening on port 8000');
});

Client.js

const fs = require('fs');
const https = require('https');

const req = https.request(
  {
    hostname: 'localhost',
    port: 8000,
    path: '/auth/integration',
    method: 'GET',
    cert: fs.readFileSync('client.crt'),
    key: fs.readFileSync('client.key'),
    ca: fs.readFileSync('server.crt'),
    passphrase:'test',
    rejectUnauthorized: false,
  },
  res => {
    res.on('data', function(data) {
      // do something with response
      console.log('Hello Data', res.statusCode, data.toString());
    });
  }
);

req.end();

Api gateway in Amazon API Gateway

• TLS protocol also offers the ability for the server to request that the client send an X.509 certificate to prove its identity
• It’s used in standards such as Open Banking, which enables secure open API integrations for financial institutions
• Mutual TLS is commonly used for business-to-business (B2B) applications.
• You can enable mutual TLS authentication on your custom domains to authenticate regional REST and HTTP APIs.
• you upload a CA public key certificate bundle as an object containing public or private/self-signed CA certs. This is used for validation of client certificates