APP Signing using CIBA (Selected Cert/device)

Owned by Einar Ársæll Hrafnsson
Last updated: Jan 30, 2024 by Þórður Roth
11 min read

Step by step instructions for service providers on how to Signing using CIBA and Auðkennis APP on a selected device (selected cert).

Table of Contents

 

Requirements

For all steps to be successful the following must be at hand.

During setup

  • Client Id (received from Auðkenni)

  • Client secret (received from Auðkenni)

  • Related party (not necessary)

  • Base URI (received from Auðkenni)

  • Private Key (to sign a JSON Web Token)

  • Public Key (to give to Auðkenni for configuration)

Information needed at runtime

  • User’s Social Id number

  • Message text for user

  • Hash value for verification code calculation

 

Setup requirements used in the examples

  • Client id: myCibaClientId

  • Client secret: MyApiClientP4$sW

  • Base URI: pfzww.audkenni.is

  • Private Key: Not shown here for security reasons

  • Public Key: Not shown

All code examples are generated using Postman. They are therefore only for demo.

 

Step 1

Step 1: (Creating Cert Choice JSON Web Token)

The first step is to create a signed JWT to use for CIBA communication.

What the JWT need to include

  • login_hint (the users Social Id number)

  • scope (openid, profile, signature. Also possible to add “related party” info here (see example))

  • acr_values (“app-certificate-choice”. This value is different between authentication/signing methods)

  • iss (the Client id)

  • aud (Should have “https://pfzww.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni“)

  • exp (the lifetime of the token)

  • binding_message (leave it as ““ (empty))

  • binding_content (leave it as ““ (empty))

 

Also needed to create the JWT

  • Private key (to sign the JWT)

  • Alg info (Should be “RS256”)

Example of JWT

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJsb2dpbl9oaW50IjoiMTIzNDU2Nzg5MCIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgc2lnbmF0dXJlIFJFTEFURURQQVJUWTpNeU93bkNsaWVudCIsImFjcl92YWx1ZXMiOiJhcHAtY2VydGlmaWNhdGUtY2hvaWNlIiwiaXNzIjoibXlDaWJhQ2xpZW50SWQiLCJhdWQiOiJodHRwczovL3Bmend3LmF1ZGtlbm5pLmlzOjQ0My9zc28vb2F1dGgyL3JlYWxtcy9yb290L3JlYWxtcy9hdWRrZW5uaSIsImV4cCI6MTYxMTE1NTgwOC4zMjUsImJpbmRpbmdfbWVzc2FnZSI6IiIsImJpbmRpbmdfY29udGVudCI6IiJ9.D8GqbBlMtckYTnUpBNG3kif-yZcDFQ3FtVEC3cNEXcQCMNqTBHdzv3Ek43t4eVGVdSyoBFpNv3xnDhHH3-EsdyTkKpI6mDcIsHaropA0qnXYKahs0rD3ml27EJ0QvPC5ykdwIA6zgnfOiWX-VLRHFOdylAlRCBTtTH957gaG1TMJI3aRpxyVVZj2YgVv7QdMAoBe3CaDwft52Rcxil8n4ZeaHNJ0sCtsY61nGdj1ARM2MbjLmmjBDEQq7a_GgoE8QvqQ5yH_3ipM9KD17N3_8HEfQMU0SdsNw7eowNzYezPwFJU0MACKSfB8xJU0oHrOVsD_31vpW1R94lVhI4-YdQ

 

Example of JWT Payload

{ "login_hint": "1234567890", "scope": "openid profile signature RELATEDPARTY:MyOwnClient", "acr_values": "app-certificate-choice", "iss": "myCibaClientId", "aud": "https://pfzww.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni", "exp": 1611155808.325, "binding_message": "", "binding_content": "" }

 

 

Step 2

 

Step 2: (Cert Choice)

To ask for users Cert Choice using Auðkennis APP a POST call is sent to following URI:
https://pfzww.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni/bc-authorize

 

Parameters needed in call

We need to add following header parameter

  • A Basic Auth header, using the Client id and Client secret

We need to add following parameter

  • request (the value should be the JWT from step 1)

 

CURL example of the call

curl --location --request POST 'https://pfzww.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni/bc-authorize' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic bXlDaWJhQ2xpZW50SWQ6TXlBcGlDbGllbnRQNCRzVw==' \ --data-urlencode 'request=eyJ0eXAiOiJKV1QuLCJhbGciOiJSUzI1NiJ9.eyJeb2dpbl9oaW58IjoiNjE3ODg4OCIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgc2lnbmF0dXJlIFJFTEFURURQQVJUWTpNeU93bkNsaWVudCIsImFjcl92YWx1ZXMiOiJzaW0tYXV0aCIsImlzcyI6Im15Q2liYUNsaWVudElkIiwiYXVkIjoiaHR0cHM6Ly9wZnp3dy5hdWRrZW5uaS5pczo0NDMvc3NvL29hdXRoMi9yZWFsbXMvcm9vdC9yZWFsbXMvYXVka2VubmkiLCJleHAiOjE2MTEwNzIxODQuOTkyLCJiaW5kaW5nX21lc3NhZ2UiOiJBdXRoZW50aWNhdGlvbiB0byBBdcOwa2VubmkiLCJiaW5kaW5nX2NvbnRlbnQiOiIifQ.a0NM11W2PNyfzki-gHTrQZqVhuNgL6Uh4sjQQy96lHsfD1NkVe7h-41JT9to-c710GpSvF1ExAcb7b7Bjmy6Ep0M3BVuz066fzv0YfiIHbXd6pQIEXVqUxHQ6mteW1MmaI-xsYDgG_ahXS7ZD8VrN2y1hOGUt1P4kMnVkWVpSQBjolxsZdV1HYn7n9Iy1z0gNaZb_3EIiNGLAHzI2zaDG4x0SFl-vkslf0eqfBMyEquKNFeoBqLLW7WT-PXpIaCQuJ_7ohqbx-pO_JI9Hm2Fv-VH9HoXUhsXWxig3YcQVqYBzq5aEdrE_mulCJMGeCWM02HTxpHennN5GdttlGVksg'

 

C# - RestSharp example of the call

 

 

Step 2: Expected response

The CIBA service answer is in JSON format.

When Step 2 is executed the signing process at the users device starts.

The response should include following

  • auth_req_id (to use in next step)

  • expires_in (the lifetime of th id)

  • interval

 

Example of answer from Step 2

 

 

Step 3

 

Step 3: (Poll for token 1)

After executing Step 2 the Cert Choice process at the users device starts. It depends on the user, the device and the network how long time this process takes.

In this step we poll for results from the cert choice process. When cert choice process is finished successfully you will receive answer with Access and Id token of the user.

To poll for tokens we send another POST call to following URI:
https://pfzww.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni/access_token

 

Parameters needed in call

We need to add following header parameter

  • A Basic Auth header, using the Client id and Client secret

We need to add following parameter

  • grant_type (the value should be: “urn:openid:params:grant-type:ciba”)

  • auth_req_id (the value should be the auth_req_id from last step answer)

 

CURL example of the call

 

C# - RestSharp example of the call

 

 

Step 3: Expected response (Cert Choice still in process)

If you run the poll call before the users cert choice process is finished you will receive a answer notifying the process isn’t finished.

The REST API service answer is in JSON format.

If you get answer like this you need to wait for short time and run Step 3 call again.

The response should include following

  • error_description

  • error

Example of answer from Step 3

 

Step 3: Expected response (Cert Choice is finished)

The answer from this call should give you the Access and Id tokens along type and lifetime.

The Id token contains a document number and a signing certificate.

The REST API service answer is in JSON format.

Best practice

Best practice is to verify the users info in the Id token against the users info in the certificate and the social Id number entered by the user in beginning (login_hint).

The response should include following

  • access_token

  • scope

  • id_token

  • token_type

  • expires_in (lifetime of the tokens)

Example of answer from step 3

 

Example of the payload in Access token

 

Example of the payload in Id token

 

 

 

Step 4

 

Step 4: (Userinfo 1)

Here we ask for the users info using the Access token as Authorization header parameter.

To get the Userinfo we send a POST call to following URI:
https://pfzww.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni/userinfo

Parameters needed in call

We need to add following header parameter

  • Token (Bearer, using the Access token from last call as value)

 

CURL example of the call

 

C# - RestSharp example of the call

 

 

Step 4: Expected response

The answer from this call should give you a document number and a signing certificate. The same as in the Id token from last step.

The REST API service answer is in JSON format.

Best practice

Best practice is to verify the users info in the Id token against the users info in the certificate and the social Id number entered by the user in beginning (login_hint).

The response should include following

  • signature (with value “na”)

  • documentNr (text, for use in next step)

  • certificate (signing certificate)

  • nationalRegisterId (The social id number of the user)

  • name (The users name)

  • sub (A unique Id of the user in our system)

  • subname (A unique Id of the user in our system)

Example of answer from step 4

 

 

 

Step 5

Step 5: (Creating Sign With Cert JSON Web Token)

The step is to create a signed JWT to use for CIBA communication.

What the JWT need to include

  • login_hint (here we put the documentNr from last step results)

  • scope (openid, profile, signature. Also possible to add “related party” info here (see example))

  • acr_values (“app-sign-with-certificate”. This value is different between authentication/signing methods)

  • iss (the Client id)

  • aud (Should have “https://pfzww.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni“)

  • exp (the lifetime of the token)

  • binding_message (the message to display at users mobile device)
    Max length of this message string is 60 characters.

  • binding_content (Hash value, used to calculate verification code)

 

Optional parameters in JWT

Three optional parameters can be added to the JWT. These optional parameters makes it possible to show messages of up to 200 characters in length and/or let the App display 3 Codes user have to select the correct Verification Code from.

  • binding_message_long (Long message string to display at users mobile device. This message string can hold up to 200 characters. “confirmation_message” must also be in JWT and must be set to “true” for this message string to be used)

  • confirmation_message (If set to “true” then a prompt window is displayed at users mobile device. The user needs to confirm before continuing the process. If set to “false” the user is prompt for PIN right away)

  • vchoice (Verification code. If set to “true” three codes are displayed for user to select the correct one to continue. If set to “false” the verification code is displayed directly)

Please note, if both vchoice and confirmation_message are set to “true” the selecting of Verification code is made on the prompt window.

 

Expected behavior when using optional parameters

binding_message_long

confirmation_message

vchoice

Expected behavior

binding_message_long

confirmation_message

vchoice

Expected behavior

Not included, included empty or with a string

Not included or with “false”

Not included or with “false”

App prompts for PIN with message from “binding_message”

Not included, included empty or with a string

Not included or with “false”

Included with “true”

App prompts for selecting of Verification Code. Displays message from “binding_message”

Not included, included empty or with a string

Included with “true”

Not included or with “false”

If “binding_message_long” contains message then a prompt window appears with that message. If “binding_message_long” is empty or not included the message from “binding_message” are displayed

Not included, included empty or with a string

Included with “true”

Included with “true”

If “binding_message_long” contains message then a prompt window appears with that message along selecting of Verification Code. If “binding_message_long” is empty or not included the message from “binding_message” are displayed along selecting of Verification Code

Included with a string up to 200 characters

Not included or with “false”

Not included or with “false”

App prompts for PIN with message from “binding_message”

Included with a string up to 200 characters

Not included or with “false”

Included with “true”

App prompts for selecting of Verification Code. Displays message from “binding_message”

Included with a string up to 200 characters

Included with “true”

Not included or with “false”

App prompts for confirmation displaying message from “binding_message_long”

Included with a string up to 200 characters

Included with “true”

Included with “true”

App prompts for selecting of Verification Code. Displays message from “binding_message_long”

 

Also needed to create the JWT

  • Private key (to sign the JWT)

  • Alg info (Should be “RS256”)

The hash value

The hash string is used to generate the verification code displayed in the users APP.

You’ll need to provide the hash string to use. That’s how you can calculate the verification code at your side to display at your website for your user to see.

The hash string should be of type SHA512. Click here to search for more info about SHA512.

The verification code is calculated by:

verification code = integer(SHA256(the hash)[-2:-1]) mod 10000

Calculate SHA256 from the hash, extract 2 rightmost bytes from the result, interpret them as a big-endian unsigned integer and take the last 4 digits in decimal form for display. SHA256 is always used here.

Please mind that the hash string should be in Base64 format.

In this example we have generated a hash string and calculated a verification code.

Text used to generate a hash string

“Auðkenni APP Signing“

Hash string generated

j9AAK/VM1kokNqRoDTHGOXZ8lFM6nt9q+vWBB1dvyItYcoJ9WH4d8HGmb3RbafzBhg1sf0cY0qBZatGaUOoLKA==

Verification code calculated from the hash

9502

 

Please note, you could be getting a different Hash string based on the Encoding type your solution is using. See here: Q&A | Why am I getting different Hash value than in Instructions?

 

Example of JWT

 

Example of JWT Payload

 

Example of JWT Payload using optional parameters

 

 

Step 6

 

Step 6: (Signing with selected Cert)

To sign using Auðkennis APP a POST call is sent to following URI:
https://pfzww.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni/bc-authorize

 

Parameters needed in call

We need to add following header parameter

  • A Basic Auth header, using the Client id and Client secret

We need to add following parameter

  • request (the value should be the JWT from step 1)

 

CURL example of the call

 

C# - RestSharp example of the call

 

 

Step 6: Expected response

The CIBA service answer is in JSON format.

When Step 2 is executed the signing process at the users device starts.

The response should include following

  • auth_req_id (to use in next step)

  • expires_in (the lifetime of th id)

  • interval

 

Example of answer from Step 6

 

 

Step 7

 

Step 7: (Poll for token)

After executing Step 2 the signing process at the users device starts. It depends on the user, the device and the network how long time this process takes.

In this step we poll for results from the signing process. When signing process is finished successfully you will receive answer with Access and Id token of the user.

To poll for tokens we send another POST call to following URI:
https://pfzww.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni/access_token

 

Parameters needed in call

We need to add following header parameter

  • A Basic Auth header, using the Client id and Client secret

We need to add following parameter

  • grant_type (the value should be: “urn:openid:params:grant-type:ciba”)

  • auth_req_id (the value should be the auth_req_id from last step answer)

 

CURL example of the call

 

C# - RestSharp example of the call

 

 

Step 7: Expected response (Signing still in process)

If you run the poll call before the user signing process is finished you will receive a answer notifying the process isn’t finished.

The REST API service answer is in JSON format.

If you get answer like this you need to wait for short time and run Step 3 call again.

The response should include following

  • error_description

  • error

Example of answer from Step 7

 

Step 7: Expected response (Signing is finished)

The answer from this call should give you the Access and Id tokens along type and lifetime.

The Id token contains a PKCS1 signature and a signing certificate.

The REST API service answer is in JSON format.

Best practice

Best practice is to verify the signature and the certificate. Verify the user’s info in the Id token against the certificate and the social Id number entered by the user in beginning (login_hint). By decoding the signature using the certificate you should end up with the hash from the earlier step.

The response should include following

  • access_token

  • scope

  • id_token

  • token_type

  • expires_in (lifetime of the tokens)

Example of answer from step 7

 

Example of the payload in Access token

 

Example of the payload in Id token

 

 

 

Step 8

 

Step 8: (Userinfo 2)

Here we ask for the users info using the Access token as Authorization header parameter.

To get the Userinfo we send a POST call to following URI:
https://pfzww.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni/userinfo

Parameters needed in call

We need to add following header parameter

  • Token (Bearer, using the Access token from last call as value)

 

CURL example of the call

 

C# - RestSharp example of the call

 

 

Step 8: Expected response

The answer from this call should give you a PKCS1 Signature and a signing certificate. The same signature and certificate as is in the Id token from last step.

The REST API service answer is in JSON format.

Best practice

Best practice is to verify the signature and the certificate. Verify the user’s info in answer against the certificate and the social Id number entered by the user in beginning (login_hint). By decoding the signature using the certificate you should end up with the hash from the earlier step.

The response should include following

  • signature (PKCS1)

  • documentNr (variable text, for Auðkennis internal usage)

  • certificate (signing certificate)

  • nationalRegisterId (The social id number of the user)

  • name (The users name)

  • sub (A unique Id of the user in our system)

  • subname (A unique Id of the user in our system)

Example of answer from step 8