Guide for configuring Keycloak login and biometric authentication.

Fetching App Configuration

Configurations are available via the Portal endpoint: http://portal.localhost.gentics.com/api/andp/appconfig

Standard Keycloak Configuration

Setting up the Environment Variable

Configure the environment variable ANDP_APP_KEYCLOAK_CONFIG_JSON_RAW using a JSON string.

Example JSON structure:

{
  "issuer": "http://keycloak.localhost.gentics.com/realms/EXTERNAL",
  "clientId": "portal",
  "scopes": ["openid", "profile", "email"]
}

As a Key-Value pair with proper escaping:

ANDP_APP_KEYCLOAK_CONFIG_JSON_RAW="{\"issuer\":\"http://keycloak.localhost.gentics.com/realms/EXTERNAL\",\"clientId\":\"portal\",\"scopes\":[\"openid\",\"profile\",\"email\"]}"
Important

  • Do not provide a Redirect URL: The Redirect URL is statically defined within the mobile app and must not be included in this configuration.

  • Fallback Behavior: If keycloakConfig is not configured, the Web Portal’s Keycloak configuration will be loaded automatically and converted into the ANDP_APP_KEYCLOAK_CONFIG_JSON_RAW format.

  • External Documentation: For the full configuration structure, refer to: https://nearform.com/open-source/react-native-app-auth/docs/usage/config/

Enabling Biometric Authentication

Environment Variable for Biometric Login

Configure the environment variable ANDP_APP_BIOMETRIC_KEYCLOAK_CONFIG_JSON_RAW with an extended structure.

Example JSON structure:

{
  "enabled": true,
  "issuer": "http://keycloak.localhost.gentics.com/realms/EXTERNAL",
  "clientId": "biometrics",
  "scopes": ["openid", "profile", "email", "offline_access"]
}

As a Key-Value pair with proper escaping:

ANDP_APP_BIOMETRIC_KEYCLOAK_CONFIG_JSON_RAW="{\"enabled\":true,\"issuer\":\"http://keycloak.localhost.gentics.com/realms/EXTERNAL\",\"clientId\":\"biometrics\",\"scopes\":[\"openid\",\"profile\",\"email\",\"offline_access\"]}"

Configuration Structure

The biometric configuration is based on the standard react-native-app-auth configuration with one additional property:

  • enabled: Boolean value to enable/disable biometric authentication.

  • All other fields follow the standard configuration (see the documentation link above).

Important

Again: Do not include a Redirect URL!

Keycloak Admin Configuration for Biometrics

To fully implement biometric authentication, perform the following steps in the Keycloak Admin Console:

1. Configure the Biometric Client

Navigate to the biometrics client in the Keycloak Admin Console. Under the Settings or OpenID Connect Settings tab, ensure the following is active: * "Use Refresh Tokens": On

2. Create Audience Mappers

You must create two "Audience" type mappers to ensure tokens are valid across clients.

Mapper 1: Biometric Audience

  • Mapper Type: Audience

  • Included Client Audience: biometrics

  • Add to ID token: true

Mapper 2: Portal Audience

  • Mapper Type: Audience

  • Included Client Audience: portal

  • Add to ID token: true

This configuration allows the mobile app to use both standard authentication and biometric authentication with Keycloak.