MobileID

In-app registration process

1042 views September 7, 2017 September 10, 2019 2

The following diagram describes the process when you want to perform the whole registration process inside your app, all the way from initializing the registration to receiving a SAML response with the result of the registration.

1) User downloads and authenticates in the app

The user downloads your app and has to authenticate when starting it. After receiving a successful authentication result:

  • Create a SignicatID account for the user (if he does not have it already), using createAccount() in SCID WS.
  • Create an artifact for the user, using createArtifact() in SCID WS. This artifact will be used in the URL in the next step.

2) Initiate the device registration

After receiving a successful authentication result, send a 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 which serves as a unique identifier for the user
    "deviceName": "myDevice", // the name of the device to add to account
    "artifact": "2wp512ljdt4y7iop9uhaaikp227hv2x0hv6dm5i23tadoan3ao" // artifact stored on the SignicatID account
}

 

Response example

{
    "statusUrl": "https://id.signicat.com/....",
    "completeUrl": "https://id.signicat.com/...",
    "status": "OK",
    "activationCode" : "651223"  // activation code to enter in the next phase
}

NOTE: To be able to perform the subsequent requests, you must keep the cookies you receive and make them available for the following requests.

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

{
    "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 receiving such an error response, you can make a GET request towards the completeURL to get the signed SAMLResponse with the same error information.

3) Start Encap activation

If the status was “OK”, you can start the Encap activation using the activationCode received in the previous step. This involves the normal startActivation()/finishActivation() calls towards the Encap Client API. For further information, see the Encap documentation.

4) Get the status of the registration process

Using the statusUrl received in step 2, make a GET request for the status of the registration.

Response example

{
    "status": "PENDING"
}

As long as you get the “PENDING” status, wait a bit and ask about the status again. You can continue to the next step when you get back the “COMPLETED” status:

{
    "status": "COMPLETED"
}

You may get back an error status and an error object, which will look like this:

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

5) Get result of the registration process

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

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

 6) Verify SAMLResponse

The SAMLResponse has to be verified by your backend server.

Was this helpful?