This section on technical documentation contains information on how to integrate with the services supported by the OpenID Connect Provider from BankID. See the problems we solve for non-technical information on features, functions, implementation guidelines and recommendations for such services.
Table of Contents
BankID service overview
The BankID service in the OIDC Provider is a multi-tennant BankID service at LoA4 having the capability to host several BankID merchant certificates. An OIDC Client may either be configured with its own BankID merchant certificate, or share a common BankID merchant certificate with other clients. The BankID service is implemented as two different Identity providers offering support for both Bank netcentric and BankID on mobile.
An OIDC Client make use of BankID either via login hints directly in the authorize request of the API, or via integration with the JS Connector.
OIDC versus BankID server
For merchants
There are several benefits for merchants integrating BankID over OIDC rather than using a legacy integration via a locally installed BankID-server:
- The integration interface is the same for both BankID netcentric and BankID on mobile.
- The merchant does not need to implement any GUI for BankID on mobile since it is taken care of by the OIDC Provider itself
- The merchant does not need to implement a selector dialog for netcentric vs. mobil since the OIDC Provider offers such a selector dialogue.
- The integration interface is based on an industry-standard API being much more convenient than implementing via the legacy BankID-server.
- The merchant may have access to value-adding services that are not available via the legacy BankID server.
- There is no need to update servers on occation; all updates are done by BankID
For partners
There are several benefits for partners as well:
- No administration of merchant certificates: this is handled by BankID
- Access to new products which may only be available through OIDC
- Easy integration with your own OIDC platform (if you use this for other services)
- Value-adding features for administrating your customers (such as Splunk dashboards and insights (WIP), customer overview in our partner portal (WIP), easier access to invoices and transaction volumes (WIP)
- In near future, we plan to offer BankID OIDC without having to order a merchant-specific certificate, making the onboarding process almot instantaneous
...
Before you start
Tip | ||
---|---|---|
| ||
Authorization Code flow with Proof Key for Code Exchange (PKCE)
Gliffy | ||||
---|---|---|---|---|
|
Authorization Request
- Connect to the discovery endpoint to get the OpenID configuration.
Note: Make sure to keep the response updated every so often (at least daily).
For the public test environment (CURRENT) the Discovery endpoint is:
https://auth.current.bankid.no/auth/realms/current/.well-known/openid-configuration.
See all environments. - Use the
authorization_endpoint
found in the Discovery endpoint response.
Note: Do not hard code this value. Retrieve the config regularly from the OIDC discovery endpoint, as it may change. - Generate a random value for
state
and store it in your user session.- The value must be non-guessable (e.g. GUID) and unique for each request.
- This value will be used to mitigate cross-site request forgery, but it can also be used by your application to link the callback request to the end-user session alongside a cookie.
- Generate a random value for
nonce
and store it in your user session.- The value must be non-guessable, cryptographically random (your framework/language most likely have support for this) and unique for each request.
- This will be used to verify integrity of ID token and mitigate replay attacks.
- Generate
code_verifier
for PKCE flow and store this in your user session.- This is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.
- This will be used to generate a code challenge (6) and during Token exchange later.
- Generate
code_challenge
from thecode_verifier
by generating a Base64-URL-encoded string of the SHA256 hash of the code verifier. - (Optional) Add any
login_hint
to the request to pre-select IDP or pre-fill user information. If user information is used we recommend using an encrypted request object. - Finally, we can build the authorization URL by adding the following query parameters (see Authorize for more options):
client_id
: Your assigned client ID with BankID OIDC.scope
: Comma separated list of scopes that indicate which information and resources you request access to. In the example below, we useopenid
andprofile
to get a regular ID token.redirect_uri
: URI to your server-side callback endpoint where you want to receive the callback response from the BankID OIDC service. This URL must be pre-registered with BankID OIDC.response_type
: Determines message flow. Only "code" is supported.state
: Your generated value forstate
.nonce
: Your generated value fornonce
.code_challenge
: Your generatedcode_challenge
.code_challenge_method=S256
- (optional)
login_hint
: Addlogin_hint
here if applicable
Code Block title Example Authorization Request GET authorization_endpoint ?client_id=your-client-id &scope=openid+profile &redirect_uri=https%3A%2F%2Fmywebapp.example.org%2Fcallback &response_type=code &state=01e3ac8e-4a26-4dfb-79ca-2631394c4144 &nonce=1fb72f68-1bea-2ba2-12d7-24df1c999d1b &code_challenge=ixDBJg7pc3yT2h65DRvhjIbGko7U-t3cYVJmdMF-hTU &code_challenge_method=S256 &login_hint=BID
- Redirect end-user to the built authorization URL to start BankID Authentication.
Authorization Code callback
If authentication is successful, the end-user will be redirected to your application at the given redirect_uri
with state
and code
as parameters.
- Verify that the
state
parameter returned corresponds to thestate
parameter for your user session. Do a POST request to the token_endpoint with the provided code to get the ID token, Access token and Refresh token.
Example request
Code Block title Example Token Request POST /auth/realms/current/protocol/openid-connect/token HTTP/1.1 Host: auth.current.bankid.no Authorization: Basic b2lkYy10ZXN0Y2xpZW50OjAxMjM0NTY3LTg5YWItY2RlZi0wMTIzLTQ1Njc4OWFiY2RlZg== Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &client_id=your-client-id &code=code=authorization-code-from-callback &redirect_uri=https%3A%2F%2Fmywebapp.example.org%2Fcallback &code_verifier=your-code-verifier
- Important: Perform Token validation
Verify the signature of the JWS tokens received and check the certificate chain of the signing key used by following this guide.
- Check claims by following this guide.
- Once validation is complete, you can access the claims in the various tokens:
- The ID token contains claims that can be used to identify the end-user. See ID token for available claims.
- The Access token can be used to access additional services such as document signing or additional user information (5).
- (optional) Fetch additional Userinfo through userinfo_endpoint.
- Use the access token you received in the previous step as Bearer token in the userinfo request
- Use the
userinfo_endpoint
found in the Discovery endpoint response. - The Userinfo response comes in JWS format so you need to perform signature validation here as well.
If authentication is cancelled (due to user action or errors)
If error
is part of the query parameters, the authentication was not completed, you need to handle the error.
- The possible ASCII values for the
error
query parameter is defined in the specification for OIDC (§3.1.4.6) or OAuth 2.0 (RFC 6749, §4.1.2.1). - If the end-user cancels an authentication request in the BankID OIDC client,
error
will have the valueaccess_denied
. - In addition to
error
, the response parametererror_description
may include BankID error codes the end-user experienced.
Next steps
Read up on how we do Key rotation and how you can do Token verification.
Our APIs are continuously adding new changes and features in API Versions and Changelog.
The list of error codes displayed to the end-user is useful for troubleshooting.
Known issues contains a list of restrictions, caveats and known problems.
The Deprecations list is also interesting to keep an eye on.