BankID CSC Signing API#

The BankID CSC Signing API is used to create qualified electronic signatures. This API is based on version 2.0.0.2 of the Cloud Signature Consortium API⁠ (opens in a new tab).

Pre-requisites#

Access to the BankID CSC Signing API#

To access the BankID CSC Signing 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⁠ (opens in a new tab). Instructions on how to create test users can be found here⁠ (opens in a new tab).

BankID CSC Signing API#

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

Hash algorithm and signature algorithm restrictions#

The service only supports the following algorithms:

• Hash algorithm OID: 2.16.840.1.101.3.4.2.1
• Signature algorithm OID: 1.2.840.10045.4.3.2

Acquiring Norwegian National Identity Number (NNIN) / Fødselsnummer#

To include the Norwegian National Identity Number (NNIN) / fødselsnummer in the certificate, the scope esign/nnin must be used when acquiring the access token from BankID OIDC and during the user authorization request to /oauth2/authorize.

The user will be given the option to approve to including the NNIN in the certificate during the authentication. Be aware that the user may decline this, in which case the process will be aborted with an access_denied error.

The NNIN will be included in the public certificate as a custom extension with the OID 2.16.578.1.61.2.4. The merchant must ensure that they handle this information in accordance with applicable data protection regulations.

Signature response#

The response from the POST /signatures/signHash method contains the raw base64 encoded signature value (r || s).
For use in CMS and other formats it usually needs to be transformed to ASN.1 DER format, like:

Ecdsa-Sig-Value ::= SEQUENCE {
        r  INTEGER,
        s  INTEGER
}

For example com.nimbusds.jose.crypto.impl.ECDSA.transcodeSignatureToDER⁠ (opens in a new tab)

Not Yet Implemented#

Login_hint#

Login_hint is not yet supported.

OpenAPI Specification#

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

Sequence diagram#

sequenceDiagram
autonumber
title: BankID CSC Signing 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#

Token single-use#

Each access token obtained from /oauth2/token must be used in the following endpoint order, exactly once per endpoint:

1. 1

   POST /credentials/list

2. 2

   POST /credentials/authorize

3. 3

   POST /signatures/signHash

If a token is reused at an endpoint it has already been used at, or if endpoints are called out of order, the service will respond with error code token_already_used (HTTP 400). To sign again, obtain a new access token by starting a new authorization flow.

POST /credentials/info can be called at any point and does not affect the token lifecycle. POST /credentials/list will return the same list of credentials and certificates for the same token, but the token must still be used in the correct order at the other endpoints.

Ensuring signer access to signed Documents#

When using this service, you must ensure that the end user who signs receives a copy of the signed document. If multiple signers are involved, you may wait to share the document until all participants have completed their signing.

iframe#

The CSC service does not support iframe embedding.

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 number of hashes that can be signed in one call is 50.