bankid-saml-idp
BankID IdP Backend API
For those who wish to implement their own BankID IdP Frontends this page contains a description of the BankID IdP Backend API.
API Endpoints
Polling
The polling endpoint is the primary endpoint that the frontend will call in order to communicate with the BankID server (via the IdP backend).
TODO: More. Periodically invoke this ….
Path: /api/poll
Method: POST
Request Parameters: The query parameter qr is optionally included in the request (possible values
are true and false, where false is the default). This parameter tells whether the frontend wants
to display a BankID QR code, and by setting the value to true the backend will generate a QR-code and
include in the resulting response (see below).
Response Status Codes:
| HTTP Status Code | Description |
|---|---|
200 |
OK |
400 |
Error - Returns an alternate response to display error for user. See UserErrorResponse |
429 |
Too many attempts - resource busy. Parallel requests have been made for the same user, a header “Retry-After” will be present as a time for when you can retry the request again. This can also happen when a request has been blocked by the circuit breaker due to API errors towards the BankID server API. This status code means that the request has been rejected before being made towards BankID’s API. |
Response Object: ApiResponse
| Field | Type | Description |
|---|---|---|
status |
String | The status code for the response. Can be any of the following: NOT_STARTED (the operation against the BankID Server has not been started), IN_PROGRESS (the BankID operation is in progress), ERROR (an error response, check messageCode to know which error message to display), COMPLETE (the BankID operation has been completed) and CANCEL (the BankID operation has been cancelled by the user). |
qrCode |
String | Optionally holds the generated QR code that is to be displayed for the user. Base64-encoded string. |
autoStartToken |
String | Optionally holds the BankID auto start token. See BankID Integration Guide. |
messageCode |
The code for the message that should be displayed for the user. |
Cancelled Operation
API-call that should be invoked if the user cancels the operation.
Path: /api/cancel
Method: POST
Request Parameters: None
Response Status Codes: 200 for a successfully received call and 500 for internal errors.
Response Object: None
Selected Device
In the case where a BankID signature is carried out we want to ensure that the user is not prompted whether to use “BankID on this device” or “Another device”. The reason is that in almost all cases a signing operation follows a login (authentication) operation, and it would not be a good user experience to have to answer the same question twice within the same session.
Path: /api/device
Method: GET
Request Parameters: None
Response Status Codes: 200 for a successfully executed call and 500 for internal errors.
Response Object: SelectedDeviceInformation
| Field | Type | Description |
|---|---|---|
isSign |
Boolean | Is the current BankID operation a sign operation? |
device |
String | The selected device. Can be any of this (BankID on this device was selected), other (BankID on another device was selected) or unknown (no previous device selection is available). |
Service/Status Information
An endpoint that delivers service, or status, information.
Path: /api/status
Method: GET
Request Parameters: None
Response Status Codes: 200 for a successfully executed call and 500 for internal errors.
Response Object: ServiceInformation
| Field | Type | Description |
|---|---|---|
status |
String | OK for no problems and ISSUES if the BankID IdP has encountered issues. |
UI Information
An endpoint that delivers information about the Relying Party, or SAML Service Provider, that has made the current authentication request to the BankID IdP as well as other configurable UI settings.
Path: /api/ui
Method: GET
Request Parameters: None
Response Status Codes: 200 for a successfully executed call and 500 for internal errors.
Response Object: UiInformation
| Field | Type | Description |
|---|---|---|
sp.displayNames.* |
Map holding pairs of language codes and display names. | Contains display names for the SP in the languages declared by the SP. |
sp.imageUrl |
String | URL to the SP logotype. |
sp.showSpMessage |
Boolean | Is true if additional SP message should be displayed in DeviceSelectView. |
display-qr-help |
Boolean | If true, the extra help texts should be display for how to scan a QR code. |
qrSize |
Integer | Holds the size of the QR code in pixels. |
accessibilityReportLink |
String | Swedish public e-services are required to include a link to the “accessibility report” (tillgänglighetsrapport) of their web site. If this property is assigned, the UI will display this link at the bottom of the page. |
providerName |
Map of strings | The name of the provider of the service delivered as a map where keys are language codes and values the name(s). If null, elements that this information should be displayed should not be included in the UI. |
Contact Information
An endpoint that delivers service contact information. Typically this information is displayed when an error has occurred.
Path: /api/contact
Method: GET
Request Parameters: None
Response Status Codes: 200 for a successfully executed call and 500 for internal errors.
Response Object: CustomerContactInformation
| Field | Type | Description |
|---|---|---|
email |
String | The email address that should be displayed in the UI for customer support/contact. |
displayInformation |
Boolean | Whether the UI should display contact information. |
UI Overrides (customizations)
An endpoint that delivers UI override according to Customizing the BankID IdP UI.
Path: api/overrides
Method: GET
Request Parameters: None
Response Status Codes: 200 for a successfully executed call and 500 for internal errors.
Response Object: FrontendOverrideResponse
| Field | Type | Description |
|---|---|---|
messages |
List of MessageOverride | Message overrides according to Message Overrides. |
css |
List of CssOverride | CSS overrides according to CSS Overrides. |
content |
List of ContentOverride | Content overrides according to Content Overrides. |
Views
When writing a custom frontend it is also useful to now about about the backend views described in this section. You can either replace the index page with your own frontend or host it separately.
If the frontend should be hosted separately the /bankid path (see below) should be disabled by using the configuration flag bankid.built-in-frontend = false.
/bankid
This is the primary view that displays the frontend that has been built into resources (defaults to Vue frontend).
/view/complete
Redirect here to consume a completed BankID operation and get a SAML Response message to be posted
back to the SAML Service Provider.
/view/cancel
Redirect here if the user wants to cancel the current login. The user will be posted back to the SAML Service Provider.
Copyright © 2023, Myndigheten för digital förvaltning - Swedish Agency for Digital Government (DIGG). Licensed under version 2.0 of the Apache License.