From 3540936aeec36f7886eb16b0e01ca19c0576ad01 Mon Sep 17 00:00:00 2001 From: Dickson Mwendia <64727760+Dickson-Mwendia@users.noreply.github.com> Date: Tue, 4 Jun 2024 16:00:42 +0300 Subject: [PATCH] Update Acrolinx scores --- .../confidential-client-assertions.md | 23 +++++++++---------- .../exceptions/msal-error-handling.md | 20 ++++++++-------- .../initializing-client-applications.md | 19 ++++++++------- .../how-to/msal-net-migration.md | 7 +++--- msal-dotnet-articles/index.md | 15 ++++++------ .../microsoft-identity-web/index.md | 11 ++++----- 6 files changed, 45 insertions(+), 50 deletions(-) diff --git a/msal-dotnet-articles/acquiring-tokens/web-apps-apis/confidential-client-assertions.md b/msal-dotnet-articles/acquiring-tokens/web-apps-apis/confidential-client-assertions.md index c8b6336c0..85a85a888 100644 --- a/msal-dotnet-articles/acquiring-tokens/web-apps-apis/confidential-client-assertions.md +++ b/msal-dotnet-articles/acquiring-tokens/web-apps-apis/confidential-client-assertions.md @@ -1,7 +1,6 @@ --- title: Client assertions (MSAL.NET) description: Learn about signed client assertions support for confidential client applications in the Microsoft Authentication Library for .NET (MSAL.NET). -services: active-directory author: Dickson-Mwendia manager: CelesteDG @@ -9,7 +8,7 @@ ms.service: msal ms.subservice: msal-dotnet ms.topic: conceptual ms.workload: identity -ms.date: 03/29/2023 +ms.date: 06/04/2024 ms.author: dmwendia ms.reviewer: saeeda, jmprieur ms.custom: devx-track-csharp, aaddev, devx-track-dotnet @@ -35,9 +34,9 @@ MSAL.NET has four methods to provide either credentials or assertions to the con ### Client assertions -This is useful if you want to handle the certificate yourself. For example, if you wish to use Azure KeyVault's APIs for signing, which eliminates the need for downloading the certificates. A signed client assertion takes the form of a signed JWT with the payload containing the required authentication claims mandated by Microsoft Entra ID, Base64 encoded. Or it can be a JWT form a different Identity Provider, for the "Federated Identity Credential" scenario. +This is useful if you want to handle the certificate yourself. For example, if you wish to use Azure KeyVault's APIs for signing, which eliminates the need for downloading the certificates. A signed client assertion takes the form of a signed JWT with the payload containing the required authentication claims mandated by Microsoft Entra ID, Base64 encoded. Or it can be a JWT from a different Identity Provider, for the "Federated Identity Credential" scenario. -Use the delegate, which enables you to compute the assertion everytime MSAL needs to get a new token from the Identity Provider. Note that MSAL will not invoke your delegate if a token is found in the cache. +Use the delegate, which enables you to compute the assertion every time MSAL needs to get a new token from the identity provider. MSAL doesn't invoke your delegate if a token is found in the cache. ```csharp string signedClientAssertion = GetOrComputeAssertion(); @@ -53,11 +52,11 @@ The [claims expected by Microsoft Entra ID](/azure/active-directory/develop/cert Claim type | Value | Description ---------- | ---------- | ---------- -aud | `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token` | The "aud" (audience) claim identifies the recipients that the JWT is intended for (here Microsoft Entra ID) See [RFC 7519, Section 4.1.3](https://tools.ietf.org/html/rfc7519#section-4.1.3). In this case, that recipient is the token endpoint of the identity provider -exp | 1601519414 | The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. See [RFC 7519, Section 4.1.4](https://tools.ietf.org/html/rfc7519#section-4.1.4). This allows the assertion to be used until then, so keep it short - 5-10 minutes after `nbf` at most. Microsoft Entra ID does not place restrictions on the `exp` time currently. -iss | {ClientID} | The "iss" (issuer) claim identifies the principal that issued the JWT, in this case your client application. Use the GUID application ID. -jti | (a Guid) | The "jti" (JWT ID) claim provides a unique identifier for the JWT. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object; if the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well. The "jti" value is a case-sensitive string. [RFC 7519, Section 4.1.7](https://tools.ietf.org/html/rfc7519#section-4.1.7) -nbf | 1601519114 | The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. [RFC 7519, Section 4.1.5](https://tools.ietf.org/html/rfc7519#section-4.1.5). Using the current time is appropriate. +aud | `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token` | The "aud" (audience) claim identifies the recipients that the JWT is intended for (here Microsoft Entra ID) See [RFC 7519, Section 4.1.3](https://tools.ietf.org/html/rfc7519#section-4.1.3). In this case, that recipient is the token endpoint of the identity provider +exp | 1601519414 | The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. See [RFC 7519, Section 4.1.4](https://tools.ietf.org/html/rfc7519#section-4.1.4). This allows the assertion to be used until then, so keep it short - 5-10 minutes after `nbf` at most. Microsoft Entra ID doesn't place restrictions on the `exp` time currently. +iss | {ClientID} | The "iss" (issuer) claim identifies the principal that issued the JWT, in this case your client application. Use the GUID application ID. +jti | (a Guid) | The "jti" (JWT ID) claim provides a unique identifier for the JWT. The identifier value MUST be assigned in a manner that ensures that there's a negligible probability that the same value can be accidentally assigned to a different data object. If the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well. The "jti" value is a case-sensitive string. [RFC 7519, Section 4.1.7](https://tools.ietf.org/html/rfc7519#section-4.1.7) +nbf | 1601519114 | The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. [RFC 7519, Section 4.1.5](https://tools.ietf.org/html/rfc7519#section-4.1.5). Using the current time is appropriate. sub | {ClientID} | The "sub" (subject) claim identifies the subject of the JWT, in this case also your application. Use the same value as `iss`. If you use a certificate as a client secret, the certificate must be deployed safely. We recommend that you store the certificate in a secure spot supported by the platform, such as in the certificate store on Windows or by using Azure Key Vault. @@ -89,7 +88,7 @@ This is an example using [Microsoft.IdentityModel.JsonWebTokens](https://www.nug } ``` -Alternatively, if you do not wish to use Microsoft.IdentityModel.JsonWebTokens: +Alternatively, if you don't wish to use Microsoft.IdentityModel.JsonWebTokens: ```csharp static string Base64UrlEncode(byte[] arg) @@ -139,7 +138,7 @@ static string GetSignedClientAssertion(X509Certificate2 certificate, string tena In some cases, developers want to inject some claims into the assertions, but would still like MSAL to handle the creation of the assertion and the signing. -`WithClientClaims(X509Certificate2 certificate, IDictionary claimsToSign, bool mergeWithDefaultClaims = true)` will produce a signed assertion containing the claims expected by Microsoft Entra ID plus additional client claims that you want to send. +`WithClientClaims(X509Certificate2 certificate, IDictionary claimsToSign, bool mergeWithDefaultClaims = true)` produces a signed assertion containing the claims expected by Microsoft Entra ID plus additional client claims that you want to send. ```csharp string ipAddress = "192.168.1.2"; @@ -152,6 +151,6 @@ app = ConfidentialClientApplicationBuilder.Create(config.ClientId) ``` -If one of the claims in the dictionary that you pass in is the same as one of the mandatory claims, the additional claim's value will be taken into account. It will override the claims computed by MSAL.NET. +If one of the claims in the dictionary that you pass in is the same as one of the mandatory claims, the additional claim's value is taken into account. It overrides the claims computed by MSAL.NET. If you want to provide your own claims, including the mandatory claims expected by Microsoft Entra ID, pass in `false` for the `mergeWithDefaultClaims` parameter. diff --git a/msal-dotnet-articles/advanced/exceptions/msal-error-handling.md b/msal-dotnet-articles/advanced/exceptions/msal-error-handling.md index 86bd915f1..c8d63d47f 100644 --- a/msal-dotnet-articles/advanced/exceptions/msal-error-handling.md +++ b/msal-dotnet-articles/advanced/exceptions/msal-error-handling.md @@ -1,7 +1,6 @@ --- title: Handle errors and exceptions in MSAL.NET description: Learn how to handle errors and exceptions, Conditional Access claims challenges, and retries in MSAL.NET. -services: active-directory author: Dickson-Mwendia manager: CelesteDG @@ -9,7 +8,7 @@ ms.service: msal ms.subservice: msal-dotnet ms.topic: conceptual ms.workload: identity -ms.date: 01/25/2023 +ms.date: 06/04/2024 ms.author: dmwendia ms.reviewer: saeeda, jmprieur ms.custom: aaddev, devx-track-dotnet @@ -26,10 +25,11 @@ ms.custom: aaddev, devx-track-dotnet [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) is thrown when the Identity Provider (Microsoft Entra ID) returns an error. It's a translation of the server error. -[MsalUIRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) is type of [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) and indicates that user interaction is required, for example because MFA is required or because the user has changed their password and a token can't be acquired silently. +[MsalUIRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) is type of [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) and indicates that user interaction is required. For example, when multifactor authentication (MFA) is required or when the user changes their password and a token can't be acquired silently. ### Processing exceptions + When processing .NET exceptions, you can use the exception type itself and the `ErrorCode` member to distinguish between exceptions. `ErrorCode` values are constants of type [MsalError](/dotnet/api/microsoft.identity.client.msalerror). You can also have a look at the fields of [MsalClientException](/dotnet/api/microsoft.identity.client.msalexception), [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception), and [MsalUIRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception). @@ -45,23 +45,23 @@ Here are the common exceptions that might be thrown and some possible mitigation | Exception | Error code | Mitigation| | --- | --- | --- | | [MsalUiRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) | AADSTS65001: The user or administrator hasn't consented to use the application with ID '{appId}' named '{appName}'. Send an interactive authorization request for this user and resource.| Get user consent first. If you aren't using .NET Core (which doesn't have any Web UI), call (once only) `AcquireTokenInteractive`. If you're using .NET core or don't want to do an `AcquireTokenInteractive`, the user can navigate to a URL to give consent: `https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={clientId}&response_type=code&scope=user.read`. to call `AcquireTokenInteractive`: `app.AcquireTokenInteractive(scopes).WithAccount(account).WithClaims(ex.Claims).ExecuteAsync();`| -| [MsalUiRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) | AADSTS50079: The user is required to use [multi-factor authentication (MFA)](/azure/active-directory/authentication/concept-mfa-howitworks).| There's no mitigation. If MFA is configured for your tenant and Microsoft Entra ID decides to enforce it, fall back to an interactive flow such as `AcquireTokenInteractive`.| +| [MsalUiRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) | AADSTS50079: The user is required to use [multifactor authentication (MFA)](/azure/active-directory/authentication/concept-mfa-howitworks).| There's no mitigation. If MFA is configured for your tenant and Microsoft Entra ID decides to enforce it, fall back to an interactive flow such as `AcquireTokenInteractive`.| | [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) |AADSTS90010: The grant type isn't supported over the */common* or */consumers* endpoints. Use the */organizations* or tenant-specific endpoint. You used */common*.| As explained in the message from Microsoft Entra ID, the authority needs to have a tenant or otherwise */organizations*.| -| [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) | AADSTS70002: The request body must contain the following parameter: `client_secret or client_assertion`.| This exception can be thrown if your application wasn't registered as a public client application in Microsoft Entra ID. In the Azure portal, edit the manifest for your application and set `allowPublicClient` to `true`. | +| [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) | AADSTS70002: The request body must contain the following parameter: `client_secret or client_assertion`.| This exception can be thrown if your application wasn't registered as a public client application in Microsoft Entra ID. In the Microsoft Entra admin center, edit the manifest for your application and set `allowPublicClient` to `true`. | | [MsalClientException](/dotnet/api/microsoft.identity.client.msalclientexception)| `unknown_user Message`: Couldn't identify logged in user| The library was unable to query the current Windows logged-in user or this user isn't Active Directory or Microsoft Entra joined (work-place joined users aren't supported). Mitigation: Implement your own logic to fetch the username (for example, john@contoso.com) and use the `AcquireTokenByIntegratedWindowsAuth` form that takes in the username.| -| [MsalClientException](/dotnet/api/microsoft.identity.client.msalclientexception)|integrated_windows_auth_not_supported_managed_user| This method relies on a protocol exposed by Active Directory (AD). If a user was created in Microsoft Entra ID without AD backing ("managed" user), this method will fail. Users created in AD and backed by Microsoft Entra ID ("federated" users) can benefit from this non-interactive method of authentication. Mitigation: Use interactive authentication.| +| [MsalClientException](/dotnet/api/microsoft.identity.client.msalclientexception)|integrated_windows_auth_not_supported_managed_user| This method relies on a protocol exposed by Active Directory (AD). If a user was created in Microsoft Entra ID without AD backing ("managed" user), this method fails. Users created in AD and backed by Microsoft Entra ID ("federated" users) can benefit from this non-interactive method of authentication. Mitigation: Use interactive authentication.| ### `MsalUiRequiredException` One of common status codes returned from MSAL.NET when calling `AcquireTokenSilent()` is `MsalError.InvalidGrantError`. This status code means that the application should call the authentication library again, but in interactive mode (AcquireTokenInteractive or AcquireTokenByDeviceCodeFlow for public client applications, do have a challenge in Web apps). This is because additional user interaction is required before authentication token can be issued. -Most of the time when `AcquireTokenSilent` fails, it is because the token cache doesn't have tokens matching your request. Access tokens expire in 1 hour, and `AcquireTokenSilent` will try to fetch a new one based on a refresh token (in OAuth2 terms, this is the "Refresh Token' flow). This flow can also fail for various reasons, for example if a tenant admin configures more stringent login policies. +Most of the time when `AcquireTokenSilent` fails, it is because the token cache doesn't have tokens matching your request. Access tokens expire in 1 hour, and `AcquireTokenSilent` tries to fetch a new one based on a refresh token (in OAuth2 terms, this is the "Refresh Token' flow). This flow can also fail for various reasons, for example if a tenant admin configures more stringent sign-in policies. -The interaction aims at having the user do an action. Some of those conditions are easy for users to resolve (for example, accept Terms of Use with a single click), and some can't be resolved with the current configuration (for example, the machine in question needs to connect to a specific corporate network). Some help the user setting-up multi-factor authentication, or install Microsoft Authenticator on their device. +The interaction aims at having the user do an action. Some of those conditions are easy for users to resolve (for example, accept Terms of Use with a single click), and some can't be resolved with the current configuration (for example, the machine in question needs to connect to a specific corporate network). Some help the user setting-up multifactor authentication, or install Microsoft Authenticator on their device. ### `MsalUiRequiredException` classification enumeration -MSAL exposes a `Classification` field, which you can read to provide a better user experience. For example to tell the user that their password expired or that they'll need to provide consent to use some resources. The supported values are part of the [`UiRequiredExceptionClassification`](/dotnet/api/microsoft.identity.client.uirequiredexceptionclassification) enum: +MSAL exposes a `Classification` field, which you can read to provide a better user experience. For example, to tell the user that their password expired or that they need to provide consent to use some resources. The supported values are part of the [`UiRequiredExceptionClassification`](/dotnet/api/microsoft.identity.client.uirequiredexceptionclassification) enum: | Classification | Meaning | Recommended handling | |-------------------|-------------------|----------------------| @@ -133,7 +133,7 @@ catch (MsalUiRequiredException ex) when (ex.ErrorCode == MsalError.InvalidGrantE ``` [!INCLUDE [Active directory error handling claims challenges](../../includes/error-handling-claims-challenges.md)] -When calling an API requiring Conditional Access from MSAL.NET, your application will need to handle claim challenge exceptions. This will appear as an [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) where the [Claims](/dotnet/api/microsoft.identity.client.msalserviceexception.claims) property won't be empty. +When calling an API requiring Conditional Access from MSAL.NET, your application needs to handle claim challenge exceptions. This appears as an [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) where the [Claims](/dotnet/api/microsoft.identity.client.msalserviceexception.claims) property won't be empty. To handle the claim challenge, use . diff --git a/msal-dotnet-articles/getting-started/initializing-client-applications.md b/msal-dotnet-articles/getting-started/initializing-client-applications.md index 3c61d2073..653b2e324 100644 --- a/msal-dotnet-articles/getting-started/initializing-client-applications.md +++ b/msal-dotnet-articles/getting-started/initializing-client-applications.md @@ -1,7 +1,6 @@ --- title: Initialize MSAL.NET client applications description: Learn about initializing public client and confidential client applications using the Microsoft Authentication Library for .NET (MSAL.NET). -services: active-directory author: Dickson-Mwendia manager: CelesteDG @@ -9,7 +8,7 @@ ms.service: msal ms.subservice: msal-dotnet ms.topic: conceptual ms.workload: identity -ms.date: 08/24/2023 +ms.date: 06/04/2024 ms.author: dmwendia ms.reviewer: ddelimarsky ms.custom: devx-track-csharp, aaddev, engagement-fy23, devx-track-dotnet @@ -18,19 +17,19 @@ ms.custom: devx-track-csharp, aaddev, engagement-fy23, devx-track-dotnet # Initialize client applications using MSAL.NET -This article describes initializing public client and confidential client applications using the Microsoft Authentication Library for .NET (MSAL.NET). To learn more about the client application types, see [Public client and confidential client applications](/azure/active-directory/develop/msal-client-applications). +This article describes initializing public client and confidential client applications using the Microsoft Authentication Library for .NET (MSAL.NET). To learn more about the client application types, see [Public client and confidential client applications](/azure/active-directory/develop/msal-client-applications). With MSAL.NET 3.x, the recommended way to instantiate an application is by using the application builders: `PublicClientApplicationBuilder` and `ConfidentialClientApplicationBuilder`. They offer a powerful mechanism to configure the application from the code, a configuration file, or even by mixing both approaches. ## Prerequisites -Before initializing an application, you first need to register it so that your app can be integrated with the Microsoft identity platform. Refer to the [Quickstart: Register an application with the Microsoft identity platform](/azure/active-directory/develop/quickstart-register-app) for more information. After registration, you may need the following information (which can be found in the Azure portal): +Before initializing an application, you first need to register it so that your app can be integrated with the Microsoft identity platform. Refer to the [Quickstart: Register an application with the Microsoft identity platform](/azure/active-directory/develop/quickstart-register-app) for more information. After registration, you'll need the following information, which can be found in the app registration page in the Microsoft Entra admin center. - **Application (client) ID** - This is a string representing a GUID. - **Directory (tenant) ID** - Provides identity and access management (IAM) capabilities to applications and resources used by your organization. It can specify if you're writing a line of business application solely for your organization (also named single-tenant application). - The identity provider URL (named the **instance**) and the sign-in audience for your application. These two parameters are collectively known as the authority. - **Client credentials** - which can take the form of an application secret (client secret string) or certificate (of type `X509Certificate2`) if it's a confidential client app. -- For web apps, and sometimes for public client apps (in particular when your app needs to use a broker), you'll have also set the **Redirect URI** where the identity provider will contact back your application with the security tokens. +- For web apps, and sometimes for public client apps (in particular when your app needs to use a broker), you need to set the **Redirect URI** where the identity provider will contact back your application with the security tokens. ## Initializing applications @@ -38,7 +37,7 @@ There are many different ways to instantiate client applications. ### Initializing a public client application from code -The following code instantiates a public client application, signing-in users in the Microsoft Azure public cloud, with their work, school or personal Microsoft accounts. +The following code instantiates a public client application, signing-in users in the Microsoft Azure public cloud, with their work, school, or personal Microsoft accounts. ```csharp IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId) @@ -57,7 +56,7 @@ IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create .Build(); ``` -In production however, certificates are recommended as they're more secure than client secrets. They can be created and uploaded to the Azure portal. The code would then be the following: +In production however, certificates are recommended as they're more secure than client secrets. They can be created and uploaded to the Microsoft Entra admin center. The code would then be the following: ```csharp IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId) @@ -105,9 +104,9 @@ The modifiers you can set on a public client application builder on Xamarin.iOS ### Modifiers specific to confidential client applications -The modifiers you can set that are specific to a confidential client application builder can be found in the `ConfidentialClientApplicationBuilder` class. The different methods can be found in the [Azure SDK for .NET documentation](/dotnet/api/microsoft.identity.client.confidentialclientapplicationbuilder). +The modifiers specific to a confidential client application builder can be found in the `ConfidentialClientApplicationBuilder` class. The different methods can be found in the [Azure SDK for .NET documentation](/dotnet/api/microsoft.identity.client.confidentialclientapplicationbuilder). -Modifiers such as `.WithCertificate(X509Certificate2 certificate)` and `.WithClientSecret(string clientSecret)` are mutually exclusive. If you provide both, MSAL will throw a meaningful exception. +Modifiers such as `.WithCertificate(X509Certificate2 certificate)` and `.WithClientSecret(string clientSecret)` are mutually exclusive. If you provide both, MSAL throws a meaningful exception. ### Example of usage of modifiers @@ -129,7 +128,7 @@ app = PublicClientApplicationBuilder.Create(clientId) .Build(); ``` -There's also an override for ADFS (MSAL.NET will only support ADFS 2019 or later): +There's also an override for ADFS (MSAL.NET only supports ADFS 2019 or later): ```csharp IPublicClientApplication app; diff --git a/msal-dotnet-articles/how-to/msal-net-migration.md b/msal-dotnet-articles/how-to/msal-net-migration.md index dce40c5d1..b2aaf6279 100644 --- a/msal-dotnet-articles/how-to/msal-net-migration.md +++ b/msal-dotnet-articles/how-to/msal-net-migration.md @@ -1,7 +1,6 @@ --- title: Migrating to MSAL.NET and Microsoft.Identity.Web description: Learn why and how to migrate from Azure AD Authentication Library for .NET (ADAL.NET) to Microsoft Authentication Library for .NET (MSAL.NET) or Microsoft.Identity.Web -services: active-directory author: Dickson-Mwendia manager: CelesteDG @@ -9,7 +8,7 @@ ms.service: msal ms.subservice: msal-dotnet ms.topic: conceptual ms.workload: identity -ms.date: 11/25/2022 +ms.date: 06/04/2024 ms.author: dmwendia ms.reviewer: jmprieur, saeeda ms.custom: devx-track-csharp, aaddev, has-adal-ref, engagement-fy23, devx-track-dotnet @@ -22,10 +21,10 @@ ms.custom: devx-track-csharp, aaddev, has-adal-ref, engagement-fy23, devx-track- Both the Microsoft Authentication Library for .NET (MSAL.NET) and Azure AD Authentication Library for .NET (ADAL.NET) are used to authenticate Microsoft Entra entities and request tokens from Microsoft Entra ID. Up until now, most developers have requested tokens from Azure AD for developers platform (v1.0) using Azure AD Authentication Library (ADAL). These tokens are used to authenticate Microsoft Entra identities (work and school accounts). -MSAL comes with benefits over ADAL. Some of these benefits are listed below: +MSAL comes with multiple benefits over ADAL, including the following: - You can authenticate a broader set of Microsoft identities: work or school accounts, personal Microsoft accounts, and social or local accounts with Azure AD B2C, -- Your users will get the best single-sign-on experience, +- Your users get the best single-sign-on experience, - Your application can enable incremental consent, Conditional Access, - You benefit from continuous innovation in term of security and resilience, - Your application implements the best practices in term of resilience and security. diff --git a/msal-dotnet-articles/index.md b/msal-dotnet-articles/index.md index e4d0ce646..9ae3b7eaa 100644 --- a/msal-dotnet-articles/index.md +++ b/msal-dotnet-articles/index.md @@ -1,14 +1,13 @@ --- title: Microsoft Authentication Library for .NET description: Learn how you can use the Microsoft Authentication Library for .NET (MSAL.NET) to acquire tokens from the Microsoft identity platform and access protected web APIs. -services: active-directory author: Dickson-Mwendia manager: CelesteDG ms.service: msal ms.subservice: msal-dotnet ms.topic: conceptual -ms.date: 03/16/2023 +ms.date: 06/04/2024 ms.author: dmwendia ms.reviewer: localden, jmprieur ms.custom: devx-track-csharp, aaddev @@ -31,7 +30,7 @@ MSAL.NET supports different application topologies, including: - [Native clients](/azure/active-directory/develop/active-directory-dev-glossary#native-client) (mobile or desktop applications) calling the Microsoft Graph API on behalf of a user. - Daemons, services, or [web clients](/azure/active-directory/develop/active-directory-dev-glossary#web-client) (web apps or web APIs) calling the Microsoft Graph API on behalf of a user, or without a user. -For more details about the supported scenarios, see [Scenarios](./getting-started/scenarios.md). +For more information about the supported scenarios, see [Scenarios](./getting-started/scenarios.md). MSAL.NET supports multiple platforms, including [.NET](https://dotnet.microsoft.com/), [.NET Framework](https://dotnet.microsoft.com/download/dotnet-framework), and [.NET MAUI](https://dotnet.microsoft.com/apps/maui). @@ -44,13 +43,13 @@ MSAL.NET supports multiple platforms, including [.NET](https://dotnet.microsoft. > [!NOTE] > MSAL.NET versions 4.61.0 and above do not provide support for Universal Windows Platform, Xamarin Android, and Xamarin iOS. Read more about the deprecation in [Announcing the Upcoming Deprecation of MSAL.NET for Xamarin and UWP](https://devblogs.microsoft.com/identity/uwp-xamarin-msal-net-deprecation/). -## Why use MSAL.NET ? +## Why use MSAL.NET? MSAL.NET provides several ways of getting a token. Using MSAL.NET is easier than using generic OAuth libraries or writing calls against the protocol. MSAL.NET provides several out-of-the-box benefits that simplify the developer workflow: -- Maintain a **token cache** and **refresh tokens** for you when they are close to expiry. +- Maintain a **token cache** and **refresh tokens** for you when they're close to expiry. - Helps you specify which **audience** you want your application to sign-in (your organization, several organizations, work, school, and Microsoft personal accounts, social identities with Microsoft Entra External ID, or users in sovereign and national clouds). -- Helps you set-up the application through **configuration** files. +- Helps you set up the application through **configuration** files. - Helps you troubleshoot the app by exposing actionable exceptions, logging, and telemetry. ## Getting started with MSAL.NET @@ -62,7 +61,7 @@ MSAL.NET provides several ways of getting a token. Using MSAL.NET is easier than ## Considerations -MSAL.NET 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: +MSAL.NET is used to acquire tokens. It's not used to protect a Web API. If you're interested in protecting a Web API with Microsoft Entra ID, check out: - [Microsoft Entra ID with ASP.NET Core](/aspnet/core/security/authentication/azure-active-directory/). Examples showcase web apps that call a web API with MSAL.NET. - [active-directory-dotnet-native-aspnetcore-v2](https://github.com/azure-samples/active-directory-dotnet-native-aspnetcore-v2) shows how to call an ASP.NET Core Web API from a WPF application using Microsoft Entra ID. @@ -81,7 +80,7 @@ For previous releases, see the [Releases on GitHub](https://github.com/AzureAD/m For work-in-progress and future releases, see [Milestones](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/milestones). -For additional information on versioning, see [Semantic versioning - API change management](resources/semantic-versioning-api-change-management.md) to understand changes in MSAL.NET public API. +For more information on versioning, see [Semantic versioning - API change management](resources/semantic-versioning-api-change-management.md) to understand changes in MSAL.NET public API. ## Samples diff --git a/msal-dotnet-articles/microsoft-identity-web/index.md b/msal-dotnet-articles/microsoft-identity-web/index.md index c9a1a7dca..0b6f45d4e 100644 --- a/msal-dotnet-articles/microsoft-identity-web/index.md +++ b/msal-dotnet-articles/microsoft-identity-web/index.md @@ -1,7 +1,6 @@ --- title: Microsoft Identity Web -description: Learn how you can use Microsoft Identity Web to add authentication and authorization to web apps, web APIs and daemon applications. -services: active-directory +description: Learn how you can use Microsoft Identity Web to add authentication and authorization to web apps, web APIs, and daemon applications. author: Dickson-Mwendia manager: CelesteDG @@ -9,7 +8,7 @@ ms.service: msal ms.subservice: microsoft-identity-web ms.topic: conceptual ms.workload: identity -ms.date: 03/30/2023 +ms.date: 06/04/2024 ms.author: jmprieur ms.reviewer: localden, jmprieur ms.custom: devx-track-csharp, aaddev @@ -24,7 +23,7 @@ Microsoft Identity Web is a set of ASP.NET Core libraries that simplifies adding When building ASP.NET Core web apps or web APIs that use Microsoft Entra ID or Azure AD B2C for identity and access management (IAM), Microsoft Identity Web is recommended for these scenarios: -- [Service/Daemon applications](/azure/active-directory/develop/scenario-daemon-overview) +- [Service/daemon applications](/azure/active-directory/develop/scenario-daemon-overview) - [Web app that signs in users](/azure/active-directory/develop/scenario-web-app-sign-user-overview) - [Web app that signs in users and calls a web API on their behalf](/azure/active-directory/develop/scenario-web-app-call-api-overview) - [Protected web API that only authenticated users can access](/azure/active-directory/develop/scenario-protected-web-api-overview) @@ -40,7 +39,7 @@ Microsoft Identity Web is available on NuGet as a set of packages that provide m - [Microsoft.Identity.Web](https://www.nuget.org/packages/Microsoft.Identity.Web) - The main package for ASP.NET Core applications. - [Microsoft.Identity.Web.OWIN](https://www.nuget.org/packages/Microsoft.Identity.Web.OWIN) - The main package for ASP.NET (OWIN) applications. -- [Microsoft.Identity.Web.TokenAcquisition](https://www.nuget.org/packages/Microsoft.Identity.Web.TokenAcquisition) - The main package for other types of applications (daemon apps on .NET framework or .NET Core). This package is referenced by Microsoft.Identity.Web and Microsoft.Identity.Web.OWIN +- [Microsoft.Identity.Web.TokenAcquisition](https://www.nuget.org/packages/Microsoft.Identity.Web.TokenAcquisition) - The main package for other types of applications (daemon apps on .NET framework or .NET Core). Microsoft.Identity.Web and Microsoft.Identity.Web.OWIN reference this package. - [Microsoft.Identity.Web.UI](https://www.nuget.org/packages/Microsoft.Identity.Web.UI) - Optional, for ASP.NET Core web apps. Adds UI for user sign-in and sign-out and an associated controller for web apps. - [Microsoft.Identity.Web.MicrosoftGraph](https://www.nuget.org/packages/Microsoft.Identity.Web.MicrosoftGraph) - Optional. Provides simplified interaction with the Microsoft Graph API. - [Microsoft.Identity.Web.MicrosoftGraphBeta](https://www.nuget.org/packages/Microsoft.Identity.Web.MicrosoftGraphBeta) - Optional. Provides simplified interaction with the Microsoft Graph API [beta endpoint](/graph/api/overview?view=graph-rest-beta&preserve-view=true). @@ -75,7 +74,7 @@ dotnet new webapp --auth SingleOrg --calls-graph --client-id "00001111-aaaa-2222 ### Getting started with MSAL.NET 1. Learn about [Scenarios](./getting-started/scenarios.md). -1. You will need to [register your app](/azure/active-directory/develop/quickstart-register-app) with Microsoft Entra ID. +1. You'll need to [register your app](/azure/active-directory/develop/quickstart-register-app) with Microsoft Entra ID. ## Samples