You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Integrate with Microsoft identity platform | Azure
3
-
description: Learn about best practicesand common oversights when integrating with the Microsoft identity platform (v2.0).
2
+
title: Best practices for Microsoft identity platform | Azure
3
+
description: Learn about best practices, recommendations, and common oversights when integrating with the Microsoft identity platform.
4
4
services: active-directory
5
5
documentationcenter: ''
6
6
author: rwike77
@@ -13,69 +13,70 @@ ms.devlang: na
13
13
ms.topic: conceptual
14
14
ms.tgt_pltfrm: na
15
15
ms.workload: identity
16
-
ms.date: 05/07/2019
16
+
ms.date: 09/11/2019
17
17
ms.author: ryanwi
18
18
ms.reviewer: lenalepa, sureshja, jesakowi
19
19
ms.custom: aaddev, identityplatformtop40
20
-
#Customer intent: As an application developer, I want to learn about security best practices so I can integrate my application with Microsoft identity platform.
20
+
#Customer intent: As an application developer, I want to learn about best practices so I can integrate my application with the Microsoft identity platform.
21
21
---
22
22
23
-
# Microsoft identity platform integration checklist
23
+
# Microsoft identity platform best practices and recommendations
24
24
25
-
The Microsoft identity platform integration checklist is intended to guide you to a high-quality and secure integration. It highlights best practices and common oversights when integrating with the Microsoft identity platform so review the list on a regular basis to make sure you maintain the quality and security of your app’s integration with the identity platform. The checklist isn't intended to review your entire application. The contents of the checklist are subject to change as we make improvements to the platform.
25
+
This article highlights best practices, recommendations, and common oversights when integrating with the Microsoft identity platform. This checklist will guide you to a high-quality and secure integration. Review this list on a regular basis to make sure you maintain the quality and security of your app’s integration with the identity platform. The checklist isn't intended to review your entire application. The contents of the checklist are subject to change as we make improvements to the platform.
26
26
27
-
If you’re just getting started, check out the [documentation](index.yml) to learn about authentication basics, application scenarios in Microsoft identity platform, and more.
28
-
29
-
## Testing your integration
27
+
If you’re just getting started, check out the [Microsoft identity platform documentation](index.yml) to learn about authentication basics, application scenarios in the Microsoft identity platform, and more.
30
28
31
29
Use the following checklist to ensure that your application is effectively integrated with the [Microsoft identity platform](https://docs.microsoft.com/azure/active-directory/develop/).
32
30
33
-
###Basics
31
+
## Basics
34
32
35
33
|||
36
34
|---|---|
37
35
|| Read and understand the [Microsoft Platform Policies](https://go.microsoft.com/fwlink/?linkid=2090497&clcid=0x409). Ensure that your application adheres to the terms outlined as they're designed to protect users and the platform. |
38
36
39
-
###Ownership
37
+
## Ownership
40
38
41
39
|||
42
40
|---|---|
43
41
|| Make sure the information associated with the account you used to register and manage apps is up-to-date. |
44
42
45
-
###Branding
43
+
## Branding
46
44
47
45
|||
48
46
|---|---|
49
47
|| Adhere to the [Branding guidelines for applications](howto-add-branding-in-azure-ad-apps.md). |
50
-
|| Provide a meaningful name and logo for your application. This information appears on your application’s consent prompt. Make sure your name and logo are representative of your company/product so that users can make informed decisions. Ensure that you're not violating any trademarks. |
48
+
|| Provide a meaningful name and logo for your application. This information appears on your [application’s consent prompt](application-consent-experience.md). Make sure your name and logo are representative of your company/product so that users can make informed decisions. Ensure that you're not violating any trademarks. |
51
49
52
-
###Privacy
50
+
## Privacy
53
51
54
52
|||
55
53
|---|---|
56
54
|| Provide links to your app's terms of service and privacy statement. |
57
55
58
-
###Security
56
+
## Security
59
57
60
58
|||
61
59
|---|---|
62
-
|| Maintain ownership of all your redirect URIs and keep the DNS records for them up-to-date.Don't use wildcards (*) in your URIs.For web apps, make sure all URIs are secure and encrypted (for example, using https schemes).For public clients, use platform-specific redirect URIs if applicable (mainly for iOS and Android). Otherwise, use redirect URIs with a high amount of randomness to prevent collisions when calling back to your app.If your app is being used from an isolated web agent, you may use https://login.microsoftonline.com/nativeclient.Review and trim all unused or unnecessary redirect URIs on a regular basis. |
60
+
||Manage your redirect URIs: <ul><li>Maintain ownership of all your redirect URIs and keep the DNS records for them up-to-date.</li><li>Don't use wildcards (*) in your URIs.</li><li>For web apps, make sure all URIs are secure and encrypted (for example, using https schemes).</li><li>For public clients, use platform-specific redirect URIs if applicable (mainly for iOS and Android). Otherwise, use redirect URIs with a high amount of randomness to prevent collisions when calling back to your app.</li><li>If your app is being used from an isolated web agent, you may use https://login.microsoftonline.com/common/oauth2/nativeclient.</li><li>Review and trim all unused or unnecessary redirect URIs on a regular basis.</li></ul>|
63
61
|| If your app is registered in a directory, minimize and manually monitor the list of app registration owners. |
64
62
|| Don't enable support for the [OAuth2 implicit grant flow](v2-oauth2-implicit-grant-flow.md) unless explicitly required. Learn about the valid scenario [here](v1-oauth2-implicit-grant-flow.md#suitable-scenarios-for-the-oauth2-implicit-grant). |
65
-
|| Don't use [resource owner password credential flow (ROPC)](v2-oauth-ropc.md), which directly handles users’ passwords. This flow requires a high degree of trust and user exposure and should only be used when other, more secure, flows can't be used. |
66
-
|| Protect and manage your app credentials. Use [certificate credentials](active-directory-certificate-credentials.md), not password credentials (client secrets). If you must use a password credential, don't set it manually. Don't store credentials in code or config, and never allow them to be handled by humans. If possible, use [managed identities for Azure resources](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview) or [Azure Key Vault](https://docs.microsoft.com/azure/key-vault/key-vault-overview) to store and regularly rotate your credentials. |
67
-
|| Make sure your application requests the least privilege permissions. Only ask for permissions that your application absolutely needs, and only when you need them. Understand the different [types of permissions](v1-permissions-and-consent.md#types-of-permissions). Only use application permissions if required; use delegated permissions where possible. For a full list of Microsoft Graph permissions, see this [permissions reference](https://docs.microsoft.com/graph/permissions-reference). |
63
+
||Move beyond username/password. Don't use [resource owner password credential flow (ROPC)](v2-oauth-ropc.md), which directly handles users’ passwords. This flow requires a high degree of trust and user exposure and should only be used when other, more secure, flows can't be used. This flow is still needed in some scenarios (like DevOps), but beware that using it will impose constraints on your application. For more modern approaches, read [Authentication flows and application scenarios](authentication-flows-app-scenarios.md).|
64
+
|| Protect and manage your confidential app credentials for web apps, web APIs and daemon apps. Use [certificate credentials](active-directory-certificate-credentials.md), not password credentials (client secrets). If you must use a password credential, don't set it manually. Don't store credentials in code or config, and never allow them to be handled by humans. If possible, use [managed identities for Azure resources](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview) or [Azure Key Vault](https://docs.microsoft.com/azure/key-vault/key-vault-whatis) to store and regularly rotate your credentials. |
65
+
|| Make sure your application requests the least privilege permissions. Only ask for permissions that your application absolutely needs, and only when you need them. Understand the different [types of permissions](v1-permissions-and-consent.md#types-of-permissions). Only use application permissions if necessary; use delegated permissions where possible. For a full list of Microsoft Graph permissions, see this [permissions reference](https://docs.microsoft.com/graph/permissions-reference). |
68
66
|| If you're securing an API using the Microsoft identity platform, carefully think through the permissions it should expose. Consider what's the right granularity for your solution and which permission(s) require admin consent. Check for expected permissions in the incoming tokens before making any authorization decisions. |
69
67
70
-
###Implementation
68
+
## Implementation
71
69
72
70
|||
73
71
|---|---|
74
72
|| Use modern authentication solutions (OAuth 2.0, [OpenID Connect](v2-protocols-oidc.md)) to securely sign in users. |
75
-
|| Don’t implement the protocols yourself – use [Microsoft-supported authentication libraries](reference-v2-libraries.md) (MSAL, server middleware). Make sure you're using the latest version of the authentication library that you've integrated with. |
73
+
|  | Don't program directly against protocols such as OAuth 2.0 and Open ID. Instead, leverage the [Microsoft Authentication Library (MSAL)](msal-overview.md). The MSAL libraries securely wrap security protocols in an easy-to-use library, and you get built-in support for [Conditional Access](/azure/active-directory/conditional-access/overview) scenarios, device-wide [single sign-on (SSO)](/azure/active-directory/manage-apps/what-is-single-sign-on), and built-in token caching support. For more info, see the list of Microsoft supported [client libraries](reference-v2-libraries.md#microsoft-supported-client-libraries) and [middleware libraries](reference-v2-libraries.md#microsoft-supported-server-middleware-libraries) and the list of [compatible third-party client libraries](reference-v2-libraries.md#compatible-client-libraries).<br/><br/>If you must hand code for the authentication protocols, you should follow a methodology such as [Microsoft SDL](https://www.microsoft.com/sdl/default.aspx). Pay close attention to the security considerations in the standards specifications for each protocol.|
74
+
|| Migrate existing apps from [Azure Active Directory Authentication Library (ADAL)](active-directory-authentication-libraries.md) to [Microsoft Authentication Library](msal-overview.md). MSAL is Microsoft’s latest identity platform solution and is preferred to ADAL. It is available on .NET and JavaScript and is also in public preview for Android, iOS, Python, and Java. Read more about migrating [ADAL.NET](msal-net-migration.md), [ADAL.js](msal-compare-msal-js-and-adal-js.md), and [ADAL.NET and iOS broker](msal-net-migration-ios-broker.md) apps.|
75
+
|| For mobile apps, configure each platform using the application registration experience. In order for your application to take advantage of the Microsoft Authenticator or Microsoft Company Portal for single sign-in, your app needs a “broker redirect URI” configured. This allows Microsoft to return control to your application after authentication. When configuring each platform, the app registration experience will guide you through the process. Use the quickstart to download a working example. On iOS, use brokers and system webview whenever possible.|
76
+
|| In web apps or web APIs, keep one token cache per account. For web apps, the token cache should be keyed by the account ID. For web APIs, the account should be keyed by the hash of the token used to call the API. MSAL.NET provides custom token cache serialization in the .NET Framework and .NET Core subplatforms. For security and performance reasons, our recommendation is to serialize one cache per user. For more information, read about [token cache serialization](msal-net-token-cache-serialization.md#token-cache-for-a-web-app-confidential-client-application).|
76
77
|| If the data your app requires is available through [Microsoft Graph](https://developer.microsoft.com/graph), request permissions for this data using the Microsoft Graph endpoint rather than the individual API. |
77
78
78
-
###End-user experience
79
+
## End-user experience
79
80
80
81
|||
81
82
|---|---|
@@ -86,7 +87,7 @@ Use the following checklist to ensure that your application is effectively integ
86
87
|| Register the full set of permissions that your app requires so admins can grant consent easily to their tenant. Use [incremental consent](azure-ad-endpoint-comparison.md#incremental-and-dynamic-consent) at run time to help users understand why your app is requesting permissions that may concern or confuse users when requested on first start. |
87
88
|| Implement a [clean single sign-out experience](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/1-WebApp-OIDC/1-6-SignOut). It’s a privacy and a security requirement, and makes for a good user experience. |
88
89
89
-
###Testing
90
+
## Testing
90
91
91
92
|||
92
93
|---|---|
@@ -102,5 +103,5 @@ Explore in-depth information about v2.0:
Copy file name to clipboardExpand all lines: articles/active-directory/develop/msal-net-token-cache-serialization.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,7 +13,7 @@ ms.devlang: na
13
13
ms.topic: conceptual
14
14
ms.tgt_pltfrm: na
15
15
ms.workload: identity
16
-
ms.date: 07/16/2019
16
+
ms.date: 09/16/2019
17
17
ms.author: jmprieur
18
18
ms.reviewer: saeeda
19
19
ms.custom: aaddev
@@ -272,7 +272,7 @@ namespace CommonCacheMsalV3
272
272
273
273
In web apps or web APIs the cache could leverage the session, a Redis cache, or a database.
274
274
275
-
An important thing to remember is that for web apps and web APIs, there should be one token cache per user (per account). You need to serialize the token cache for each account.
275
+
In web apps or web APIs, keep one token cache per account. For web apps, the token cache should be keyed by the account ID. For web APIs, the account should be keyed by the hash of the token used to call the API. MSAL.NET provides custom token cache serialization in .NET Framework and .NET Core subplatforms. Events are fired when the cache is accessed, apps can choose whether to serialize or deserialize the cache. On confidential client applications that handle users (web apps that sign in users and call web APIs, and web APIs calling downstream web APIs), there can be many users and the users are processed in parallel. For security and performance reasons, our recommendation is to serialize one cache per user. Serialization events compute a cache key based on the identity of the processed user and serialize/deserialie a token cache for that user.
276
276
277
277
Examples of how to use token caches for web apps and web APIs are available in the [ASP.NET Core web app tutorial](https://ms-identity-aspnetcore-webapp-tutorial) in the phase [2-2 Token Cache](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/2-WebApp-graph-user/2-2-TokenCache). For implementations have a look at the following folder [TokenCacheProviders](https://github.com/AzureAD/microsoft-authentication-extensions-for-dotnet/tree/master/src/Microsoft.Identity.Client.Extensions.Web/TokenCacheProviders) in the [microsoft-authentication-extensions-for-dotnet](https://github.com/AzureAD/microsoft-authentication-extensions-for-dotnet) library (in the [Microsoft.Identity.Client.Extensions.Web](https://github.com/AzureAD/microsoft-authentication-extensions-for-dotnet/tree/master/src/Microsoft.Identity.Client.Extensions.Web) folder.
0 commit comments