MFA Guides

MFA / API Documentation

The majority of the below code can be reviewed in InstallPath\SelfServiceSite\assets\self-service-portal-****randomguid***.js if clarification is needed.

Return of user enrolled methods GET

The path: https://servername.fqdn.etc/api/v1/users/, followed by the username/domain (https://servername.fqdn.etc/api/v1/users/epsilon/2faone) could return JSON data similar to what is shown below:

{
    "data":{
        "type":"user",
        "userId":6,
        "username":"epsilon",
        "domain":"2FAONE",
        "authMethods"{
            {
                "type":"authMethod",
                "authMethodId":2,
                "displayName":"AD",
                "pinRequired":false,
                "pinLabel":""},
            {
                "type":"authMethod",
                "authMethodId":10,
                "displayName":"OTP",
                "pinRequired":false,
                "pinLabel":"PIN"},
            {
                "type":"authMethod",
                "authMethodId":11,
                "displayName":"PingMe",
                "pinRequired":false,
                "pinLabel":""
            }
        ]
     }
} 

UserID being their UserID in our database. AuthMethods returned are only the available enrolled auth methods, any non enrolled methods are omitted.

Curl Example for user 2faone\conroe

curl -X GET \
  https://dev.cloud.2fa.com/api/v1/users/conroe/2faone \
  -H 'Postman-Token: 131472dc-7e45-4a21-9a7d-f73354d33bfe' \
  -H 'cache-control: no-cache'Response ---  200 OK
{
    "data": {
        "type": "user",
        "userId": 80,
        "username": "conroe",
        "domain": "2FAONE",
        "authMethods": [
            {
                "type": "authMethod",
                "authMethodId": 2,
                "authProfileId": 0,
                "displayName": "AD",
                "pinRequired": false,
                "pinLabel": ""
            },
            {
                "type": "authMethod",
                "authMethodId": 10,
                "authProfileId": 13,
                "displayName": "OTP",
                "pinRequired": true,
                "pinLabel": "PIN"
            },
            {
                "type": "authMethod",
                "authMethodId": 11,
                "authProfileId": 0,
                "displayName": "PingMe",
                "pinRequired": false,
                "pinLabel": ""
            },
            {
                "type": "authMethod",
                "authMethodId": 15,
                "authProfileId": 12,
                "displayName": "FIDO",
                "pinRequired": true,
                "pinLabel": "PIN"
            }

        ]
    }
}

Note

NOTE: The information for all active users in the database will be returned. The default authentication set and a userID outside of the range of existing IDs will be returned for any nonexistent users.

Authenticate a User to Generate an AuthToken

https://servername/api/v1/authenticate/<methodID>

Currently Supported Method IDs:

  • 1 RapidIdentity Password

  • 2 AD

  • 6 Contactless Card

  • 10 OTP

  • 11 PingMe

  • 15 FIDO

Body

{
    "userId": “<the user id received from the api/v1/user call>",
    "methodId": “<the method id as listed above>",
    "firstData": “<whatever is the default auth data required, e.g. card number, bio template, etc. - for PingMe it can just be an empty string or put in the words “PingMe">",
    "secondData": “<whatever is the second factor required, if required, e.g. PIN - for PingMe it can just be an empty string or put in the words “PingMe”>"
}
Response 200 OK
{
    "data": {
        "type": "authToken",
        "authToken": "<example string21176a8a-9738-4997-ad75-68c3a6a59772>",
        "userId": 80
    }
}
Curl Examples

Example for Password

curl -X POST \
  https://dev.cloud.2fa.com/api/v1/authenticate \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: ca71d64e-0739-4ba5-8ead-0cc30005c8b9' \
  -H 'cache-control: no-cache' \
  -d '{"userId":"80",
"methodId": "2",
"firstData":"<string>",
"secondData":"" }'

Example Authenticate Card

curl -X POST \
  https://dev.cloud.2fa.com/api/v1/authenticate \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: fb50f1db-3ad7-4188-ad40-43783568db6e' \
  -H 'cache-control: no-cache' \
  -d '{"userId":"80",
"methodId": "6",
"firstData":"049D651AB95380",
"secondData":"124578" }'

Method ID 6 = contactless

firstData = CUID of card submitted as read by Active X plugin

secondData = user pin submitted if required. Leave blank if no PIN required

Example Authenticate PING

curl -X POST \
  https://dev.cloud.2fa.com/api/v1/authenticate \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 0a802514-f7b7-42d9-8d7f-3ff35f7b1ae8' \
  -H 'cache-control: no-cache' \
  -d '{"userId":"80",
"methodId": "11",
"firstData":"PingMe",
"secondData":"" }'

firstData will be static PingMe

SecondData = is user PIN.

If no PIN is submitted, ping will automatically send. If PIN is submitted incorrectly, no PING will be sent and 403 will return.

Example for OTP

curl -X POST \
  https://dev.cloud.2fa.com/api/v1/authenticate \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: c1c5cf29-cb58-4f65-a0e1-0d6b41982c83' \
  -H 'cache-control: no-cache' \
  -d '{"userId":"80",
"methodId": "10",
"firstData":"4312765",
"secondData":"" }'

firstData is users OTP or a valid auth tokenSecond data is user PIN -- not required for AuthCode

Ex Authenticate RapidIdentity password

curl -X POST \
  https://dev.cloud.2fa.com/api/v1/authenticate \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 0fbb8de1-76be-4352-9f7c-3f8b4e8a089f' \
  -H 'cache-control: no-cache' \
  -d '{"userId":"1",
"methodId": "1",
"firstData":"<string>",
"secondData":"" }'

GET Credential

When authenticated with AuthToken, should return users enrolled credentials with device IDs. This can be used to display all enrolled devices for a user. Headers must include a valid userID and AuthToken combination.

curl -X GET \
  https://dev.cloud.2fa.com/api/v1/credentials \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 1ea78200-3ecc-480d-8070-90da1ded2ba9' \
  -H 'authToken: 0b05c0b2-0372-4c7c-a787-6a5c2f987fb5' \
  -H 'cache-control: no-cache' \
  -H 'userID: 80'

Response 200 OK

Example for Response

[
    {
        "type": "credential",
        "authMethodId": 2,
        "deviceId": 80,
        "displayName": "2FAONE\\conroe",
        "credentialData": ""
    },
    {
        "type": "credential",
        "authMethodId": 10,
        "deviceId": 10039,
        "displayName": "5568ef96b1a81528",
        "credentialData": "Soft Token"
    },
    {
        "type": "credential",
        "authMethodId": 10,
        "deviceId": 61603,
        "displayName": "1113",
        "credentialData": "Hard Token"
    },
    {
        "type": "credential",
        "authMethodId": 15,
        "deviceId": 80186,
        "displayName": "Gorp",
        "credentialData": ""
    }
]

Deleting User Credentials

HTTPDELETE

servername/api/v1/credentials/<methodID>/<deviceID>

Valid userID and AuthToken must be submitted in headers

Method ID and Device ID can be retrieved from /credentials GET

BODY should be empty

Response 200 OK

{
    "data": [
        {
            "type": "credential",
            "authMethodId": <methodID>,            "deviceId": <deviceID>,
            "displayName": "<string>",
            "credentialData": "Soft Token"
        }
    ]
}

Above data is returned if additional deviceIDs of same method exist
OR  If no other devices of same method ID exist
{
    "data": []
}

curl -X DELETE \
  https://dev.cloud.2fa.com/api/v1/credentials/10/61603 \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 1d0eb191-39e5-40f1-b375-ddd88e33bcdd' \
  -H 'authToken: 4b607dc7-4f7f-4216-976d-76b107209d13' \
  -H 'cache-control: no-cache' \
  -H 'userID: 80' \
  -d '  '

Manually nullify Auth Token -- POST

Post to api/v1/authenticate/logout with userId and authToken to kill in header

Auth token expiration apllies otherwise from Database Settings table

dbo.Settings

AuthTokenAbsoluteExpirationTime = time in seconds until authtoken is invalidated regardless of inactivity

AuthTokenExpirationTime = time in seconds until authtoken is invalidated due to inactivity

Enroll a credential -- POST

api/v1/credentials/methodID

Example for Contactless

api/v1/credentials/6

 {
        "userId": 80,
        "methodId": 6,
        "credData": {
        	"cuid": "049d651ab95380AAAA",
        	"pin" : "1245",
        	"label": "HereisFre"}
}

Cuid = cuid of card as read by Active X Plugin

Pin = user PIN to be submitted

Note

If omitted and UseGlobalPIN = true in Settings table, pin set in user’s OTP data will be automatically submitted as the PIN.

Label = Users choice for card name, may be left blank

GET /api/v1/credentials/6 HTTP/1.1

Host: dev.cloud.2fa.com

authToken: 21176a8a-9738-4997-ad75-68c3a6a59772

userID: 80

Content-Type: application/json

cache-control: no-cache

Postman-Token: 0d7ed2e7-aea0-4eba-8d44-2732d9448291

 {
        "userId": 80,
        "methodId": 6,
        "credData": {
        	"cuid": "049d651ab95380AAAA",
        	"pin" : "1245",
        	"label": "HereisFre"}
}------WebKitFormBoundary7MA4YWxkTrZu0gW--

Enroll OTP

{
                    "userId": “80”,
                    "methodId": "10",
                    "credData": {
                        "serial": “<serialnumberOfOTP”,
                        "otp1": “111222”,
                        "otp2": “222333”,
                        "pin": “1245”
                    }

curl -CX POST\

  https://dev.cloud.2fa.com/api/v1/credentials/10 \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: d7ada9ac-7f0c-4109-a94c-fa7b797dd32d' \
  -H 'authToken: ae6494a4-3899-4293-a130-4a00cf3fd259' \
  -H 'cache-control: no-cache' \
  -H 'userID: 80' \
  -d '{
                    "userId": “80”,
                    "methodId": "10",
                    "credData": {
                        "serial": “<serialnumberOfOTP”,
                        "otp1": “111222”,
                        "otp2": “222333”,
                        "pin": “1245”
                    }                    
'

Response 200 OK

Or

Response 400 Bad Request

{
    "Message": "Could not process request"
}

Indicates that OTPs submitted failed to validate

Return Custom Links

Using the self-service APIs, after a user has a authenticated login, call /users/customlinks. If the user is in an admin-type role then the response will include an URL to the admin portal and a label.

Examples of admin-type roles

Manage_Authentication_Methods, Manage_Authentication_Sets, Manage_Roles, Manage_Users, Manage_Reports, Manage_Clients, or Configure_CM

Example response to /users/customlinks

{
 “data”:[
    {
    “url”:“https://mfaqa.cloud.2fa.com/ONE/admin_portal/validateAuthToken.aspx?token=dd60e583-cadb-47f5-8182-f6fbbd599d71&id=1“,
       “label”:“Admin Portal”
    }
 ]
}

submit USERID and AuthToken headers

curl -X GET \
  https://dev.cloud.2fa.com/api/v1/users/customlinks \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: bd6f5cb7-025d-4902-aa9d-802679c0aae7' \
  -H 'authToken: 01f25269-7e5e-4589-a741-39f5e932abcc' \
  -H 'cache-control: no-cache' \
  -H 'userID: 1'

Response 200 OK

{
    "data": [
        {
            "url": "https://dev.cloud.2fa.com/ONE/admin_portal/validateAuthToken.aspx?token=01f25269-7e5e-4589-a741-39f5e932abcc&id=1",
            "label": "Admin Portal"
        }
    ]
}

Note

Above response reads Admin Portal URL from dbo.Settings and provide link allows user to login directly to Admin portal

Response 403 Forbidden

Auth token is invalid for userID provided