Signing

Consent Signature

1037 views December 19, 2018 May 3, 2019 3

A number of eID methods, such as 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. 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 fairly easy: notify our team and they will set up the necessary configuration.

 

Consent Signature technical overview

The typical life cycle of a Consent Signature request is:

  • Merchant determines that consent is required from the end-user
  • Merchant backend initializes the consent signature request to Signicat utilizing the OIDC protocol
  • Signicat relays the signature request to the Identity Provider; the Identity Provider sends a notification to the end-user’s mobile device
  • End-user signs the request on the mobile device
  • Merchant completes the process by downloading the SDO from Signicat

 

How to integrate Consent Signature

If you are building your own browserless native app and want to utilize mobile text-only signing, or Consent Signature, you can do so using our OpenID Connect (OIDC) protocol. The Consent Signature process is based on the OIDC Authorization Code Flow. The required steps are detailed below:

  1. Inform Signicat Operations that you would like to use the Consent Signature solution. Signicat will request some information about this setup.
    • If you wish to test your solution using our demo service, please use Client ID demo-inapp-sign, Redirect URI https://labs.signicat.com/redirect and method name nbid-inapp-sign or sbid-inapp-sign.
  2. Since Consent Signature is a headless solution, you will have to do all the calls towards the Signicat OIDC server from your own backend. Your backend will need to fulfill two major requirements:
    • The HTTP client should support HTTP Cookies, which should persist throughout the entire OIDC session.
    • The HTTP client should support and follow any HTTP redirects.
  3. Begin crafting the OIDC Authorization Request. The parameters are standard OIDC parameters, but the payload has to be encrypted in order to ensure the integrity of the signature. Examples of Authorization Request encryption in a number of common languages can be found at https://github.com/signicat/OIDC-MLE/tree/master/authorize-encrypt-examples. The requirements are as follows:
    • The HTTP request can be made using either GET or POST.
    • The authorization request must contain the HTTP header “Accept: application/json”.
    • The payload must be a Request Object (per OIDC Core specifications, section 6.1). 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).
      • 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 authorization 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. Please note that the value for this claim must be a list. For the example of Norwegian BankID, the claim to add looks like this: "login_hint": ["birthdate-ddmmyy", "phone-nnnnnnnn"].
  4. Once the OIDC Authorization 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.
    1. The response will contain a session cookie. This cookie must be used in consecutive requests.
    2. If the JSON instead contains “error” and “error_description” attributes, something went wrong, and the error_description attribute should contain valuable debugging information.
  5. At this point, it is time to start polling for a result:
    • For Norwegian BankID, the polling URI is returned as a STATUS_URI in the Authorization 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.
    • 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.
  6. Do 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 in step 3 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, and the rest of the flow is according to the OIDC standard (see “Receiving the Authorization Response” here. The “basic authorization” to use for the demo-inapp-sign OIDC client will be ZGVtby1pbmFwcDptcVotXzc1LWYyd05zaVFUT05iN09uNGFBWjd6YzIxOG1yUlZrMW91ZmE4.
  7. Do an HTTP GET request towards https://<ENV>.signicat.com/oidc/signature to retrieve the SDO (signed data object), with the access token in the authorization header.
    • The access token is valid for a relatively short amount of time. As such, it is critical that you download and store the resulting SDO document. Once the access token has expired, it will no longer be possible to retrieve the SDO document.

The following sequence diagram illustrates the Consent Signature sequence:

A functional example of this flow can be found at https://github.com/signicat/py-consent-sign.

Method-specific considerations

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

Swedish BankID Norwegian BankID
collectUrl statusUri
progressStatus status
completeUrl completeUri

Note that when the STATUS is not yet complete, the value returned with SwedishBankID is OUTSTANDING_TRANSACTION, whereas Norwegian BankID uses pending. When the STATUS is complete, the the value returned with SwedishBankID is COMPLETE, whereas Norwegian BankID uses finished.

 

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",
}

Other sources

Was this helpful?