Using PhenixID HTTP API for NetID Access (SITHS/EFOS/Myndighets CA/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=COMPLETE or an error is returned.
Prerequisites
- PhenixID Authentication Services HTTP API for NetID Access 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 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 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 COMPLETE 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>”}