How to setup the HTTP API for Swedish BankID authentication
Prerequisites
- BankID test client certificate (FPTestcert2_20150818_102329.p12 for test environments)
- BankID customer client certificate (for production environments)
- Access to BankID infrastructure from PhenixID Server
- Access to BankID infrastructure from Mobile device
- Access to BankID infrastructure from Client
BankID will stop supporting personalNumber in auth and sign requests in version 6.0 of their API.
In version 4.7 of PAS you can modify your valves by adding the attribute "version": "v6.1" and removing references to personalNumber. Make sure your solution supports launching authentication with qr-code or autostartToken.
Authentication
It is recommended to add authentication to the API. These authentication methods are supported:
- Client certificate (recommended).
Use a reverse proxy to add client certificate authentication. Add valves to the pipe(s) to verify the certificate.
- Basic authentication
Add valves to the pipes to perform basic authentication verification.
Add BankID certificate
- Login to configuration manager
- Go to Scenarios->Federation->Keystore
- Add new keystore
- Upload bankid certificate (p12 or pfx format) and enter the password
- Click create
- Copy the ID value when created - this value will be used in later steps.
Add local http-api module
- Login to configuration manager
- Click the Advanced tab
- Open Modules (click on the pen)
- Add this module (if module is already added, only add tenant and/or allowedOperation):
{
"module": "com.phenixidentity~phenix-api-authenticate",
"enabled": "true",
"config": {
"tenant": [
{
"id": "t1",
"displayName": "Tenant1",
"allowedOperation": [
"bankid_start_auth",
"bankid_check_auth"
]
}
]
},
"id": "authapi_module"
}- Click Stage Changes and Commit Changes
- Open NODE_GROUPS (click on the pen)
- Add id of the newly added module to module_refs. Example below. (You can skip this step if the module was already added)
{
"name": "WIN-DHB3ICNDG4E",
"description": "Default node (created automatically)",
"config": {
"module_refs": "authapi_module,sealapp,signapp_1,......"
},
"created": "2017-07-03T11:38:03.135Z",
"id": "493afd0e-0fe8-40e4-b1a1-a24a5e2df6e2",
"modified": "2017-07-03T14:39:43.257Z"
}- Click Stage Changes and Commit Changes
Add pipes to trigger BankID authentication and collect authentication status
- Click the Advanced tab
- Open Pipes (click on the pen)
- Add these pipes. Change these properties to suit your environment:
- bankid_keystore -> ID value of the keystore uploaded in previous step.
{"id": "bankid_start_auth","description": "Start auth with bankid","valves": [{"name": "BankIDAuthenticateValve","config": {"bankid_keystore" : "<ID value copied in previous step>","mode": "test","version": "v6.0","user_visible_data": "{{request.usd}}","user_visible_data_format": "simpleMarkdownV1","user_non_visible_data": "{{request.unvd}}","requirement": "{{request.requirement}}","client_ip_request_param": "X-Forwarded-For"}}]}
{
"id": "bankid_check_auth",
"description": "Check auth",
"valves": [
{
"name": "BankIDCollectAuthenticationStatusValve",
"config": {
"bankid_keystore": "<ID value copied in previous step>",
"mode": "test",
"version": "v6.0",
"transactionID": "{{request.transactionID}}",
"customerID": "{{request.tenant}}"}
}]
}- Click Stage Changes and Commit Changes
Test
Use a HTTP rest client for testing and debugging. Follow this document to structure the HTTP requests properly.