Add User Federated Identity Credential (user_fic) grant type support

[Avery-Dunn]

This PR adds support for the user_fic (User Federated Identity Credential) grant type to MSAL Java, enabling Leg 3 of the agent identity protocol. This allows an agent application to exchange a federated identity credential (obtained from Leg 2's instance token) for a user-scoped access token, enabling the agent to act on behalf of a specific user.

What's included

New public APIs:

• IConfidentialClientApplication.acquireToken(UserFederatedIdentityCredentialParameters) — acquires a user-scoped token using the user_fic grant type
• UserFederatedIdentityCredentialParameters — parameter object with builder pattern, supporting:
  • .builder(scopes, username, assertion) — identify user by UPN
  • .builder(scopes, userObjectId, assertion) — identify user by Object ID (UUID)
  • .forceRefresh(boolean) — bypass cache and hit IdP
  • .tenant(String) — override tenant
  • .claims(ClaimsRequest) — claims challenge support
  • .extraHttpHeaders(Map) — additional HTTP headers
  • .extraQueryParameters(Map) — (deprecated) present only to satisfy IAcquireTokenParameters interface; scheduled for removal

Token request behavior:

• Sends grant_type=user_fic in the POST body
• Sends user_federated_identity_credential=<T2> (the instance token from Leg 2)
• Sends either user_id=<OID> or username=<UPN> (mutually exclusive, enforced by API design)
• Augments scopes with openid, profile, offline_access (user-flow behavior, not app-flow)
• Sends client_info=1 to receive account information in the response
• Claims are passed via the 3-arg OAuthAuthorizationGrant constructor, ensuring correct merging with clientCapabilities in TokenRequestExecutor (rather than being silently overwritten)

Cache behavior:

• Tokens are stored in the user token cache with full account information
• Subsequent calls for the same user return cached tokens without hitting the IdP (unless forceRefresh=true)
• Account lookup uses findCachedAccount() which matches by OID (homeAccountId prefix, case-insensitive) or UPN (case-insensitive)
• Cache read is performed synchronously via tokenCache().getAccounts(clientId) to avoid potential deadlock when the app runs on a single-thread executor (the previous approach of getAccounts().get() submitted work to the same executor)
• App-only tokens and user_fic tokens are correctly isolated — user_fic goes through the account-aware silent path, never the app-token lookup path
• When performing a cache-based silent request, claims, tenant, extraHttpHeaders, and extraQueryParameters from the original parameters are propagated to the SilentParameters

Internal changes:

• AcquireTokenByUserFederatedIdentityCredentialSupplier — orchestrates cache-then-network logic, including synchronous findCachedAccount() with case-insensitive OID/UPN matching and parameter propagation to silent requests
• UserFederatedIdentityCredentialRequest — constructs the OAuth2 grant with correct parameters; uses 3-arg OAuthAuthorizationGrant constructor for proper claims handling
• GrantConstants.USER_FIC — new grant type constant
• ConfidentialClientApplication.acquireToken(UserFederatedIdentityCredentialParameters) — routes to the new supplier
• PublicApi.ACQUIRE_TOKEN_BY_USER_FEDERATED_IDENTITY_CREDENTIAL — telemetry enum

Tests:

• UserFederatedIdentityCredentialTest.java — 21 unit tests covering:
  • Input validation (null/blank scopes, username, assertion, userObjectId)
  • Correct OAuth2 parameters sent in POST body (grant_type, user_fic, username/user_id, scopes)
  • Mutual exclusion of user_id vs username
  • ForceRefresh behavior (cache bypass)
  • Cache hit on second call (no network)
  • Multi-user cache isolation (two UPNs, two OIDs — correct token returned for each)
  • Single-account fallback (does not return wrong user's token)
  • Parameter builder correctness (UPN and OID variants)
• UserFicIT.java — 5 integration tests covering:
  • Full flow with UPN (Leg 1+2 → Leg 3)
  • Full flow with OID (UUID-based user identification)
  • Cache hit on second call (returns cached token without network)
  • ForceRefresh bypasses cache
  • (note: previously named FicIT.java, renamed for consistency)
• AgenticIT.java — 6 integration tests (shared with FMI), including 2 FIC-specific tests:
  • Agent acquiring user token for Graph via user_fic
  • App-only vs user token cache isolation

Alignment with MSAL .NET

This implementation matches the user_fic behavior on MSAL .NET's main branch. Key equivalences:

.NET	Java
AcquireTokenByUserFederatedIdentityCredential(scopes, username, assertion)	acquireToken(UserFederatedIdentityCredentialParameters.builder(scopes, username, assertion).build())
WithForceRefresh(true)	.forceRefresh(true)
WithExtraQueryParameters (inherited from base builder, old overload deprecated)	.extraQueryParameters(Map) (deprecated on parameters, satisfies interface)
User token cache storage	Account-aware cache with synchronous findCachedAccount()
grant_type=user_fic + scope augmentation + client_info=1	Same
Claims passed to grant constructor (merged with clientCapabilities)	Same — uses 3-arg OAuthAuthorizationGrant for proper merging

Differences from .NET (intentional)

Aspect	.NET	Java	Rationale
User identification	Only username (UPN)	Both username and userObjectId (UUID)	Java is a superset; OID is the immutable identifier and preferred when available
Cache strategy	Always hits IdP; developer must call AcquireTokenSilent separately	Built-in cache-then-network in single call	More convenient API; matches Java's OBO pattern
Cache read mechanism	Async with cancellation token	Synchronous tokenCache().getAccounts(clientId)	Avoids deadlock on single-thread executors; Java's existing OBO uses same pattern
CCS routing header	Sends datacenter routing hint	Not sent	Performance optimization only; can be added later
extraQueryParameters deprecation	Old Dictionary<string,string> overload deprecated; new IDictionary<string,(string,bool)> available	Entire extraQueryParameters API deprecated (matching Java-wide pattern)	Java hasn't introduced the cache-key-aware replacement yet; will be removed SDK-wide

[neha-bhargava]

Overall looks good. I would like to see some end to end tests as well where an assertion is built and passed to user fic. The test setup is up and working and used in MISE PR.

[neha-bhargava]

Minor comment, otherwise looks good

[neha-bhargava]

UPN match below is equalsIgnoreCase but OID match here is case-sensitive startsWith on oid.tid. Should be case-insensitive equality on the OID segment, no?

[Avery-Dunn]

The code now splits homeAccountId on "." and compares the OID segment with equalsIgnoreCase, consistent with the UPN matching.

[neha-bhargava]

All these constants are duplicated accross test files. If there is a change in tenant or app id these will need to be updated in all places. Can we have these in a single constants file?

[Avery-Dunn]

Moved all shared agentic/FMI/FIC constants to TestConstants.java. All three integration test classes (FmiIT, AgenticIT, UserFicIT) now reference TestConstants.AGENTIC_* instead of local declarations.

[Copilot]

Pull request overview

Adds MSAL4J support for the user_fic (User Federated Identity Credential) grant type in ConfidentialClientApplication, enabling agent identity “Leg 3” user-scoped token acquisition with built-in cache-then-network behavior.

Changes:

• Introduces new public API acquireToken(UserFederatedIdentityCredentialParameters) plus the corresponding parameters/request types and user_fic grant constants/telemetry.
• Adds AcquireTokenByUserFederatedIdentityCredentialSupplier to orchestrate cache lookup (silent) and fallback to network (user_fic) acquisition.
• Adds unit + integration tests covering request construction, caching semantics, and multi-user isolation.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/UserFederatedIdentityCredentialTest.java	New unit tests validating body params, scope augmentation, caching, and multi-user behavior.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/UserFederatedIdentityCredentialRequest.java	New request type building the user_fic OAuth grant parameters.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/UserFederatedIdentityCredentialParameters.java	New public parameters + builder for user_fic requests.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/PublicApi.java	Adds telemetry enum for the new public API.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IConfidentialClientApplication.java	Adds new public interface method for user_fic token acquisition.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/GrantConstants.java	Adds user_fic grant type + parameter constants.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ConfidentialClientApplication.java	Routes new API call into request execution.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AcquireTokenByUserFederatedIdentityCredentialSupplier.java	Implements cache-then-network orchestration for the new flow.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AbstractApplicationBase.java	Wires request type to new supplier.
msal4j-sdk/src/integrationtest/java/com/microsoft/aad/msal4j/UserFicIT.java	New integration tests for end-to-end user_fic agent identity scenarios.
msal4j-sdk/src/integrationtest/java/com/microsoft/aad/msal4j/AgenticIT.java	Expands agent identity integration coverage to include user_fic flows and cache isolation.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/UserFederatedIdentityCredentialTest.java:530

• Local variables in this test use snake_case (e.g., alice_oid/alice_upn/alice_token, bob_oid/...). MSAL4J tests generally use Java-style camelCase for local variables; consider renaming to improve consistency and readability.

        String alice_oid = "oid-alice-1111";
        String alice_upn = "alice@contoso.com";
        String alice_token = "access-token-alice";

        String bob_oid = "oid-bob-2222";

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.