Certificate Authentication (mTLS)

Yanzi supports authentication with client-side certificates (mTLS) for added security. This enables secure clients to authenticate without exposing passwords or token credentials.

Certificate Enrollment

Enrollment is the initial process of exchanging a username and password for a client certificate. This is typically done only once per client.

Note

There are many ways to generate keys and CSRs, but in this guide we will use the openssl command line tool.

Step 1: Create a client key.

Run the below command on a trusted machine. This will generate a 2048 bit RSA private key in cert.key and a Certificate Signing Request (CSR) in cert.csr.

openssl req -out cert.csr -new -newkey rsa:2048 -nodes -keyout cert.key

Warning

Never share your private key. It might be advisable to encrypt the key at rest.

Step 2: Exchange the CSR for an certificate

Yanzi exposes a REST-endpoint for performing certificate issuance. Key details are:

Endpoint: https://webportal.yanzi.se/portal/cop/signing/device
Http Method: POST
Required header:
    Content-Type: application/json
Request Body:
{
    "did": "some-unique-device-id",
    "yanziId": "mattias@yanzi.se",
    "password": "great_password",
    "csr": <contents of the cert.csr file from step 1>
}

A typical successful response:

{
    "status": "ACCEPTED",
    "certificateChain": "-----BEGIN CERTIFICATE ..."
}

To use the result, save the certificate chain to a file such as cert.crt.

Authenticating to cirrus using mTLS

mTLS is supported in most standard libraries. Here follows a short example of a node.js project using the files generated in the previous chapter to open a connection to cirrus.

Warning

Not all api gateways(cirrus servers) support mTLS. Check with yanzi which cirrus server you should be using.

const WebSocket = require('ws');
const fs = require('fs')

const ws = new WebSocket('wss://cirrus22.yanzi.se/cirrusAPI', {
    key: fs.readFileSync('cert.key'),
    cert: fs.readFileSync('cert.crt'), //Contents of the certificateChain response earlier
});

ws.on("message", function (response) {
    // Pretty print the message
    console.log(JSON.stringify(JSON.parse(response), null, 4))
})

ws.on("open", function () {
    // When the connection is opened, we're already logged in!
})