Before you start
OpenID Connect with Authorization Code flow
OpenID Connect is a protocol for authentication that builds on the OAuth 2.0 authorization framework. This getting started guide describes how to integrate BankID in your application using authorization code flow.
The steps necessary to perform an OpenID Connect authentication request is:
- Redirect the end-user to the authorization endpoint with applicable parameters.
- The end user authenticates using BankID and is redirected back to your web application.
- Handle the redirect request by checking parameters and handle potential errors.
- Exchange the code parameter for tokens by making a request to the token endpoint.
- Use the ID token to identify the user.
- Use the Access token to access resource servers, for example in the context of signing documents online.
- Use the Refresh token to retrieve new access tokens.
Note that implicit flow is not supported as recommended by IETF (https://tools.ietf.org/html/draft-ietf-oauth-security-topics-13).
Implementation
Initiate authentication request
- Connect to the appropriate OIDC discovery endpoint using your preferred framework and store the JSON response in your application.
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. - Use the
authorization_endpoint
found in the Discovery endpoint response.
Note: Do not hard code theauthorization_endpoint
value. Always retrieve it from the OpenID Connect configuration, as it may change. - Generate a random string value and store it in a variable called
state
.
Important: 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 can also be used to link the callback to the original request. - Generate a random string value and store it in a variable called
nonce
.
Important: 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. - Store the
state
andnonce
value in your application so they can be retrieved later, i.e. using your preferred session mechanism. These values should be stored together. - Build the authorization URL by adding the following query parameters (see Authorize for more options and details):
client_id
: Unique client identifier provided when provisioning the client.scope
: Specify which information (see ID token) and resources you request access to. In the example, we useopenid
andprofile
to get a regular ID token.redirect_uri
: URI to your server-side callback endpoint where you want to receive response from the BankID OIDC service.response_type
: Determines message flow. Only "code" is supported.state
: Your generated value forstate
.nonce
: Your generated value fornonce
.
Example authorization requestGET authorization_endpoint ?client_id=myclient-bankid-current &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
- Redirect end-user to the completed authorization URL.
Handle callback from BankID OIDC
- Create an endpoint in your web application's backend for receiving the callback from the application (i.e. a GET request to your redirect_uri).
- Check that the
state
query parameter returned corresponds to thestate
parameter you created when initiating the request.- If the
state
is missing or is not matching astate
value stored in your application, reject the request. - If the
state
match astate
stored in your application, update thestate
from in your session mechanism and continue to the next step.
- If the
- Check if the request contains the response parameter
error
.- If the
error
parameter is not present, continue to the next step. - If the
error
parameter is present, 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
might be available, but it is only intended for developers and not to be shared with the end-user.
- The possible ASCII values for the
- If the
- Retrieve the ID token, Access token and Refresh token. by sending a POST request to the token endpoint.
- Verify that the
nonce
claim in the received ID token corresponds to thenonce
value you belonging to the same session (i.e. the nonce belonging to the state).- If the
nonce
is missing or does not match the nonce stored in your application, reject the request and do not continue. - If the
nonce
match thenonce
stored in your application, delete thestate
andnonce
in your session mechanism and continue to the next step.
- If the
- Verify that the
- 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 through api-userinfo.
Next steps
It is recommended to take a look at Session handling to get a better understanding of the session lifetime.
Known issues contains a list of restrictions, caveats and known problems.
The Deprecations list is also interesting to keep an eye on.
The list of error codes displayed to the end-user is useful for troubleshooting.