Using PhenixID HTTP API for Swedish Freja eID authentication

Overview

To use the API, two methods must be called. The first API method call is to trigger the authentication. This will return a authRef value. The second API method call will poll the status of the authentication. The API client must poll until a status=APPROVED, CANCELED, RP_CANCELED or EXPIRED is returned.

Prerequisites

- PhenixID Authentication Services Freja eID Authentication HTTP API configured

- Freja eID client

- Freja eID enrolled

- If PhenixID Authentication Services HTTP API is protected with client certificate authentication: Client certificate (p12)

- If PhenixID Authentication Services HTTP API is protected with basic authentication: Username and password

Trigger authentication - data to be fetched before api call

To trigger Freja eID authentication, the api client must fetch one of these values to be used as the userIdentifier, depending on the use case:

- Personal identification number (personnummer)

- Organization ID

- Email address

 

Trigger authentication - api call

Request

Method: HTTP PUT

Endpoint: /api/authentication/freja_eid_start_auth

Headers:

Name Value
 Mandatory Comment
Content-Type application/json Yes
tenant t1 Yes .Value must be given to you by PhenixID Authentication Services admin, it might differ depending on the environment.
Authorization <basic_auth_value> No If applicable, username and password must be given to you by PhenixID Authentication Services admin.

Body:

The body must contain a json structure. 

{   
"attributesToGet":"SSN,BASIC_USER_INFO",   
"reqiredRegistrationLevel":"EXTENDED",   
"userInfoType":"SSN",   
"userIdentifier":"197501297852"
}

Json structure properties:

Name Value Mandatory Comment
attributesToGet
 List of requested attribute sets Yes Check this for more info on relevant values.
reqiredRegistrationLevel
 Required registration level of Freja eID profile Yes Check this for more info on relevant values.
userInfoType
 User profile type Yes Check this for more info on relevant values.
userIdentifier
 The user identifier value Yes Picked up by the API client before triggering the authentication

Example request (Please note that authorization data is not included in this example).

 

PUT /api/authentication/freja_eid_start_auth HTTP/1.1
Host: demo.phenixid.net
Content-Type: application/json
tenant: t1
Cache-Control: no-cache
{   
"attributesToGet":"SSN,BASIC_USER_INFO",   
"reqiredRegistrationLevel":"EXTENDED",   
"userInfoType":"SSN",   
"userIdentifier":"191212121212"
}

Response

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3900
{
  "authRef": "sdfsdfksjgl-iG8bx1Gb_biC2pw-eyKpbkhsteUnzBMinkhcjQuxzFiyixasdarvewas"
}

Poll authentication status - using authRef

The API client must fetch the authRef value returned by the Trigger authentication call.

The API client must call the Poll authentication status API method periodically until it returns a status, indicating the end of the transaction.

Poll authentication status - api call

Request

Method: HTTP PUT

Endpoint: /api/authentication/freja_eid_check_auth

Headers:

Name Value Mandatory Comment
Content-Type application/json Yes
tenant t1 Yes This value must be given to you by the PhenixID Authentication Services admin.
Authorization <basic_auth_value> No Basic authentication username and password must be given to you by PhenixID Authentication Services admin.

Body:

The body must contains a json structure. 

{"authReg":"..."}

Json structure properties:

Name Value Mandatory Comment
authRef <Value_returned_from_trigger_auth> Yes

Example request (Please note that authorization data is not included in this example).

PUT /api/authentication/freja_eid_check_auth HTTP/1.1
Host: demo.phenixid.net
Content-Type: application/json
tenant: t1
Cache-Control: no-cache
{ "authRef": "sdfsdfksjgl-iG8bx1Gb_biC2pw-eyKpbkhsteUnzBMinkhcjQuxzFiyixasdarvewas" }

Response

Response

The response body JSON structure properties:

 

Name Comment
status Status of transaction. Read here for more info.
ssn Personal identification number (personnummer) of Freja eID holder, if ssn was requested for.
givenName Given name (first name) of Freja eID holder. 
sn Last name of Freja eID holder.
mail Email address of Freja eID holder, if email was requested for.
organisationIdIdentifier Organisation ID identifier of Freja eID holder, if OrgID was requested for.
fullResponse Full response in JWT format.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 390010
{    
"organisationIdIdentifier": "",    
"mail": "",    
"givenName": "Tolvan",    
"fullResponse": "...",
"sn": "Tolvansson",    
"signRef": null,    
"status": "APPROVED",    
"ssn": "191212121212"}