HTTP Authentication API

Authentication API is based on HTTP. Requests are sent with the HTTP PUT method. Depending on authentication type or stage in the authentication process the request & response may differ. The basics of the request/response will still follow the same pattern.

In addition to authentication, tokens can be enrolled and deleted.

The achieve an authentication the pattern will similar to what is described below.

Authentication with username, password & OTP sent over SMS

  1. Request is sent
    • This request will often contain data for validation of usernames and passwords.
  2. Response received (potentially containing additional identity data)
    • Outcome of the first request (OK/NOT OK). Body may contain data. Potential data in response is agreed at configuration time but can also be dynamically added.
  3. New request with additional authentication data
    • This request will often contain data used to validate an OTP from ether an SMS.
  4. Response received (telling if the OTP was correct)
    • Outcome of the second request (OK/NOT OK). Body may contain data. Potential data in response is agreed at configuration time but can also be dynamically added.

 

The last part of the URI is mapped to a PhenixID pipe that handles the actual authentication.

The request

Authentication always starts with a client sending a request to the server. The request has two required header, “tenant” and “Content-Type”.

Content-Type must have value of “application/json”.

tenant must have a value matching the module configuration.  

URL pattern is http(s)://<host>:<port_if_non_default>/api/ authentication/<operation>.

In most cases data needs to be sent in addition to theoperation.Adding a JSON object to the HTTP body does this.

All data are expected to be String data types,“key”: ”value”.

Example http body:

{
"username":"username",
"password":"supersecret"
}

 

The response

After sending the request a successful response would return http status 200. The response body contains either an empty JSON object, {}, or a JSON body with data that might be of use further in the authentication.

 

Using state

Doing authentications when multiple requests are required the server need some way of maintaining state (like a web browser using session cookies).

There are two ways of handling state:

  1. Adding a parameter to the body,session_alias.The session_alias is used as the equivalent to a browser cookie. Difference is that the client sets it.If sent in a request the server will associate that request with any other requests with the samesession_alias. There are built in measures ensure no other client can hi-jack a session alias other the intended one.
  2. Letting the PhenixID server creating a session. The response will then contain the session id, which the client then will add as a parameter,session_id, in the subsequent requests.

Depending on use case and requirements the server should be configured to handle one of the two possible methods.

 

Handling tokens

Tokens can be enrolled/assigned to users. This is done in two steps.

  1. Request a token by calling “token/requesttoken”. Body must have  “userid” 
{
	"userid":"my_user_name"
}

The response will contain the id and secret of the token. The secret the must by entered in the PhenixID Pocket Pass app by the user.

Example response

{
  "id": "9a8ca2ff-7da9-42b7-aaf5-ec273fee42a1",
  "secret": "VBKPOPZQIHOLZHH5",
  "assignedTo": "aandren",
  "displayName": "aandren@customer",
  "status": "PENDING",
  "tokenType": "SWTOKEN",
  "type": "TOTP",
  "length": "6",
  "timeStep": "30",
  "epoch": "0",
  "mode": "1",
  "drift": "0"
}

 

Assigning the token to the user second request is required. Path is “/token/enrolltoken” with body

{
	"tokenid":"id from prev request"
}

Note that the tokenid is only valid for 5 minutes after the request.

A enrolled token can be deleted by sending a delete request to “token/deletetoken” with body:

{
	"tokenid":"0b731999-44c6-4ae8-829d-a34024fc7cfb"
}

Creating PhenixID OneTouch assignments

Path: onetouch/assign

allowedOperation name: assign

Body must be in the format of a PhenixID One Touch JSON assignment.

 

assigned_to must be set to userid bound to onetouch token.

Example request:

PUT /api/authentication/onetouch/assign HTTP/1.1

Host: demo.phenixid.net

Content-Type: application/json

tenant: phenixid

Authorization: Basic YWRmczphZGZz

Cache-Control: no-cache

{ "assigned_to": "XXX", "notify": "true", "ttl" : "1", "form": { "controls": [ { "id": "html", "type": "html", "value": "%3Cdiv%20style%3D%22background-color%3A%20%23ffffff%22%3E%0A%20%20%20%20%3Cspan%20style%3D%22font-family%3A%20arial%2Csans-serif%22%3EConfirm%20login%20for%20user%3A%20andebjo%3C%2Fspan%3E%0A%20%20%20%20%3C%2Fbr%3E%0A%20%20%20%20%3Cspan%20style%3D%22font-family%3A%20arial%2Csans-serif%22%3Eand%20service%3A%20Test%20application%3C%2Fspan%3E%0A%3C%2Fdiv%3E" }, { "id": "c", "type": "button", "value": "Yes", "action": "CONFIRM" }, { "id": "r", "type": "button", "value": "No", "action": "REJECT" } ] } }

 

Example response body:

{

   "id": "7170015e-0f38-43d6-bccb-570b49b7a380"

}

 

Verifying an PhenixID OneTouch assignment

Path: “onetouch/check”

allowedOperation name: check

Body

{
  "id": "id from previous request"
}

Response body will contain status of the assignment.

Three possible status codes:

  • PENDING
  • ACCEPTED
  • REJECTED

 Example request:

PUT /api/authentication/onetouch/check HTTP/1.1

Host: demo.phenixid.net

tenant: phenixid

Content-Type: application/json

Authorization: Basic YWRmczphZGZz

Cache-Control: no-cache

{ "id": "7170015e-0f38-43d6-bccb-570b49b7a380" }

 

 

Example response body:

{

   "assigned_to": "XXX",

   "notify": "true",

   "ttl": "1",

   "form": {

       "controls": [

           {

               "id": "html",

               "type": "html",

               "value": "%3Cdiv%20style%3D%22background-color%3A%20%23ffffff%22%3E%0A%20%20%20%20%3Cspan%20style%3D%22font-family%3A%20arial%2Csans-serif%22%3EConfirm%20login%20for%20user%3A%20andebjo%3C%2Fspan%3E%0A%20%20%20%20%3C%2Fbr%3E%0A%20%20%20%20%3Cspan%20style%3D%22font-family%3A%20arial%2Csans-serif%22%3Eand%20service%3A%20Test%20application%3C%2Fspan%3E%0A%3C%2Fdiv%3E"

           },

           {

               "id": "c",

               "type": "button",

               "value": "Yes",

               "action": "CONFIRM"

           },

           {

               "id": "r",

               "type": "button",

               "value": "No",

               "action": "REJECT"

           }

       ]

   },

   "expires": "2017-07-11T13:01:19.547Z",

   "status": "PENDING",

   "id": "7170015e-0f38-43d6-bccb-570b49b7a380",

   "created": "2017-07-11T12:56:19.547Z"

}

Restricting client access

Restrictions are placed on the last part of the URI. The value of this string is compared to the “allowedOperation” section for each tenant. If the value is not found in the list the operation is discarded.

Error codes

Three error codes are possible:

  • 401 - authentication failed in some way. Http response body will contain an error message.
  • 401 - with the header WWW-Authenticate. Server is expecting basic authentication before executing the request. No information in the body
  • 500 General server error. Body will contain error message.

System authentication

Server can be configured to either use basic authentication or client certificate for clients to authenticate them selves prior to executing any request. Invalid authentication between client and server will generate an error and execution will be aborted.

Module installation 

{
            "module": "com.phenixidentity~phenix-api-authenticate",
            "enabled": "true",
            "config": {
                "tenant": [{
                        "id": "default",
                        "displayName": "PhenixID",
                        "allowedOperation": [“operation_one”,” operation_two”]
                    }],
                "ssl": "true",
                "port": "8443",
                "authenticate": "basic" 
            }
        }