Kazoo Multi Factor Authentication

Overview

Integrating Kazoo to MFA providers to secure accessing the Crossbar API endpoints. Users are authenticating with their usual Kazoo credentials and then will be authenticated through a second factors like a pin code recieved by text message or a phone call or a push notification.

Caution: Please make sure that NTP service is configured on Kazoo servers and that your server's time is correct! Otherwise MFA request would be failed or would be invalid.

Multi Factor Authentication flow

MFA process involves these steps:

  1. Initiate the authentication with your auth module/method with your user name and password (or token) as before.
  2. If the auth method that you are using is configured to preforms the multi factor it goes to kazoo multi factor auth to process the request.
  3. Based on auth module configuration, MFA provider settings will be fetched either from account's that have configured the auth module or from default provider in system_auth
  4. If no MFA provider configuration was found, the auth request will be successful and a token will be generated as a normal auth-request as before
  5. If the MFA provider is disabled based on the configuration, a HTTP 401 unauthorized error will be returned.
  6. Provider module will try to validate the request and settings and return a HTTP 401 unauthorized if some parameters is invalid and provide an appropriate error message.
  7. If the request doesn't have a response from MFA provider (if there is no multi_factor_response inside the body of the request) it will generate the required information that the client needs to preform second-factor auth with the provider. Crossbar will reply a HTTP 401 unauthorized with the payload simliar to this:
{
  "data": {
    "messages": "client needs to preform second-factor authentication",
    "multi_factor_request": {
      "provider_name": "{PROVIDER_NAME}",
      "settings": {
        //any arbitrary data from the multi factor provider
      }
    }
  }
}
  1. After the client performed the MFA with the provider, it should issue the same auth request this time with payload included the response from MFA provider
  2. In this second request, kazoo provider module will try to verifying the request and provider response, if the provider response that user is claiming could be verified the request will be authorized and a token will be generated as before. Otherwise a HTTP 401 unauthorized error will be returned.

Where provider configuration comes from

If mfa_option is not present in the Claims or settings could not be fetched from Account's database the system default provider settings from system_auth will be used (which by default has an empty settings). Otherwise the Account's settings will be used.

System config auth/default_multi_factor_provider contains the name of the default MFA provider for fetching the default provider settings.

Multi Factor Providers

Duo Two-Factor Authentication

Two-factor authentication with Duo makes it easy to add strong two-factor authentication to Kazoo. Users can receive a text message, a phone call or push notification to their Duo mobile application.

Before you begin
  1. Sign up for a Duo account.
  2. Log in to the Duo Admin Panel and navigate to Applications.
  3. Click Protect an Application and locate Web SDK in the applications list. Click Protect this Application to get your Integration Key (IKey), Secret Key (SKey), and API Hostname. (See Duo's Getting Started for more help)
  4. Generate a strong application key with a python code like below:
import os, hashlib
print hashlib.sha1(os.urandom(32)).hexdigest()
Authenticate Users using Kazoo Duo integration
  1. Use Crossbar multi factor API endpoint to configure Duo by you IKey, SKey, AKey, API hostname.
  2. Enable multi factor (See Crossbar Auth Config) for a Crossbar auth module.
  3. Users can now use a usual Crossbar authentication procedure (for example with cb_user_auth).
  4. Kazoo auth MFA and Crossbar will return sig_request and api_hostname to client.
  5. Use Duo-Web-v2.js to implement Duo client side for performing 2FA authentication. See Duo Web (steps 3 and beyond in Instructions section).
  6. Send back the Duo response to kazoo by repeating the auth request in step 3 by adding multi_factor_response as payload.
  7. If sig_response is valid, user's will be authenticated and a token will be generated, otherwise a HTTP 401 unauthorized will be returned.
# Sample Duo configuration (see step 1 above)
{
  "data": {
    "provider_name": "duo",
    "provider_type": "multi_factor",
    "enabled": true,
    "settings": {
      "integration_key": "{YOUR_DUO_IKEY}",
      "secret_key": "{YOUR_DUO_SKEY}",
      "application_secret_key": "{YOUR_DUO_AKEY}",
      "api_hostname": "{YOUR_API_HOSTNAME}",
      "duo_expire": 300, //optional
      "app_expire": 3600 //optional
    }
  }
}
# Crossbar return sig_request (see step 4 above)
{
  "data": {
    "messages": "client needs to preform second-factor authentication",
    "multi_factor_request": {
      "provider_name": "duo",
      "settings": {
        "duo_sig_request": "{SIG_REQUEST}",
        "duo_api_hostname": "{YOUR_DUO_API}"
      }
    }
  }
}

Which sig_request is a string similar to TX|dGVzdHVzZXJ8RElYWFhYWFhYWFhYWFhYWFhYWFh8MTQ4Njc2OTgwOQ==|28af5ae63742cfc52f36002a146ee181326cd40d:APP|dGVzdHVzZXJ8RElYWFhYWFhYWFhYWFhYWFhYWFh8MTQ4Njc2OTgwOQ==|1f02e643de667f188f409a13b7770dce0a1be777.

Notice the TX and APP parts which separated by :. You need the APP part later to merge it with response from Duo when you're sending it to Kazoo.

# Client sends Duo response to Kazoo with this payload

Duo will authenticate user by the whatever methods user has chosen and then will respond to Duo JavaScript client with a payload similar to this:

{
    "response":{
        "cookie": "AUTH|dGVzdHVzZXJ8RElYWFhYWFhYWFhYWFhYWFhYWFh8MTYxNTcyNzI0Mw==|d20ad0d1e62d84b00a3e74ec201a5917e77b6aef",
        "result": "SUCCESS",
        "reason": "User approved",
        ....
    },
    "stat": "OK"
}

You need to merge cookie with APP from previous part and send it to Kazoo with a payload like below.

{
  "data": {
    "multi_factor_response": "AUTH|dGVzdHVzZXJ8RElYWFhYWFhYWFhYWFhYWFhYWFh8MTYxNTcyNzI0Mw==|d20ad0d1e62d84b00a3e74ec201a5917e77b6aef:APP|dGVzdHVzZXJ8RElYWFhYWFhYWFhYWFhYWFhYWFh8MTQ4Njc2OTgwOQ==|1f02e643de667f188f409a13b7770dce0a1be777",
  }
}

Notice that the cookie Duo sent to you (AUTH|...|...) was merged with APP|...|... from previous step (separated with a colon): AUTH|...|...:APP|...|....

Edit this page here