BankID API

BankID API acts as proxy  in front of the actual BankID.  Apart from the ability to deploy anywhere there is also  support for multiple client certificates, augmenting the response before sending the response back to the calling client.

The supported BankID API version is 5. Specifications followed  is 3.2.1 issued by Finansiell ID-Teknik BID AB. Many things looks pretty much like if one where using the BankID API directly so moving to PhenixID bankid API should not mean a great deal of work.

General notes

This API is to be considered as a connection point for other applications requiring BankID authentication or signing. 

It is not to be exposed without additional security layers such as firewalls and TLS encryption.

Configuration

Configure the module according to the example:


 {
 	"name": "com.phenixidentity~phenix-api-bankid",
 	"enabled": "true",
 	"config": {
 		"tenant": [{
 			"id": "<id of the calling tenant>",
            "password": "<password of the calling tenant>",
 			"bankidStore": "<id of the key store>",
 			"mode": "test",
            "onCompletePipeID":"<id of the pipe executed after an completed bankID request>"
 		}],
 		"http_config_ref": "<id of the http configuration used>"
 	}
 }

Tenant configuration

PhenixID BankID supports multiple calling tenants.  Each tenant must be configured in order to be allowed calling the API.

Name Description Default value
id id used to identify the calling tenant N/A
password password used to identify the calling tenant N/A
bankidStore Id if the PAS store used when communication with the actual BankID API. N/A
mode If using the BankID test environment or node (prod/test is valid value) prod
onCompletePipeID If configured, PAS will perform a pipe execution before sending the respons back to the calling client. The data recieved from the pipe will be added to the BankID response and sent to the client. N/A

Starting an authentication

The request to start an authentication is done using HTTP PUT to "api/authentication/bankid/auth/start". Example shown below.

PUT: api/authentication/bankid/auth/start

HEADERS:
Content-Type:application/json
tenant:default
password:secret

BODY:
{
"endUserIp": "127.0.0.1"
}

Note that the headers in the example are mandatory where tenant & password  are variable.

The HTTP body is expected to be json formatted. enduserIp is mandatory. 

In addition "personalNumber" can be added. 

The API supports adding requirement which is transparent to BankID documentation.

Starting an signature request

The request to start an authentication is done using HTTP PUT to "/api/authentication/bankid/sign/start". Example shown below.

PUT: /api/authentication/bankid/sign/start

HEADERS:
Content-Type:application/json
tenant:default
password:secret

BODY:
{
"endUserIp": "127.0.0.1",
"userVisibleData":"Gött räksmörgås"
}

Note that the headers in the example are mandatory where tenant & password  are variable.

The HTTP body is expected to be json formatted. enduserIp and userVisibleData are mandatory. 

In addition personalNumber and userNonVisibleData can be added. 

The API supports adding requirement which is transparent to BankID documentation.

Response from a start auth or start sign

Since the API is pretty much proxying requests to BankID expected responses are documentented in the BankID documentation.

The PAS server have 3 possible response codes:

  • 403 - Tenant failure
  • 400 - Parsing failure/missing mandatory data
  • 500 - General server error

Getting status from an order

The request to start an authentication is done using HTTP PUT to "/api/authentication/bankid/collect". Example shown below.

PUT: /api/authentication/bankid/collect

HEADERS:
Content-Type:application/json
tenant:default
password:secret

BODY:
{
"orderRef": "413200b2-976b-4769-8722-7b7dd37411f9"
}

Note that the headers in the example are mandatory where tenant & password  are variable.

The HTTP body is expected to be json formatted. orderRef is mandatory. 

Response from a collect call.

Since the API is pretty much proxying requests to BankID expected responses are documentented in the BankID documentation.

If the order returns as COMPLETE and the onCompletePipeID is configured, the PIPE id will be executed. The response from the pipe will the n be added to the bankid response and sent to the client.

Data sent to the executing pipe is:

  • personalNumber
  • name
  • givenName
  • surname
  • ipAddress
  • notBefore
  • notAfter
  • signature
  • signature
  • ocspResponse
  • tenant
  • orderRef

Cancelling an order

To cancel a pending order send call to /api/authentication/bankid/cancel

Example

PUT: /api/authentication/bankid/cancel

HEADERS:
Content-Type:application/json
tenant:default
password:secret

BODY:
{
"orderRef": "413200b2-976b-4769-8722-7b7dd37411f9"
}