Authenticate using mutual TLS

Leveraging the mutual Transport Layer Security (mTLS) encrypted protocol for client authentication ensures a secure and seamless identity experience that meets FAPI 2.0 (Financial-grade API) requirements. This approach overcomes the vulnerability of compromising a client identity by mutually validating client and server with X.509 certificates on the network level and preventing token theft through certificate-based binding. For more information, refer to RFC 8705 (OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens).

How it works

In user authentication and client authentication scenarios, mutual client and Mosaic certificate authentication occurs during the TLS handshake before any data is sent over HTTPS. During the handshake, the client presents its certificate to Mosaic for validation.

• For self-signed certificates, Mosaic validates the certificate against the JWKS provided in the client settings.
• For CA-signed certificates, Mosaic validates them against the full certificate chain previously provided in the client settings — from the end-entity (client) certificate back to a trusted root.

For example, a client requests a token (Step 3) using mTLS authentication. Upon the receiving the client access token, your app validates it (Step 4) and then uses this token to authorize the call.

Step 1: Obtain certificates

Use strong cryptography to secure the client authentication process. Mosaic enables you to authenticate using self-signed or CA-signed certificates.

-----BEGIN CERTIFICATE-----
MIIFJDCCBAygAwIBAgIUEeLI1epi5t/raeHK/6UnMwZ8DP4wDQYJKoZIhvcNAQEL
....
KoPFmnhBOjTlcEB2azJOV3jYCJqImLY
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIE6jCCA9KgAwIBAgIUV49I69r0HAlOsD4WXv1ROrut4T8wDQYJKoZIhvcNAQEL
...
U98pDI9m81HgbDmq4gCl8Y+cylJr0ycmcBDXTkIHWqpVGKFOMqL9MPbIgC1SLnYU
-----END CERTIFICATE-----

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "CpTM4iGliMoklgafvDXA4TbclcynyD_wMgjOfhiCUUE",
      "x5c": ["MIIDazCCAlOgAwIBAgIURndmlRmyo9snXN45B..."],
      "alg": "RS256",
      "e": "AQAB",
      "n": "vXoSLHWtv_t7f78rvKGPkLDuc-9MkzvLiWf-iUfQm..."
    }
  ]
}

Step 2: Submit certificate to Mosaic

Configure your Mosaic client to use mTLS as an authentication method and provide the public certificate or certificate chain. It will be used to prove the client identity to the server.

• For OIDC implementations : from the Admin Portal under Applications , click your application and proceed to the OIDC client settings to update the authentication method to mTLS (self-signed) or mTLS (CA-signed) . If you don't already have an application, you'll need to create one first (see Create application ).
  • For self-signed mTLS , provide the JWKS you've generated in Step 1 .
  • For CA-signed mTLS , provide a certificate chain (in the PEM format) you've generated in Step 1 . Optionally, define Subject DN attributes (Common name ( CN ), Organization ( O ), and others) to enforce certificate validation against these values. :::warning FAPI 2.0 compliance

Consider enabling "Enforce FAPI 2.0 compliance" when creating a client. See Manage clients

:::

• If using SSO Service : from the Admin Portal under SSO Service , navigate to Service Definition > Client groups and proceed to the OIDC client settings to update the authentication method to mTLS (self-signed) or mTLS (CA-signed) , and submit a certificate. To configure SSO management clients, navigate to Service Definition > Management clients .
  • For self-signed mTLS , provide the JWKS you've generated in Step 1 .
  • For CA-signed mTLS , provide a certificate chain (in the PEM format) you've generated in Step 1 . Optionally, define Subject DN attributes (Common name ( CN ), Organization ( O ), and others) to enforce certificate validation against these values.

Step 3: Authenticate client

Authenticate a client and obtain a client access token by sending a POST request like the one below to the /oidc/token endpoint, along with the parameters listed below.

import https from 'https';
import fs from 'fs';
import fetch from 'node-fetch';

// Load mTLS credentials
const agent = new https.Agent({
  cert: fs.readFileSync('CLIENT_CERTIFICATE_FILE'),
  key: fs.readFileSync('CLIENT_PRIVATE_KEY_FILE'),
  rejectUnauthorized: true
});

async function run() {
  const formData = new URLSearchParams({
    client_id: 'CLIENT_ID',
    grant_type: 'client_credentials'
  });

  const resp = await fetch(
    'https://api.transmitsecurity.io/cis/oidc/token',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: formData.toString(),
      agent // Enables mTLS
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();

Step 4: Validate tokens

The /oidc/token response includes a client access token. Tokens must be validated as described here. If you enable token binding, the generated token will be bound to a certificate (cnf claim). Validate the token signatures using the public key retrieved from the JWKS endpoint:

  https://api.transmitsecurity.io/cis/oidc/jwks

Next steps

When authentication with mTLS is enabled, a certificate and key should be used in all calls that typically leverage client secrets, including:

• Obtaining client access tokens with /oidc/token
• Obtaining user access tokens with /oidc/token
• Initiating a PAR request with /oidc/request
• Login a user with /oidc/auth
• Initiating a backchannel flow with /oidc/backchannel
• Initiating a device flow with /oidc/device/auth
• Revoking a token /oidc/token/revocation
• etc.

For example, below are sample requests leveraging mTLS in the PAR and CIBA flows:

import https from 'https';
import fs from 'fs';
import fetch from 'node-fetch';

// Load mTLS credentials
const agent = new https.Agent({
  cert: fs.readFileSync('CLIENT_CERTIFICATE_FILE'),
  key: fs.readFileSync('CLIENT_PRIVATE_KEY_FILE'),
  rejectUnauthorized: true
});

async function run() {
  const formData = {
    client_id: 'CLIENT_ID',
    redirect_uri: 'REDIRECT_URI',
    response_type: 'code',
    scope: 'openid',
    code_challenge: 'HASHED_CODE_VERIFIER',
    code_challenge_method: 'S256'
  };

  const resp = await fetch(
    `https://api.transmitsecurity.io/cis/oidc/request`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams(formData).toString(),
      agent // Enables mTLS
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();

import https from 'https';
import fs from 'fs';
import fetch from 'node-fetch';

// Load mTLS credentials
const agent = new https.Agent({
  cert: fs.readFileSync('CLIENT_CERTIFICATE_FILE'),
  key: fs.readFileSync('CLIENT_PRIVATE_KEY_FILE'),
  rejectUnauthorized: true
});

async function run() {
  const formData = {
    client_id: 'CLIENT_ID',
    scope: 'openid',
    login_hint: 'LOGIN HINT',
    binding_message: 'MESSAGE'
  };

  const resp = await fetch(
    `https://api.transmitsecurity.io/cis/oidc/backchannel`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams(formData).toString(),
      agent // Enables mTLS
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();