PhenixID Documentation

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 be similar to what is described below.

Authentication with username, password & OTP sent over SMS

Request is sent

This request will often contain data for validation of usernames and passwords.

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.

New request with additional authentication data

This request will often contain data used to validate an OTP from ether an SMS.

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”.

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:

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.

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.

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.

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

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.

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