Using PhenixID HTTP API for NetID Access (SITHS/EFOS/Own CA) 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 transaction ID value. The second API method call will poll the status of the authentication. The API client must poll until a status=OK or an error is returned.

Prerequisites

- PhenixID Authentication Services HTTP API configured

- NetID Access client

- NetID Access 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 NetID authentication, the api client may fetch this value:

- Certificate subject id (this can be the user personal number, hsa-id, userPrincipalName. It depends on the certificate that is used)

 

To trigger NetID Access authentication with autostart, no data needs to be fetched.

For information how to use autostart for NetID Access, please view the relying party guidelines for NetID Access.

Trigger authentication - api call

Request

Method: HTTP PUT

Endpoint: /api/authentication/netid_start_auth

Headers:

Name Value
 Mandatory Comment
Content-Type application/json Yes
tenant t1 Yes .Value must be given to you by PhenixID Signing Service 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 Signing Service admin.

Body:

The body must contains a json structure. 

{
"pnr":"..",
}

Json structure properties:

Name Value Mandatory Comment
pnr <certificate subject id> Yes Certificate subject Id (userID).

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

 

PUT /api/authentication/netid_start_auth HTTP/1.1
Host: demo.phenixid.net
Content-Type: application/json
tenant: t1
Cache-Control: no-cache
{ "pnr":"191212127771" }

Response

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3900
{
  "transactionID":"829b3b56-5a0a-449f-8dc8-50e6772c076f"
}

Poll authentication status - use transactionID

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

The API client must call the Poll authentication status API method periodically until it returns a status OK or an error message.

Poll authentication status - api call

Request

Method: HTTP PUT

Endpoint: /api/authentication/netid_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 Signing Service admin.
Authorization <basic_auth_value> No Basic authentication username and password must be given to you by PhenixID Signing Service admin.

Body:

The body must contains a json structure. 

{"transactionID":"..."}

Json structure properties:

Name Value Mandatory Comment
transactionID <Value_returned_from_trigger_sign> Yes

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

PUT /api/authentication/netid_check_auth HTTP/1.1
Host: demo.phenixid.net
Content-Type: application/json
tenant: t1
Cache-Control: no-cache
{ "transactionID": "b3734e10-d5e4-49a9-b5fb-affa89e31191" }

Response

Response

The response body JSON structure properties:

 

Name Possible values Comment
status COMPLETE
OUTSTANDING_TRANSACTION
USER_SIGN
PENDING
SIGN_VALIDATION_FAILED
ERROR
CANCELLED

 PENDING -> User did not yet open the NetID Access application. Continue to poll.

OUTSTANDING_TRANSACTION-> User did not yet open the NetID Access application. Continue to poll.

USER_SIGN -> User opened the BankID application. Continue to poll.

COMPLETE-> Successful authentication. Stop polling

Other status -> Stop polling
name
Full name of Certificate holder. Only available if status=OK.
givenName
Given name (first name) of Certificate holder. Only available if status=OK.
surName
Last name of Certificate holder. Only available if status=OK.
ocspResponse
OCSP response value of the authentication. Only available if status=OK.
signature
Signature value of the authentication. Only available if status=OK.
message
Error message. Only available if status=ERROR.
details
Detailed error message. Only available if status=ERROR.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 390010
{
    "surName": "Landgren",
    "givenName": "Reine",
    "name": "Reine Landgren",
    "status": "OK"
}

Common errors

Common errors from the NetID Access backend will result in a HTTP Status 200 with a body containing the error message:

{”message”:”<error explained>”}