Skip to content

Commit

Permalink
Merge pull request #81 from alexbuckgit/alexbuckgit/docutune-autopr-2…
Browse files Browse the repository at this point in the history
…0231115-214327-7462136-ignore-build

[BULK] - DocuTune - Rebranding of Azure Active Directory to Microsoft Entra terminology
  • Loading branch information
Dickson-Mwendia authored Nov 27, 2023
2 parents 5604f3a + cac0609 commit 24b2d3a
Show file tree
Hide file tree
Showing 17 changed files with 46 additions and 44 deletions.
4 changes: 2 additions & 2 deletions msal-java-articles/advanced/aad-b2c.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: "You can use MSAL4J to sign-in users with social identities by usin

# Use MSAL4J to sign-in users with social identities

You can use MSAL4J to sign users in with social identities by using [Azure Active Directory B2C](https://aka.ms/aadb2c) (AAD B2C). AAD B2C is built around the notion of [policies](/azure/active-directory-b2c/custom-policy-overview). In MSAL4J, specifying a policy translates to providing an authority - when you instantiate a client application, you need to specify the policy in the authority configuration
You can use MSAL4J to sign users in with social identities by using [Azure Active Directory B2C](https://aka.ms/aadb2c) (Azure AD B2C). Azure AD B2C is built around the notion of [policies](/azure/active-directory-b2c/custom-policy-overview). In MSAL4J, specifying a policy translates to providing an authority - when you instantiate a client application, you need to specify the policy in the authority configuration

## Authority for a B2C tenant and policy

Expand All @@ -21,7 +21,7 @@ Generally, the authority to use is `https://login.microsoftonline.com/tfp/{tenan

If you are using username and password flows with MSAL4J, also known as Resource Owner Password Credentials (ROPC), be aware of the following limitations:

- The flow only works for local accounts, where you register with AAD B2C using an email or username. This flow does not work if federating to any of the identity providers supported by B2C (Facebook, Google, etc.).
- The flow only works for local accounts, where you register with Azure AD B2C using an email or username. This flow does not work if federating to any of the identity providers supported by B2C (Facebook, Google, etc.).
- Currently, there is no `id_token` returned from B2C when implementing the ROPC flow from MSAL. This means an that an account object cannot be created, so in the cache, there will be no account and no user. The [`acquireTokenSilently`](xref:com.microsoft.aad.msal4j.AbstractClientApplicationBase.acquireTokenSilently(com.microsoft.aad.msal4j.SilentParameters)) flow will not work in this scenario. However, ROPC does not show a UI, so there will no impact to the user experience.

## Instantiating an application
Expand Down
2 changes: 1 addition & 1 deletion msal-java-articles/advanced/best-practices-enterprise.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,5 @@ description: "To build robust, enterprise-ready applications, you will need to f

To build robust, enterprise-ready applications, you will need to ensure that you implement a few additional guardrails. We recommend developers to:

- Handle exceptions, both when acquiring a token, but also when calling a protected web API. In particular, if an application runs in an Azure AD tenant where the tenant admins have set [Conditional Access](/azure/active-directory/conditional-access/overview) policies to enforce Multiple Factor Authentication (MFA), you will need to handle a claim challenge which is described in [Exceptions](./exceptions.md).
- Handle exceptions, both when acquiring a token, but also when calling a protected web API. In particular, if an application runs in a Microsoft Entra tenant where the tenant admins have set [Conditional Access](/azure/active-directory/conditional-access/overview) policies to enforce Multiple Factor Authentication (MFA), you will need to handle a claim challenge which is described in [Exceptions](./exceptions.md).
- Enable [Logging](/azure/active-directory/develop/msal-logging?tabs=java) to troubleshoot applications, while respecting user privacy and remain compliant with privacy regulations, such as GDPR.
10 changes: 5 additions & 5 deletions msal-java-articles/advanced/integrated-windows-authentication.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
title: Integrated Windows Authentication
description: "If your desktop or mobile application runs on Windows, and on a machine connected to a Windows domain (AD or AAD joined) it is possible to use the Integrated Windows Authentication (IWA) to acquire a token silently."
description: "If your desktop or mobile application runs on Windows, and on a machine connected to a Windows domain (Active Directory or Microsoft Entra joined) it is possible to use the Integrated Windows Authentication (IWA) to acquire a token silently."
---

# Integrated Windows Authentication

If your desktop or mobile application runs on Windows, and on a machine connected to a Windows domain (AD or AAD joined) it is possible to use the Integrated Windows Authentication (IWA) to acquire a token silently. No UI is required when using the application.
If your desktop or mobile application runs on Windows, and on a machine connected to a Windows domain (Active Directory or Microsoft Entra joined) it is possible to use the Integrated Windows Authentication (IWA) to acquire a token silently. No UI is required when using the application.

```java
final String AUTHORITY;
Expand All @@ -25,9 +25,9 @@ IAuthenticationResult future = app.acquireToken(parameters).get();

### Constraints

- *Federated** users only, i.e. where authentication is being federated to an on-premise authority (ADFS for example), or [hybrid scenarios](/azure/active-directory/hybrid/whatis-hybrid-identity) where seamless-sso is enabled. Pure cloud tenants, where users are directly in Azure Active Directory, without any Active Directory backing, cannot use this flow.
- *Federated** users only, i.e. where authentication is being federated to an on-premise authority (ADFS for example), or [hybrid scenarios](/azure/active-directory/hybrid/whatis-hybrid-identity) where seamless-sso is enabled. Pure cloud tenants, where users are directly in Microsoft Entra ID, without any Active Directory backing, cannot use this flow.
- IWA does NOT bypass MFA (multi factor authentication). If MFA is configured, IWA might fail if an MFA challenge is required, because MFA requires user interaction.
> This one is tricky. IWA is non-interactive, but 2FA requires user interactivity. You do not control when the identity provider requests 2FA to be performed, the tenant admin does. From our observations, 2FA is required when you login from a different country, when not connected via VPN to a corporate network, and sometimes even when connected via VPN. Don’t expect a deterministic set of rules, Azure Active Directory uses AI to continuously learn if 2FA is required. You should fallback to a user prompt if IWA fails
> This one is tricky. IWA is non-interactive, but 2FA requires user interactivity. You do not control when the identity provider requests 2FA to be performed, the tenant admin does. From our observations, 2FA is required when you login from a different country, when not connected via VPN to a corporate network, and sometimes even when connected via VPN. Don’t expect a deterministic set of rules, Microsoft Entra ID uses AI to continuously learn if 2FA is required. You should fallback to a user prompt if IWA fails
- The authority passed in the `PublicApplication` needs to be:
- tenanted (of the form `https://login.microsoftonline.com/{tenant}/` where `tenant` is either the guid representing the tenant ID or a domain associated with the tenant.
- for any work and school accounts (`https://login.microsoftonline.com/organizations/`)
Expand All @@ -41,4 +41,4 @@ IAuthenticationResult future = app.acquireToken(parameters).get();
- either you as a developer have pressed the **Grant** button on the Azure portal for yourself,
- or a tenant admin has pressed the **Grant/revoke admin consent for {tenant domain}** button in the **API permissions** tab of the registration for the application
- or you have provided a way for users to consent to the application
- or you have provided a way for the tenant admin to consent for the application
- or you have provided a way for the tenant admin to consent for the application
2 changes: 1 addition & 1 deletion msal-java-articles/advanced/managed-identity.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ For failed requests the error response contains a correlation ID that can be use

### Potential errors

#### `MsalServiceException` Error Code: `managed_identity_failed_response` Error Message: An unexpected error occurred while fetching the AAD token
#### `MsalServiceException` Error Code: `managed_identity_failed_response` Error Message: An unexpected error occurred while fetching the Microsoft Entra token

This exception might mean that the resource you are trying to acquire a token for is either not supported or is provided using the wrong resource ID format. Examples of correct resource ID formats include `https://management.azure.com/.default`, `https://management.azure.com`, and `https://graph.microsoft.com`.

Expand Down
14 changes: 7 additions & 7 deletions msal-java-articles/advanced/migrate-adal-msal-java.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ description: Learn how to migrate your Azure Active Directory Authentication Lib

This article highlights changes you need to make to migrate an application that uses the Azure Active Directory Authentication Library (ADAL) to the Microsoft Authentication Library (MSAL).

Both the Microsoft Authentication Library for Java (MSAL4J) and Azure AD Authentication Library for Java (ADAL4J) are used to authenticate Microsoft Entra ID entities and request tokens from Microsoft Entra ID. Until now, most developers have worked with Microsoft Entra ID developer platform (v1.0) to authenticate with various identities, such as work and school accounts, by requesting tokens using Azure AD Authentication Library (ADAL).
Both the Microsoft Authentication Library for Java (MSAL4J) and Azure AD Authentication Library for Java (ADAL4J) are used to authenticate Microsoft Entra entities and request tokens from Microsoft Entra ID. Until now, most developers have worked with Azure AD for developers (v1.0) to authenticate with various identities, such as work and school accounts, by requesting tokens using Azure AD Authentication Library (ADAL).

MSAL offers the following benefits:

- Because it uses the newer Microsoft identity platform, you can authenticate a broader set of Microsoft identities such as Microsoft Entra ID identities, Microsoft accounts, and social and local accounts through Microsoft Entra ID Business to Consumer (B2C).
- Because it uses the newer Microsoft identity platform, you can authenticate a broader set of Microsoft identities such as Microsoft Entra identities, Microsoft accounts, social and local accounts through Azure AD Business to Consumer (Azure AD B2C), and social or local customer accounts through Microsoft Entra External ID.
- Your users will get the best single-sign-on experience.
- Your application can enable incremental consent, as well as support new features, such as Conditional Access.

Expand Down Expand Up @@ -48,27 +48,27 @@ The following table shows how ADAL4J functions map to the new MSAL for Java func

## IAccount instead of IUser

ADAL4J handled users. Although a user represents a single human or software agent, it can have one or more accounts in the Microsoft identity system. For example, a user may have several Microsoft Entra ID, Microsoft Entra ID B2C, or Microsoft personal accounts.
ADAL4J handled users. Although a user represents a single human or software agent, it can have one or more accounts in the Microsoft identity system. For example, a user may have several Microsoft Entra ID, Azure AD B2C, or Microsoft personal accounts.

MSAL for Java defines the concept of Account via the `IAccount` interface. This is a breaking change from ADAL4J. It captures the fact that the same user can have several accounts, and perhaps even in different Microsoft Entra ID directories. MSAL for Java provides better information in guest scenarios because home account information is provided.
MSAL for Java defines the concept of Account via the `IAccount` interface. This is a breaking change from ADAL4J. It captures the fact that the same user can have several accounts, and perhaps even in different Microsoft Entra directories. MSAL for Java provides better information in guest scenarios because home account information is provided.

## Cache persistence

ADAL4J didn't have support for token cache. MSAL for Java adds a [token cache](/azure/active-directory/develop/msal-acquire-cache-tokens) to simplify managing token lifetimes by automatically refreshing expired tokens when possible and preventing unnecessary prompts for the user to provide credentials when possible.

## Common Authority

In v1.0, if you use the `https://login.microsoftonline.com/common` authority, users can sign in with any Microsoft Entra ID account (for any organization).
In v1.0, if you use the `https://login.microsoftonline.com/common` authority, users can sign in with any Microsoft Entra account (for any organization).

If you use the `https://login.microsoftonline.com/common` authority in v2.0, users can sign in with any Microsoft Entra ID organization, or even a Microsoft personal account (MSA). In MSAL for Java, if you want to restrict login to any Microsoft Entra ID account, use the `https://login.microsoftonline.com/organizations` authority (which is the same behavior as with ADAL4J). To specify an authority, set the `authority` parameter in the <xref:com.microsoft.aad.msal4j.PublicClientApplication.Builder> method when you instantiate a `PublicClientApplication` class.
If you use the `https://login.microsoftonline.com/common` authority in v2.0, users can sign in with any Microsoft Entra organization, or even a Microsoft personal account (MSA). In MSAL for Java, if you want to restrict login to any Microsoft Entra account, use the `https://login.microsoftonline.com/organizations` authority (which is the same behavior as with ADAL4J). To specify an authority, set the `authority` parameter in the <xref:com.microsoft.aad.msal4j.PublicClientApplication.Builder> method when you instantiate a `PublicClientApplication` class.

## v1.0 and v2.0 tokens

The v1.0 endpoint (used by ADAL) only emits v1.0 tokens.

The v2.0 endpoint (used by MSAL) can emit v1.0 and v2.0 tokens. A property of the application manifest of the web API enables developers to choose which version of token is accepted. See `accessTokenAcceptedVersion` in the [application manifest](/azure/active-directory/develop/reference-app-manifest) reference documentation.

For more information about v1.0 and v2.0 tokens, see [Azure Active Directory access tokens](/azure/active-directory/develop/access-tokens).
For more information about v1.0 and v2.0 tokens, see [Microsoft Entra access tokens](/azure/active-directory/develop/access-tokens).

## ADAL to MSAL migration

Expand Down
4 changes: 2 additions & 2 deletions msal-java-articles/advanced/msal-error-handling-java.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ This article gives an overview of the different types of errors and recommendati

Exceptions in Microsoft Authentication Library (MSAL) are intended for app developers to troubleshoot, not for displaying to end users. Exception messages are not localized.

When processing exceptions and errors, you can use the exception type itself and the error code to distinguish between exceptions. For a list of error codes, see [Azure AD Authentication and authorization error codes](/azure/active-directory/develop/reference-error-codes).
When processing exceptions and errors, you can use the exception type itself and the error code to distinguish between exceptions. For a list of error codes, see [Microsoft Entra authentication and authorization error codes](/azure/active-directory/develop/reference-error-codes).

During the sign-in experience, you may encounter errors about consents, Conditional Access (e.g., multi-factor authentication, device management, location-based restrictions), token issuance and redemption, and user properties.

Expand Down Expand Up @@ -83,7 +83,7 @@ In certain cases when calling an API requiring Conditional Access, you can recei

## Retrying after errors and exceptions

You're expected to implement your own retry policies when calling MSAL. MSAL makes HTTP calls to the Microsoft Entra ID service, and occasionally failures can occur. For example the network can go down or the server is overloaded.
You're expected to implement your own retry policies when calling MSAL. MSAL makes HTTP calls to the Microsoft Entra service, and occasionally failures can occur. For example the network can go down or the server is overloaded.

### HTTP 429

Expand Down
2 changes: 1 addition & 1 deletion msal-java-articles/advanced/service-to-service-calls.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: "Web APIs can acquire tokens in the name of a user, leveraging User

Web APIs can acquire tokens in the name of a user, leveraging User assertions. Web API cannot have any user interaction, and therefore when a web API (named "Web API #1") needs to call another Web API (named "Web API #2") in the name of a user, it needs to use the [On Behalf Of OAuth 2.0 flow](/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow).

This flow is a confidential client flow, and therefore the first web API provides client credentials (client secret or certificate), as well as an `UserAssertion`. The first web API will receive a bearer token and send it to Azure AD by embedding it into a `UserAssertion` to request another token to the downstream second Web API.
This flow is a confidential client flow, and therefore the first web API provides client credentials (client secret or certificate), as well as an `UserAssertion`. The first web API will receive a bearer token and send it to Microsoft Entra ID by embedding it into a `UserAssertion` to request another token to the downstream second Web API.

```java
// This is the confidential client application representing Web Api #1
Expand Down
12 changes: 7 additions & 5 deletions msal-java-articles/advanced/support-for-adfs.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,16 @@ Active Directory Federation Services (AD FS) in Windows Server enables you to ad

There are usually two ways of authenticating against AD FS:

- MSAL connects to Azure Active Directory, which then federates to AD FS.
- MSAL connects to Microsoft Entra ID, which then federates to AD FS.
- MSAL connects directly to an AD FS authority.

MSAL4J supports both these flows.

## MSAL connects to Azure AD, which then federates to AD FS
<a name='msal-connects-to-azure-ad-which-then-federates-to-ad-fs'></a>

MSAL4J supports connecting to Azure AD, which signs in managed-users (users managed in Azure AD) or federated users (users managed by another identity provider such as AD FS). MSAL4J does not know about the fact that users are federated. As far as it’s concerned, it talks to Azure AD.
## MSAL connects to Microsoft Entra ID, which then federates to AD FS

MSAL4J supports connecting to Microsoft Entra ID, which signs in managed-users (users managed in Microsoft Entra ID) or federated users (users managed by another identity provider such as AD FS). MSAL4J does not know about the fact that users are federated. As far as it’s concerned, it talks to Microsoft Entra ID.

The authority you use in this case is the usual authority (authority host name + tenant, common, or organizations).

Expand All @@ -25,7 +27,7 @@ The authority you use in this case is the usual authority (authority host name +
When you call the AcquireToken with AuthorizationCodeParameters or DeviceCodeParameters, the user experience is typically:

1. The user enters their account ID.
2. Azure AD displays briefly the message "Taking you to your organization's page".
2. Microsoft Entra ID displays briefly the message "Taking you to your organization's page".
The user is redirected to the sign-in page of the identity provider. The sign-in page is usually customized with the logo of the organization.
3. Supported AD FS versions in this federated scenario are AD FS v2, AD FS v3 (Windows Server 2012 R2), and AD FS v4 (AD FS 2016).

Expand All @@ -35,4 +37,4 @@ MSAL4J provides support for directly authenticating with AD FS 2019. In this cas

## Acquiring a token using AcquireToken with IntegratedWindowsAuthenticationParameters or UsernamePasswordParameters

When acquiring a token using AcquireToken with IntegratedWindowsAuthenticationParameters or UsernamePasswordParameters, MSAL4J gets the identity provider which to contact based on the username. MSAL4J receives a SAML token after contacting the identity provider. MSAL4J then provides the SAML token to Azure AD as a user assertion (similar to the on-behalf-of flow) to get back a JWT.
When acquiring a token using AcquireToken with IntegratedWindowsAuthenticationParameters or UsernamePasswordParameters, MSAL4J gets the identity provider which to contact based on the username. MSAL4J receives a SAML token after contacting the identity provider. MSAL4J then provides the SAML token to Microsoft Entra ID as a user assertion (similar to the on-behalf-of flow) to get back a JWT.
Loading

0 comments on commit 24b2d3a

Please sign in to comment.