Document toolboxDocument toolbox

Simple flow implementation guide

Owned by Jan Åge Lavik
Last updated: 22 Mar 2024 by Markdown Macros for Confluence
2 min read

API

The simplified flow can be used for text signing and can be initiated by providing the sign scope and the text to be signed, i.e. sign_txt, as query parameters to the authorization request:

GET [authorize_endpoint]... &scope=sign&sign_txt=base64encoded(utf8-string)

The text to be signed must be base64 encoded and provided in the query parameter sign_txt.

The result contains the basic signatures of the merchant and end user, as well as the hash over the received text. The result is contained in the sign_result claim in the ID token.

Claims

The following table show the additional claims in the id_token after a simplified flow sign session has been finished.

ClaimExampleDescription
sign_result
"sign_result" : {
    "endUser" : "MIAGC...",
    "merchant" : "MIAGC...",
    "hash" : "4oK3g..."
}

Signatures of the merchant and end user, as well as the hash over the received text.

Step-by-step

Simple-text signing allows the end user to sign a predefined text. The result contains the basic signatures of the merchant and end user, as well as the hash over the received text.

Following the regular Authorization Code flow:

StepWhat you doEndpointMethodConsiderationsRemarks
1

Get the key properties of the OIDC provider

Openid-configurationGET

2Build the authorization URL, and redirect the user to the authorization endpointAuthorizeGET

Include sign scope and sign_txt as query parameters.

In the callback, make sure to check for error and matching states

sign_txt is the text to be signed, and must be base64 encoded.

This is where the end user interacts with BankID.

(warning) Note that sign_txt has a limit of 150 characters. Use the SEID-SDO flow if the text length exceeds this limit. BankID on mobile has a limit of 118 characters.

3Exchange authorization code for tokensTokenPOST

Check matching state and nonce in callback.

The ID Token will contain signed data in sign_result claim.

4Fetch our public keys and use these to validate token signaturesJwkGET

Example sign_result claim:


"sign_result" : 
{
    "endUser" : "MIAGC...",
    "merchant" : "MIAGC...",
    "hash" : "4oK3g..."
}

Sequence diagram