CM Authenticator
CM Authenticator

Introduction

CM Authenticator is an easy to use authentication product that ensures the identity of your online users by adding an extra factor of authentication via the mobile phone.

When a user tries to login on your environment, the extra authentication will be presented to verify their attempt. The user can approve or deny this request instantly and securely via the CM Authenticator app on their smartphone. If there is no app available, an SMS can be received instead. Once the attempt has been approved, the user can then safely proceed.

Prerequisites

Authentication flow

Instant:

  1. Create an instant authentication request
    • User has the app installed, but not your environment added? A QR code image will be returned.
  2. The API will deliver it to the user via SMS or push
  3. Check the authentication status:
    • Listen for changes using the WebSocket and verify the JWT
    • Checking the status manually
  4. If approved, grant the user access

OTP:

  1. Create an OTP authentication request
  2. The API will deliver it to the user via SMS or push
  3. The user enters the OTP
  4. Verify the OTP
  5. If correct, grant the user access

API implementations

Request requirements

The API endpoint is https://api.auth.cmtelecom.com/authenticator/v1.0 and will be called BASE_URL.

To verify requests, the Authorization header is used. This header contains a JSON Web Token and follows the format: Authorization: Bearer JWT_TOKEN.

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA.

More about JWT and a list of implementing libraries: jwt.io.

JWT structure

JWT's are signed using the HMAC-SHA256 algorithm and your environment secret as the key.

Header:

{
  "alg": "HS256",
  "typ": "JWT"
}

Required:

  • alg = algorithm: must be set to HS256 (HMAC SHA-256)
  • typ = type: must be set to JWT

Payload:

{
  "iat": 1483228800,
  "nbf": 1483228800,
  "exp": 1483228860,
  "sig": "b648d17f048ec72f7e54b107faa2c87625ae9d639734cc5f978194e5d3a0c211",
  "auth_id": "2b1f49da-b05d-4f46-ec2f-3668d976fd2c"
}

Required:

  • iat = issued at: claim identifies the time at which the JWT was issued.
  • nbf = not before: claim identifies the time before which the JWT MUST NOT be accepted for processing.
  • exp = expiration time: claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.

Depends on request (may be optional or required):

  • sig = signature: the SHA-256 HMAC of the raw JSON body used to verify the integrity of the request body. Use your environment secret for the HMAC secret.
  • auth_id = authentication ID: the ID of the authentication request

Authentication request

Create an authentication request

URL: BASE_URL/auth_type
Method: POST

Where auth_type is the authentication type:

  • instant: Send a push notification or SMS link where the user can approve or deny the authentication request.
  • otp: Send a One-Time Password code which the user has to enter on your website.

Headers:

Authorization: Bearer JWT_TOKEN
Content-Type: application/json

JWT fields:
sig (required)

Body:

{
    "environment_id": "f5b25bd3-c922-4797-95e7-7d51368607e6",
    "phone_number": "+31601234567",
    "message_type": "auto",
    "expiry": 30,
    "ip": "203.0.113.1"
}

Parameters:

  • environment_id: The ID of the environment, you obtain this from the dashboard.
  • phone_number: The phone number in the international E.164 format.
  • message_type (optional):
    • auto (default): It will automatically determine the message type. When the authentication request cannot be delivered as a push message, it will fallback to SMS.
    • push: Only sent the authentication using a push message, no fallback to SMS.
    • sms: Only sent the authentication request using SMS.
  • expiry: The validity period of the authentication request in seconds.
  • ip: The IP-address of the user, used to determine its location.
  • callback_url (optional): The URL to receive authentication status updates on. This URL must support JSON POST requests. The structure of the request is:
{
    "auth_id":"75a0bd86-e52b-6f50-5ee4-e6c6f95616fa",
    "auth_status":"approved",
    "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoX2lkIjoiMTdkNmE4OTItMGJlNS0zOGYzLWYwMmUtOG..."
}

The field token is a JWT token that can be used to verify the request. Use your environment secret for the JWT secret.

Response:

{
    "id": "2b1f49da-b05d-4f46-ec2f-3668d976fd2c",
    "environment": {
        "id": "f5b25bd3-c922-4797-95e7-7d51368607e6",
        "name": "MaxCorp"
      },
    "phone_number": "+31601234567",
    "auth_type": "instant",
    "message_type": "auto",
    "auth_status": "open",
    "expiry":60,
    "ip": "203.0.113.1",
    "created_at": "2017-01-01T00:00:00+00:00"
}

The field auth_status can have one of the following statuses:

  • open: The authentication is generated and is waiting for a response.
  • approved: The authentication has been approved.
  • denied: The authentication has been denied.
  • expired: The authentication has expired.
  • failed: There was an error while sending the notification.

Update authentication request (instant)

URL: BASE_URL/instant/auth_id
Method: PUT

Headers:

Authorization: Bearer JWT_TOKEN
Content-Type: application/json

JWT fields:
auth_id (required)
sig (optional)

Body:

{
    "auth_status":"approved"
}

Parameters:

  • auth_status: The status of an authentication request. It must be either approved or denied.

Response:

{
  "id": "4fa441d8-41d3-ddd4-e409-d63faa143d22",
  "environment": {
    "id": "f5b25bd3-c922-4797-95e7-7d51368607e6",
    "name": "MaxCorp"
  },
  "phone_number": "+31601234567",
  "auth_type": "instant",
  "message_type": "sms",
  "auth_status": "approved",
  "expiry": 600,
  "ip": "203.0.113.1",
  "created_at": "2017-01-01T00:00:00+00:00"
}

Update authentication request (OTP)

URL: BASE_URL/otp/auth_id
Method: PUT

Headers:

Authorization: Bearer JWT_TOKEN
Content-Type: application/json

JWT fields:
auth_id (required)
sig (optional)

Body:

{
    "pin":"12345"
}

Parameters:

  • pin: The One-Time-Password code

Response:

{
  "id": "4fa441d8-41d3-ddd4-e409-d63faa143d22",
  "environment": {
    "id": "f5b25bd3-c922-4797-95e7-7d51368607e6",
    "name": "MaxCorp"
  },
  "phone_number": "+31601234567",
  "auth_type": "otp",
  "message_type": "sms",
  "auth_status": "approved",
  "expiry": 600,
  "ip": "203.0.113.1",
  "created_at": "2017-01-01T00:00:00+00:00"
}

Retrieve information about an authentication request

URL: BASE_URL/auth_type/auth_id
Method: GET

Headers:

Authorization: Bearer JWT_TOKEN

JWT fields:
auth_id (required)

Response:

{
  "id": "a8f0e833-ad04-83a6-7c51-93c6a3a6bc70",
  "environment": {
      "id": "f5b25bd3-c922-4797-95e7-7d51368607e6",
      "name": "MaxCorp"
  },
  "phone_number": "+31601234567",
  "auth_type": "instant",
  "message_type": "sms",
  "auth_status": "open",
  "expiry": 600,
  "ip": "203.0.113.1",
  "geoip": {
    "country_code": "NL",
    "region": "North Brabant",
    "city": "Breda",
    "latitude": 51.5719,
    "longitude": 4.7683
  },
  "created_at": "2017-01-01T00:00:00+00:00"
}

Listen for authentication request status updates

WebSocket location: https://status.auth.cmtelecom.com/auth/v1.0/ws

Upon opening the WebSocket connection, send this JSON message to subscribe for status changes for a specific authentication request:

{
   "type": "subscribe",
   "auth_id": "e1f9f988-1322-4f78-9e3f-1f3ccfa13506"
}

When the user approves or denies the authentication request you will receive a message with the following structure:

{
    "auth_id":"e1f9f988-1322-4f78-9e3f-1f3ccfa13506",
    "auth_status":"approved",
    "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoX2lkIjoiYmJhZjczMWMt..."
}

The field token is a JWT token. Verify the JWT token with your environment secret, to confirm it's coming from the Authenticator API. JWT token also contains the fields: auth_id and auth_status.

QR code

URL: BASE_URL/qr/qr_id
Method: GET

Response type: image/png
Content: environment_id,device_environment_secret