App2App Logins via Hypermedia Authentication API

App2App Logins via Hypermedia Authentication API

operate

Intro

The App2App Mobile Architecture article describes how App2App can be used to implement Strong Customer Authentication (SCA). It also discusses how to use App2App in an Open Banking setup with multiple merchants and banks.

This tutorial will demonstrate how to run a basic App2App solution using a mobile code sample, the Curity Identity Server, and an external mobile app.

Login App

You can use the BankID App to sign in the user in with strong authentication, via the BankID public test environment:

BankID App

In real-world usage, the BankID app would be integrated into a bank’s PSD2 and Open Banking solutions. Merchant apps could then integrate with the bank solution, allowing consumers to sign in to merchant apps with BankID to access their bank account information securely.

App2App Components

The components that enable this are illustrated below. The mobile app calls the Curity Identity Server, which in turn makes API calls over Mutual TLS to BankID’s back end.

App2App Architecture

The client app retrieves the login result by polling the Curity Identity Server, which will issue an authorization code once BankID indicates a successful login.

Technical Setup

BankID Test Account

To get up and running with a developer test account, visit the BankID Developer Page and follow the below steps.

StepDescription
Get an AccountFollow the instructions in the ‘How to get a test BankID’ document
Android App DownloadDownload the test APK file from the developer page
iOS App DownloadDownload BankID from the App Store and set the server to ‘cavainternal.test.bankid.com’ in configuration settings

Once this is complete, test a sign-in from the website at https://demo.bankid.com using either a desktop browser or a mobile browser.

  • From a desktop browser, select the second option and perform a Web2App login on your mobile device.
  • From a mobile browser, select the first option and perform an App2App login when prompted.

BankID Testing

In both cases, it is then necessary to enter your mobile security code on the device, after which the browser client will receive the authentication result by polling BankID APIs.

Mobile Security Code

BankID Mutual TLS Setup

The connection from the Curity Identity Server to the BankID API uses a financial-grade Mutual TLS connection. To enable Mutual TLS, the system utilizes the following Public Key Infrastructure (PKI) resources:

ResourceDescription
BankID Test Client Certificate + Private KeyA client-side credential used for the Mutual TLS connection
BankID Test Issuer Root CertificateThe public key of the root certificate authority for testing

The first of these can be downloaded from the developer page. Both its private key password and the root certificate are provided in section 8 of the BankID Relying Party Guidelines document.

Next, in the Curity Identity Server, add the issuer root certificate to the trust store and the client key to the client key store:

BankID Crypto

BankID Authenticator Setup

In the Admin UI, you can configure an HTTP Client that connects to the BankID Test Environment using Mutual TLS. Select the client keystore, and also select the ‘Use Trust Store’ option so that the issuer certificate is trusted:

BankID HTTP Client

Next, add a BankID authenticator and select the HTTP Client you configured. Ensure that the OAuth client uses ‘mode=test’ for the BankID test environment.

BankID Authenticator

Mobile Code Sample

Curity’s HAAPI Android Code Sample demonstrates an App2App login. This is how HAAPI guides the user through an authentication workflow:

Android HAAPI Sample

BankID is not supported for emulators, so you will need to run the sample on a real device. This tutorial will use Android, where there are fewer prerequisites for running demo apps on devices, though equivalent steps could be followed for iOS.

Create an OAuth Client

In the below screenshot, an OAuth client with a name that matches the code sample has been created, with the following three capabilities, as needed for HAAPI logins. See the Android HAAPI SDK article for full details on configuration.

Android Sample Capabilities

Configure Mobile Client Attestation

The Curity Identity Server ensures that no malicious app can spoof a genuine HAAPI mobile client and attempt authentication. This is done using a technique called Client Attestation, which requires some additional settings:

Android Sample Attestation Settings

Run an App2App Login

To run the sample on a mobile device, begin by clicking an initial login button to send a standard OpenID Connect authorization redirect message.

Next, you will be presented with a list of authenticators configured for the mobile client. This screen can be bypassed if the client has only one authenticator or if an authenticator is selected at runtime by the client. This can be accomplished by sending the OpenID Connect claims parameter with an ‘acr’ value:

Mobile Authenticators

Next, select the BankID authenticator, then choose the BankID option to deep-link to the BankID app on the same device. If required, the client app could decide not to present this intermediate screen so that the deep link is immediate:

Mobile Launch

The user will then be switched to the BankID app and will enter their BankID Security Code. While this is taking place, the client app polls the Curity Identity Server. This mechanism keeps the user informed and enables any failure conditions to be handled gracefully:

Mobile Polling

Once sign-in completes successfully, the Curity Identity Server receives a success result from BankID and issues an authorization code. A real app would then swap the code for tokens in the standard OAuth manner, then call its own APIs:

Mobile Login Complete

API Driven Login Behavior

The sample app allows itself to be driven by Hypermedia API JSON responses, which contain instructions for the client to follow. A few examples are summarized below. These actions will be familiar to anyone who has worked with OAuth messages:

Action TypeDescription
Automatic RedirectA hypermedia instruction to redirect to a URL with parameters
External LinksInvoking a deep link or opening a system browser when this is the more secure option
Form DisplayData containing form elements to render and a POST URL for submitting edits such as entered credentials
Receiving ResultsReceiving the final authorization code at the end of the workflow, or an error result

Below is a partial response from the Authentication API instructing the client to launch the BankID app:

{
    "metadata": {
        "viewName": "authenticator/bankid/launch/index"
    },
    "type": "authentication-step",
    "actions": [
        {
            "template": "client-operation",
            "kind": "login",
            "title": "Login with BankID",
            "model": {
                "name": "bankid",
                "arguments": {
                    "href": "bankid:///?autostarttoken\u003d0a5f3080-ce01-43ef-b9f1-796efcb31ade\u0026redirect\u003dnull",
                    "autoStartToken": "0a5f3080-ce01-43ef-b9f1-796efcb31ade",
                    "redirect": "https%3A%2F%2Fgarcher.ngrok.io%2Fdev%2Fauthn%2Fauthenticate%2Fbankid1%2Flaunch"
                }
            }
        }
    ]
}

A key benefit of hypermedia-driven workflows is that they are very easy to update dynamically. This is usually more straightforward to manage than releasing a new app version, then waiting for users to upgrade.

Video Tutorial

The below video provides step-by-step instructions on getting App2App logins working using BankID. This includes the BankID setup and the Curity Identity Server configuration.

Future Improvements

At Curity, we are continuing to improve our HAAPI SDKs to make it as easy as possible to integrate into apps. Our samples provide classes that reliably handle all types of responses for Web, iOS, and Android. We also offer default presentations for UI elements, which can be customized as required.

HAAPI flows have some security improvements over standard OAuth redirects, as explained in our Hypermedia Authentication API Whitepaper. We are working with the Financial Grade API (FAPI) Working Group and other parties to establish HAAPI and its security features as a standard.

Conclusion

The Curity Identity Server has proven support for App2App authentication to enable the integration of ‘out of the box’ Strong Customer Authentication solutions. We frequently extend our Authentication Service to support additional providers.

Using the Hypermedia Authentication API provides customers with a high-quality solution at a low cost. The result is more secure apps, a better login user experience, and an overall easier implementation.

Sign up now for a free webinar to learn more about App2App Login with Authentication Workflows

Register Now

Let’s Stay in Touch!

Get the latest on identity management, API Security and authentication straight to your inbox.

Keep up with our latest articles and how-tos using RSS feeds