link
Developer Pages

# Consent Signature

Page contents

# Introduction

A number of ID methods, such as Signicat's MobileID, Swedish BankID and Norwegian BankID, support the signing of text elements such as consent messages. Designed to fill the gap between document signing and pure text consents, this can be used to confirm a payment transaction or to give consent to usage of personal data for a particular purpose.

Note

Consent Signature contrasts with traditional document signature mechanisms, as it applies specifically to small text elements.

Through the process of signing a consent, merchants are able to securely identify the end-user according to EU regulations and the user is legally bound to the message in question, meaning that the resulting signature can be used as evidence.

Consent Signature is a separate configuration within our OpenID Connect (OIDC) protocol. Using Consent Signature if you already have an existing customer relationship with Signicat is easy: Contact Signicat Support to have the necessary configuration set up.

The typical life cycle of a Consent Signature request is:

  1. Merchant determines that consent is required from the end-user
  2. Merchant backend initialises the Consent Signature request to Signicat using the OIDC protocol
  3. Signicat relays the signature request to the Identity Provider; the Identity Provider sends a notification to the end-user's mobile device
  4. End-user signs the request on the mobile device
  5. Merchant completes the process by downloading the SDO (signed data object) from Signicat.

If you are building your own browserless native app and want to use mobile text-only signing, or Consent Signature, you can do so using the OpenID Connect (OIDC) protocol. The Consent Signature process is based on the OIDC authorisation code flow.

The steps for integrating Consent Signature are detailed below:

# 1. Informing Signicat

Inform Signicat that you would like to use the Consent Signature solution. Signicat will request some information about this setup.

# 2. Testing your solution

If you wish to test your solution using our demo service, use the following details:

  • Client ID demo-inapp-sign
  • Redirect URI https://labs.signicat.com/redirect
  • Method name nbid-inapp-sign or sbid-inapp-sign or mobileid-inapp-consent-sign

# 3. Backend prerequisites

Since Consent Signature is a headless solution, you will have to perform all the calls towards the Signicat OIDC server from your own backend. Your backend will need to fulfill two major requirements:

  1. The HTTP client should support HTTP Cookies, which should persist throughout the entire OIDC session.
  2. The HTTP client should support and follow any HTTP redirects.

# 4. Crafting the OIDC authorisation request

Begin crafting the OIDC authorisation request. The parameters are standard OIDC parameters, but the payload has to be encrypted with Full Message-Level Encryption (MLE) in order to ensure the integrity of the signature.

Examples of authorisation request encryption in a number of common languages can be found at https://github.com/signicat/OIDC-MLE/tree/master/authorize-encrypt-examples (opens new window).

The requirements are as follows:

The HTTP request can be made using either GET or POST.

The authorisation request must contain the HTTP Header "Accept: application/json".

The payload must be a Request Object (per OIDC Core specifications, section 6.1 (opens new window)). An example is provided in the section on method-specific considerations below.

The request must be an encrypted JWT, which contains the aforementioned Request Object (as specified at https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests (opens new window)).

  • The JWE token must be encrypted with the public key "use":"enc" available at https://<ENV>.signicat.com/oidc/jwks.json.

  • The protected header for the JWE token must contain the following claims:

    • "enc"="A256CBC-HS512"
    • "typ"="JWE"
    • "kid" and "alg"

The values for kid and alg are specified at https://<ENV>.signicat.com/oidc/jwks.json.

The authorisation request must contain the scope value signicat.sign.

The Request Object must contain the text to be signed. The claim name is signicat_signtext. This is the text to be signed that will be displayed on the end-user's phone .

The Request Object must contain the user's national identification number as a claim. The value for the national identification number claim must be a list. For the example of Norwegian BankID, the claim to add looks like this: "login_hint": ["birthdate-ddmmyy", "phone-nnnnnnnn"].

# 5. Receiving the JSON response

Once the OIDC authorisation request is sent from the HTTP Client to the Signicat OIDC server, you will receive a JSON response. The exact format of the response is dependent on the method in question. Details can be found in the section on method-specific considerations below.

Important

The response will contain a session cookie. This cookie must be used in consecutive requests.

If the JSON instead contains error and error_description attributes, something went wrong and the error_description attribute should contain valuable debugging information.

# 6. Polling for a result

At this point, it is time to start polling for a result:

  1. For Norwegian BankID, the polling URI is returned as a STATUS_URI in the authorisation request response. The exact format of the response is dependent on the method in question. Details can be found in the section on method-specific considerations below.
  2. The status won't be complete before the user has finished, but once the user has finished, a COMPLETE_URI attribute will also be present in the object.

# 7. Completing the operation

Perform an HTTP GET request towards the COMPLETE_URI provided. After a series of redirects, the HTTP client is going to arrive at the OIDC redirect URI requested earlier with code and state URL parameters.

The web service hosted at this redirect URI should extract the code and state query parameters from the request made by the app HTTP client.

The rest of the flow is according to the OIDC standard (see "Receiving the authorisation response" here. The basic authorisation to use for the demo-inapp-sign OIDC client will be ZGVtby1pbmFwcDptcVotXzc1LWYyd05zaVFUT05iN09uNGFBWjd6YzIxOG1yUlZrMW91ZmE4.

# 8. Retrieving the response

Perform an HTTP GET request to the signature endpoint of the Signicat OIDC backend. This will retrieve the response in the form of either a signed JSON Web Token (JWT) or an LTV-SDO with a signed JSON Web Token as the payload, depending on the configuration at Signicat's end.

GET <SIGNICAT_SIGNATURE_ENDPOINT> Authorization: Bearer <access_token>

The access token is valid for a relatively short amount of time. As such, it is critical that you download and store the response. Once the access token has expired, it will no longer be possible to retrieve the response.

# Sequence diagram

The following sequence diagram illustrates the Consent Signature sequence:

click-to-zoom

Note

You can find a functional example of the Consent Signature process flow at https://github.com/signicat/py-consent-sign (opens new window).

# Method-specific considerations

The following table illustrates the differences in the Authorisation response depending on the ID method used.

Swedish BankID Norwegian BankID MobileID
collectUrl statusUri statusUrl
progressStatus status status
completeUrl completeUri completeUrl

When the STATUS is not yet complete, the values returned are as follows:

Swedish BankID Norwegian BankID MobileID
OUTSTANDING_TRANSACTION pending PENDING

When the STATUS is complete, the the values returned are as follows:

Swedish BankID Norwegian BankID MobileID
COMPLETE finished COMPLETED

A typical payload Request Object for Swedish BankID looks as follows:

    {
        "login_hint": ["subject-nnnnnnnnnnnn"],
        "scope": "openid profile signicat.sign",
        "signicat_signtext": "I confirm my purchase of broadband subscription Medium500.",
        "acr_values": "urn:signicat:oidc:method:sbid-inapp-sign",
        "response_type": "code",
        "redirect_uri": "https://labs.signicat.com/redirect",
        "state": 'state123',
        "client_id": "demo-inapp-sign"
    }

A typical payload Request Object for Norwegian BankID looks as follows:

    {
        "login_hint": ["birthdate-ddmmyy","phone-nnnnnnnn"],
        "scope": "openid profile signicat.sign",
        "signicat_signtext": "I confirm my purchase of broadband subscription Medium500.",
        "acr_values": "urn:signicat:oidc:method:nbid-inapp-sign",
        "response_type":"code",
        "redirect_uri": "https://labs.signicat.com/redirect",
        "state": 'state123'
        "client_id": "demo-inapp-sign"
    }

A typical payload Request Object for Signicat MobileID looks as follows:

    {
         "login_hint":["externalRef-sampleUser","deviceId-4f5d09bb-4f21-4b4a-8d0d-d1bfc7cf0a9a","metaData-TYPICALLY_BASE64_JSON"],
         "scope":"openid profile signicat.sign",
         "signicat_signtext":"I confirm my purchase of broadband subscription Medium500.",
         "acr_values":"urn:signicat:oidc:method:mobileid-inapp-consent-sign",
         "response_type":"code",
         "redirect_uri":" https://labs.signicat.com/redirect",
         "state":"state123",
         "client_id":"sample-mobileid-oidc-client"
    }

# Other sources

Last updated: 01/11/2022 08:35 UTC

← Business signature →