MobileID

In-app authentication process

263 views September 7, 2017 October 20, 2017 0

To support in-app authentication, you need to handle the whole authentication process from your app – all the way from initializing the authentication to receiving a SAML Response with the result of the authentication.

1) Initiate the authentication

Send POST request to the in-app URL you have received from Signicat.

Request example

{
    "apiKey": "abcd1234efgh5678", // API key which grants access to this method, received from Signicat
    "externalRef": "user123", // the app has to keep track of the externalRef for the user
    "deviceId": "abcd-efgh-ijkl-mnop-qrst-uvwx" // extracted from EncapController:getRegistrationId()
}

Response example

{
    "statusUrl": "https://id.signicat.com/....",
    "completeUrl": "https://id.signicat.com/...",
    "status": "OK"
}
To be able to perform the subsequent requests, you must keep the cookies you receive and make these available for the next requests.

If an error occurs during init, you will get a status indicating this, and an error object will be present:

Response error example
{
    "statusUrl": "https://id.signicat.com/....",
    "completeUrl": "https://id.signicat.com/...",
    "status": "ERROR",
    "error": {
        "code": "urn:signicat:error:idp:ACCESS_DENIED",
        "message": "Access denied. Wrong credentials."
    }
}

Upon error, you can make a GET request towards the completeUrl to get the signed SAMLResponse with the same error information.

2) Start Encap authentication

If the status was “OK”, you can start the Encap authentication. This involves the normal startAuthentication()/finishAuthentication() calls towards the Encap Client API.

If you are using push notifications, you can either:

  • start the authentication directly after having received the response in step 1 (but then you need to have logic in place to not start authentication upon push), or
  • wait for the push message and then start the authentication (this would enable uniform handling of authentications triggered from web auth and in-app auth)

3) Get status of authentication process

Using the statusUrl received in step 1, make a GET request for the status of the authentication.

Response example
{
    "status": "PENDING"
}

As long as you get the “PENDING” status, you need to wait a short period before asking for status again.

You can continue to the next step when you get back “COMPLETED” status:

Response example

{
    "status": "COMPLETED"
}

Also here, you could get back an error status and an error object:

Response example

{
    "status": "ERROR"
    "error": {
        "code": "urn:signicat:error",
        "message": "The authentication failed due to ..."
    }
}

4) Get result of authentication process

Using the completeUrl received in step 1, make a GET request for the SAMLResponse containing the result of the authentication. As a result you will get the SAMLResponse back:

Response example

{
    "SAMLResponse": "<base64 encoded SAMLResponse>"
    "target": "https://yourtargeturl.com"
}

5) Verify SAMLResponse

The SAMLResponse needs to be verified by your backend server. Based on the result of this verification, you may want to create a session (via cookie or some other token) which the app can use in further communication with your backend services.

Everything after having received the SAMLResponse is your responsibility. Signicat does not have any responsibility for how the result of the authentication is used.

Was this helpful?