Authentication API - com.phenixidentity~phenix-api-authenticate

The com.phenixidentity~phenix-api-authenticate module allows for API based integration through HTTP(S). This is often from a third party application requiring advanced configuration.

Basic information

In some cases there are reasons why an application or a third party vendor need a custom authentication mechanism. This is when com.phenixidentity~phenix-api-authenticate  module can help. It allows for extrem flexibility and can serve multiple clients/tenants. 

The call from a client will result in the execution of PIPE. Based on the result from the PIPE the calling client can take appropriate action (allow/reject) t. 



Configuration

Name
 Description Mandatory
name
 Name of the module Yes
id Unique id of the module Yes
config
 Custom configuration section
 Yes
http_configuration_ref
 The http listener used Yes
tenant Configuration used to identify calling client and verify their  access when calling.
List of tenants.		 Yes 
{
    "name": "com.phenixidentity~phenix-api-authenticate",
    "id": "api_module",
    "config": {
        "http_configuration_ref": "d8baaa02-2ead-473c-88b8-a7aa08a53332",
        "tenant": [{
                "id": "default",
                "displayName": "PhenixID",
                "allowedOperation": ["authenticate"]
            }]
    }
}
Click to copy

Tenant configuration

At least one tenant needs to be configured in order for the API to work. Two mandatory attributes are mandatory:

  • id
  •  allowedOperation 
Name Desciption Mandatory
id tenant identifier.  yes
allowedOperation
 A list of allowed operations executed by this tenant. Operation is equal to the last part of the URI. yes

Calling the API

All api calls has the base URI of <host_port>/api/authentication/<operation>. All operations must be made using HTTP method PUT.

Required headers are:

  • tenant - with the value used as id in tenant configuration
  • Content-Type with value of "application/json"

The ending part of the URI is automatically mapped to a PIPE with the same id the last part of the URI.

Sending data

Data can be sent to the API by setting key/values using json in the HTTP body

{
	"username":"nackastrand"
}
Click to copy

Only strings are allowed. Deep json structures is not supported.

Response

Three possible response codes can be received:

  • 200 - all is good
  • 403 - something went wrong. See log for more info.
  • 500 - a general server failure. See log for more info.


Getting data back

If required data can be sent back to the client. to enable this ensure that the executing pipe returns a single item with the data required.

It will be sent back as JSON to the HTTP API.