Bank iD
Start developing nowDocumentationFAQ

Log in
Register
Bank iD

Bank iD is a digital solution for companies that allows safe client identification and electronic signature.

info@bankid.cz
Navigation

Start developing now Documentation FAQ UX manual Bank iD

Documents

Terms of use Privacy policy

  1. Documentation
  2. Code Examples
Docs
How to get started with Bank iD
Highlevel Overview
API Overview
Code Examples
Code ExamplesBank iD OIDC ConfigurationExample of building a Bank iD Login URIToken exchange exampleUserInfo or Profile Call exampleExample of obtaining specific Bank iD products
Security
Mobile Applications
Support
API
Bank iD APIs for SeP
SeP APIs for Bank iD
Bank docs
Overview for Banks
Bank APIs
Security
Error callbacks
Bank API
IDP APIs for Bank iD
Bank iD APIs for IDP

Code Examples#

Version: 1.1 updated 26.07.2022

We've prepared examples on our GitHub, where you can check out authentication (Bank iD CONNECT, Bank iD IDENTIFY):

  • CURL
  • Java
  • .NET
  • NodeJS
  • JavaScript
  • PHP

Next you can find examples of authorization (Bank iD SIGN):

  • NodeJS
  • .NET
  • PHP

We continuously update and supplement the examples.

This document contains several examples for calling and using essential Bank iD services. The code samples are intended primarily for the first acquaintance on the Bank iD Sandbox.

Prepared examples:

  • Bank iD OIDC Configuration
  • Authorization URI
  • Token exchange
  • Profile and Userinfo Call
  • Bank iD Products

Bank iD OIDC Configuration#

Example of obtaining OpenID Connect configuration data from Bank iD Sandbox

This configuration provides information about OpenID Connect service:

  • endpoint addresses
  • encryption and signing algorithms
  • list of supported scopes and claims
  • list of supported grants and functions
import com.nimbusds.oauth2.sdk.http.HTTPRequest;
import com.nimbusds.oauth2.sdk.http.HTTPResponse;
import com.nimbusds.oauth2.sdk.id.Issuer;
import com.nimbusds.openid.connect.sdk.op.OIDCProviderConfigurationRequest;
import com.nimbusds.openid.connect.sdk.op.OIDCProviderMetadata;
import java.net.URI;

...

    // The Bank iD Sandbox issuer uri
    String bankIDIssuerURI = "https://oidc.sandbox.bankid.cz/";

    // Create new issuer
    Issuer issuer = new Issuer(bankIDIssuerURI);
    
    // Request for configuration
    OIDCProviderConfigurationRequest request = new OIDCProviderConfigurationRequest(issuer);
    try {
        HTTPRequest httpRequest = request.toHTTPRequest();
        
        // Call for configuration
        HTTPResponse httpResponse = httpRequest.send();
        
        // Parsing Bank iD Configuration
        OIDCProviderMetadata opMetadata = OIDCProviderMetadata.parse(httpResponse.getContentAsJSONObject());
        
        // Obtain the auth endpoint URI
        URI auth = opMetadata.getAuthorizationEndpointURI();
        
    } catch(IOException e) {
        // TODO processing the error
    } catch(ParseException e) {
        // TODO processing the error
    }

...

Example of building a Bank iD Login URI#

The example uses values and parameters relevant to the Bank iD service. We recommend obtaining the URL for the correct auth endpoint call from the OIDC configuration endpoint Bank iD. We also recommend that you verify supported scopes and grants against the configuration.

The exact values of the parameters should correspond to the application settings in the Bank iD Developer Portal.

import com.nimbusds.oauth2.sdk.ResponseType;
import com.nimbusds.oauth2.sdk.Scope;
import com.nimbusds.oauth2.sdk.id.ClientID;
import com.nimbusds.oauth2.sdk.id.State;
import com.nimbusds.openid.connect.sdk.AuthenticationRequest;
import com.nimbusds.openid.connect.sdk.Nonce;
import com.nimbusds.openid.connect.sdk.Prompt;
import java.net.URI;

...

    // Application configuration from Bank iD dev. portal
    String[] scopes = {"openid", "profile.titles", "profile.name", "profile.email", "offline_access"};
    ClientID clientId = new ClientID(" ... application client_id ...");
    String redirectURI = "https://application.my/callback";

    // Creating the required scopes
    Scope scope = new Scope(scopes);

    try {
        
        // Construct the AuthenticationRequest Builder with scope, client_id and redirect_uri parameters
        AuthenticationRequest.Builder authBuilder = new AuthenticationRequest.Builder(
            // We are generating a URL for code_grant
                new ResponseType("code"),
                scope,
                clientId,
                new URI(redirectURI));
        
        // Set the auth endpoint URI
        authBuilder.endpointURI(new URI(authorizationEndpoint));
        
        // Set random (default constructor) state
        authBuilder.state(new State());
        
        // Set random (default constructor) nonce
        authBuilder.nonce(new Nonce());
        
        // Set prompt=consent
        authBuilder.prompt(new Prompt("consent"));

        // ... and build the auth login URI
        AuthenticationRequest request = authBuilder.build();

    } catch (URISyntaxException e) {
        // TODO processing the error
    }

...

Token exchange example#

Example of obtaining OIDC tokens in exchange for issued code. This exchange needs to be done in the case of a code grant authorization flow after successfully completing the authorization. The issuance of a refresh_token is conditional on the registration of a refresh token grant at the Developer Portal for application and the use of the scope offline_access in the /auth request. The example assumes that the application already has code obtained from a callback call to a redirect URI.

import com.nimbusds.jwt.JWT;
import com.nimbusds.oauth2.sdk.*;
import com.nimbusds.oauth2.sdk.auth.ClientAuthentication;
import com.nimbusds.oauth2.sdk.auth.ClientSecretPost;
import com.nimbusds.oauth2.sdk.auth.Secret;
import com.nimbusds.oauth2.sdk.id.ClientID;
import com.nimbusds.oauth2.sdk.token.AccessToken;
import com.nimbusds.oauth2.sdk.token.RefreshToken;
import com.nimbusds.openid.connect.sdk.OIDCTokenResponseParser;
import java.net.URI;

...

    // Application configuration from Bank iD dev. portal
    ClientID clientId = new ClientID(" ... application client_id ...");

    // Application redirect URI ()
    String redirectURI = "https://application.my/callback";
    
    // Client secret value
    String clintSecretStr = "... application client secret ...";
    
    // Bank iD token endpoint (from discovery endpoint)
    String tokenEndpoint = "https://oidc.sandbox.bankid.cz/token";
    
    // Code from callback on redirect URI
    String code = "... code ...";
    
    try {
        // Set the code object
        AuthorizationCode authorizationCode = new AuthorizationCode(code);
        
        // Set the redirectURI and create code grant object
        URI callbackURI =  new URI(redirectURI);
        AuthorizationGrant codeGrant = new AuthorizationCodeGrant(authorizationCode, callbackURI);
    
        // Set the client_secret value and create client authentication
        Secret clientSecret = new Secret(clintSecretStr);
        ClientAuthentication clientAuth = new ClientSecretPost(clientId, clientSecret);
    
        // Create token endpoint URI and make the token request
        URI tokenEndpointURI = new URI(tokenEndpoint);
        TokenRequest request = new TokenRequest(tokenEndpointURI, clientAuth, codeGrant);
    
        // Get the token response
        TokenResponse tokenResponse = OIDCTokenResponseParser.parse(request.toHTTPRequest().send());
        if (tokenResponse.indicatesSuccess()) {
            
            // Get success response
            AccessTokenResponse successResponse = tokenResponse.toSuccessResponse();
            
            // Obtaining an access_token
            AccessToken accessToken = successResponse.getTokens().getAccessToken();
            
            // and also obtaining an refresh_token (if can)
            RefreshToken refreshToken = successResponse.getTokens().getRefreshToken();
            
            // and and finally obtaining an id_token
            JWT idToken = successResponse.getTokens().toOIDCTokens().getIDToken();
            
            ...
            
        } else {
            // TODO processing the error
        }
    } catch (URISyntaxException e) {
        // TODO processing the error
    } catch (ParseException e) {
        // TODO processing the error
    } catch (IOException e) {
        // TODO processing the error
    }

UserInfo or Profile Call example#

Example of how to get user data from the Bank iD UserInfo and Profile API. The example assumes that the end-user was before the call properly authenticated itself, and the code was exchanged for a access_token. The range of data provided corresponds to the used scopes.

The example shows retrieving data in the form of JSON.

import com.nimbusds.oauth2.sdk.ParseException;
import com.nimbusds.oauth2.sdk.http.HTTPResponse;
import com.nimbusds.oauth2.sdk.token.BearerAccessToken;
import com.nimbusds.openid.connect.sdk.UserInfoRequest;
import java.net.URI;

...

    // Set the right data API url (for example UserInfo)
    String userInfoURL = "https://oidc.sandbox.bankid.cz/userinfo";
    
    try {
        URI userInfoEndpoint = new URI(userInfoURL);
        
        // You must have a valid access_token
        BearerAccessToken token = BearerAccessToken.parse("Bearer .... my access token ...");
    
        // And call the API
        HTTPResponse dataResponse = new UserInfoRequest(userInfoEndpoint, token)
                        .toHTTPRequest()
                        .send();
    
        // Data in JSON format
        String data = dataResponse.getContentAsJSONObject().toJSONString();
    
    } catch (URISyntaxException e) {
        // TODO processing the error
    } catch (ParseException e) {
        // TODO processing the error
    } catch (IOException e) {
        // TODO processing the error
    }

...

Example of obtaining specific Bank iD products#

Data of individual products are obtained from /userinfo and /profile API. Userinfo endpoint is primarily intended for obtaining CONNECT product data. The Profile API is used to get data from identification products such as IDENTIFY, IDENTIFY PLUS, and IDENTIFY AML.

The data content of individual products depends on what scope the application has set in the Developer Portal and what scope was finally agreed by the user during the authentication process.

As object classes of Bank iD products for this example, it is possible to use examples of java classes in the public Bank iD repository. The structure of all essential Bank iD products (CONNECT, IDENTIFY, IDENTIFY PLUS and IDENTIFY AML) is available in the repository Bank iD Examples.

import com.google.gson.Gson;
import com.nimbusds.oauth2.sdk.ParseException;
import com.nimbusds.oauth2.sdk.http.HTTPResponse;
import com.nimbusds.oauth2.sdk.token.BearerAccessToken;
import com.nimbusds.openid.connect.sdk.UserInfoRequest;
import cz.bankid.examples.product.IdentifyAML;
import java.net.URI;

...

    // Set the right data API url (for example UserInfo)
    String profileURL = "https://oidc.sandbox.bankid.cz/profile";
    
    try {
        URI profileEndpoint = new URI(profileURL);
        
        // You must have a valid access_token
        BearerAccessToken token = BearerAccessToken.parse("Bearer .... my access token ...");
    
        // And call the Profile API
        HTTPResponse profileResponse = new UserInfoRequest(profileEndpoint, token)
                .toHTTPRequest()
                .send();
    
        // Use Gson for transformation
        Gson gson = new Gson();
        if (profileResponse.getStatusCode() != 200) {
    
            // Convert json to IdentifyAML product (from Bank iD repository)
            IdentifyAML amlProduct = gson.fromJson(
                    profileResponse.getContentAsJSONObject().toJSONString(), 
                    IdentifyAML.class
            );
    
            // Get name from users data
            String userName = amlProduct.getFamily_name();
    
            ...
        
        }
    
    } catch (URISyntaxException e) {
        // TODO processing the error
    } catch (ParseException e) {
        // TODO processing the error
    } catch (IOException e) {
        // TODO processing the error
    }

...