Nexus Documentation
Nexus Documentation
Breadcrumbs

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

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".

 


> authenticate(subject, method)
>   method: 4 
>   subject:
>     credentials:
>       do: token




< 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.

 


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




< 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

 


<  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

 


< 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.

 


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




<  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".

 


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




<  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

 


< 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

 


< 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

 


< 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

 


< 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

 


# (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.

 


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




<  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.

 


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




< 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.