azuread/microsoft-authentication-library-common-for-android

Purpose and module topology

This is the internal shared authentication foundation for ADAL and MSAL Android, not a standalone app or public API. It is a Gradle multi-module repository rooted at settings.gradle; primary Android/runtime implementation is common, while common4j holds platform-neutral Java/Kotlin primitives. Supporting test/lab clients are separate modules.

Primary entry surfaces

Consumers enter through controller/command abstractions and Android authorization/broker components rather than an executable main:

• Command orchestration: common4j/src/main/com/microsoft/identity/common/java/controllers/CommandDispatcher.java, common4j/src/main/com/microsoft/identity/common/java/commands/TokenCommand.java.

• Android routing: common/src/main/java/com/microsoft/identity/common/internal/controllers/LocalMSALController.java, common/src/main/java/com/microsoft/identity/common/internal/controllers/BrokerMsalController.java.

• Android UI/activity boundary: common/src/main/java/com/microsoft/identity/common/internal/providers/oauth2/AuthorizationActivity.java.

OAuth/OIDC provider pipeline

Provider-neutral OAuth2 request, response, PKCE, token-cache, and discovery types live in common4j; Microsoft-specific AAD, Microsoft STS, B2C, and ADFS strategies specialize them. The usual flow is command parameters → controller/strategy → authorization or token HTTP exchange → parsed token result/cache.

• common4j/src/main/com/microsoft/identity/common/java/providers/oauth2/OAuth2Strategy.java

• common4j/src/main/com/microsoft/identity/common/java/providers/microsoft/azureactivedirectory/AzureActiveDirectoryOAuth2Strategy.java

• common4j/src/main/com/microsoft/identity/common/java/providers/microsoft/microsoftsts/MicrosoftStsOAuth2Strategy.java

Android interactive authorization

Android-specific code selects browser/custom-tab/WebView flows, launches activities/fragments, validates redirects, and handles web challenges including PKeyAuth, certificate authentication, passkeys/FIDO, and browser switching. This is the boundary between protocol logic and Android UI/intent lifecycle.

• common/src/main/java/com/microsoft/identity/common/internal/providers/oauth2/AndroidAuthorizationStrategy.java

• common/src/main/java/com/microsoft/identity/common/internal/ui/browser/BrowserAuthorizationStrategy.java

• common/src/main/java/com/microsoft/identity/common/internal/ui/webview/challengehandlers/ChallengeFactory.java

Broker and device-registration boundary

Broker operation adapts SDK requests/results and dispatches cross-process calls through Android AccountManager, bound services, and content providers, with validation and fallback strategies. AIDL declares service contracts. Device registration is a related IPC/protocol subsystem.

• common/src/main/java/com/microsoft/identity/common/internal/broker/BrokerRequest.java

• common/src/main/java/com/microsoft/identity/common/internal/broker/ipc/IpcStrategyWithBackup.kt

• common/src/main/aidl/com/microsoft/identity/client/IMicrosoftAuthService.aidl

• common/src/main/java/com/microsoft/identity/deviceregistration/AndroidDeviceRegistrationClientController.java

Credentials, cache, and cryptographic storage

Account/credential DTOs and OAuth token caches are cross-platform; Android supplies SharedPreferences and Android Keystore-backed protection. Device proof-of-possession keys, JWT/JWE signing/encryption, and cache migration protect or evolve persisted authentication state.

• common4j/src/main/com/microsoft/identity/common/java/cache/MsalOAuth2TokenCache.java

• common/src/main/java/com/microsoft/identity/common/crypto/AndroidAuthSdkStorageEncryptionManager.java

• common/src/main/java/com/microsoft/identity/common/internal/platform/AndroidDevicePopManager.java

Native authentication and observability

Native-auth models commands for sign-in, sign-up, MFA, JIT, and password reset as stateful API exchanges, alongside conventional browser-based OAuth. Logging, telemetry events, and OpenTelemetry abstractions span commands, broker calls, UI, cache, and HTTP.

• common/src/main/java/com/microsoft/identity/common/nativeauth/internal/controllers/NativeAuthMsalController.kt

• common4j/src/main/com/microsoft/identity/common/java/nativeauth/providers/NativeAuthOAuth2Strategy.kt

• common4j/src/main/com/microsoft/identity/common/java/telemetry/Telemetry.java

• common4j/src/main/com/microsoft/identity/common/java/opentelemetry/OpenTelemetryHolder.java

Runtime and external dependencies

The production target is Android, implemented in Java and Kotlin with Android manifests/resources and Android IPC/Keystore/AccountManager/WebView APIs. Network traffic uses URL-connection HTTP abstractions; external identity services include Azure Active Directory/Microsoft STS, Azure AD B2C/CIAM, ADFS, and optionally Google federated sign-in. Lab and Key Vault generated API clients support integration infrastructure rather than core runtime behavior: LabApiUtilities/src/main/com/microsoft/identity/labapi/utilities/client/LabClient.java, keyvault/src/main/java/com/microsoft/identity/internal/test/keyvault/api/CertificatesApi.java.