APP Authentication using REST API (api_v202) #NEW
Step by step instructions for service providers on how to communicate with our REST API for authentication using Auðkennis APP.
Table of Contents
- 1 Table of Contents
- 2 Requirements
- 3 Setup requirements used in the examples
- 4 Step 1
- 5 Step 2
- 5.1 Step 2: (Authenticate using Auðkennis APP)
- 5.1.1 Callbacks
- 5.1.1.1 IDToken1 (_id: 0)
- 5.1.1.2 IDToken2 (_id: 1)
- 5.1.1.3 IDToken3 (_id: 2)
- 5.1.1.4 IDToken4 (_id: 3)
- 5.1.1.5 IDToken5 (_id: 4)
- 5.1.1.6 IDToken6 (_id: 5)
- 5.1.1.6.1 Display the verification code directly
- 5.1.1.6.2 Display three codes to select from
- 5.1.1.6.3 Example of callback answer to send in call
- 5.1.1.7 IDToken7 (_id: 6)
- 5.1.1.8 IDToken8 (_id: 7)
- 5.1.1.8.1 Text used to generate a hash string
- 5.1.1.8.2 Hash string generated
- 5.1.1.8.3 Verification code calculated from the hash
- 5.1.1.8.4 Example of callback answer to send in call
- 5.1.1.9 IDToken9 (_id: 8)
- 5.1.2 Example of the whole body in a call
- 5.1.3 CURL example of the call
- 5.1.4 C# - RestSharp example of the call
- 5.1.1 Callbacks
- 5.2 Step 2: Expected response
- 5.1 Step 2: (Authenticate using Auðkennis APP)
- 6 Step 3
- 7 Step 4
- 8 Step 5
- 9 Step 6
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)
Redirect URI (Auðkenni receives from Service provider)
Information needed at runtime
User’s Social Id number
Message text for user
Verification code
Code challenge
Code verifier
Setup requirements used in the examples
Client id: myApiClientId
Client secret: MyApiClientP4$sW
Base URI: pfzww.audkenni.is
Redirect URI: http://localhost:3000/callback
All code examples are generated using Postman. They are therefore only for demo.
Step 1
Step 1: (Starting the authenticating process)
To start the authentication process an empty POST call is sent to following URI:
https://pfzww.audkenni.is:443/sso/json/realms/root/realms/audkenni/authenticate?authIndexType=service&authIndexValue=api_v202
Notice the Query parameter “authIndexValue”. It’s value is to select the REST API version to use.
CURL example of the call
curl --location --request POST 'https://pfzww.audkenni.is:443/sso/json/realms/root/realms/audkenni/authenticate?authIndexType=service&authIndexValue=api_v202' \
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=2.0,protocol=1.0' \
--data-raw '{}'
C# - RestSharp example of the call
var client = new RestClient("https://pfzww.audkenni.is:443/sso/json/realms/root/realms/audkenni/authenticate?authIndexType=service&authIndexValue=api_v202");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Accept-API-Version", "resource=2.0,protocol=1.0");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Step 1: Expected response
The REST API service answer is in JSON format.
The response should include following
authId (to use in next step)
callbacks (they need to be “answered” in next step)
Example of answer from Step 1
{
"authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoSW5kZXhWYWx1ZSI6ImFwaV92MTAwIiwib3RrIjoiNTY0djRwZnRrODFvM2RucmM2MnQ0bDVyNWoiLCJhdXRoSW5kZXhUeXBlIjoic2VydmljZSIsInJlYWxtIjoiL2F1ZGtlbm5pIiwic2Vzc2lvbklkIjoiKkFBSlRTUUFDTURJQUJIUjVjR1VBQ0VwWFZGOUJWVlJJQUFKVE1RQUNNRE0uKmV5SjBlWEFpT2lKS1YxUWlMQ0pqZEhraU9pSktWMVFpTENKaGJHY2lPaUpJVXpJMU5pSjkuWlhsS01HVllRV2xQYVVwTFZqRlJhVXhEU2paaFdFRnBUMmxLVDFRd05VWkphWGRwV2xjMWFrbHFiMmxSVkVWNVQwVk9RMUY1TVVsVmVra3hUbWxKYzBsdFJuTmFlVWsyU1cxU2NHTnBTamt1TG5Calh6ZHdTWGg2TWpaemJVUmxNVTFXTFhvNGVsRXViSEo2WjBSNE5uZEtUbU00WW01M1pWWkJaSFF4ZUZBdE4zRnNWbGs0Um5GamExOXJNMnRRYWtJNFdXSjBkV3REVkdaa1F6QnNMVFV0TjBwVmVITkRUM1ZYTjNwTlEweFFVMDVGVEd4QlVWZEVPRGhCU2tjNE5sUkxkVWhWTW14VGFHdFlURGxPUlVaeVIwWmpVbVp1VkZCU1NuUjFka2hwVUhnMmEzSmpiMkpYUzB0MVluRllZa1l4ZUdGNE0yaHljekEzZGtrNGMycE5UVnBJTlZSclNqTmlXakJoTTNKRVgxWm1hWGd3UTNZd1pVaFFVbGxXZVU5WU0xbEhZVFJ3WmtOcFRXMXVibVZOVUdoMFYxTXpOSGsxVUcxRlpXNVNUbTVHYTBaR05rOVNXR1l0UVd0WFEwaE5OVUpGV2xsUVduTlBZVkZ1TVdjNVNGbFVXWFZ3TURGZmJYcDZhMkZWVlhWdFdVVjZlRmhMYWxvMk56TldUWEJJYmxsTVpHOHRNRVE1VGt0QlJ6VnlTV3BHT1hOVVJVZEljUzFtY0V0aVQweHpZVVZPYWxORldISjJXV2xoU2tsRGFtNDRWRGh5ZFVKM1RWaFhUekJ0UkdsamFHMVdTbXB3VFRKT1NYRk9lVEpPVEZVdGJXVTBlRFpXTlRCNk5EWkdXVlZXY3pGaFpIWnVXR1Y1V0dGa2NqSnJabUZZUjJKTlYxbHNkSFJ1VGtSNWJtNHdURXhKTlRWVmVrOUpiWHByU2tkSFJUZDJWbUZQVTBaVlltNWZWSGRxY0hoVVFsVlNiVVYwYW1WWmQyTTFWRlZGYjFGNVZURnJXSEZTVGxGdk4wWmtSMUpIVkU1UlJHMVVUM2xvWm5GUGFGUmpVMTk0WlVkUWRYSTVWR0ZpYlhnMVV6QkJXRTlpT0RWb2FrcDZUM1pMU3kxa2NEbHlNV1ZKVjJRd2VrMVVURjg1YUcxTVJHbzJXRFF3U1hSQk1qWnRjVEJOVEdreFJtOHlZalpSYVdSNVNGbG1lRWR6TVhSbmNWWnhPVmRZU2xKbFZHUXpZbDlzUVRZNVRtcDVObGxNWmxwdmNFdG1TRGRaUlc5VllVUlhhMmQ1V2kxemMyZG5lbGQ2YUdSdWVFczFUbUkxZW1SWlVGaGhaMmQzVkRKalUyZ3hOV3hrU1VSTVVqTkdSMDkzYkhaM1FsYzBTbGgzV0RoR09EbHZTMEZxVkhaWE9VMVBWRmhmUW1kU1NXNHRWbGhFY25GR1oydFFRMkZZUlVabVdrWkVkMFU0WW1aQkxtRlNhRWh2TW1SNFJHOXZVR3BIYW5wRFpHWm5SM2MuZnl3eFVnQWhnQjJVNVA1UjVjNnduOVdORVB2Nm13akNNMzJmalhNc3d6SSIsImV4cCI6MTYxMDk2NjU1MywiaWF0IjoxNjEwOTY2MjUzfQ.OIuisFJ3LDA4WpKzDlfJMcu8tUgltFuyUCnto1WQzHo",
"callbacks": [
{
"type": "NameCallback",
"output": [
{
"name": "prompt",
"value": "Sláðu inn clientId"
}
],
"input": [
{
"name": "IDToken1",
"value": ""
}
],
"_id": 0
},
{
"type": "NameCallback",
"output": [
{
"name": "prompt",
"value": "Sláðu inn Related Party"
}
],
"input": [
{
"name": "IDToken2",
"value": ""
}
],
"_id": 1
},
{
"type": "NameCallback",
"output": [
{
"name": "prompt",
"value": "Sláðu inn App Titil"
}
],
"input": [
{
"name": "IDToken3",
"value": ""
}
],
"_id": 2
},
{
"type": "NameCallback",
"output": [
{
"name": "prompt",
"value": "Sláðu inn símanúmer eða kennitölu"
}
],
"input": [
{
"name": "IDToken4",
"value": ""
}
],
"_id": 3
},
{
"type": "NameCallback",
"output": [
{
"name": "prompt",
"value": "Sláðu inn skilaboð til notanda"
}
],
"input": [
{
"name": "IDToken5",
"value": ""
}
],
"_id": 4
},
{
"type": "NameCallback",
"output": [
{
"name": "prompt",
"value": "Nota vchoice (true eða false)"
}
],
"input": [
{
"name": "IDToken6",
"value": ""
}
],
"_id": 5
},
{
"type": "NameCallback",
"output": [
{
"name": "prompt",
"value": "Nota confirmMessage (true eða false)"
}
],
"input": [
{
"name": "IDToken7",
"value": ""
}
],
"_id": 6
},
{
"type": "NameCallback",
"output": [
{
"name": "prompt",
"value": "Sláðu inn Hash gildi"
}
],
"input": [
{
"name": "IDToken8",
"value": ""
}
],
"_id": 7
},
{
"type": "ChoiceCallback",
"output": [
{
"name": "prompt",
"value": "Veldu auðkenningarleið"
},
{
"name": "choices",
"value": [
"sim",
"card",
"app",
"cardnew",
"cardold"
]
},
{
"name": "defaultChoice",
"value": 0
}
],
"input": [
{
"name": "IDToken9",
"value": 0
}
],
"_id": 8
}
]
}
Step 2
Step 2: (Authenticate using Auðkennis APP)
To authenticate using Auðkennis APP another POST call is sent to following URI:
https://pfzww.audkenni.is:443/sso/json/realms/root/realms/audkenni/authenticate?authIndexType=service&authIndexValue=api_v202
Callbacks
There are 8 callbacks that needs to be answered in this call.
IDToken1 (_id: 0)
This callback need your Client Id as an input value (myApiClientId in this example)
Example of callback answer to send in call
IDToken2 (_id: 1)
This callback is for a “related party” information. To use if you have a client of your own you are authenticating for (you are acting as Identity provider for your customer).
The input value of this callback may be left with empty string (““) as an answer.
In this example we set the value as “MyOwnClient”.
Example of callback answer to send in call
IDToken3 (_id: 2)
A special contract between Auðkenni and service provider is required in order to activate this callback.
This parameter allows service providers that act as identity providers for their customers to display the name of their customers in the app title. The service provider must only use this parameter to set the name of the original service provider and for nothing else.
The value needs to be encoded to base 64 and the original value can not be more than 32 bytes in UTF-8 encoding.
The input value of this callback may be left with empty string (““) as an answer.
Example of callback answer to send in call
IDToken4 (_id: 3)
This callback is for the Social Id number of the user authenticating. Here you put the Social Id number into the input value.
In this example we use the number “1234567890”.
Example of callback answer to send in call
IDToken5 (_id: 4)
This callback is for the message sent to the user authenticating. A text message that is displayed in the users APP. Max length of this message string is 60 characters.
In this example we use the message: “Authentication to Auðkenni”
Example of callback answer to send in call
IDToken6 (_id: 5)
There are two different methods for verification code usage. One is to just display the verification code itself so the user can visually verify it. The other one is to display 3 different codes which the user has to select the correct one from. The latter method is more secure but not needed at all times.
Display the verification code directly
To only display the correct verification code, set the input value to “false”.
Display three codes to select from
To display three codes to select from, set the input value to “true”.
Example of callback answer to send in call
IDToken7 (_id: 6)
Confirm message is a feature that, if set, will let the App prompt the user with a message window. The user will then need to confirm to continue authentication process. By using this option the max length of the message string displayed to the user gets from 60 characters up to 200 characters.
To use this option set input value to “true”.
Example of callback answer to send in call
IDToken8 (_id: 7)
This callback is for a hash string value. This 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 Authentication”
Hash string generated
n/kRNhXaZ2jFKv8KlQX7ydgedXUmVy8b2O4xNq2ZxHteG7wOvCa0Kg3rY1JLOrOBXYQm+z2FRVwIv47w8gUb5g==
Verification code calculated from the hash
4141
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 callback answer to send in call
IDToken9 (_id: 8)
This callback is for selecting authentication method. There are three options to select from: sim (0), card (1) and app (2).
Since we are authenticating using Auðkennis APP in this example, we set the input value to 2.
Example of callback answer to send in call
Example of the whole body in a call
CURL example of the call
C# - RestSharp example of the call
Step 2: Expected response
The REST API service answer is in JSON format.
When Step 2 is executed the authentication process at the users device starts.
The response should include following
authId (to use in next step)
callbacks (with waitTime and message)
Example of answer from Step 2
Step 3
Step 3: (Polling)
After executing Step 2 the authentication 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 authentication process. When authentication process is finished successfully you will receive answer with a tokenId which will in next step allow you get the Authentication Code. The tokenId is your login session token.
To poll for results we send yet another POST call to following URI:
https://pfzww.audkenni.is:443/sso/json/realms/root/realms/audkenni/authenticate
Body to send
This call need a JSON body sent with it, including two objects
authId (from last answer)
PollingWaitCallback (from last answer)
CURL example of the call
C# - RestSharp example of the call
Step 3: Expected response (Authentication still in process)
If you run the poll call before the user authentication process is finished you will receive a similar answer as in Step 2.
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, using the authId from the last response. Each time you receive a new “waiting” answer you also receive a new authId to use next time.
The response should include following
authId (to use in next step)
callbacks (with waitTime and message)
Example of answer from Step 3
Step 3: Expected response (Authentication is finished)
When authentication process is finished successfully you will receive answer with a tokenId which will in next step allow you get the Authentication Code. The tokenId is your login session token.
The REST API service answer is in JSON format.
The response should include following
tokenId (to use in next step)
successUrl
realm
Example of answer from Step 3
Step 4
Step 4: (Get Authentication Code)
Now, when we have our login session token we can continue to next step, which is to get our Authentication Code.
To get the Authentication Code we send a GET call to following URI:
https://pfzww.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni/authorize?service=api_v202&client_id=myApiClientId&response_type=code&scope=openid profile signature&code_challenge=5WnuXW4ALVNtX9G6MydkrPs-F2suz0TQkoaKBsk8Hzk&code_challenge_method=S256&state=abc123&redirect_uri=http://localhost:3000/callback
Header needed in the call
For this call to work we need to add a header object. It should be Cookie with the value “audsso=the tokenId from last call”.
Query parameters needed in the call
client_id
scope (openid, profile, signature)
code_challenge (search for info about code_challenge and code verifier)
state (search for info about state)
redirect_uri
CURL example of the call
C# - RestSharp example of the call
Step 4: Expected response
The JSON body of the answer should simply contain a “1”.
Header in response
You should receive following header object in the answer
Location (should contain URI with a query parameter named “code”
This “code” parameter is the Authentication Code you will use for the exchange process in next step.
Example of “code” in response
Step 5
Step 5: (Exchange Authentication Code with Access and Id token)
Now that we have the Authentication code we can finally ask for the Access and Id token of the user authenticated.
To exchange the Authentication Code for Access and Id token we send a 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 parameters
client_id
redirect_uri
code_verifier (search for info about code_challenge and code verifier)
code (the Authentication Code from last step)
client_secret
CURL example of the call
C# - RestSharp example of the call
Step 5: Expected response
The answer from this call should give you the Access and Id tokens along scope info, type and lifetime.
The Id token contains a PKCS1 signature and a authentication 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. 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
id_token
scope
token_type
expires_in (lifetime of the tokens)
Example of answer from step 5
Example of the payload in Access token
Example of the payload in Id token
Step 6
Step 6: (Userinfo)
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 parameters
Authorization (Bearer, using the Access token from last call as value)
CURL example of the call
C# - RestSharp example of the call
Step 6: Expected response
The answer from this call should give you a PKCS1 Signature and a authentication 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. 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 (authentication 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 6