Client ID and User Authentication with mTLS

Mutual Transport Layer Security (mTLS) authentication is supported for:

• OpenID clients
• End-user PKI authentication via the Identity Provider
• PKI certificate import
• Other OpenID client PKI authentication methods (JWT)

Using the certificate extracted from the TLS connection, the HID Authentication Service mTLS validation flow is as follows: 

1. Validate the certificate trust path (using the defined mtls_truststore).
2. Validate the certificate status (using CRL or other mechanisms such as OCSP).
3. Validate the certificate binding:
   • OpenID client JWT authentication - verify of the JWT signature
   • OpenID or end-user PKI certificate matching - validate the rules with user information
   • OpenID or end-user PKI certificate check - verify the TLS certificate matches the registered user certificate

To enable authentication via mTLS, you must define the truststore and register your Client ID.

Configure a Truststore for mTLS Authentication

During the Mutual TLS (mTLS) authentication flow (PKI import or authentication), the client X.509 certificates must be forwarded to HID Authentication Service so they can be checked before issuing an access_token.

To enable the certificate check, you must define the truststore so HID Authentication Service can verify the certificate trust path in the keystore file.

You can define a specific truststore for each tenant.

POST https://[base-server-url]/configuration/{tenant}/v2/Custo/Keystores
{
    "schemas": ["urn:hid:scim:api:idp:2.0:Customization"],
    "id": "mtls_truststore",
    "payload": {
        "truststore_type": "pem",
        "truststore_b64": "base64 encoded keystore file"
    }
}

Where:

• id - unique identifier for the custom truststore

• payload:

  • truststore_type - type of the keystore file (for example, .pem)

  • truststore_b64 - contents of the keystore file containing the full certificate chain for the certificate authority (CA) encoded in base64

Register Your Client ID

The register endpoint is used to create Client IDs:

• Register the Client ID in the UG_CLIENTID group

• Fetch the internal ID of the Client ID

• Use the internal ID to assign the role RL_CLIENTID to the newly created Client ID

hid_sessiontransfer_type: "NUM001", grant_types: ["urn:hid:oauth:grant-type:client-secret-pki"],…}
client_id: "535320231218399443174389014721746114892495025388"
client_id_issued_at: 1600432579
client_name: "test"
grant_types: ["urn:hid:oauth:grant-type:client-secret-pki"]
hid_ciba_callback_format_plain: false
hid_client_channel: "CH_EXTRAPP"
hid_client_group: "UG_CLIENTID"
hid_client_pki_policy: "AT_EMPPKI"
hid_client_pwd_policy: "AT_SYSLOG"
hid_sessiontransfer_type: "NUM001"
hid_user_authn_policy: "AT_STDPWD"
hid_user_channel: "CH_EXTRAPP"
id_token_encrypted_response_alg: "RSA-OAEP-256"
jwks: {,…}
redirect_uris: ["https://client.example.org", "https://client2.example.org"]
registration_client_uri: "https://[baser-server-url]/{tenant}/authn/register/535320231218sadfas2903459239479838098745446114892495025388"
tls_client_certificate_bound_access_tokens: false
token_endpoint_auth_method: "private_key_jwt"

{
    "hid_sessiontransfer_type": "NUM001",
    "grant_types": ["urn:hid:oauth:grant-type:client-secret-pki"],
    "jwks": {
        "keys": [
            {
                "kty": "RSA",
                "x5t#S256": "uFUHzgzuK82KnrgryerywewItIIOThkahs8IjB7wMUugUMBL6JwC10",
                "e": "AQAB",
                "kid": "client1",
                "x5c":["MIIDkTCCAnngWAWRAIBAgIJAMFobKOVtr\/1MA0GCSqGSIb3DQEBCwUAMF4xCdIjiokjhSDUIISDQ8wDQYDVQQIDAZQT0xBTkQxDzANBgNVBAcMBktSQUtPVzEMMAoGA1UECgwDSElEMQ0wCwYDVQQLDARBQUFTMRAwDgYDVQQDDAdST09UIENBMB4XDTE5MDExMDA2NTI0NFoXDTIxMTAzMDA2NTI0NFowXjELMAkGA1UEBhMCUEwxDzANBgNVBAgMBlBPTEFORDEPMA0GA1UEBwwGS1JBS09XMQwwCgYDVQQKDANISUQxDTALBgNVBAsMBEFBQVMxEDAOBgNVBAMMB2NssdgserKJIHUHOggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC1OjsoRxaTLrEOje2ORkubixdu2MCH4MIFu6bOZ3c+La8SKmGHJUZHJXG+ma8YjRQ15p3RexZaPXcZMgMyfGNtuzCzmgM03bSkh5Bn7hRN1aHqGZIxX6yWZZxCM3nrJzs\/4s6Ju74zZHX\/P4ls99xsUt\/3BImbwnF7s\/iCLSWSZI6in+HVSm5uLvYKTHS2jGvydn47N6+skwV5Z3jNaNOiePUf2z0cRA9hYclTPNIK13IfOyNIiJpO64b2q+3NOx5Ynd4IO1E+92ilifi4Vn\/UB0bjH9tI6bus2gTRZTB3RypFAgD5BpfmX8p8enWiPfbx3\/DSdalrCCIp2Ck\/D265AgMBAAGjUjBQMB8GA1UdIwQYMBaAFOmbPW3BBUD5a42Fn1ux3orFKQvgMAkGA1UdEwQCMAAwCwYDVR0PBAQDAgTwMBUGA1UdEQQOMAyCCiUlRE9NQUlOJSUwDQYJKoZIhvcNAQELBQADggEBAGOu87caxPE4d9wNUmmj4xgLUPxbZvDuu2r7QFaRAhUFc3UH53HqsOIqAIXIpciI3a7Wxel\/3FHMAmZc1\/xP0jAf2RGimnc6TNOZQFADvJ9SnfOGqHIR\/k7njhgDWAOjElzLYKJJQh4\/02izNEPyHg1r3dzhGBJtdvzlesc8QC6bEQ8raHumNFbf5LVmI2C\/Gws1g4YO8HIXbBtJkpozLOVC7nV4qwIFIc00DXkyQfxtajwAFLhGazeMHkrTgfja3WgbykmmCIFSiHHQZkOOqb+6n1qlqS3QnFI6zP3ctT8XTlSbCW9\/w5rA02lCUOASlXdwDuVh78pnjY03FvOXNE8="],
                "n":  "tTo7KEcWky6xDo3tjkZLm4sXbtjAh-DCBbumzmd3Pi2vEiphhyVGRyVxvpmvGI0UNead0XsWWj13GTIDMnxjbbsws5oDNN20pIeQZ-4UTdWh6hmSMV-slmWcQjN56yc7P-LOibu-M2R1_z-JbPfcbFLf9wSJm8Jxe7P4gi0lkmSOop_h1Upubi72Ckx0toxr8nZ-OzevrJMFeWd4zWjTonj1H9s9HEQPYWHJUzzSCtdyHzsjSIiaTuuG9qvtzTseWJ3eCDtRPvdopYn4uFZ_1AdG4x_bSOm7rNoE0WUwd0cqRQIA-QaX5l_KfHp1oj328d_w0nWpawgiKdgpPw9uuQ"
            }
        ]
    },
    "hid_client_group":"UG_CLIENTID",
    "registration_client_uri":"https:\/\/dev.test.testcloud.com\/idp\/t56dfgsdtrwer456300432457464\/authn\/register\/534777218399443174389014721746114892495025388",
    "redirect_uris": [
        "https:\/\/client.example.org",
        "https:\/\/client2.example.org"
    ],
    "hid_client_channel":"CH_EXTRAPP",
    "token_endpoint_auth_method":"private_key_jwt",
    "client_id":"535320231218399443174389014wer436435632395025388",
    "hid_client_pwd_policy":"AT_SYSLOG",
    "id_token_encrypted_response_alg":"RSA-OAEP-256",
    "hid_client_pki_policy":"AT_EMPPKI",
    "hid_ciba_callback_format_plain":false,
    "hid_user_channel":"CH_EXTRAPP",
    "hid_user_authn_policy":"AT_STDPWD",
    "client_id_issued_at":16003456579,
    "tls_client_certificate_bound_access_tokens":false,
    "client_name":"test"
}

Authenticating with mTLS

The token endpoint is used for mTLS-based authentication:

POST https://${mtls_url}:8443/idp/${tenant}/authn/token

grant_type=urn:hid:oauth:grant-type:client-secret-pki&client_id=${ClientId}&scope=openid
${clientID}

The following details can be passed along with the payload:

• Client ID
• Private Key of the client registered with PKI Authenticator (.key or .pem format)
• Client certificate with which client ID was registered (.cer or .pem format)
• Server root CA certificate