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.

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"
}

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.

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.

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"
}

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"

}

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"

}

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.

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.

Server can be configured to force http basic authentication, client certificate authentication or OAuth authentication for clients prior to executing any operation. Invalid authentication between client and server will generate an error and execution will be aborted.

To achieve system authentication, add a configuration parameter to the module, callerVerificationPipe, with the id of a pipe that will verify api-client credentials. 

When using HTTP Basic Authentication, the API module will fetch the username and password from the Authorization header. Username and password will be passed to the callerVerificationPipe (and allowedOperation pipes) using request parameters username_api and password_api. 

{
            "module": "com.phenixidentity~phenix-api-authenticate",
            "enabled": "true",
            "config": {
                "tenant": [{
                        "id": "default",
                        "displayName": "PhenixID",
                        "callerVerificationPipe" : "pipeValidateClientCert",
                        "allowedOperation": [“operation_one”,” operation_two”]
                    }],
                "http_configuration_ref" : "idHttpConf" //Http connection pointer. If omitted, it will inherit port/ssl from http authentication module.
            }
        }

The parameter tenant is of type array to make this feature multi-tenant.