Authenticate with Swedish BankID using the Nexus XPI Web Service (SOAP) API

This article is valid for Digital Access 6.2 and later

This article describes authenticating with Swedish BankID using the Nexus XPI Web Service (SOAP) API. See also Swedish national eID - BankID and Mobile BankID for more information.

Operations

Method	Request parameters	Response Type	Description
authenticate	subject, method	Subject	Authenticates a subject using the specified method.

Authenticate

Request parameters

Name

Type

Required

Description

subject

Property	Type	Required	Description
~~country~~	String	N	Not used for Swedish BankID
credentials[]	MapItem[]	N
credentials[].key	String	Y
credentials[].value[]	byte[]	Y
~~language~~	String	N	Not used for Swedish BankID
principals[]	MapItem[]	N
principals[].key	String	Y
principals[].value[]	byte[]	Y

Y

A subject representing the entity to be authenticated.

method

Integer

Y

An integer with the ID of the authentication method to be used.

Response parameters

Type

Required

Description

subject

Property	Type	Required	Description
~~country~~	String	N	Not used for Swedish BankID
credentials[]	MapItem[]	N
credentials[].key	String	Y
credentials[].value[]	byte[]	Y
~~language~~	String	N	Not used for Swedish BankID
principals[]	MapItem[]	N
principals[].key	String	Y
principals[].value[]	byte[]	Y

Y

The supplied subject populated with username and session principals.

Faults

Type

Description

WSException

Property	Type	Description
faultinfo	WSExceptionFault	Object wrapping error information

If general FaultException occurs.

AuthenticationException

Property

Type

Description

faultInfo

AuthenticationException

Possible error codes:

1101 - Authentication failed
1103 - Service not available

If authentication failed. For example, providing an invalid method.

ChallengeException

Property

Type

Description

faultInfo.subject

Subject

The Subject being authenticated, with the credential set pre-populated with the next set of required parameter names.

faultInfo.method

integer

The method IDs requiring additional credentials.

faultInfo.code

integer

Possible error codes:

1102 - Authentication challenge
1104 - Provider name needed

If additional credentials are required.

Initial authentication request

Request action	Description	Request example	Response example
token	The `token` credentials do-action is used to request a token from BankID. The returning `token` is used in the [TOKEN] part of the Launch URL and can be used to launch the BankID app automatically on the same device. The `token` is the preferred initial do-action, since the user does not need to enter their personal number, making it more secure. More on how to handle `token` response can be found in the next section, "Handle token response".	Request example CODE `> authenticate(subject, method) > method: 4 > subject: > credentials: > do: token`	Response example CODE `< ChallengeException: < code: 1102 < message: Additional credentials... < method: 4 < subject: < principals: < session: 5585klkp5yww < credentials: < text: 1113a7d6-b17d-430c-8064... < status: qrcode`

Handle token response

Response status	Description	Request example (poll-loop)	Poll response example
qrcode	Verify that the ChallengeException code is 1102 and then get the subject from the exception. It contains the new principals required in subsequent requests. Verify that the subject credentials status is `qrcode`, then read the BankID token from the subject credentials text. The token is used to create a Launch URL. The BankID token is valid up to 30 seconds, then it needs to be renewed. The renew procedure is explained in section "Handle poll response with status showqr". To use Animated QR code, see section "Handle poll response with status continue". To follow the status of the ongoing authentication, start a `poll-loop`, sending do-action `poll` request every second.	Example: poll-loop CODE `> authenticate(subject, method) > method: 4 > subject: > principals: > session: 5585klkp5yww > credentials: > do: poll`	Example: Poll response CODE `< ChallengeException: < code: 1102 < subject: < principals: < session: 5585klkp5yww < credentials: < text: Starta din BankID-app. < status: continue`

Handle poll response

Response status	Description	Request example	Response example
continue	If the response subject credentials status is `continue`, then the user has not yet started the BankID app. If needed, update the information in the user browser to indicate that user needs to start the BankID app. If Animated QR code is used, then perform credentials do-action `calc_qr` and follow the instructions in section "Handle calc_qr response".	NA	Example: continue CODE `< ChallengeException: Additional credentials... < code: 1102 < message: Additional credentials required. < subject: < principals: < session: 5585klkp5yww < credentials: < text: Starta BankID-appen... < status: continue`
sign	If the response subject credentials `status` is `sign`, then the user has started the BankID app but not yet authenticated. If needed, update the information in the user browser to indicate that user needs to authenticate in the BankID app.	NA	Example: sign CODE `< ChallengeException: < code: 1102 < subject: < principals: < session: 5585klkp5yww < credentials: < text: Skriv in din säkerhetskod... < status: sign`
showqr	If the response subject credentials status is `showqr` then the [TOKEN] in the Launch URL has expired. The BankID token used in the Launch URL is valid up to 30 seconds, then it needs to be renewed. If Launch URL is used, renew `token` by performing credentials do-action `token`, then follow the instructions in section "Handle token response". If Animated QR code is used, then no special action needed, simply continue doing `calc_qr` after poll response status `showqr`.	Example: CODE `> authenticate(subject, method) > method: 4 > subject: > principals: > session: 5585klkp5yww > credentials: > do: token`	Example: CODE `< ChallengeException: Additional credentials... < code: 1102 < message: Additional credentials required. < subject: < principals: < session: 5585klkp5yww < credentials: < text: Misslyckades att... < status: showqr`
done	If the response subject credentials `status` is `done`, then always terminate the `poll-loop` and perform credentials do-action `done`. Then follow the instructions in section "Handle done response".	Example CODE `> authenticate(subject, method) > method: 4 > subject: > principals: > session: 5585klkp5yww > credentials: > do: done`	Example CODE `< ChallengeException: Additional credentials... < code: 1102 < message: Additional credentials required. < subject: < principals: < credentials: < text: Var god vänta... < status: done`

Handle done response

Description	Request example	Response example
If no exception thrown calling authenticate and the response subject principal’s username has a value then the user is successfully authenticated. If an expected serial number exists, compare it with value in eid-userinfoserialnumber or extract SERIALNUMBER from username manually. See section "User response attributes".	NA	Example CODE `< subject: < principals: < session: 5585klkp5yww < username: CN=Anders Andersson,...`
User canceled authentication in the BankID app. The response subject credentials errcode is userCancel. See section "Handle error in done response".	NA	Example CODE `< ChallengeException: < code: 1102 < subject: < credentials: < errcode: userCancel < errmsg: åtgärden avbruten. < status: done`
User did not scan QR code and did not launch using a button. After 3 minutes the BankID transaction expires due to inactivity. The response subject credentials `errcode` is `startFailedWithQR`. See Handle error in done response	NA	Example CODE `< ChallengeException: < code: 1102 < subject: < credentials: < errcode: startFailedWithQR < errmsg: Misslyckades att... < status: done`
User started the BankID app either by scanning QR code or by clicking a button with launch URL. After 3 minutes the BankID transaction expires due to inactivity. The response subject credentials `errcode` is `expiredTransaction`. See section "Handle error in done response".	NA	Example CODE `< ChallengeException: < code: 1102 < subject: < credentials: < errcode: expiredTransaction < errmsg: BankID-appen svarar in... < status: done`
If the user starts two parallel authentications with same BankID. The transaction started first is aborted and returning errcode is `cancelled` The second transaction is also aborted and returning errcode is empty, and errmsg is `Internt tekniskt fel. Försök igen`. See section "Handle error in done response".	NA	Example CODE `# (first aborted transaction): < ChallengeException: < code: 1102 < subject: < credentials: < errcode: cancelled < errmsg: åtgärden avbruten. För... < status: done # (second aborted transaction): < ChallengeException: < code: 1102 < subject: < credentials: < errmsg: Internt tekniskt fel... < status: done`

Handle calc_qr response

Response status Description Request example Response example

calc_qr

Verify that subject credentials status is calc_qr, then read the Animated QR code data from subject credentials text.

Generate a QR code image on the webpage for the user to scan with the BankID app.

Continue performing credentials do-action calc_qr after poll response status continue.

Example

CODE

>  subject:
>    principals:
>      session: 5585klkp5yww
>    credentials:
>      do: calc_qr

Example

CODE

<  ChallengeException: Additional credentials...
<  	code: 1102
<  	message: Additional credentials required.
<  subject:
<    principals:
<      session: 5585klkp5yww
<    credentials:
<      text: bankid.c7ff94bc-b96b-4b3f...
<      status: calc_qr

Handle user cancel

Attribute Description Request example Response example

cancel

When the user selects to cancel the ongoing authentication process, request the cancel credentials do-action.

Example

CODE

> authenticate(subject, method)
>   method: 4 
>   subject:
>     principals: 
>       session: 5585klkp5yww 
>     credentials:
>       do: cancel

Example

CODE

< ChallengeException:
<   code: 1102 
<   subject:
<     credentials:
<       errmsg: åtgärden avbruten.
<       status: done

User response attributes

Attribute	Description	Example value
username	Subject of the user's BankID certificate. Only returned when user has authenticated.	CN=Anders Andersson, OID.2.5.4.41=(200811 14.40) Anders Andersson - Mobilt BankID, SERIALNUMBER=199305011612, GIVENNAME=Anders, SURNAME=Andersson, O=Testbank A AB (publ), C=SE
displayname	Display name from the Subject of the user's BankID certificate.	Anders Andersson
eid-userinfo-certid	Serial number of the user's BankID certificate.	8427483655028210100
eid-userinfo- commonname	Common name from the Subject of the user's BankID certificate.	Anders Andersson
eid-userinfo-country	Country from the Subject of the user's BankID certificate.	SE
eid-userinfo-givenName	Given name from the Subject of the user's BankID certificate.	Anders
eid-userinfo-issuer	Issuer of the user's BankID certificate.	CN=Testbank A Customer CA3 v1 for BankID Test, SERIALNUMBER=111111111111, O=Testbank A AB (publ), C=SE
eid-userinfo-notafter	The user's BankID certificate expiry date.	Thu Aug 11 23:59:59 CEST 2022
eid-userinfo-notbefore	The user's BankID certificate creation date.	Tue Aug 11 00:00:00 CEST 2020
eid-userinfo-organization	Organization from the Subject of the user's BankID certificate.	Testbank A AB (publ)
eid-userinfoserialnumber	Serial number from the Subject of the user's BankID certificate.	199305011612
eid-userinfo-surname	Surname from the Subject of the user's BankID certificate.	Andersson

Handle error in done response

Recommendations
When credentials do-action `done` fails, log `errcode` and `errmsg` from the returning subject credentials and terminate the `poll-loop` and provide a way for the user to retry. When exception other than `ChallengeException` thrown, a subject is not returned then log exception details and terminate the `poll-loop`.

General

Topic	Description
Encoding	All binary data is encoded in UTF-8.
Polling timeout	Using a `polling timeout` ensures the user browser is not polling indefinitely, it is recommended to terminate the `poll-loop` if polling time exceeds 3 minutes.
Document scope	Other operations and initial do-actions are not covered in this document.