Rest Integration Guide

Authentication using REST API’s is a sequence of calls against the AM authentication endpoint that will depend on the configured authentication tree. It works by sending across data called callbacks where AM will indicate which information it requires as part of the Callback and the requester needs to provide that information and send it to the authentication endpoint.

Example

The default Audkenni Authentication flow is to present a user with a selection screen and a possibility to enter his phonenumber. The calls below show which request/responses need to be performed to perform this authentication when choosing to authenticate with mssp.

1: Start authentication

The first call is an empty POST to the authentication endpoint as can be seen below:

curl --location --request POST 'https://idp.audkenni.is:443/sso/json/realms/root/realms/audkenni/authenticate' \
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=2.0,protocol=1.0' \
--data-raw ''

This will give the following response:

{
    "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ2ODJvbW5tOTE0MjltN2RuaWlzNHBxOHU3MiIsInJlYWxtIjoiL2F1ZGtlbm5pIiwic2Vzc2lvbklkIjoiKkFBSlRTUUFDTURJQUJIUjVjR1VBQ0VwWFZGOUJWVlJJQUFKVE1RQUNNREUuKmV5SjBlWEFpT2lKS1YxUWlMQ0pqZEhraU9pSktWMVFpTENKaGJHY2lPaUpJVXpJMU5pSjkuWlhsS01HVllRV2xQYVVwTFZqRlJhVXhEU2paaFdFRnBUMmxLVDFRd05VWkphWGRwV2xjMWFrbHFiMmxSVkVWNVQwVk9RMUY1TVVsVmVra3hUbWxKYzBsdFJuTmFlVWsyU1cxU2NHTnBTamt1TG5KSWFuZENjbVJGU3pJMGEwaHJiM1l5VmxsVVVuY3VPRWhzVEd0MFMwa3dWMGx4UTNGU1dFNWlWRkpJTkhoSFlYTXphak16U21SaFUwZDZWVWR1WlhWa2EwOVNlV0poYjBOaGJqQkVhR2xaUVRWWlpEZGtWSE0yTURWaFUyVXRWMDlyUVZkMVZ6VkZVRlUxVDJOVVVqTlZObGROTFVKRVoxRmxMVFpITkZaeE5uQldRVTQ1YzFZMU9XbDBkamRJV1dOYVF6bERlR3RITjBFdFdHeFFSMFV0ZUdnNVkwcDJZamRQV1dNemQwczFaVlJRUjNvMGRqTXpaRWxGZUd4WVNrWlJZbkV3ZVMxSGRHUXhaVWxhZEd4TVEzQlNaRE51TFhFMFJEbGtWM0l4YldwMk5XOHRXVUphV0doR05uZHZaSGh6WVhRMVpGbFNZMHhaY21WS2JubHBialoyZDNSTGFIbG5RM2M0TlhWTk1taEZURGhTTm1WeU1HaHpNVTVrWTBoemNIUlNWVlJKUm1OdVVXVXdVMHgyUVV4MmRFMUJkMkV3Tm1wRWVuSkJhRmRzWTI4MmFsVTBOMDVWYkZGRlZFY3lkV1oyWjNocU9HNVhTRWRTYmtsaGRFNUVWMVpDYXpkU1VsTkhTekJpZGpoVlp6SXhlRm80YVVGdGJraEVYMUpvTlhkbGFtWklhaTAzY25GbE9VbEpjbGxKYlVsbWREZExjMUpXVkZOeFZHOXVkVkI2WHpSdVFWRkJVazkxTlRaa09EZDZTRkF6TFRWdlNtZGxWRGh2VERSQ1JuaDNaVWd4TFc1SmVVWlZXVVZqTlZkTVVHc3hjamRhY25SUlYydEpZelpuVjJoMlpsY3dkRzFqVm1ab1ozTTVkV3hQZFVkSWVYZFlPSEV5YUVSbVZETm9lRWRxU0UxWk1tVlpjM1JKTFhJNGVUTjVTVUZyV1d4VldHNHdhMUJ0UkhWSU5HUm1jSFZZWkVaVFVXeHdRVVJVWW1Wc2FtRnllalJJTlVaRlJWRnlVamxDWVdab1pWRlNNbEZhVVU5VGFWcEVNbU0zVUc5UE1tNW9kemRrVkRkVU5WWmtXa2RoWm5samVubFNXR0p2VDBoUGFUSmFiRXRuWVRsVWMxWkxXV1ZPV0hOcGNUazNiSFJLZEdVMlgzWnBjalJHVFVWdU5WVjNZMGhuZWkxaE5FdHpSSGs1WWt4dk5sUnRRMHhpZG5KaFVuRlJZV014TVdoTWJsOVROWEJGUTNkbWRHNWxVbE4xZFRWaVpYRXRSMEl1Y0VJME9GbExOVjlsU1MwNFVFdzFkSGxSVFVWblp3LmRiNERVUU5jMlJBbDlMUG4xbUkzY0ZXQk5HaUFGZlc2VFFKblhyYWNuSzQiLCJleHAiOjE1Nzk2OTI0NjgsImlhdCI6MTU3OTY5MjE2OH0.TMBeWV-kyR0ed8qfGDGIqRnnNBCh-rDcTlqYxy-IkXk",
    "callbacks": [
        {
            "type": "NameCallback",
            "output": [
                {
                    "name": "prompt",
                    "value": "templates.user.LoginTemplate.loginprompt"
                }
            ],
            "input": [
                {
                    "name": "IDToken1",
                    "value": ""
                }
            ],
            "_id": 0
        },
        {
            "type": "ChoiceCallback",
            "output": [
                {
                    "name": "prompt",
                    "value": "Choose Authenticator"
                },
                {
                    "name": "choices",
                    "value": [
                        "sim",
                        "card"
                    ]
                },
                {
                    "name": "defaultChoice",
                    "value": 0
                }
            ],
            "input": [
                {
                    "name": "IDToken2",
                    "value": 0
                }
            ],
            "_id": 1
        }
    ]
}

2: Enter Phonenumber and Choice

From the callback above you will see its has 2 callback. A NameCallback which an empty input IDToken1 which needs to contain the phoneNumber and a ChoiceCallback which has as an empty input IDToken2 which should contain the choice of authentication method (index number of element in the array)

So the next call looks like this:

curl --location --request POST 'https://idp.audkenni.is:443/sso/json/realms/root/realms/audkenni/authenticate' \
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=2.0,protocol=1.0' \
--data-raw '{
    "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ2ODJvbW5tOTE0MjltN2RuaWlzNHBxOHU3MiIsInJlYWxtIjoiL2F1ZGtlbm5pIiwic2Vzc2lvbklkIjoiKkFBSlRTUUFDTURJQUJIUjVjR1VBQ0VwWFZGOUJWVlJJQUFKVE1RQUNNREUuKmV5SjBlWEFpT2lKS1YxUWlMQ0pqZEhraU9pSktWMVFpTENKaGJHY2lPaUpJVXpJMU5pSjkuWlhsS01HVllRV2xQYVVwTFZqRlJhVXhEU2paaFdFRnBUMmxLVDFRd05VWkphWGRwV2xjMWFrbHFiMmxSVkVWNVQwVk9RMUY1TVVsVmVra3hUbWxKYzBsdFJuTmFlVWsyU1cxU2NHTnBTamt1TG5KSWFuZENjbVJGU3pJMGEwaHJiM1l5VmxsVVVuY3VPRWhzVEd0MFMwa3dWMGx4UTNGU1dFNWlWRkpJTkhoSFlYTXphak16U21SaFUwZDZWVWR1WlhWa2EwOVNlV0poYjBOaGJqQkVhR2xaUVRWWlpEZGtWSE0yTURWaFUyVXRWMDlyUVZkMVZ6VkZVRlUxVDJOVVVqTlZObGROTFVKRVoxRmxMVFpITkZaeE5uQldRVTQ1YzFZMU9XbDBkamRJV1dOYVF6bERlR3RITjBFdFdHeFFSMFV0ZUdnNVkwcDJZamRQV1dNemQwczFaVlJRUjNvMGRqTXpaRWxGZUd4WVNrWlJZbkV3ZVMxSGRHUXhaVWxhZEd4TVEzQlNaRE51TFhFMFJEbGtWM0l4YldwMk5XOHRXVUphV0doR05uZHZaSGh6WVhRMVpGbFNZMHhaY21WS2JubHBialoyZDNSTGFIbG5RM2M0TlhWTk1taEZURGhTTm1WeU1HaHpNVTVrWTBoemNIUlNWVlJKUm1OdVVXVXdVMHgyUVV4MmRFMUJkMkV3Tm1wRWVuSkJhRmRzWTI4MmFsVTBOMDVWYkZGRlZFY3lkV1oyWjNocU9HNVhTRWRTYmtsaGRFNUVWMVpDYXpkU1VsTkhTekJpZGpoVlp6SXhlRm80YVVGdGJraEVYMUpvTlhkbGFtWklhaTAzY25GbE9VbEpjbGxKYlVsbWREZExjMUpXVkZOeFZHOXVkVkI2WHpSdVFWRkJVazkxTlRaa09EZDZTRkF6TFRWdlNtZGxWRGh2VERSQ1JuaDNaVWd4TFc1SmVVWlZXVVZqTlZkTVVHc3hjamRhY25SUlYydEpZelpuVjJoMlpsY3dkRzFqVm1ab1ozTTVkV3hQZFVkSWVYZFlPSEV5YUVSbVZETm9lRWRxU0UxWk1tVlpjM1JKTFhJNGVUTjVTVUZyV1d4VldHNHdhMUJ0UkhWSU5HUm1jSFZZWkVaVFVXeHdRVVJVWW1Wc2FtRnllalJJTlVaRlJWRnlVamxDWVdab1pWRlNNbEZhVVU5VGFWcEVNbU0zVUc5UE1tNW9kemRrVkRkVU5WWmtXa2RoWm5samVubFNXR0p2VDBoUGFUSmFiRXRuWVRsVWMxWkxXV1ZPV0hOcGNUazNiSFJLZEdVMlgzWnBjalJHVFVWdU5WVjNZMGhuZWkxaE5FdHpSSGs1WWt4dk5sUnRRMHhpZG5KaFVuRlJZV014TVdoTWJsOVROWEJGUTNkbWRHNWxVbE4xZFRWaVpYRXRSMEl1Y0VJME9GbExOVjlsU1MwNFVFdzFkSGxSVFVWblp3LmRiNERVUU5jMlJBbDlMUG4xbUkzY0ZXQk5HaUFGZlc2VFFKblhyYWNuSzQiLCJleHAiOjE1Nzk2OTI0NjgsImlhdCI6MTU3OTY5MjE2OH0.TMBeWV-kyR0ed8qfGDGIqRnnNBCh-rDcTlqYxy-IkXk",
    "callbacks": [
        {
            "type": "NameCallback",
            "output": [
                {
                    "name": "prompt",
                    "value": ""
                }
            ],
            "input": [
                {
                    "name": "IDToken1",
                    "value": "8422263"
                }
            ],
            "_id": 0
        },
        {
            "type": "ChoiceCallback",
            "output": [
                {
                    "name": "prompt",
                    "value": "Choose Authenticator"
                },
                {
                    "name": "choices",
                    "value": [
                        "sim",
                        "card"
                    ]
                },
                {
                    "name": "defaultChoice",
                    "value": 0
                }
            ],
            "input": [
                {
                    "name": "IDToken2",
                    "value": 0
                }
            ],
            "_id": 1
        }
    ]
}'

This will give the following response:

3: Authenticate

Note that the response from above does not contain an input element, so for the next call you can just send the response body as the request. After you authenticated on your phone you can do the following request:

When you successfully entered your pin on the phone the response will look like this:

The tokenId is your login session token.

Possible start points

Several trees have been configured and each tree has a separate first call.

default

For the default authentication the start call is:

MSSP only

For the tree when only MSSP authentication is enforced the start call is:

Nexus only

For the tree when only Nexus authentication is enforced the start call is:

Documents

Rest Integration Guide

Example

Possible start points

Related content