Skip to main content

Mobile Authentication with Deep Links

Mobile Authentication with Deep Links is a special use case. It comes into play when an [out-of-band channel] is required, but only a mobile device is available. It uses deep linking to be able to navigate between the mobile device's browser and the Access App.

Prerequisites​

  • The Base Setup and nevisFIDO Setup are completed.
  • The Out-of-Band Registration is completed.
  • A relying party application is available, which is capable of participating in out-of-band flows. Such an application is called Browser Application. For additional information, see the chapter Out-of-Band Registration in the Nevis Mobile Authentication Concept and Integration Guide.
    • The relying party must be able to call the Dispatch Token Service of the nevisFIDO component with a payload requesting the link dispatcher. For further information, see the nevisFIDO Reference Guide, chapter Dispatch Token Service.

Documentation references​

Should you wish to learn about deep linking, mobile authentication or Nevis in general, see the following sources:

  • The Nevis Mobile Authentication - Concept and Integration Guide
  • Chapter Out-of-Band Operations Using Push, QR Code or Deep Links in the Nevis Access App Guide
  • Chapter Out-of-Band Registration in the Nevis Mobile Authentication Concept and Integration Guide
  • Android App Links1
  • Universal Links (iOS)2

Tutorial​

Mobile Authentication with Deep Links is a more complex use case with a lot of nuances. This tutorial supports you in setting up the use case.

The tutorial uses the following URLs as examples:

https://example.siven.dev/
https://app.example.siven.dev/

Make sure to adapt them to match your environment, when necessary.

Part 1 - Requesting an Access App​

  1. Open the Virtual Host pattern of your nevisAdmin 4 project. Go to the Frontend Address field/property in Basic Settings tab.
    1. Enter the backend URL in this field.
    2. Then enter a second URL in the same field.
      1. This second address must be the same as the first one, except for the "app" subdomain. For example, if your first address is https://**app**.example.siven.dev/, https://app.user9000.admin4aks.azure.nevis.dev.
      2. The domain in this second address will be the Deep Link Domain. So in our example, the deep link domain would beapp.example.siven.dev.
  2. Now you can order an Access App:
    1. Follow the instructions on the page Ordering an Access App of the Nevis Access App Guide.
    2. Make sure to provide the backend URL and the deep link domain you specified in [step 1], so that they can be built into the application.
    3. When the application is built, note down the information in the following table. You will need this information later on - without it, deep linking support is not possible.
SystemInformation to obtain
iOSTeam Identifier, Bundle Identifier
AndroidPackage Name, SHA256 Fingerprint

Part 2 - Creating the basic Mobile Authentication with Deep Links pattern​

  1. Add the Mobile Authentication with Deep Links pattern to your nevisAdmin 4 project. Set the following fields:
  2. Assign the existing nevisFIDO Instance pattern to the nevisFIDO field/property.
  3. Assign the existing Virtual Host pattern to the Virtual Hosts field/property.
  4. Specify the Deep Link Path in the Deep Link Base Path field/property. The deep link path is the path rendered into the deep links. For example, a deep link path that will only be used for registration would look like this:
/registration

You can only set one deep link path

You cannot set multiple deep link paths. The path set in the Deep Link Base Path field will be used in every deep link that the backend generates.

Part 3 - Creating and hosting well-known files​

For deep linking to work well, the mobile operating system needs to fetch a well-known file from the backend. The operating system uses this file to verify the deep links. This section explains how to create such a file. As Android and iOS have different well-known files, we show you the process for both.

For Android​

  1. In case of Android, the well-know file is called Android App Links. Visit the Statement List Generator site and provide the following information:

    Input required by the generatorInformation you have
    Hosting site domainDeep Link Domain
    App package namePackage Name
    App package fingerprint (SHA256)SHA256 Fingerprint

    With this information, the List Generator can generate the content of the Android App Links file we have to host.

  2. After entering the required information, click the Generate statement button. The tool will now generate a text and display it in the field below the Generate statement button. The following figure shows how the tool and the generated text look like:

    Statement List Generator and Tester

  3. Copy the generated text into a new file. Save the file under the following name: assetlinks.json

  4. Go to the Mobile Authentication with Deep Links pattern and upload the file assetlinks.json into the Android App Links field.

For iOS​

  1. In case of iOS, the well-known file is called Apple App Site Association. This is a boilerplate of the JSON file structure:

    {
     "applinks": {
     "apps": [],
     "details": [
     {
     "appID": "<app-id>",
     "paths": [
     "*/<deep-link-base-path>"
     ]
     }
     ]
     }
    }

  2. To build the App ID, take the iOS Team Identifier and the Bundle Identifier, place them together and put a dot between them:

    App ID = <Team Identifier>.<Bundle Identifier>

    For example, see the following table:

    Team IdentifierBundle IdentifierApp ID
    U8KPBF668Hch.nevis.accessappU8KPBF668H.ch.nevis.accessapp

  3. Copy the Apple App Site Association boilerplate into a new file. Replace the placeholders in between the angle brackets with the information shown in the next table:

    Placeholder in the boilerplateInformation you have
    app-idApp ID
    deep-link-base-pathDeep Link Path

  4. Name the file apple-app-site-association (without any extension!) and save it. An example of how this file might look like can be found here.

  5. Go to the Mobile Authentication with Deep Links pattern and upload the file apple-app-site-association into the Apple App Site Association field.

Part 4 - Configuring the relying party application​

See also Protecting a Web Application.

The relying party application is responsible for requesting the deep link from the nevisFIDO component and rendering/displaying the link to the end user. This application is not provided by Nevis. Deploy it independently. This section shows how to integrate the relying party application into the project to enable deep links.

  1. Add a Web Application pattern to your nevisAdmin 4 project (or open the pattern, in case there already exists one for the relying party application). Specify the following fields:
  2. Virtual Hosts field, Basic Settings tab: Assign the same Virtual Host pattern to this field as the one assigned to the Mobile Authentication with Deep Links pattern.
  3. Frontend Paths field, Basic Settings tab: Specify any desired frontend path.
  4. Authentication Realm field, Basic Settings tab: Assign the same Authentication Realm pattern as the one assigned to the Mobile Device Registration pattern (which you created when you configured the Out-of-Band Registration).
  5. Application Access Token field, Basic Settings tab: Assign the same token as the one assigned to the Mobile Device Registration pattern.
  6. Backend Addresses field, Backend Connection tab: Provide an accurate backend address that points to the relying party application's backend.

Part 5 - Deployment​

Deploy the configuration with nevisAdmin 4.

Test​

Now that we have deployed the Mobile Authentication with Deep Links use case, we can test it.

  1. Open a browser on the mobile device where the Access App is installed

  2. Navigate to the relying party application. The URL of the application can be constructed by merging the Backend URL and whatever you configured in the Frontend Pathsfield of the Web Application pattern.

  3. Log in.

  4. The relying party application will approach nevisFIDO for a deep link, which it should render on the screen. The following figure shows how it might look like:

    Deep link sample

    For debugging purposes, this is an example how the generated link should look like:

    https://app.example.siven.dev/registration?dispatchTokenResponse=eyJubWFfZGF0YSI6eyJ0b2tlbiI6ImZjNGYyNGRjLWU4OGQtNGNhNC04ZWU5LTQ0OTM2NDdhNTViMyIsInJlZGVlbV91cmwiOiJodHRwczovL3VzZXI5MDAwLmFkbWluNGFrcy5henVyZS5uZXZpcy5kZXYvbmV2aXNmaWRvL3Rva2VuL3JlZGVlbS9yZWdpc3RyYXRpb24ifSwibm1hX2RhdGFfY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vanNvbiIsIm5tYV9kYXRhX3ZlcnNpb24iOiIxIn0

  5. Click the link, after which a banner should be visible, prompting you to choose the application to open the link.

  6. Choose the Access App.

  7. Complete the registration process shown in the Access App user interface.

Congratulations

You just executed out-of-band mobile registration, using deep links!

[1] http://developer.android.com/training/app-links,http://github.com/google/digitalassetlinks/blob/master/well-known/details.md

[2] http://developer.apple.com/library/archive/documentation/General/Conceptual/AppSearch/UniversalLinks.html/