Introduction


# Use rubygems

gem install auth-armor


# Or use bundler

gem 'auth-armor'


# Then require the gem.

require 'auth-armor'

Auth Armor turns smart mobile devices into modern secure authenticators preventing attacks and un-authorized access.

Passwords and shared secrets are outdated and insecure. Account take-overs, password theft and breaches cost billions each year and are getting worse.

Use Auth Armor to protect websites, apps, backoffice and more with our simple API. Get running in minutes.

Authorization

To obtain an Access token, you must make a request to the Auth Armor OAuth2 server using the client_credentials OAuth2 grant.

Request

curl -X POST 
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
https://login.autharmor.com/connect/token

require "auth-armor"
AuthArmor::Client.new(client_id: "CLIENT_ID", client_secret: "CLIENT_SECRET")

<?php
  // Place your credentials in autharmor_creds.php. File should contain the following 3 lines:
  $this->client_id = "YourClientID";
  $this->client_secret = "YourClientSecret";
?>

Param	Required	Description
client_id	Yes	Client ID from Auth Armor
client_secret	Yes	Client Secret from Auth Armor
scope	No	Permissions that the token will be allowed to perform

Response

{
  "access_token":"eyJhbGciOiJSUzI1N...",
  "expires_in":600,
  "token_type":"Bearer",
  "scope":"aarmor.api.generate_invite_code aarmor.api.request_auth"
}

API Access

Both the client_id and client_secret are obtained via the developer dashboard located at https://dashboard.autharmor.com

Login then select or create a project. Navigate to the Api Access section and create a new api client. when you create a client, you are asked to give the client permissions, or scopes; select one more more scopes here. Please see the scopes section for more info. After client creation, you will be presented with a client_id and client_secret. Copy these values into your request.

Scopes

Scopes are permissions that the token will be allowed to perform. There are two scopes allowed. They are aarmor.api.generate_invite_code and aarmor.api.request_auth. When you create an api access client, you will be asked to select what scopes the client is allowed to perform. When requesting a token using that client, you can optionally leave the scope field blank. If left blank, all of the scopes that are assigned to the client will be applied to the token. If you specify the scopes in the token request, the token will then only have the scopes that were requested.

The access token returned will be used as a Bearer token for all the other requests.

Send Invite

Request


curl -XPOST
-H 'Authorization: Bearer TOKEN'
-H "Content-type: application/json"
-d '{
  "nickname": "john_doe",
  "reference_id": "123456789"
}'
'https://api.autharmor.com/invite/request'

AuthArmor::Client.invite_request(
  nickname: "NICKNAME"
)

<php
  AuthArmor->invite_request(nickname: "NICKNAME")
?>

Before you can send auth requests, you must invite users to your project. You can use the invite API to request an invite, then send to your users. Auth Armor supports two ways users can be invited. Either methods first needs a call to the Auth Armor invite API

Param	Required	Description
nickname	Yes	This is a friendly display name for your user. It would be best to set the nickname to the username value or something similar so you can relate to your system. If your usernames are email addresses, consider masking the email address before using as a nickname to avoid personal information being stored in Auth Armor. You can search history using this ID
reference_id	No	This is an optional value that you can set to further cross reference your records. For example, you could set this value to your unique value in your system such as a UUID, a row ID, or some other value. You can search history using this ID.
reset_and_reinvite	No	Default is false. If you need to reset the current user and reinvite, set this flag to true. This will remove all mobile devices and/or active pending invites and create a new invite. Use caution when using this - it will reset any existing user with this nickname

QR code

AuthArmor::Client.generate_qr_code

Example

To use the QR code format, please format a json payload like below:

{
  "type":"profile_invite",
  "version":1,
  "format_id":1,
  "payload": {
    "aa_sig": "AA_SIG",
    "invite_code":"INVITE_CODE"
  }
}

A QR code can be generated and then scanned, much like many of the other authenticators out there. In the app, a user simply needs to scan the QR code to get setup for your project.

Then generate a QR code using this payload text. The QR code can then be scannedin the app

Invite link

AuthArmor::Client.get_invite_link

Example

https://invite.autharmor.com/?i=aacc137b-e13e-4f35-9d3b-402d530d954c&aa_sig=6036145BEB43D02F61F5D41CE43F8BA5858ECBC2ED4AA7F35C8176BE37B92E68

In this method, the user can either click a link and follow invite instructions, or by using our client SDK, you can open a small pop-up window that will drive the invite process.

Invite Link format:

https://invite.autharmor.com/?i=INVITE_CODE>&aa_sig=AA_SIG

Response

Response

{
    "nickname": "sample test",
    "auth_profile_id": "706751cf-012d-4576-b639-654d0dfbdb5c",
    "invite_code": "43748ae...",
    "date_expires": "2020-07-11T17:18:56.3058075Z",
    "invite_type": "WebInviteAndOrQRCode",
    "aa_sig": "6433C0A...."
}

Param	Description
nickname	Echoing back this value from the request.
auth_profile_id	This is the ID you will use to send an auth request. You must save this ID somewhere with your user records
invite_code	This is the unique invite code for this invite.
date_expires	This is when the invite will expire
invite_type	This is the invite type, right now, the only option is "TBD".
aa_sig	This is a special signature check value that helps prevent abuse.

Push Request

This is the API Endpoint to use for sending an auth request to your user(s).


curl -XPOST
-H 'Authorization: Bearer TOKEN'
-H "Content-type: application/json"
-d '{
  "nickname": "sample_user",
  "action_name": "Login",
  "short_msg": "Login requested detected from IP: 192.160.0.1",
  "nonce": "some unique value of your choice here"
  }'
'https://api.autharmor.com/auth/request'

AuthArmor::Client.auth_request(
  nickname: "sample_user",
  action_name: "Login",
  short_msg: "This is a test message",
  nonce: "some unique value of your choice here"
)

<?php
  AuthArmor->auth_request(
    nickname: "sample_user",
    action_name: "Login",
    short_msg: "This is a test message",
    nonce: "some unique value of your choice here"
  )
?>

Param	Required	Description
nickname	Yes	The nickname for the user you want to send this auth request to.
action_name	Yes	This is the action name that shows up in the push notification. This is the action the user is approving. Examples: “Login”, “Money Transfer”, “Account update”, etc. The min length is 2, and the max length is 25.
short_message	Yes	This is the short message that will appear in the app under the action name.
nonce	No	An optional value that is signed and returned in the request. This helps validate the response was from your request and no one has done a man-in-the-middle attack.
timeout_in_seconds	No	This is the amount of time you want to allow the auth to be valid before it expires. The min is 15, and max is 300. This is optional, and if not provided, will use the default time for the project.
accepted_auth_methods	No	This is an optional field. If you do not send it, Auth Armor will allow any type of auth method, including biometric, security key or even pin fall back from non-biometric devices.
origin_location_data	No	You can specify location data in the format of latitude and longitude. If provided, location details will show in the push message about the origin of the request.

If you send accepted_auth_methods param, you must provide a rule to go along with it. The accepted auth methods currently supported are: mobileDevice and securityKey.

Mobile Device

Using Mobile Device


curl -XPOST
-H 'Authorization: Bearer TOKEN'
-H "Content-type: application/json"
-d '{
  "nickname": "sample_user",
  "action_name": "Login",
  "short_msg": "Login requested detected from IP: 192.160.0.1",
  "nonce": "some unique value of your choice here",
  "timeout_in_seconds": "120",
  "accepted_auth_methods": [
      {
        "name": "mobiledevice",      
        "rules": [
          {
            "name": "forcebiometric",
            "value": "true"
          }
        ]
      }
    ]
  }'
'https://api.autharmor.com/auth/request'

AuthArmor::Client.auth_request(
  nickname: "sample_user",
  action_name: "Login",
  short_msg: "This is a test message",
  nonce: "some unique value of your choice here",
  accepted_auth_methods: "mobiledevice",
  forcebiometric: true
)

<?php
  AuthArmor->auth_request(
    nickname: "sample_user",
    action_name: "Login",
    short_msg: "This is a test message",
    nonce: "some unique value of your choice here",
    accepted_auth_methods: [{
      "name": "mobiledevice",
      "rules": {
        "name": "forcebiometric",
        "value": true
      }
    }]
  )
?>

The current rules for mobileDevice are forceBiometirc. This can either be set to true or false.

If forceBiometric is set to true, a mobile device will be required and biometrics will be required. Pin fallback and non-biometric devices will not be compatible with this method. Only biometrics, such as fingerprint or faceID will be allowed.

If forcebiometric is set to false, then a mobile device must be used, and a security key will not be allowed. Pin fallback and non-biometric devices using a pin will also be allowed

Security Key

Using Security Key


curl -XPOST
-H 'Authorization: Bearer TOKEN'
-H "Content-type: application/json"
-d '{
  "nickname": "sample_user",
  "action_name": "Login",
  "short_msg": "Login requested detected from IP: 192.160.0.1",
  "nonce": "some unique value of your choice here",
  "timeout_in_seconds": "120",
  "accepted_auth_methods": [
      {
        "name": "securitykey"     
      }
    ]
  }'
'https://api.autharmor.com/auth/request'

AuthArmor::Client.auth_request(
  nickname: "sample_user",
  action_name: "Login",
  short_msg: "This is a test message",
  nonce: "some unique value of your choice here",
  accepted_auth_methods: "securitykey"
)

<?php
  AuthArmor->auth_request(
    nickname: "sample_user",
  action_name: "Login",
  short_msg: "This is a test message",
  nonce: "some unique value of your choice here",
    accepted_auth_methods: [{
      "name": "securitykey"
    }]
  )
?>

At this time, there are no rules for security keys.

If you set to security key, then mobile device will not be allowed, meaning no pin or biometrics are performed. Only a security key will be allowed. At this time, Auth Armor is using U2F. Full FIOD2 with user presence is coming soon.

Response

Param	Description
auth_history_id	This is the unique ID for the auth request.
response_code	The response code result – 0 = unknown, 2 = success, 3 = declined, 4 = possible fraud attempt, 5 = timeout.
response_message	The text representation of the result code.
authorized	Boolean – if the auth request is authenticated.
auth_details	Auth detail object, request and response details. More details defined in the table below.

Mobile Device Response


{
    "auth_history_id": "36f0d...",
    "response_code": 2,
    "response_message": "Success",
    "authorized": true,
    "auth_details": {
        "request_details": {
            "date": "2020-07-11T17:09:44.7860965Z",
            "auth_profile_details": {
                "auth_profile_id": "706751cf-012d-4576-b639-654d0dfbdb5c",
                "nickname": "john_doe",
                "ref_id": "123456789"
            },
            "origin_location_data": {
                "latitude": null,
                "longitude": null
            },
            "accepted_auth_methods": [
                {
                    "name": "MobileDevice",
                    "rules": [
                        {
                            "name": "ForceBiometric",
                            "value": false
                        }
                    ]
                }
            ]
        },
        "response_details": {
            "date": "2020-07-11T17:09:53.3862361Z",
            "auth_method": {
                "name": "MobileDevice",
                "usetype": "biometric"
            },
            "secure_signed_message": {
                "signed_data": "eyJtZXNzYWdlX2RhdGEi.....",
                "signature_data_details": {
                    "hash_value": "20bc1578...",
                    "signature_data": "{\"signature_data\":{\"counter\":17,\"signature_value\":\"MEUCIH...=\",\"challenge\":\"20bc15....\"},\"metaData\":{},\"version\":1,\"format\":1,\"key_Id\":\"\"}",
                    "auth_method_usetype": "biometric",
                    "signing_method": "AuthArmor_ECDsa",
                    "auth_method": "MobileDevice",
                    "hash_method": "Sha256"
                },
                "signed_data_type": "AuthResponse",
                "signature_validation_details": {
                    "public_key": "MFkwEwYHKoZI....==",
                    "key_size": "256",
                    "key_type": "EC",
                    "signing_algorithm": "SHA256",
                    "curve_type": "secp256r1",
                    "key_format": "x.509"
                },
            },
            "mobile_device_details": {
                "platform": "Android",
                "model": "Samsung A50s"
            }
        }
    }
}

Security Key Response


{
    "auth_history_id": "36f0d...",
    "response_code": 2,
    "response_message": "Success",
    "authorized": true,
    "auth_details": {
        "request_details": {
            "date": "2020-07-11T17:09:44.7860965Z",
            "auth_profile_details": {
                "auth_profile_id": "706751cf-012d-4576-b639-654d0dfbdb5c",
                "nickname": "john_doe",
                "ref_id": "123456789"
            },
            "origin_location_data": {
                "latitude": null,
                "longitude": null
            },
            "accepted_auth_methods": [
                {
                    "name": "SecurityKey",
                    "rules": []
                }
            ]
        },
        "response_details": {
            "date": "2020-07-11T17:09:53.3862361Z",
            "auth_method": {
                "name": "SecurityKey",
                "usetype": "u2f_securitykey"
            },
            "secure_signed_message": {
                "signed_data": "eyJtZXNzYWdlX2RhdGEi.....",
                "signature_data_details": {
                    "hash_value": "20bc1578...",
                    "signature_data": "{\"keyHandle\":\"bIap1cuTOBhl7VDd4Z56rFPkFJL0ow927f1kWI0SC3_oHjuTFxm7OUcHRrfavcjudIAkyuHiIC_WzKPAYaJPdA\",\"clientData\":\"eyJ0eXAiOiJuYXZpZ2F0b3IuaWQuZ2V0QXNzZXJ0aW9uIiwiY2hhbGxlbmdlIjoiNzQyNjJhZDU4NTYzMjQxZjQ0ZjNjNzFmZjZiYjA3MWQ2NDUyNTc5YmQzZjRkZWI4M2UzZmZiYzU1YWU4OThjZSIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOjRqMFpQRFNEMnJSWmlDV0JqR051aFRBNDNCcmZyV0orYitRc2E2aGZkaGsifQ\",\"signatureData\":\"AQAAAIYwRQIgGcCfCahRWxI5NbFvLY_0Nsc0hgAj7I67i9d0f4F3mCoCIQC4oByT5AW2GaqWOjeHLCr9pszmmG9pLqFBQEO7l1arQw\"}",
                    "auth_method_usetype": "u2f_securitykey",
                    "signing_method": "AuthArmor_ECDsa",
                    "auth_method": "SecurityKey",
                    "hash_method": "Sha256"
                },
                "signed_data_type": "AuthResponse",
                "signature_validation_details": {
                    "public_key": "MFkwEwYHKoZI....==",
                    "key_size": "256",
                    "key_type": "EC",
                    "signing_algorithm": "SHA256",
                    "curve_type": "secp256r1",
                    "key_format": "x.509"
                },
            },
            "mobile_device_details": {

            }
        }
    }
}

Auth Details

Param	Description
request_details	Object for all the request details. More details defined in the request details table.
response_details	Object for all the response details. More details defined in the response details table.

Request Details

Param	Description
date	The date the auth request was made.
auth_profile_details	The details of the auth_profile that was targeted. More details defined in the auth profile details table.
origin_location_data	If location data was provided in the request, it is echoed here. More details defined in the location data table.
accepted_auth_methods	The accepted auth methods for this request. If it was provided, these values are echoed back. If not provided, then all methods are echoed back with default rules. More details defined in the accepted auth methods table.

Auth Profile Details

Param	Description
auth_profile_id	Echo back the ID in the request.
nickname	The nickname of the auth_profile record.
ref_id	The ref id of the auth profile record.

Origin Location Data

Param	Description
latitude	Latitude location.
longitude	Longitude location.

Accepted Auth Methods

Param	Description
name	The accepted method name.
rules	The rules for the accepted auth method.

Response Details

Param	Description
date	The date the auth request was responded to.
auth_method	The auth method that was used for the response. If there was a timeout, or declined, this will not be populated. More details defined in the auth method table.
secure_signed_message	An object representing the signed object and cryptographic signature details. More details defined in the secure signed message table.
mobile_device_details	The details of the mobile device that wasused to facilitate the auth. Even if the auth method was security key, there was still a mobile device where the app was installed. More details defined in the mobile devices details table.

Auth Method

Param	Description
name	The name of the auth method used.
usetype	The way the auth method was used. Options for mobile device are: biometric or pin.

Secure Signed Message

Param	Description
signed_data	This is a base64 payload of the data that was signed for the auth request.
signature_data_details	The data that is used to validate the signed data. More details defined in the signature data details table.

Signature Data Details

Param	Description
hash_value	The hashed value of the signed_data base64 data.
signature_data	Dynamic JSON payload with signature data based on the auth method. More details below.
auth_method_usetype	The way the auth method was used.
auth_method	The auth method that was used to sign this data.
hash_method	The hashing method of the base64 signed data.
signing_method	How the message was signed.

Signature Data (security key)

Param	Description
keyHandle	The U2F KeyHandle that was used.
clientData	The clientdata from the U2F security key.
signatureData	The signature from the U2F security key.

Signature Data (mobile device)

Param	Description
counter	The counter value from the security key.
signature_value	The base64 encoded signature value from the security key.
challenge	The hash value from the base64 signed message. This is the value that is signed.
meta	Data about the signature - mostly reserved for future use.
version	The version of the signature data.
format	The format of the signature data.
key_id	The key id. Not used at this time

Signature Validation Details

Param	Description
public_key	The public key value used to validate the signature.
key_size	The size of the public/private key.
key_type	The type of key used. EC is the only key supported currently
signing_algorithm	The type of hashing algorithm used to sign – the only possible value right now is SHA256.
curve_type	The type of curve used if applicable.
key_format	The format of the key, the only value right now is x.509.

Mobile Device Details

Param	Description
platform	The mobile platform that was used (Android or iOS).
model	The model of the device.

Errors

The Auth Armor API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your Access token is not valid.
402	Request Payment -- Request for payment.
404	Not Found -- The specified auth profile does not exist.
405	Method Not Allowed -- You tried to access an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The auth profile requested has been removed from our servers.
415	Unsupported Media Type -- You requested a format that isn't json.
418	I'm a teapot.
429	Too Many Requests -- You're making too many requests!!! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.