This tutorial shows how to run a code example that implements mobile OpenID Connect in a Kotlin App using the Hypermedia Authentication API (HAAPI). See also the API Driven Demo Client tutorial for an introductory guide that runs a simple web client.

Overview

The code example provides a basic Android implementation to demonstrate how to integrate a HAAPI-driven authentication flow in an app. It uses the HAAPI UI SDK, a high-level SDK that handles the whole flow, requiring just minimal configuration and customization. The app initially presents a view to start the authentication process:

The authentication workflow is then managed as a series of fast API requests that return JSON responses. The SDK processes each API response to perform various actions including rendering of forms:

Once authentication completes, the app presents its Authenticated View, to simulate a mobile app that works with access tokens to call APIs. The app can then easily perform other OAuth operations such as refreshing tokens and ending the authenticated session:

From this point onwards the app will operate like a traditional mobile OAuth client and call APIs.

Get the Code

First, ensure that you are running an up-to-date version of Android Studio, then clone the GitHub repository and open its folder to view the Kotlin classes used.

Quick Start

The easiest way to run the code example is to point it to a deployed and preconfigured instance of the Curity Identity Server, running in Docker. This is done via a script included with the example that is explained in the Mobile Setup how-to:

./start-idsvr.sh

The result is a working instance of the Curity Identity Server, listening on the Android emulator's default host IP (https://10.0.2.2:8443), ready for the mobile app to connect to. The Admin UI is also available and can be accessed using the following details:

The deployed system also includes a user account of demouser / Password1 that can be used to sign in.

Configuration

The code example uses the following client settings, including the haapi and code capabilities. For further details on HAAPI specific settings refer to the Android HAAPI Client Setup tutorial. Include the issue-token-bound-authorization-code setting if using version 9.0 or later of the Curity Identity Server.

<config xmlns="http://tail-f.com/ns/config/1.0">
  <profiles xmlns="https://curity.se/ns/conf/base">
    <profile>
    <id>token-service</id>
    <type xmlns:as="https://curity.se/ns/conf/profile/oauth">as:oauth-service</type>
      <settings>
        <authorization-server xmlns="https://curity.se/ns/conf/profile/oauth">
          <client-store>
            <config-backed>
              <client>
                <id>haapi-android-client</id>
                <client-name>Haapi Android Client</client-name>
                <no-authentication>true</no-authentication>
                <redirect-uris>app://haapi</redirect-uris>
                  <proof-key>
                    <require-proof-key>false</require-proof-key>
                  </proof-key>
                  <refresh-token-ttl>3600</refresh-token-ttl>
                  <scope>address</scope>
                  <scope>email</scope>
                  <scope>openid</scope>
                  <scope>phone</scope>
                  <scope>profile</scope>
                  <capabilities>
                    <code>
                    </code>
                    <haapi>
                      <issue-token-bound-authorization-code>true</issue-token-bound-authorization-code>
                    </haapi>
                  </capabilities>
                  <validate-port-on-loopback-interfaces>true</validate-port-on-loopback-interfaces>
                  <attestation>
                    <disable-attestation-validation>true</disable-attestation-validation>
                      <android>
                        <package-name>io.curity.haapidemo</package-name>
                        <signature-digest>Z2DKEZO2XWFWQnApoRCzhqhIxzODe7BUsArj4Up9oKQ=</signature-digest>
                        <signature-digest>QqGGZJ4Kzv75J1MyPtG2WA59Z1ezNIshN1o1Ayh7qU4=</signature-digest>
                        <android-policy>android-dev-policy</android-policy>
                      </android>
                    </attestation>
                </client>
            </config-backed>
          </client-store>
        </authorization-server>
      </settings>
    </profile>
  </profiles>
</config>

Updating the App Configuration

The demo app's configuration settings are specified in the Configuration class. If running the quick start, use the default values. If you deployed the Curity Identity Server with ngrok, or have your own configuration, then you need to provide the details to the app configuration. Update the newInstance method in the Configuration class to return proper values:

fun newInstance(): Configuration =
    Configuration(
        clientId = "haapi-android-client",
        baseURLString = "https://idsvr.example.com",
        tokenEndpointPath = "/token",
        authorizationEndpointPath = "/authorize",
        userInfoEndpointPath = "/userinfo",
        redirectURI = "app://haapi",
        scope = listOf("openid", "profile", "address"),
        useSSL = true
    )

Run the App

Once the above configuration is complete, run the app and use whichever authenticators and users are configured in the Curity Identity Server. If using the quickstart option, the username-password authenticator is already configured, and the following username and password can be used to log in: demouser / Password1.

HAAPI Integration

Integration with the HAAPI UI SDK is described in detail in the Android integration guide and can be summarized in these steps that the app implements:

1. In the app/build.gradle file, the SDK is defined as a dependency.
2. The DemoApplication class implements an interface from the SDK and creates a configuration object that is then used by the SDK itself.
3. The AndroidManifest.xml file has a declaration of the HAAPIFlowActivity — an activity provided by the SDK.
4. The MainActivity class is responsible for starting the HAAPI activity. When the authentication is complete, the obtained tokens are returned to the MainActivity. These are then passed to another activity, that is responsible for displaying them.

Use and Refresh Access Tokens

Once a HAAPI mobile client obtains an access token it will use it to call APIs in the standard way, by sending them as bearer tokens in the HTTP Authorization header. When the access token expires, the refreshAccessToken method of the HaapiFlowViewModel class is used to get a new set of tokens. Have a look at the TokensViewModel and TokensFragment classes (in the TokensFragment.kt file) to see how to obtain the view model and use it to refresh tokens.

Logout

Logout can be implemented in a simple manner, by just removing tokens from the app and redirecting back to the MainActivity (unauthenticated view). Have a look at the TokensViewModel class (in the TokensFragment.kt file) to see how to perform logout.

Use Many Authentication Methods

The code example also supports a more advanced deployment, that supports accessing the instance of the Curity Identity Server remotely, e.g., when you want to test the mobile app from a physical device. Edit the start-idsvr.sh and stop-idsvr.sh files to use ngrok (set USE_NGROK=true). This will result in exposing the containerized instance of the Curity Identity Server under a random domain similar to https://87ce095409f9.ngrok.io.

The advanced deployment automates a setup to enable passwordless authentication using passkeys. This requires some additional configuration, including the use of associated domains. For further details on the advanced deployment, see the Configure Native Passkeys for Mobile Logins tutorial. Many other authentication methods are also possible, as summarized in the Advanced Authentication Flows page.

Customize the Look and Feel

The UI SDK allows for a simple change of the styles used by the view components. Have a look at the res/values/styles.xml and res/values/colors.xml files to see the techniques used in the demo app to change the default theme. Note that the custom theme is applied to the HAAPIFlowActivity in the AndroidManifest.xml file. Have a look at the customization tutorial to learn more about changing the look and feel of your authentication flow.

Non-Compliant Devices

The HAAPI SDK uses hardware-backed attestation features to perform secure client authentication. Some older Android devices may not support the recommended method for client attestation. In these cases use a fallback method of proving the client identity before authentication. Have a look at the Implementing HAAPI Fallback tutorial to learn how to configure this.

Model SDK Code Example

The UI SDK is implemented using the lower level Android Model SDK, which uses raw API responses. The Android HAAPI Model SDK Code Example demonstrates an alternative approach, where the model SDK is used directly, but considerably more plumbing code is needed.

To use the code example, execute the ./start-idsvr.sh script and then run the app from Android Studio. First locate the OAuth configuration settings in the Configuration.kt module and update them if required:

Configuration(
      name = name,
      clientId = "haapi-android-client",
      baseURLString = "https://10.0.2.2:8443",
      tokenEndpointURI = "https://10.0.2.2:8443/oauth/v2/oauth-token",
      authorizationEndpointURI = "https://10.0.2.2:8443/oauth/v2/oauth-authorize",
      userInfoEndpointURI = "https://10.0.2.2:8443/oauth/v2/oauth-userinfo",
      metaDataBaseURLString = "https://10.0.2.2:8443/oauth/v2/oauth-anonymous",
      redirectURI = "app://haapi",
      followRedirect = true,
      isSSLTrustVerificationEnabled = false,
      selectedScopes = listOf("openid", "profile")
)

Study the code example's main classes to understand the logic. The DemoApplication class creates a HaapiAccessor factory class, which instantiates a HaapiManager. A FlowActivity provides the user interface for login screens. A HaapiFlowViewModel starts the flow and processes each API response until authentication completes. The start and end of the authentication flow are shown in the following simplified code snippet:

private fun startHaapi() {

      executeHaapi {
          haapiAccessor.haapiManager.start()
      }
  }

private fun processHaapiResult(haapiResult: HaapiResult) {
    
    if (haapiResult is OAuthAuthorizationResponseStep) {
        fetchAccessToken(latestResponse)
    }

    ...
}

Conclusion

The Hypermedia Authentication API provides a number of benefits to mobile apps, in terms of both financial grade security and login usability:

• The app gets an improved login user experience.
• The Curity Identity Server and the HAAPI SDK deal with the security, so the application only requires simple code.
• The authentication workflow can be changed without needing to redeploy the app.
• Only genuine mobile clients can attempt user authentication.
• Man In the Browser (MITB) risks are eliminated for most authentication methods.