# 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.
# 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 initialises the Consent Signature request to Signicat using 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 (signed data object) from Signicat.
# How to integrate Consent Signature
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
orsbid-inapp-sign
ormobileid-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:
- 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.
# 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 athttps://<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:
- 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. - 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:
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"
}