link

# Backend-initiated operations: Finalise operation

# Sequence diagram

The diagram below illustrates a scenario where the AUTHORIZATION_CODE has been successfully retrieved.

click-to-zoom

Note

The MobileID process is finalised in the same way regardless of whether the operation in question is registration, authentication, Authorisation or Consent Signature.

# Check status

Note

This is just one implementation possibility. It is possible to execute the implementation in different ways.

While the operation is ongoing between your app and Signicat, the client (browser) may execute polling calls to your backend using the previously received status URL, which executes a call to Signicat.

This can be executed (periodically at pre-configured intervals) until the received result is COMPLETED.

# Request

GET <STATUS_URL>

# Response

{
    "status":"PENDING"/"COMPLETED"
}

# Complete operation

# 1. Retrieve authorisation code

Signicat's backend sends a request for the authorisation code to the CUSTOMER_REDIRECT_URL.

Important

  • It is important that the HTTP GET does not use or inherit the HTTP Header Accept:application/json from the previous calls to Signicat.

  • Make sure that your HTTP client follows all redirects until either the AUTHORIZATION_CODE or an error is returned.

# Request

GET <COMPLETE_URL>

# Response

AUTHORIZATION_CODE

If an error occurs and the AUTHORIZATION_CODE cannot be retrieved, an error message will be returned. The following is one example of a possible error response.

{
    "status":"ERROR",
    "data":"The Resource Owner did not complete the login. urn:signicat:error; Unspecified error"
}

# 2. Retrieve access token and id token

The authorisation code is exchanged for an access token, id token and optionally refresh token.

# Request

POST <SIGNICAT_TOKEN_ENDPOINT> HTTP/1.1
Content-Type: application/json
Authorization: Basic <CUSTOMER_BASIC_AUTH_HEADER>
# Request body
client_id=<CUSTOMER_CLIENT_ID>&
redirect_uri=<CUSTOMER_REDIRECT_URI>&
grant_type=authorization_code&
code=<AUTHORIZATION_CODE>

# Response

{
    "access_token":"<ACCESS_TOKEN>",
    "token_type":"Bearer",
    ...
}

# 3. Retrieve device properties (optional)

Additional information (such as data on the authenticated user) can be retrieved from Signicat's OIDC backend using the /userinfo endpoint.

# Request optional
GET <SIGNICAT_USERINFO_ENDPOINT> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>
# Response

For registration:

{
    "sub":"WGrzaZJTOm7hJ-uDN4zK9zMhPgg1qznE",
    "name":"<EXTERNAL_REF>"
    ...
}

For authentication and Authorisation:

{
    "sub":"WGrzaZJTOm7hJ-uDN4zK9zMhPgg1qznE",
    "externalRef":"ca389fae-153d-11ec-82a8-0242ac130003",
    "deviceName":"sampleDevice",
    ...
}

# Risk attributes

Optionally, Signicat can configure your service to return risk attributes. These can be used to reduce fraud by means of improved risk evaluation. Risk attributes can be retrieved with all operations: registration, authentication, Authorisation or Consent Signature.

For details on how to return risk attributes, refer to our risk attributes guide.

# Further reading

Last updated: 25/04/2022 09:50 UTC