BankID Cloud Signature Consortium (CSC)

The BankID Cloud Signature Consortium (CSC) API is used to create qualified electronic signatures. This API is based on version 2.0.0.2 of the Cloud Signature Consortium API.

Pre-requisites

Access to the BankID eSign CSC API

To access the BankID eSign CSC API the merchant must have a BankID OIDC client with the scope esign/csc. This access token is only used for CSC oauth2/token (subsequent calls are authorized with the CSC access token).

curl --request POST \
  --url https://auth.{{env}}.bankid.no/auth/realms/{env}/protocol/openid-connect/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data scope=esign/csc \
  --data 'client_id={{client_id}}' \
  --data 'client_secret={{client_secret}}'

BankID Test users

Create BankID test users in BankIDs preprod environment. Instructions on how to create test users can be found here.

BankID eSign CSC API

The following methods are used in the BankID eSign CSC API:

CSC Call	Description	Authorization
POST /info	(Optional) Get information about the CSC service such as supported methods.	None
GET /oauth2/authorize	Initiate OAuth 2.0 authorization flow	None, but clientID and redirectUri are validated
POST /oauth2/token	Exchange the authorization code for an access token	Client credential access token from BankID OIDC
POST /credentials/list	Start the key and certificate generation. Returns a list of available credentials and certificates	CSC service token from /oauth2/token
POST /credentials/authorize	Authorize the access to the credential for remote signing, according to the authorization mechanisms associated to it. This method returns the Signature Activation Data (SAD) required to authorize the signatures/signHash method.	CSC service token from /oauth2/token
POST /signatures/signHash	Sign the data-to-be-signed hash	CSC service token from /oauth2/token

OpenAPI Specification

Please refer to the BankID CSC OpenAPI spec for more details and examples.

Sequence diagram

sequenceDiagram
autonumber
title: BankID eSign CSC API

 %%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryBorderColor': '#7C0000',
      'fontFamily': 'Arial',
      'fontSize': '24px'
      }
  }
}%%
    participant Merchant as Merchant
    participant BIDOIDC as BankID OIDC

    actor User

    box rgb(255,204,203) BankID eSign Infrastructure
        participant BIDCSC as  BankID CSC
        participant OIDC as eID Integration Hub
    end

    Note over Merchant, BIDOIDC: Merchant request API access
    Merchant-->>+BIDOIDC: Request access (scope esign/csc)
    BIDOIDC-->>-Merchant: Return access token


    Note over Merchant, BIDCSC: CSC: Authentication
    Merchant->>User: Redirect for CSC authentication
    User->>BIDCSC: Initiate CSC authentication
    BIDCSC -->>+User: Redirect to eID Hub
    User->>OIDC: Initiate OIDC authorization
    OIDC -->>User: Present IDPs
    User->>-OIDC: Authorize

    Note over User, OIDC: T&C and Certificate  acceptance
   OIDC ->>+User: Present certificate-to-be and T&C
   User -->>-OIDC: User accepts

    OIDC-->>User: Redirect Authorize response (auth code )

    User-->>BIDCSC: Redirect Authorize response (auth code )

   Note over Merchant, BIDCSC: CSC: User onboarding
    BIDCSC-->>Merchant: Redirect with auth code

    Merchant->>+BIDCSC: Get Token (POST oauth2/token)
    BIDCSC-->>-Merchant: Return Access Token (scope service)

    Merchant->>+BIDCSC: Post CSC credentials/list

    BIDCSC-->>-Merchant: Return certificates

    Merchant->>Merchant: Create *AdES structure and final data-to-be-signed hash

    Note over Merchant, BIDCSC: CSC: Signature Authorization

    Merchant->>+BIDCSC: CSC POST credentials/authorize
    BIDCSC-->>-Merchant: Return SAD

    Note over Merchant, BIDCSC: CSC Signature Creation
    Merchant->>+BIDCSC: CSC POST signatures/signHash
    BIDCSC-->>-Merchant: Return signature

Signature Visual Appearance

You may use the following image as template for the visual appearance of the signature.

Restrictions and limitations

Supported IDPs

The service supports the following IDPs:

• BankID Norway (High)

Max amount of hashes to be signed

The service supports signing of multiple hashes in one call. The maximum amount of hashes that can be signed in one call is 100. This is subject to change.

Known issues

• Only Norwegian Bokmål (nb-NO) is currently supported.