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.
Instant:
OTP:
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'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 JWTPayload:
{
"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 requestURL: 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.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"
}
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 codeResponse:
{
"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"
}
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"
}
WebSocket location: https://status.auth.cmtelecom.com/authenticator/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.
You can implement CM Authenticator within your own app with the help of a software development kit (SDK)
The SDK's are available on GitHub:
iOS SDK: https://github.com/cmdisp/authenticator-sdk-ios
Android SDK: https://github.com/cmdisp/authenticator-sdk-android
URL: BASE_URL/qr/qr_id
Method: GET
Response type: image/png
Content: environment_id,device_environment_secret