iOS - Native Login Module

Early Adopter Status

The Native Login module is currently in early adopter status. Configuration and availability are subject to change. Work with your Q2 representative to determine if Native Login is appropriate for your deployment.

Native Login provides a fully native SwiftUI-based authentication UI for Q2DevApp. It replaces the standard web-based login screen with a platform-native experience that includes username/password authentication, biometric enrollment, multi-user support, and configurable footer links.

Unlike InboundSSO, which delegates authentication to an external identity provider (Okta), Native Login authenticates directly against the Q2 platform using the same credentials as the web experience.

Authentication Architecture

The Native Login module:

• presents a native SwiftUI login form with username and password fields
• authenticates directly against the Q2 platform (Ardent) via LogonUser
• supports biometric authentication (Face ID / Touch ID) enrollment and login
• supports multi-user selection for shared devices
• reads UI configuration (login buttons, footer links) from the platform via Tecton
• theming (logos, backgrounds, colors) is driven by the standard Q2 theming pipeline

Native Login vs InboundSSO vs Web Login

Capability	Native Login	InboundSSO	Web Login
Authentication target	Q2 Platform (Ardent)	External IdP (Okta)	Q2 Platform (web)
UI technology	Native SwiftUI	System browser (ASWebAuthenticationSession)	WKWebView
Biometric support	Built-in enrollment and login	Not included	Not included
Multi-user support	Built-in	Not included	Not included
External IdP federation	No	Yes (Okta + upstream)	No
Custom branding	Platform theming (logos, backgrounds)	IdP login page styling	Platform theming
Offline capability	Biometric login without network	None	None

Native Login Sequence

Enabling Native Login

There are two parts to enabling Native Login on iOS:

1. ensure the Native Login module is available to your DevApp build
2. configure the module entry in settings.json

1. Verify the Module Is Included

Make sure your DevApp includes the Q2-provided Native Login module package for your SDK version. If you are starting from a current DevApp template supplied by Q2, follow the instructions below to add it.

For adding or updating package wiring, follow Using Third-Party SDKs and apply the package, product, and class names below.

For the current iOS Native Login module, use:

• Git URL: https://code.q2developer.com/Q2Antilles/native/modules/ios/Q2NativeLogin.git
• Package name: Q2NativeLogin
• Product name: Q2NativeLogin
• Class name: Q2NativeLoginModule
• Version: 1.0.2

2. Configure settings.json

Add the Native Login module to the modules array in your DevApp settings.json.

{
  "modules": [
    {
      "name": "Native Login",
      "gitUrl": "https://code.q2developer.com/Q2Antilles/native/modules/ios/Q2NativeLogin.git",
      "packageName": "Q2NativeLogin",
      "productName": "Q2NativeLogin",
      "className": "Q2NativeLoginModule",
      "version": "1.0.2",
      "identifier": "com.q2.mobile.module.nativelogin",
      "data": {
        "uiConfiguration": [
          {
            "type": "loginButtons",
            "items": []
          },
          {
            "type": "ualButtons",
            "items": []
          }
        ]
      },
      "enabled": true
    }
  ]
}

Package Metadata Fields

Field	Value	Purpose
name	"Native Login"	Display name (used in logs)
gitUrl	"https://code.q2developer.com/Q2Antilles/native/modules/ios/Q2NativeLogin.git"	Git repository URL used by SPM to fetch the xcframework
packageName	"Q2NativeLogin"	SPM package name (matches the distribution repo's Package.swift name)
productName	"Q2NativeLogin"	SPM library product name (used in the import statement)
className	"Q2NativeLoginModule"	Entry point class (used by NSClassFromString at runtime)
version	"1.0.2"	Version tag to resolve from the distribution repo
identifier	"com.q2.mobile.module.nativelogin"	Module identifier used by Tecton and platform services
data	{...}	Runtime UI configuration (see data Configuration below)
enabled	true	Set to true to activate the module

data Configuration Reference

The data object configures the login screen UI elements at build time. It contains a uiConfiguration array that defines button groups displayed on the native login screen.

uiConfiguration

An array of button group objects. Each group has a type and an items array of button definitions.

Group Type	Description
loginButtons	Buttons displayed below the login form (e.g., "Enroll Now", "Contact Us")
ualButtons	Buttons displayed in the upper action area above the login form

Button Item Fields

Each item in the items array supports:

Field	Type	Required	Description
displayName	string	Yes	Button label. Supports localization keys (prefixed with _t.) that resolve at runtime via the platform localization system.
link	string	Yes	Action target. A URL for url link type, or a phone number for phone link type.
linkType	string	Yes	One of: url, phone
target	string	For url type	Determines how the URL is presented: self (navigate within app/UUX), popup (in-app over-browser), browser (open in external Safari)
buttonStyle	string	No	Visual style: secondary (outlined button) or text (text-only link)

Example with Buttons Configured

{
  "data": {
    "uiConfiguration": [
      {
        "type": "loginButtons",
        "items": [
          {
            "displayName": "_t.mob.enrollnow",
            "link": "https://your-fi.example.com/enrollment",
            "linkType": "url",
            "target": "self",
            "buttonStyle": "secondary"
          },
          {
            "displayName": "Forgot Password",
            "link": "https://your-fi.example.com/forgot-password",
            "linkType": "url",
            "target": "popup",
            "buttonStyle": "secondary"
          },
          {
            "displayName": "_t.main_page.contactUs",
            "link": "8005551234",
            "linkType": "phone",
            "buttonStyle": "text"
          }
        ]
      },
      {
        "type": "ualButtons",
        "items": [
          {
            "displayName": "About Us",
            "link": "https://your-fi.example.com/about",
            "linkType": "url",
            "target": "browser",
            "buttonStyle": "secondary"
          }
        ]
      }
    ]
  }
}

URL Target Behavior

Target	Behavior
self	Navigates within the app's UUX webview — use for enrollment or internal flows
popup	Opens an in-app browser overlay (over-browser) — user stays in the app context
browser	Opens in external Safari — use for external sites not controlled by the FI

Localization Keys

Button displayName values prefixed with _t. are resolved at runtime through the Q2 platform localization system. This allows buttons to be localized without app rebuilds. If a plain string is provided (no _t. prefix), it is displayed as-is.

Additional Platform Configuration

Beyond the data node in settings.json, Native Login also reads configuration from the Q2 platform at runtime:

• Footer Links — configurable links displayed below the login form are delivered via a footer-links.json filemap asset from the platform CDN
• Theming — FI logos, login background images, and colors are delivered through the standard Q2 theming pipeline
• Localization — all user-facing strings (error messages, prompts, button labels) are localized through the platform localization system
• Compliance Logo — FDIC/NCUA logo visibility is controlled by the top-level complianceLogo setting in settings.json

Work with your Q2 representative to configure these platform-level settings for your deployment.

Top-Level settings.json Flags

The following top-level flags in settings.json are relevant when using Native Login:

Flag	Value	Purpose
complianceLogo	"1"	Set to "1" to display the FDIC/NCUA compliance logo on the login screen
urlScheme	"yourscheme"	URL scheme used for over-browser redirect callbacks (needed if login buttons use popup target)

Versioning

The current Native Login module version is 1.0.2. In future releases the module version will be aligned with the Q2 Mobile SDK version — at that point, upgrading your Q2 Mobile SDK dependency will mean updating the Native Login module version to match.

Settings Integration

Native Login exposes the following module setting that can be read or written by the platform:

Setting Identifier	Type	Description
biometricEnablementModuleSetting	Bool	Whether biometric authentication is enabled for the current user

This setting is managed through the standard Q2 module settings interface and can be surfaced in the app's settings screen via Tecton configuration.

Validation Checklist

Before testing, verify the following:

• the Native Login module entry exists in settings.json with "enabled": true
• packageName is "Q2NativeLogin" (must match exactly for runtime class loading)
• className is "Q2NativeLoginModule"
• identifier is "com.q2.mobile.module.nativelogin"
• the Q2 platform (Tecton) is configured for native login for your FI
• nativeLogin flag in settings.json top-level is set to true

Migrating from InboundSSO

If you are currently using InboundSSO and want to switch to Native Login:

1. Remove or disable the InboundSSO module entry in settings.json
2. Add the Native Login module entry as shown above
3. Ensure your Q2 platform configuration supports direct authentication (not federated IdP-only)
4. Coordinate with your Q2 representative to enable Native Login server-side

note

Native Login and InboundSSO are mutually exclusive — only one authentication module should be enabled at a time. If both are enabled, the module loaded first will handle platform authentication.

Related Documentation

• InboundSSO Module
• Setup DevApp
• Module Settings
• Using Third-Party SDKs