From 606bf03c37d5babd73887c50c32f0dc763f0407b Mon Sep 17 00:00:00 2001 From: Alex Buck Date: Wed, 15 Nov 2023 16:43:29 -0500 Subject: [PATCH 1/2] [BULK] - DocuTune - Rebranding of Azure Active Dir --- msal-java-articles/advanced/aad-b2c.md | 4 ++-- .../advanced/best-practices-enterprise.md | 2 +- .../advanced/integrated-windows-authentication.md | 10 +++++----- msal-java-articles/advanced/managed-identity.md | 2 +- .../advanced/migrate-adal-msal-java.md | 14 +++++++------- .../advanced/msal-error-handling-java.md | 4 ++-- .../advanced/service-to-service-calls.md | 2 +- msal-java-articles/advanced/support-for-adfs.md | 12 +++++++----- msal-java-articles/breadcrumb/toc.yml | 4 ++-- .../acquiring-tokens-with-authorization-codes.md | 4 ++-- .../getting-started/acquiring-tokens.md | 6 +++--- .../getting-started/client-applications.md | 2 +- .../getting-started/client-credentials.md | 4 ++-- .../getting-started/device-code-flow.md | 4 ++-- msal-java-articles/getting-started/faq.md | 6 +++--- .../getting-started/why-use-msal4j.md | 4 ++-- msal-java-articles/index.md | 6 +++--- 17 files changed, 46 insertions(+), 44 deletions(-) diff --git a/msal-java-articles/advanced/aad-b2c.md b/msal-java-articles/advanced/aad-b2c.md index 7b4300a..b904063 100644 --- a/msal-java-articles/advanced/aad-b2c.md +++ b/msal-java-articles/advanced/aad-b2c.md @@ -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 @@ -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 diff --git a/msal-java-articles/advanced/best-practices-enterprise.md b/msal-java-articles/advanced/best-practices-enterprise.md index cb402bd..8e93856 100644 --- a/msal-java-articles/advanced/best-practices-enterprise.md +++ b/msal-java-articles/advanced/best-practices-enterprise.md @@ -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. diff --git a/msal-java-articles/advanced/integrated-windows-authentication.md b/msal-java-articles/advanced/integrated-windows-authentication.md index 95deb2f..b085265 100644 --- a/msal-java-articles/advanced/integrated-windows-authentication.md +++ b/msal-java-articles/advanced/integrated-windows-authentication.md @@ -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; @@ -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/`) @@ -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 \ No newline at end of file + - or you have provided a way for the tenant admin to consent for the application diff --git a/msal-java-articles/advanced/managed-identity.md b/msal-java-articles/advanced/managed-identity.md index 52ecdf5..35e37d3 100644 --- a/msal-java-articles/advanced/managed-identity.md +++ b/msal-java-articles/advanced/managed-identity.md @@ -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`. diff --git a/msal-java-articles/advanced/migrate-adal-msal-java.md b/msal-java-articles/advanced/migrate-adal-msal-java.md index f15849a..f922be3 100644 --- a/msal-java-articles/advanced/migrate-adal-msal-java.md +++ b/msal-java-articles/advanced/migrate-adal-msal-java.md @@ -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 Microsoft Entra developer platform (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, and social and local accounts through Microsoft Entra Business to Consumer (B2C). - 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. @@ -48,9 +48,9 @@ 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, Microsoft Entra 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 @@ -58,9 +58,9 @@ ADAL4J didn't have support for token cache. MSAL for Java adds a [token cache](/ ## 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 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 method when you instantiate a `PublicClientApplication` class. ## v1.0 and v2.0 tokens @@ -68,7 +68,7 @@ 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 diff --git a/msal-java-articles/advanced/msal-error-handling-java.md b/msal-java-articles/advanced/msal-error-handling-java.md index dc6120a..682ec11 100644 --- a/msal-java-articles/advanced/msal-error-handling-java.md +++ b/msal-java-articles/advanced/msal-error-handling-java.md @@ -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. @@ -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 diff --git a/msal-java-articles/advanced/service-to-service-calls.md b/msal-java-articles/advanced/service-to-service-calls.md index d783662..2c0bc33 100644 --- a/msal-java-articles/advanced/service-to-service-calls.md +++ b/msal-java-articles/advanced/service-to-service-calls.md @@ -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 diff --git a/msal-java-articles/advanced/support-for-adfs.md b/msal-java-articles/advanced/support-for-adfs.md index ca08ab5..9b0a065 100644 --- a/msal-java-articles/advanced/support-for-adfs.md +++ b/msal-java-articles/advanced/support-for-adfs.md @@ -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 + -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). @@ -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). @@ -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. diff --git a/msal-java-articles/breadcrumb/toc.yml b/msal-java-articles/breadcrumb/toc.yml index 7923a0f..1a39846 100644 --- a/msal-java-articles/breadcrumb/toc.yml +++ b/msal-java-articles/breadcrumb/toc.yml @@ -2,7 +2,7 @@ tocHref: / topicHref: /index items: - - name: Entra + - name: Microsoft Entra tocHref: /entra/ topicHref: /entra/index items: @@ -12,4 +12,4 @@ items: - name: MSAL Java tocHref: /entra/msal/java - topicHref: /entra/msal/java/index \ No newline at end of file + topicHref: /entra/msal/java/index diff --git a/msal-java-articles/getting-started/acquiring-tokens-with-authorization-codes.md b/msal-java-articles/getting-started/acquiring-tokens-with-authorization-codes.md index 053fc7f..83928d0 100644 --- a/msal-java-articles/getting-started/acquiring-tokens-with-authorization-codes.md +++ b/msal-java-articles/getting-started/acquiring-tokens-with-authorization-codes.md @@ -1,11 +1,11 @@ --- title: Acquiring tokens with authorization codes -description: "The Authorization Code flow is suitable when the application requires the user's interaction with the Azure AD STS during authentication." +description: "The Authorization Code flow is suitable when the application requires the user's interaction with the Microsoft Entra STS during authentication." --- # Acquiring tokens with authorization codes -The Authorization Code flow is suitable when the application requires the user's interaction with the Azure AD STS during authentication. One such case is when users login to Web applications (web sites) using Open Id connect. The web application receives an authorization code which it can redeem to acquire a token for Web APIs. +The Authorization Code flow is suitable when the application requires the user's interaction with the Microsoft Entra STS during authentication. One such case is when users login to Web applications (web sites) using OpenID Connect. The web application receives an authorization code which it can redeem to acquire a token for Web APIs. Requests for authorization codes are delegated to the developer. To understand how to request an authorization code, see [Authorization code flow](/azure/active-directory/develop/active-directory-protocols-oauth-code). To construct the authorization code URL where the user will input their credentials, you can use the [authorization code URL builder](../advanced/authorization-code-url-builder.md) diff --git a/msal-java-articles/getting-started/acquiring-tokens.md b/msal-java-articles/getting-started/acquiring-tokens.md index 86ff8be..a4ffc2d 100644 --- a/msal-java-articles/getting-started/acquiring-tokens.md +++ b/msal-java-articles/getting-started/acquiring-tokens.md @@ -22,14 +22,14 @@ Follow the topics below for detailed explanation with MSAL4J code usage for each - Acquire tokens [interactively with system browser](./acquiring-tokens-interactively.md) - Acquire tokens by [authorization code](./acquiring-tokens-with-authorization-codes.md) after letting the user sign-in through the authorization request URL. - It's also possible (but not recommended) to get a token with a [username and password](/azure/active-directory/develop/scenario-desktop-acquire-token?tabs=java#username--password). -- For applications running on Windows machines and joined to a domain or to Azure AD, it is possible to acquire a token silently, leveraging [Integrated Windows Authentication (IWA)](../advanced/integrated-windows-authentication.md). -- Finally, for applications running on devices which don't have a web browser, it's possible to acquire a token through the [device code flow](./device-code-flow.md), which provides the user with a URL and a code. The user goes to a web browser on another device, enters the code and signs-in, and then Azure AD returns back a token to the browser-less device. +- For applications running on Windows machines and joined to a domain or to Microsoft Entra ID, it is possible to acquire a token silently, leveraging [Integrated Windows Authentication (IWA)](../advanced/integrated-windows-authentication.md). +- Finally, for applications running on devices which don't have a web browser, it's possible to acquire a token through the [device code flow](./device-code-flow.md), which provides the user with a URL and a code. The user goes to a web browser on another device, enters the code and signs-in, and then Microsoft Entra ID returns back a token to the browser-less device. ### Confidential client applications - Acquire token **as the application itself** using [client credentials](./client-credentials.md), and not for a user. For example, in apps which process users in batches and not a particular user such as in syncing tools. - In the case of Web Apps or Web APIs **calling another downstream Web API in the name of the user**, use the [On Behalf Of flow](../advanced/service-to-service-calls.md) to acquire a token based on some User assertion (SAML for instance, or a JWT token). -- **For Web apps in the name of a user**, acquire tokens by [authorization code](/azure/active-directory/develop/scenario-web-app-call-api-acquire-token?tabs=java) after letting the user sign-in through the authorization request URL. This is typically the mechanism used by an application which lets the user sign-in using Open ID Connect, but then wants to access Web APIs for this particular user. +- **For Web apps in the name of a user**, acquire tokens by [authorization code](/azure/active-directory/develop/scenario-web-app-call-api-acquire-token?tabs=java) after letting the user sign-in through the authorization request URL. This is typically the mechanism used by an application which lets the user sign-in using OpenID Connect, but then wants to access Web APIs for this particular user. ## MSAL4J caches tokens diff --git a/msal-java-articles/getting-started/client-applications.md b/msal-java-articles/getting-started/client-applications.md index 2c6f7e0..f794341 100644 --- a/msal-java-articles/getting-started/client-applications.md +++ b/msal-java-articles/getting-started/client-applications.md @@ -12,7 +12,7 @@ description: "How to start configuring client applications with MSAL Java." Before instantiating your app with MSAL4J: 1. Understand the types of Client applications available- [Public Client and Confidential Client applications](/azure/active-directory/develop/msal-client-applications). -1. You'll need to [register](/azure/active-directory/develop/quickstart-register-app) the application with Azure AD. You will therefore know: +1. You'll need to [register](/azure/active-directory/develop/quickstart-register-app) the application with Microsoft Entra ID. You will therefore know: - Its `clientID` (a string representing a GUID) - The identity provider URL (named the instance) and the sign-in audience for your application. These two parameters are collectively known as the authority. - Possibly the `TenantID` in the case you are writing a line of business application (just for your organization, also named single-tenant application) diff --git a/msal-java-articles/getting-started/client-credentials.md b/msal-java-articles/getting-started/client-credentials.md index 8578600..5f997c4 100644 --- a/msal-java-articles/getting-started/client-credentials.md +++ b/msal-java-articles/getting-started/client-credentials.md @@ -13,7 +13,7 @@ There are three types of client secrets in MSAL4J: ## Client Credentials with application secret in MSAL4J -During the registration of a the confidential client application with Azure AD, a client secret is generated (a kind of application password). When the client wants to acquire a token in its own name it will: +During the registration of a the confidential client application with Microsoft Entra ID, a client secret is generated (a kind of application password). When the client wants to acquire a token in its own name it will: - Create `IClientCredential` using the `ClientCredentialFactory`, passing in the client secret, which should be a string. @@ -24,7 +24,7 @@ IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_S ## Client Credentials with certificate -In this case, when the application is registered with Azure AD, it uploads the public key of a certificate. When it wants to acquire a token, the client application will +In this case, when the application is registered with Microsoft Entra ID, it uploads the public key of a certificate. When it wants to acquire a token, the client application will - Create `IClientCredential` using the `ClientCredentialFactory`, passing in either both the public and private keys, or a InputStream of the pkcs12 diff --git a/msal-java-articles/getting-started/device-code-flow.md b/msal-java-articles/getting-started/device-code-flow.md index 91af6ab..a3aa678 100644 --- a/msal-java-articles/getting-started/device-code-flow.md +++ b/msal-java-articles/getting-started/device-code-flow.md @@ -1,11 +1,11 @@ --- title: Device code flow -description: "Interactive authentication with Azure AD requires a web browser. However, in the case of devices and operating systems that do not provide a Web browser, Device code flow lets the user use another device (for instance another computer or a mobile phone) to sign-in interactively." +description: "Interactive authentication with Microsoft Entra ID requires a web browser. However, in the case of devices and operating systems that do not provide a Web browser, Device code flow lets the user use another device (for instance another computer or a mobile phone) to sign-in interactively." --- # Device code flow -Interactive authentication with Azure AD requires a web browser. However, in the case of devices and operating systems that do not provide a Web browser, Device code flow lets the user use another device (for instance another computer or a mobile phone) to sign-in interactively. By using the device code flow, the application obtains tokens through a two-step process especially designed for these devices/OS. Examples of such applications are applications running on iOT, or Command-Line tools (CLI). +Interactive authentication with Microsoft Entra ID requires a web browser. However, in the case of devices and operating systems that do not provide a Web browser, Device code flow lets the user use another device (for instance another computer or a mobile phone) to sign-in interactively. By using the device code flow, the application obtains tokens through a two-step process especially designed for these devices/OS. Examples of such applications are applications running on iOT, or Command-Line tools (CLI). A typical device code flow follows the steps: diff --git a/msal-java-articles/getting-started/faq.md b/msal-java-articles/getting-started/faq.md index b8b1167..9ea4c98 100644 --- a/msal-java-articles/getting-started/faq.md +++ b/msal-java-articles/getting-started/faq.md @@ -21,13 +21,13 @@ MSAL is implementing a custom version of the OAuth2 protocol. Also, for some spe ### Is MSAL a general library for token acquisition using OAuth2 protocol? -No. MSAL is a client library for Azure Active Directory (AAD), Active Directory Federation Services (ADFS), and Azure Active Directory B2C. There are some custom notions such as “resource” required by ADAL which are considered extensions to the general OAuth2 protocol spec and not supported by other STS’s. +No. MSAL is a client library for Microsoft Entra ID, Active Directory Federation Services (ADFS), and Azure Active Directory B2C. There are some custom notions such as “resource” required by ADAL which are considered extensions to the general OAuth2 protocol spec and not supported by other STS’s. ## API Ramp Up ### Should I turn off authority validation by passing false to the constructor? -It depends on what type of authority you talk to. If it is ADFS, you have to pass false as ADFS does not currently support authority validation. If it is AAD, you still have the option to pass false, but it is recommended to be true, especially if you get the address of the authority from a third party (e.g. via 401 challenge). This is to protect applications and users from being redirected to malicious endpoints to enter their credentials. +It depends on what type of authority you talk to. If it is ADFS, you have to pass false as ADFS does not currently support authority validation. If it is Microsoft Entra ID, you still have the option to pass false, but it is recommended to be true, especially if you get the address of the authority from a third party (e.g. via 401 challenge). This is to protect applications and users from being redirected to malicious endpoints to enter their credentials. ### What overload of AcquireToken should I call? @@ -40,7 +40,7 @@ It depends on the type of client application you use and the scenario you need a Problems in MSAL could have various reasons. These are the common culprits: 1. Your machine has connection issues. -2. Your applications/users are not properly configured on AAD or ADFS. +2. Your applications/users are not properly configured on Microsoft Entra ID or ADFS. 3. You are using an incorrect API for your task (MSAL has several similar overloads for the method AcquireToken). 4. There is a bug in MSAL! Yes, that is always possible. If you are certain that none of the items above are the reason for the failure, please report it to us and we will investigate and fix the bug if exists. diff --git a/msal-java-articles/getting-started/why-use-msal4j.md b/msal-java-articles/getting-started/why-use-msal4j.md index fa185c6..a28a4dd 100644 --- a/msal-java-articles/getting-started/why-use-msal4j.md +++ b/msal-java-articles/getting-started/why-use-msal4j.md @@ -30,7 +30,7 @@ It also adds value by: ## Token acquisition -MSAL4J is used to acquire tokens. It's not used to protect a Web API. If you are interested in protecting a Web API with Azure AD, check out the following resources: +MSAL4J is used to acquire tokens. It's not used to protect a Web API. If you are interested in protecting a Web API with Microsoft Entra ID, check out the following resources: -- [Spring Starter for Azure Active Directory](/azure/developer/java/spring-framework/spring-boot-starter-for-azure-active-directory-developer-guide?tabs=SpringCloudAzure4x) +- [Spring Starter for Microsoft Entra ID](/azure/developer/java/spring-framework/spring-boot-starter-for-azure-active-directory-developer-guide?tabs=SpringCloudAzure4x) - [Validating tokens manually](/azure/active-directory/develop/access-tokens#validating-tokens) diff --git a/msal-java-articles/index.md b/msal-java-articles/index.md index fd6ebf3..a7504f4 100644 --- a/msal-java-articles/index.md +++ b/msal-java-articles/index.md @@ -5,12 +5,12 @@ description: "The Microsoft Authentication Library for Java (usually shortened t # Microsoft Authentication Library for Java -The Microsoft Authentication Library for Java (usually shortened to MSAL Java or MSAL4J) enables applications to integrate with the [Microsoft identity platform](/azure/active-directory/develop/v2-overview). It allows you to sign in users or apps with Microsoft identities (Azure AD, Microsoft accounts, and Azure AD B2C accounts) and obtain tokens to call Microsoft APIs such as [Microsoft Graph](https://graph.microsoft.io/) or your own APIs. It is built using industry standard OAuth2 and OpenID Connect protocols. +The Microsoft Authentication Library for Java (usually shortened to MSAL Java or MSAL4J) enables applications to integrate with the [Microsoft identity platform](/azure/active-directory/develop/v2-overview). It allows you to sign in users or apps with Microsoft identities (Microsoft Entra ID, Microsoft accounts, and Azure AD B2C accounts) and obtain tokens to call Microsoft APIs such as [Microsoft Graph](https://graph.microsoft.io/) or your own APIs. It is built using industry standard OAuth2 and OpenID Connect protocols. ## Overview 1. [Why use MSAL4J?](getting-started/why-use-msal4j.md) -1. **Pre-requisite**: Before using MSAL4J you will have to [register your applications with Azure AD](/azure/active-directory/develop/active-directory-integrating-applications). +1. **Pre-requisite**: Before using MSAL4J you will have to [register your applications with Microsoft Entra ID](/azure/active-directory/develop/active-directory-integrating-applications). 1. To start using MSAL4J, instantiate and configure the [client application](getting-started/client-applications.md). 1. Learn about the ways to [acquire a token](getting-started/acquiring-tokens.md) using MSAL4J. 1. Follow [best practices for a robust enterprise ready application](advanced/best-practices-enterprise.md). @@ -21,7 +21,7 @@ The Microsoft Authentication Library for Java (usually shortened to MSAL Java or MSAL4J can be used by applications to acquire tokens to access protected APIs. Tokens can be acquired by different **application types**: desktop applications, web applications, web APIs, and applications running on devices that don't have a browser (such as IoT devices). In MSAL4J, applications are categorized as follows: - **Public client applications (desktop and mobile)**. These types of apps cannot store app secrets securely. -- **Confidential client applications (web apps, web APIs, and daemon applications)**. These type of apps securely store a secret registered with Azure AD. +- **Confidential client applications (web apps, web APIs, and daemon applications)**. These type of apps securely store a secret registered with Microsoft Entra ID. Learn more details about instantiating and configuring the above in the [Client applications](./getting-started/client-applications.md) topic. From cac06097eb5a95d98861eaf3acbf9e389d42c298 Mon Sep 17 00:00:00 2001 From: Dickson Mwendia <64727760+Dickson-Mwendia@users.noreply.github.com> Date: Mon, 27 Nov 2023 14:04:18 +0300 Subject: [PATCH 2/2] Apply suggestions from code review --- msal-java-articles/advanced/migrate-adal-msal-java.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/msal-java-articles/advanced/migrate-adal-msal-java.md b/msal-java-articles/advanced/migrate-adal-msal-java.md index f922be3..8aca826 100644 --- a/msal-java-articles/advanced/migrate-adal-msal-java.md +++ b/msal-java-articles/advanced/migrate-adal-msal-java.md @@ -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 entities and request tokens from Microsoft Entra ID. Until now, most developers have worked with Microsoft Entra 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 identities, Microsoft accounts, and social and local accounts through Microsoft Entra 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. @@ -48,7 +48,7 @@ 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 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 directories. MSAL for Java provides better information in guest scenarios because home account information is provided.