MobileID

In-app registration process

204 views September 7, 2018 December 5, 2018 0

The following sequence diagram describes the MobileID app registration process when you want to perform the whole registration process inside your app, including identifying the user.

1) Initiate the registration

Integration with the MobileID app is done via the same API as Signicat’s other ID methods. See “Get started with authentication“ for more information.

To initiate the registration, send a GET request to the in-app URL you have received from Signicat. As a response, you will receive a redirect URI generated by your server, as well as another message containing a pairing code and a list of links.

Request example

GET https://preprod.signicat.com/oidc/authorize?response_type=code&scope=openid+mobileid&client_id=demo-preprod&redirect_uri=https://example.com/redirect&state=123abc&acr_values=urn:signicat:oidc:method:mobileid-reg-inapp

Response example

{
    "pairingCode": "673900",
    "links": [
        {
            "rel": "status",
            "href": "https://id01.signicat.com/std/poll/nbidmobile/a6405ccd514b40979e3e78e035b77a085d8d10f0c30c11e89549000c299de349/",
            "type": "GET"
        },
        {
            "rel": "pairing-code",
            "href": "https://id01.signicat.com/std/method/nbidmobile/a6405ccd514b40979e3e78e035b77a085d8d10f0c30c11e89549000c299de349/pairing-code",
            "type": "GET"
        },
        {
            "rel": "confirm",
            "href": "https://id01.signicat.com/std/method/nbidmobile/a6405ccd514b40979e3e78e035b77a085d8d10f0c30c11e89549000c299de349/confirmation",
            "type": "GET"
        },
        {
            "rel": "complete",
            "href": "https://id01.signicat.com/std/method/nbidmobile/a6405ccd514b40979e3e78e035b77a085d8d10f0c30c11e89549000c299de349/complete",
            "type": "GET"
        },
        {
            "rel": "cancel",
            "href": "https://id01.signicat.com/std/method/nbidmobile/a6405ccd514b40979e3e78e035b77a085d8d10f0c30c11e89549000c299de349/cancel",
            "type": "GET"
        },
        {
            "rel": "mobileid",
            "href": "https://id01.signicat.com/std/method/nbidmobile/a6405ccd514b40979e3e78e035b77a085d8d10f0c30c11e89549000c299de349/mobileid",
            "type": "GET"
        },
        {
            "rel": "sms",
            "href": "https://id01.signicat.com/std/method/nbidmobile/a6405ccd514b40979e3e78e035b77a085d8d10f0c30c11e89549000c299de349/sms",
            "type": "POST"
        }
    ]
}

JSON responses

Name Type Description
pairingCode string A short-lived six-digit code that must be registered with the MobileID app
links link object Links to status, pairing-code, complete, cancel, mobileid endpoints
status string Status of the registration process
pairing-code string Pairing code that is generated by the Signicat server and validated on the MobileID app
confirmation string Information about the device that has been used for the registration process
complete string Completes the registration process
cancel string The user can use this link to cancel the process
mobileid string Information on how to download the app
sms string Sends an SMS with a link to the App Store and Google Play. The request must include the phone number in this format: +CCNNNNNNNN

2) Start the MobileID app with the pairing code received in step 1

The user will be instructed to create a PIN code and, optionally, register a fingerprint in the MobileID app.

3) Get the status of the registration process

Using the status link received in step 1, send a GET request for the status of the registration.

Response example

{
  "finished": true,
  "error": false,
  "errorMessageKey": null
}

If “finished” is not true, you need to wait a short period before asking for status again.

You can continue to the next step when “finished” is true and “error” is false.

4) Optionally, get registration process confirmation

When the status link returns finished=true, you can send an optional GET request to the confirm link returned in step 1. This will return information about the device that has been registered. It can be used to inform the user what has happened before completing the operation.

Response example

{
  "model":"SM-G950F",
  "os":"Android",
  "name":"Samsung Galaxy S8",
  "success":true
}

5) Get the result of the registration process

Call the complete URL that you received in step 1. As a response, you will get the redirect URI to your endpoint with a “code” query parameter.

6) Send token request

Use the redirect URI and the code received in step 5 to send a POST request towards the token endpoint. The request must contain the following URI-encoded parameters:

  • client_id: Your client ID
  • redirect_uri: Must equal the URI the flow started with
  • grant_type=authorization_code: We are using an authorization code for this flow, hence the value of this parameter
  • code: Must equal the code received in step 5

Request example

curl -XPOST "https://preprod.signicat.com/oidc/token" -H "Authorization: Basic ZGVtby1wcmVwcm9kOm1xWi1fNzUtZjJ3TnNpUVRPTmI3T240YUFaN3pjMjE4bXJSVmsxb3VmYTg=" -d "client_id=demo-preprod&redirect_uri=https://example.com/redirect&grant_type=authorization_code&code=CODE GOES HERE"

Response example

{"access_token":"eyJra...","token_type":"Bearer","refresh_token":"S4rkjLZ-13aXtuLhyHngFZGcC2mbmKcK","scope":"mobileid profile openid","expires_in":1800,"id_token":"eyJra..."}

Extract the access token from the response to use it in the next step.

7) Send userinfo request

Use the access token to fetch the deviceId with a GET request.

Request example

curl -XGET "https://preprod.signicat.com/oidc/userinfo" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response example

{"sub":"uIFLTWW_xgxkWPImFo5JXtzhzZqK4mBf","deviceId":"UlzxrYaXmrvR2Njm7ydRf9FeDV7VLilX"} 

Note that the response will vary depending on the ID method. For further information, refer to OIDC Response Examples.

Save the deviceId, as it will be used to start any future authentication processes from that user.

Any further actions after receiving this response are your responsibility. Signicat does not have any responsibility for how the result of the registration is used.

Was this helpful?