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:

1. Redirect the end-user to the authorization endpoint with applicable parameters. 
2. The end user authenticates using BankID and is redirected back to your web application.
3. Handle the redirect request by checking parameters and handle potential errors. 
4. Exchange the code parameter for tokens by making a request to the token endpoint. 
   
   1. Use the ID token to identify the user.
   2. Use the Access token to access resource servers, for example in the context of signing documents online.
   3. Use the Refresh token to retrieve new access tokens.

Implementation

Initiate authentication request

...

Authorization Code flow with Proof Key for Code Exchange (PKCE)

Authorization Request

1. 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.
   
   
2. Use the authorization_endpoint found in the Discovery endpoint response.
   Note: Do not hard code the authorization_endpoint this value. Always retrieve it from the OpenID Connect configurationRetrieve the config regularly from the OIDC discovery endpoint, as it may change.
   
   
3. Generate a random string value for state and store it in a variable called stateyour user session.
   Important:
   1. The value must be non-guessable (e.g. GUID) and unique for each request.
   2. 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
   original request
   1. end-user session alongside a cookie.
      
      
   1. Generate a random string value for nonce and store it in a variable called nonceyour user session.
      Important:
      1. The value must
      be 
      1. be non-guessable, cryptographically random (your framework/language most likely have support for this)
       and
      1. and unique for each request.
      2. This will be used to verify integrity of ID token and mitigate replay attacks.
         
      Store the state and nonce value in your application so they can be retrieved later, i.e. using your preferred session mechanism. These values should be stored together.
      Build
      1. 
         
      1. Generate code_verifier for PKCE flow and store this in your user session.
         1. 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.
         2. This will be used to generate a code challenge (6) and during Token exchange later.
            
            
      2. Generate code_challenge from the code_verifier by generating a Base64-URL-encoded string of the SHA256 hash of the code verifier.
         
         
      3. Finally, build the authorization URL by adding the following query parameters (see see Authorize for more options and details):
         • client_id: Unique client identifier provided when provisioning the clientYour assigned client ID with BankID OIDC.
         • scope: Specify Comma separated list of scopes that indicate which information (see ID token) and resources you request access to. In the example below, we use openid and profile 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 for state.
         • nonce: Your generated value for nonce.
         • code_challenge: Your generated code_challenge.
         • code_challenge_method=S256



         Code Block
         title Example authorization requestAuthorization Request
         GET authorization_endpoint ?client_id=myclientyour-bankidclient-currentid &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

         &code_challenge=ixDBJg7pc3yT2h65DRvhjIbGko7U-t3cYVJmdMF-hTU &code_challenge_method=S256

      4. Finally redirect end-user to the completed 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. 

      1. Verify that the state parameter returned corresponds to the state parameter for your user session.

      2. Do a POST request to the token_endpoint with the provided code to get the ID token, Access token and Refresh token. 

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

      3. Important: Perform Token validation

         1. Verify the signature of the JWS tokens received and check the certificate chain of the signing key used by following this guide.

         2. Check claims by following this guide.
            
            
      4. Once validation is complete, you can access the claims in the various tokens:
         1. The ID token contains claims that can be used to identify the end-user. See ID token for available claims.
         2. The Access token can be used to access additional services such as document signing or additional user information (5).
            
            
      5. (optional) Fetch additional Userinfo through userinfo_endpoint.
         1. Use the access token you received in the previous step as Bearer token in the userinfo request
         2. Use the userinfo_endpoint found in the Discovery endpoint response.
         3. 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 value access_denied.
      • In addition to error, the response parameter error_description

      ...

      • may include BankID error codes the end-user experienced.

      ...

      Next steps

      It is recommended to take a look at Session handling to get a better understanding of the session lifetime.

      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.The list of error codes displayed to the end-user is useful for troubleshooting.