Skip to content

Commit

Permalink
Update Wiki links to docs
Browse files Browse the repository at this point in the history
  • Loading branch information
localden committed Sep 8, 2023
1 parent ecfb6d2 commit a2afa53
Show file tree
Hide file tree
Showing 22 changed files with 41 additions and 50 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Once MSAL.NET has acquired a user token to call a Web API, it caches it. If you

### Confidential client application

If you are build an ASP.NET Core application, use [Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web/wiki), which handles all these for you.
If you are build an ASP.NET Core application, use [`Microsoft.Identity.Web`](https://github.com/AzureAD/microsoft-identity-web), which handles all these for you.

Otherwise, in confidential client applications, you should not call `AcquireTokenSilent` before:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -166,4 +166,3 @@ Sample | Platform | Description
In case you want to learn more about Device code flow:

- [OAuth standard - device flow](https://tools.ietf.org/html/draft-ietf-oauth-device-flow-07#section-3.4)
- (_Legacy library_) How this was done with the V1 endpoint: [Device code flow in ADAL.NET](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/Device-profile-for-devices-without-web-browsers)
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ If your desktop or mobile application runs on Windows and on a machine connected
## IWA Constraints

- **Federated** users only, i.e. those created in an Active Directory and backed by Azure Active Directory. Users created directly in Azure AD, without AD backing - **managed** users - cannot use this auth flow. This limitation does not affect the Username/Password flow.
- Does not work for MSA users. For MSA uses try out [WAM](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/wam)
- Does not work for MSA users. For MSA uses try out [WAM](./wam.md)
- IWA is for apps written for .NET Framework, .NET Core and UWP platforms
- 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](./acquiring-tokens-interactively.md) if IWA fails
Expand Down Expand Up @@ -165,7 +165,7 @@ Some of those issues include:

- An account is not being available to perform IWA
- An IWA policy is preventing auto-IWA authentication
- Proxy or configuration issues prevent NTLM protocol (usually the case for 401 [Negotiate](https://www.ietf.org/rfc/rfc4559.txt)/NTLM challenge presented by the endpoint for Windows authentication. You may be able to try using your own [HttpClient](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/HttpClient) or changing the current version of .NET to work around this issue).
- Proxy or configuration issues prevent NTLM protocol (usually the case for 401 [Negotiate](https://www.ietf.org/rfc/rfc4559.txt)/NTLM challenge presented by the endpoint for Windows authentication. You may be able to try using your own [HttpClient](../../advanced/httpclient.md) or changing the current version of .NET to work around this issue).
- In case the Error Message is "Object reference not set to an instance of an object." [enable MSAL logging](/azure/active-directory/develop/msal-logging-dotnet) at Warning level to see more details.

For more information see [AD FS Troubleshooting - Integrated Windows Authentication](/windows-server/identity/ad-fs/troubleshooting/ad-fs-tshoot-iwa)
Original file line number Diff line number Diff line change
Expand Up @@ -188,8 +188,6 @@ This flow **only works for local accounts** (where you register with B2C using a

If you are a B2C developer using Google as an identity provider we recommend you use the system browser, as Google does not allow [authentication from embedded webviews](https://developers.googleblog.com/2016/08/modernizing-oauth-interactions-in-native-apps.html). Currently, `login.microsoftonline.com` is a trusted authority with Google. Using this authority will work with embedded webview. However using `b2clogin.com` is not a trusted authority with Google, so users will not be able to authenticate.
We will provide an update to the wiki and this [issue](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/688) if things change.
## Caching with B2C in MSAL.NET

### Known issue with Azure B2C
Expand All @@ -207,7 +205,7 @@ The customer impact is that when trying to display the username field, are you g

#### Mitigation of the lack of `tid`

The suggested workaround is to use the [Caching by Policy](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/AAD-B2C-specifics#acquiring-a-token-to-apply-a-policy).
The suggested workaround is to use the [Caching by Policy](/azure/active-directory/develop/msal-net-b2c-considerations#known-issue-with-azure-ad-b2c).

Alternatively, you can use the `tid` claim, if you are using the [B2C custom policies](/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy), because it provides the capability to return additional claims to the application. To learn more about [Claims Transformation](/azure/active-directory-b2c/claims-transformation-technical-profile).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ When users login to Web applications (web sites) using OpenID Connect, the web a

## ASP.NET and ASP.NET Core: use Microsoft.Identity.Web

If you are building a web app on ASP.NET Core, the recommendation is to use [Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web/wiki)
If you are building a web app on ASP.NET Core, the recommendation is to use [`Microsoft.Identity.Web`](https://github.com/AzureAD/microsoft-identity-web/)

## Application registration

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,6 @@ For advanced scenarios, 2 more types of credentials can be used. See details at
### Code snippet

```csharp

// this object will cache tokens in-memory - keep it as a singleton
var singletonApp = ConfidentialClientApplicationBuilder.Create(config.ClientId)
// don't specify authority here, we'll do it on the request
Expand All @@ -38,7 +37,6 @@ var singletonApp = ConfidentialClientApplicationBuilder.Create(config.ClientId)
var authResult = await app.AcquireTokenForClient(scopes: new [] { "some_app_id_uri/.default"}) // uses the token cache automatically, which is optimized for multi-tenant access
.WithAuthority(AzureCloudInstance.AzurePublic, "{tenantID}") // do not use "common" or "organizations"!
.ExecuteAsync();

```

**Important: do not use `common` or `organizations` authority for client credential flows.**
Expand All @@ -49,24 +47,24 @@ Note: Token cache performance was significantly improved in MSAL 4.30.0.

## Custom Cache Serialization

If your service is multi-tenant (i.e. it needs tokens for a resource that is in different tenants), see [MSAL for client credential flow in multi-tenant services](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Multi-tenant-client_credential-use).
If your service is multi-tenant (i.e. it needs tokens for a resource that is in different tenants), see [MSAL for client credential flow in multi-tenant services](../../advanced/client-credential-multi-tenant.md).

You can serialize the token cache to a location of your choice for example in-memory or in distributed location like Redis. You would do this to:

- share the token cache between several instances of `ConfidentialClientApplication` OR
- share the token cache between several instances of [`ConfidentialClientApplication`](xref:Microsoft.Identity.Client.ConfidentialClientApplication) OR
- persist the token cache to Redis to share it between different machines

Please see [distributed cache implementations](https://github.com/AzureAD/microsoft-identity-web/tree/master/src/Microsoft.Identity.Web.TokenCache/Distributed) and [binding the token cache](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/token-cache-serialization#token-cache-for-a-daemon-app).
Please see [distributed cache implementations](https://github.com/AzureAD/microsoft-identity-web/tree/master/src/Microsoft.Identity.Web.TokenCache/Distributed) and [binding the token cache](/azure/active-directory/develop/msal-net-token-cache-serialization).

This [sample](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/blob/b48c10180665260a1aec78a9acf7d1b1ff97e5ba/ConfidentialClientTokenCache/Program.cs) shows token cache serialization.
Check our [sample](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/blob/b48c10180665260a1aec78a9acf7d1b1ff97e5ba/ConfidentialClientTokenCache/Program.cs) to see how token cache serialization works.

## High Availability

**Problem:**
My service is running out of memory.

**Solution:**
See [MSAL for client credential flow in multi-tenant services](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Multi-tenant-client_credential-use).
See [MSAL for client credential flow in multi-tenant services](../../advanced/client-credential-multi-tenant.md).
Provision enough RAM on the machines running your service or use a distributed cache.
A single token is a only a few KB in size, but there is 1 token for each tenant! A multi-tenant service sometimes needs tokens for 0.5M tenants.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: "How to use MSAL.NET to authenticate on behalf of a user."

## If you are using ASP.NET Core

If you are building a web API on top of ASP.NET Core or ASP.NET Classic, we recommend that you use Microsoft.Identity.Web. See [Web APIs with Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web/wiki/web-apis).
If you are building a web API on top of ASP.NET Core or ASP.NET Classic, we recommend that you use `Microsoft.Identity.Web`. See [Web APIs with `Microsoft.Identity.Web`](https://github.com/AzureAD/microsoft-identity-web/wiki/web-apis).

Check the decision tree: [Is MSAL.NET right for me?](/entra/msal/dotnet/getting-started/choosing-msal-dotnet)

Expand All @@ -26,9 +26,9 @@ This flow, named the On-Behalf-Of flow (OBO), is illustrated by the top part of

The OBO call is done by calling the <xref:Microsoft.Identity.Client.IConfidentialClientApplication.AcquireTokenOnBehalfOf(System.Collections.Generic.IEnumerable{System.String},Microsoft.Identity.Client.UserAssertion)> method on the `IConfidentialClientApplication` interface.

This call looks in the cache by itself - so you do not need to call `AcquireTokenSilent` and does not store refresh tokens.
This call looks in the cache by itself - so you do not need to call `AcquireTokenSilent` and does not store refresh tokens.

For scenarios where continuous access is needed without an assertion, see [OBO for long lived processes](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/on-behalf-of#long-running-obo-processes)
For scenarios where continuous access is needed without an assertion, see [OBO for long lived processes](../web-apps-apis/on-behalf-of-flow.md)

> **Note:** Make sure to pass an access token, not an ID token, into the `AcquireTokenOnBehalfOf` method. The purpose of an ID token is as a confirmation that a user was authenticated and it contains some user-related information. While an access token determines whether a user has access to a resource, which is more appropriate in this On-Behalf-Of scenario. MSAL is focused on getting good access tokens. ID tokens are also obtained and cached but their expiry is not tracked. So it's possible for an ID token to expire and `AcquireTokenSilent` will not refresh it.
Expand Down Expand Up @@ -132,11 +132,11 @@ Pass the `sessionKey` which is associated with the current user's session and wi

It is strongly recommended to [use a distributed persisted cache](/azure/active-directory/develop/msal-net-token-cache-serialization?tabs=aspnetcore) in a web API scenario. Since these APIs store the refresh token, MSAL will not suggest an expiration, as refresh tokens have a long lifetime and can be used over and over again.

It is recommended that you set L1 and L2 eviction policies manually, for example a max size for the L1 cache and a sliding expiration for the L2.
It is recommended that you set L1 and L2 eviction policies manually, for example a max size for the L1 cache and a sliding expiration for the L2.

### Exception handling

In a case when `AcquireTokenInLongRunningProcess` throws an exception when it cannot find a token and the L2 cache has a cache entry for the same cache key, verify that the L2 cache read operation completed successfully. `AcquireTokenInLongRunningProcess` is different from the `InitiateLongRunningProcessInWebApi` and `AcquireTokenOnBehalfOf`, in that it is if the cache read fails, this method is unable to acquire a new token from Azure AD because it does not have an original user assertion. If using Microsoft.Identity.Web.TokenCache to enable distributed cache, set [OnL2CacheFailure](https://github.com/AzureAD/microsoft-identity-web/wiki/Token-Cache-Troubleshooting#i-configured-a-distributed-l2-cache-but-nothings-gets-written-to-it) event to retry the L2 call and/or add extra logs, which can be enabled [like this](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Logging#logging-in-a-distributed-token-cache).
In a case when `AcquireTokenInLongRunningProcess` throws an exception when it cannot find a token and the L2 cache has a cache entry for the same cache key, verify that the L2 cache read operation completed successfully. `AcquireTokenInLongRunningProcess` is different from the `InitiateLongRunningProcessInWebApi` and `AcquireTokenOnBehalfOf`, in that it is if the cache read fails, this method is unable to acquire a new token from Azure AD because it does not have an original user assertion. If using Microsoft.Identity.Web.TokenCache to enable distributed cache, set [OnL2CacheFailure](https://github.com/AzureAD/microsoft-identity-web/wiki/Token-Cache-Troubleshooting#i-configured-a-distributed-l2-cache-but-nothings-gets-written-to-it) event to retry the L2 call and/or add extra logs, which can be enabled [through built-in MSAL functionality](../../advanced/exceptions/msal-logging.md).

### Removing accounts

Expand All @@ -150,7 +150,7 @@ Starting with MSAL 4.51.0, to remove cached tokens call `StopLongRunningProcessI

## Practical usage of OBO in an ASP.NET / ASP.NET Core application

If you are building a web API on to of ASP.NET Core, we recommend that you use Microsoft.Identity.Web. See [Web APIs with Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web/wiki/web-apis).
If you are building a web API on to of ASP.NET Core, we recommend that you use `Microsoft.Identity.Web`. See [Web APIs with `Microsoft.Identity.Web`](https://github.com/AzureAD/microsoft-identity-web/wiki/web-apis).

In an ASP.NET / ASP.NET Core Web API, OBO is typically called on the `OnTokenValidated` event of the `JwtBearerOptions`. The token is then not used immediately, but this call has the effect of populating the user token cache. Later, the controllers will call `AcquireTokenSilent`, which will have the effect of hitting the cache, refreshing the access token if needed, or getting a new one for a new resource, but for still for the same user.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,13 @@ description: Learn Microsoft's Advanced Client Credential Multi-Tenant with MSAL

## Decision point - Microsoft.Identity.Web or Microsoft.Identity.Client (MSAL)?

If you use ASP.NET Core, you are encouraged to adopt [Microsoft.Indentity.Web](https://github.com/AzureAD/microsoft-identity-web/wiki), which provides a higher level API over token acquisition and has better defaults. See [Is MSAL.NET right for me?](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Is-MSAL.NET-right-for-me%3F)
If you use ASP.NET Core, you are encouraged to adopt [`Microsoft.Indentity.Web`](https://github.com/AzureAD/microsoft-identity-web/wiki), which provides a higher level API over token acquisition and has better defaults. See [Is MSAL.NET right for me?](../getting-started/choosing-msal-dotnet.md)

## Decision point - token caching

MSAL maintains a token cache which grows with each token acquired. MSAL manages token lifetimes in a smart way, so you should use its cache. You have the option of using in-memory caching or distributed caching.

See [MSAL.NET Token Cache Serialization](/azure/active-directory/develop/msal-net-token-cache-serialization?tabs=aspnet).
See [MSAL.NET Token Cache Serialization](/azure/active-directory/develop/msal-net-token-cache-serialization).

We recommend using persisted distributed caches (e.g. Redis, Cosmos etc.) for all user flows.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,5 +19,5 @@ This is a conditional access policy applied by the tenant admin. For details see
To satisfy this requirement you will have to leverage WAM on Windows or the system browser (Edge on Chromium). On mobile platform, you'll need to enable the brokers (Microsoft Authenticator and Company portal)

- If you are writing a desktop application running on Windows, see [WAM integration for Desktop applications](../../acquiring-tokens/desktop-mobile/wam.md).
- [On iOS and Android](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Xamarin-Docs), just [enable the broker](/azure/active-directory/develop/msal-net-use-brokers-with-xamarin-apps)
- The same principles apply to Web Applications, though given you are in a browser you must leverage a browser which can "talk to" WAM (that is either Edge on Chromium or Chrome with the Azure AD extensions. For details see [Conditional access conditions](/azure/active-directory/conditional-access/concept-conditional-access-conditions#chrome-support).
- [On iOS and Android](../../acquiring-tokens/desktop-mobile/xamarin.md), we recommend [enabling the authentication broker](/azure/active-directory/develop/msal-net-use-brokers-with-xamarin-apps)
- The same principles apply to Web Applications, though given you are in a browser you must leverage a browser which can "talk to" WAM (that is either Edge on Chromium or Chrome with the Azure AD extensions). For details see [Conditional access conditions](/azure/active-directory/conditional-access/concept-conditional-access-conditions#chrome-support).
4 changes: 2 additions & 2 deletions msal-dotnet-articles/advanced/exceptions/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ MSAL throws `MsalClientException` for things that go wrong inside the library (e

When calling `AcquireTokenInteractive`, a browser or the broker is invoked to handle user interaction. If the user closes this process or if they hit the browser back button, MSAL generates an `MsalClientException` with the error code `authentication_canceled` (`MsalError.AuthenticationCanceledError`).

On Android, this exception can also occur if a [browser with tabs](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Android-system-browser#known-issues) is not available.
On Android, this exception can also occur if a [browser with tabs](/azure/active-directory/develop/msal-net-system-browser-android-considerations) is not available.

2. HTTP Exceptions

Expand Down Expand Up @@ -63,4 +63,4 @@ To handle the claim challenge, you will need to use the `.WithClaims(claims)` me

### Retry policies

See [Retry-Policy](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Retry-Policy)
See [Retry-Policy](../exceptions/retry-policy.md)
3 changes: 0 additions & 3 deletions msal-dotnet-articles/advanced/exceptions/msal-logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,9 +121,6 @@ Using `MyIdentityLogger`:
.Build();
```

> [!TIP]
> See the [MSAL.NET wiki](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki) for samples of MSAL.NET logging and more.
## Next steps

For more code samples, refer to [Microsoft identity platform code samples](/azure/active-directory/develop/sample-v2-code).
Loading

0 comments on commit a2afa53

Please sign in to comment.