How forgerock/forgerock-android-sdk works
Project Type and Purpose
• This is an Android SDK (library) for integrating Ping/ForgeRock Identity Platform into Android apps.
• It contains a sample “e2e” app, multiple SDK modules (auth UI, core auth, 2FA authenticator, risk plugin, core utilities), and integration-test modules.
File Structure
• Top-level Gradle modules:
– e2e/app: sample Android application demonstrating the SDK (MVVM + Jetpack Compose navigation).
– forgerock-auth-ui: UI components for authentication callbacks (Fragments, ViewModels).
– forgerock-auth: core authentication flows (network client, callback model, session manager, token manager).
– forgerock-authenticator: one-time password (TOTP/HOTP) and push-notification authenticator library.
– forgerock-core: shared low-level utilities—network interceptors, encryption, secure storage, key-store management.
– ping-protect: risk evaluation plugin module.
– forgerock-integration-tests: instrumentation tests against real or mocked services.
• Config and buildSrc directories contain Gradle plugin code, common build scripts, CI/CD configuration, and publishing logic.
README for Technical Stack and Use Cases
• Kotlin + Java libraries
• Gradle Kotlin DSL builds
• Android min API 23+
• Uses OkHttp for HTTP, Jetpack Compose (in e2e), AndroidX libraries
• Callback-driven auth tree traversal via REST calls to ForgeRock AM or Ping Cloud
Main Components and Their Relationships
a. Sample App (e2e/app)
– UI layer: Activities + Compose navigation + ViewModels
– Depends on: forgerock-auth-ui + forgerock-auth + forgerock-core
b. forgerock-auth-ui
– Android Fragments & Dialogs for each Callback type
– Publishes callback results to ViewModels
– Depends on: forgerock-auth (to request next node), forgerock-core (for interceptors)
c. forgerock-auth
– AuthServiceClient: orchestrates callback requests/responses
– FRAuth, FRSession, TokenManager: handles login, refresh, single-sign-on
– Uses: OkHttp interceptors, JSON parsing, secure cookie/storage from forgerock-core
– Emits callback objects that forgerock-auth-ui consumes
d. forgerock-authenticator
– MechanismFactory, Push & OATH generators, notification handlers
– Integrated into forgerock-auth self-service flows for 2FA
e. ping-protect
– Risk evaluation callbacks plugged into auth tree
f. forgerock-core
– Networking: OkHttpClientProvider, interceptors (AccessTokenInterceptor, CookieInterceptor)
– Encryption & storage: EncryptedSharedPreferences, KeyStoreManager
– Utility: Logger, JSON extensions, Supplier/Listener patterns
g. External Systems
– ForgeRock Identity Platform (Ping Cloud / PingAM REST API)
– Third-party Identity Providers (Google, Facebook, Apple)
– WebAuthn & device binding backends
Data Flow / Interaction Paths
• UI → Auth-UI fragments → forgerock-auth AuthServiceClient → HTTP → Identity Platform
• Responses (Callback tree) flow back through interceptors → AuthServiceClient → Auth-UI → UI
• Token and session state stored via forgerock-core secure storage
• 2FA (OATH/Push) flows triggered by forgerock-authenticator plugged into forgerock-auth self-service calls
Architectural Patterns & Principles
• Layered modularization: UI layer, domain/auth logic layer, core infrastructure layer
• Dependency injection by Gradle modules: core has zero upstream deps; auth depends on core; auth-UI depends on auth; sample depends on all
• Callback pipeline: tree of Callback objects serialized ↔ deserialized as JSON
• Interceptor pattern: OkHttp interceptors handle token injection, cookie marshalling
• Observer pattern: FRListener / SingleLiveEvent for asynchronous events