Skip to content

Commit dd3105c

Browse files
authored
Merge pull request #182777 from MicrosoftDocs/master
Merge master to live, 4 AM
2 parents ee9bae3 + f27f001 commit dd3105c

File tree

110 files changed

+1966
-705
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

110 files changed

+1966
-705
lines changed

.github/workflows/stale.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@ jobs:
1919
close-pr-label: auto-close
2020
exempt-pr-labels: keep-open
2121
operations-per-run: 1200
22-
ascending: true
23-
start-date: '2021-03-19'
22+
ascending: false
23+
# start-date: '2021-03-19'
2424
stale-pr-message: >
2525
This pull request has been inactive for at least 14 days.
2626
If you are finished with your changes, don't forget to sign off. See the [contributor guide](https://review.docs.microsoft.com/help/contribute/contribute-how-to-write-pull-request-automation) for instructions.

articles/active-directory/authentication/fido2-compatibility.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ This table shows support for authenticating Azure Active Directory (Azure AD) an
3434

3535
## Unsupported browsers
3636

37-
The following operating system and browser combinations are not supported, but future support and testing is being investigated. If you would like to see other operating system and browser support, please leave feedback using the product feedback tool at the bottom of the page.
37+
The following operating system and browser combinations are not supported, but future support and testing is being investigated. If you would like to see other operating system and browser support, please leave feedback on our [product feedback site](https://feedback.azure.com/d365community/).
3838

3939
| Operating system | Browser |
4040
| ---- | ---- |

articles/active-directory/develop/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,8 @@
157157
- name: App security
158158
displayName: least privilege, secure app configuration, conditional access
159159
items:
160+
- name: Zero trust best practices for app developers
161+
href: zero-trust-for-developers.md
160162
- name: Best practices for least privileged access for apps
161163
href: secure-least-privileged-access.md
162164
- name: Security best practices for Azure AD application registration

articles/active-directory/develop/active-directory-optional-claims.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,15 +50,15 @@ The set of optional claims available by default for applications to use are list
5050
| `acct` | Users account status in tenant | JWT, SAML | | If the user is a member of the tenant, the value is `0`. If they are a guest, the value is `1`. |
5151
| `auth_time` | Time when the user last authenticated. See OpenID Connect spec.| JWT | | |
5252
| `ctry` | User's country/region | JWT | | Azure AD returns the `ctry` optional claim if it's present and the value of the field is a standard two-letter country/region code, such as FR, JP, SZ, and so on. |
53-
| `email` | The reported email address for this user | JWT, SAML | MSA, Azure AD | This value is included by default if the user is a guest in the tenant. For managed users (the users inside the tenant), it must be requested through this optional claim or, on v2.0 only, with the OpenID scope. This value is not guaranteed to be correct, and is mutable over time - never use it for authorization or to save data for a user, only use the object ID or subject claims. If you require an addressable email address in your app, request this data from the user directly, using this claim as a suggestion or pre-fill in your UX. |
53+
| `email` | The reported email address for this user | JWT, SAML | MSA, Azure AD | This value is included by default if the user is a guest in the tenant. For managed users (the users inside the tenant), it must be requested through this optional claim or, on v2.0 only, with the OpenID scope. This value is not guaranteed to be correct, and is mutable over time - never use it for authorization or to save data for a user. For more information, see [Validate the user has permission to access this data](access-tokens.md#validate-the-user-has-permission-to-access-this-data). If you require an addressable email address in your app, request this data from the user directly, using this claim as a suggestion or pre-fill in your UX. |
5454
| `fwd` | IP address.| JWT | | Adds the original IPv4 address of the requesting client (when inside a VNET) |
5555
| `groups`| Optional formatting for group claims |JWT, SAML| |Used with the GroupMembershipClaims setting in the [application manifest](reference-app-manifest.md), which must be set as well. For details see [Group claims](#configuring-groups-optional-claims) below. For more information about group claims, see [How to configure group claims](../hybrid/how-to-connect-fed-group-claims.md)
5656
| `idtyp` | Token type | JWT access tokens | Special: only in app-only access tokens | Value is `app` when the token is an app-only token. This is the most accurate way for an API to determine if a token is an app token or an app+user token.|
5757
| `login_hint` | Login hint | JWT | MSA, Azure AD | An opaque, reliable login hint claim. This claim is the best value to use for the `login_hint` OAuth parameter in all flows to get SSO. It can be passed between applications to help them silently SSO as well - application A can sign in a user, read the `login_hint` claim, and then send the claim and the current tenant context to application B in the query string or fragment when the user clicks on a link that takes them to application B. To avoid race conditions and reliability issues, the `login_hint` claim *doesn't* include the current tenant for the user, and defaults to the user's home tenant when used. If you are operating in a guest scenario, where the user is from another tenant, then you must still provide a tenant identifier in the sign in request, and pass the same to apps you partner with. This claim is intended for use with your SDK's existing `login_hint` functionality, however that it exposed. |
5858
| `sid` | Session ID, used for per-session user sign-out. | JWT | Personal and Azure AD accounts. | |
5959
| `tenant_ctry` | Resource tenant's country/region | JWT | | Same as `ctry` except set at a tenant level by an admin. Must also be a standard two-letter value. |
6060
| `tenant_region_scope` | Region of the resource tenant | JWT | | |
61-
| `upn` | UserPrincipalName | JWT, SAML | | An identifer for the user that can be used with the username_hint parameter. Not a durable identifier for the user and should not be used to uniquely identity user information (for example, as a database key). Instead, use the user object ID (`oid`) as a database key. Users signing in with an [alternate login ID](../authentication/howto-authentication-use-email-signin.md) should not be shown their User Principal Name (UPN). Instead, use the following ID token claims for displaying sign-in state to the user: `preferred_username` or `unique_name` for v1 tokens and `preferred_username` for v2 tokens. Although this claim is automatically included, you can specify it as an optional claim to attach additional properties to modify its behavior in the guest user case. You should use the `login_hint` claim for `login_hint` use - human-readable identifiers like UPN are unreliable.|
61+
| `upn` | UserPrincipalName | JWT, SAML | | An identifier for the user that can be used with the username_hint parameter. Not a durable identifier for the user and should not be used for authorization or to uniquely identity user information (for example, as a database key). Instead, use the user object ID (`oid`) as a database key. For more information, see [Validate the user has permission to access this data](access-tokens.md#validate-the-user-has-permission-to-access-this-data). Users signing in with an [alternate login ID](../authentication/howto-authentication-use-email-signin.md) should not be shown their User Principal Name (UPN). Instead, use the following ID token claims for displaying sign-in state to the user: `preferred_username` or `unique_name` for v1 tokens and `preferred_username` for v2 tokens. Although this claim is automatically included, you can specify it as an optional claim to attach additional properties to modify its behavior in the guest user case. You should use the `login_hint` claim for `login_hint` use - human-readable identifiers like UPN are unreliable.|
6262
| `verified_primary_email` | Sourced from the user's PrimaryAuthoritativeEmail | JWT | | |
6363
| `verified_secondary_email` | Sourced from the user's SecondaryAuthoritativeEmail | JWT | | |
6464
| `vnet` | VNET specifier information. | JWT | | |
@@ -82,7 +82,7 @@ These claims are always included in v1.0 Azure AD tokens, but not included in v2
8282
| `in_corp` | Inside Corporate Network | Signals if the client is logging in from the corporate network. If they're not, the claim isn't included. | Based off of the [trusted IPs](../authentication/howto-mfa-mfasettings.md#trusted-ips) settings in MFA. |
8383
| `family_name` | Last Name | Provides the last name, surname, or family name of the user as defined in the user object. <br>"family_name":"Miller" | Supported in MSA and Azure AD. Requires the `profile` scope. |
8484
| `given_name` | First name | Provides the first or "given" name of the user, as set on the user object.<br>"given_name": "Frank" | Supported in MSA and Azure AD. Requires the `profile` scope. |
85-
| `upn` | User Principal Name | An identifer for the user that can be used with the username_hint parameter. Not a durable identifier for the user and should not be used to uniquely identity user information (for example, as a database key). Instead, use the user object ID (`oid`) as a database key. Users signing in with an [alternate login ID](../authentication/howto-authentication-use-email-signin.md) should not be shown their User Principal Name (UPN). Instead, use the following `preferred_username` claim for displaying sign-in state to the user. | See [additional properties](#additional-properties-of-optional-claims) below for configuration of the claim. Requires the `profile` scope.|
85+
| `upn` | User Principal Name | An identifer for the user that can be used with the username_hint parameter. Not a durable identifier for the user and should not be used for authorization or to uniquely identity user information (for example, as a database key). For more information, see [Validate the user has permission to access this data](access-tokens.md#validate-the-user-has-permission-to-access-this-data). Instead, use the user object ID (`oid`) as a database key. Users signing in with an [alternate login ID](../authentication/howto-authentication-use-email-signin.md) should not be shown their User Principal Name (UPN). Instead, use the following `preferred_username` claim for displaying sign-in state to the user. | See [additional properties](#additional-properties-of-optional-claims) below for configuration of the claim. Requires the `profile` scope.|
8686

8787
## v1.0-specific optional claims set
8888

171 KB
Loading
Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: "Increase app security by following Zero Trust principles"
3+
titleSuffix: Microsoft identity platform
4+
description: Learn how following the Zero Trust principles can help increase the security of your application, its data, and which features of the Microsoft identity platform you can use to build Zero Trust-ready apps.
5+
services: active-directory
6+
author: chrischiedo
7+
manager: CelesteDG
8+
9+
ms.service: active-directory
10+
ms.subservice: develop
11+
ms.topic: conceptual
12+
ms.workload: identity
13+
ms.date: 12/02/2021
14+
ms.custom: template-concept
15+
ms.author: cchiedo
16+
ms.reviewer: nichola, arielsc, marsma
17+
18+
# Customer intent: As a developer, I want to learn about the Zero Trust principles and the features of the Microsoft identity platform that I can use to build applications that are Zero Trust-ready.
19+
---
20+
21+
# Build Zero Trust-ready apps using Microsoft identity platform features and tools
22+
23+
You can no longer assume a secure network perimeter around the applications you build. Nearly every app you build will, by design, be accessed from outside the network perimeter. You also can’t guarantee every app you build is secure or will remain so after it’s deployed.
24+
25+
Knowing this as the app developer, it's your responsibility to not only maximize your app’s security, but also minimize the damage your app can cause if it’s compromised.
26+
27+
Additionally, you are responsible for supporting the evolving needs of your customers and users, who will expect that your application meets their Zero Trust security requirements.
28+
29+
By learning the principles of the [Zero Trust model](https://www.microsoft.com/security/business/zero-trust?rtc=1) and adopting their practices, you can:
30+
- Build more secure apps
31+
- Minimize the damage your apps could cause if there is a breach
32+
33+
## Zero Trust principles
34+
35+
The Zero Trust model prescribes a culture of explicit verification rather than implicit trust. The model is anchored on three key [guiding principles](/security/zero-trust/#guiding-principles-of-zero-trust):
36+
- Verify explicitly
37+
- Use least privileged access
38+
- Assume breach
39+
40+
## Best practices for building Zero Trust-ready apps with the Microsoft identity platform
41+
42+
Follow these best practices to build Zero Trust-ready apps with the [Microsoft identity platform](./v2-overview.md) and its tools.
43+
44+
### Verify explicitly
45+
46+
The Microsoft identity platform offers authentication mechanisms for verifying the identity of the person or service accessing a resource. Apply the best practices described below to ensure that you *verify explicitly* any entities that need to access data or resources.
47+
48+
|Best practice |Benefits to app security |
49+
|----------------|---------------------------|
50+
|Use the [Microsoft Authentication Libraries](./reference-v2-libraries.md) (MSAL).|MSAL is a set of Microsoft’s authentication libraries for developers. With MSAL, you can authenticate users and applications, and acquire tokens to access corporate resources using just a few lines of code. MSAL uses modern protocols ([OpenID Connect and OAuth 2.0](./active-directory-v2-protocols.md)) that remove the need for apps to ever handle a user's credentials directly. This vastly improves the security for both users and applications as the identity provider becomes the security perimeter. Also, these protocols continuously evolve to address new paradigms, opportunities, and challenges in identity security.|
51+
|Adopt enhanced security extensions like [Continuous Access Evaluation](../conditional-access/concept-continuous-access-evaluation.md) (CAE) and Conditional Access authentication context when appropriate.|In Azure AD, some of the most used extensions include [Conditional Access](../conditional-access/overview.md) (CA), [Conditional Access authentication context](./developer-guide-conditional-access-authentication-context.md) and CAE. Applications that use enhanced security features like CAE and Conditional Access authentication context must be coded to handle claims challenges. Open protocols enable you to use the [claims challenges and claims requests](./claims-challenge.md) to invoke extra client capabilities. This might be to indicate to apps that they need to re-interact with Azure AD, like if there was an anomaly or if the user no longer satisfies the conditions under which they authenticated earlier. As a developer you can code for these extensions without disturbing their primary code flows for authentication.|
52+
|Use the correct **authentication flow** by [app type](./v2-app-types.md) for authentication. For web applications, you should always aim to use [confidential client flows](./authentication-flows-app-scenarios.md#single-page-public-client-and-confidential-client-applications). For mobile applications, you should use [brokers](./msal-android-single-sign-on.md#sso-through-brokered-authentication) or the [system browser](./msal-android-single-sign-on.md#sso-through-system-browser) for authentication. |The flows for web applications that can hold a secret (confidential clients) are considered more secure than public clients (for example: Desktop and Console apps). When you use the system web browser to authenticate your mobile apps, you get a secure [single sign-on](../manage-apps/what-is-single-sign-on.md) (SSO) experience that supports app protection policies.|
53+
54+
### Use least privileged access
55+
56+
Using the Microsoft identity platform, you can grant permissions (scopes) and verify that a caller has been granted proper permission before allowing access. You can enforce least privileged access in your apps by enabling fine-grained permissions that allow you to grant the smallest amount of access necessary. Follow the practices described below to ensure you adhere to the [principle of least privilege](/secure-least-privileged-access.md).
57+
58+
| Do | Don't |
59+
| ------------------------------------- | -------------- |
60+
| Evaluate the permissions you request to ensure that you seek the absolute least privileged set to get the job done. | Create "catch-all" permissions with access to the entire API surface. |
61+
| When designing APIs, provide granular permissions to allow least-privileged access. Start with dividing the functionality and data access into sections that can be controlled via [scopes](./v2-permissions-and-consent.md#scopes-and-permissions) and [App roles](./howto-add-app-roles-in-azure-ad-apps.md). | Add your APIs to existing permissions in a way that changes the semantics of the permission. |
62+
| Offer **read-only** permissions. "*Write* access", includes privileges for create, update, and delete operations. A client should never require write access to only read data | ----- |
63+
| Offer both [delegated and application](/graph/auth/auth-concepts#delegated-and-application-permissions) permissions. Skipping application permissions can create hard requirement for your clients to achieve common scenarios like automation, microservices and more. | ----- |
64+
| Consider "standard" and "full" access permissions if working with sensitive data. Restrict the sensitive properties so that they cannot be accessed using a "standard" access permission, for example *Resource.Read*. And then implement a "full" access permission, for example *Resource.ReadFull*, that returns all available properties including sensitive information.|----- |
65+
66+
67+
### Assume breach
68+
69+
The Microsoft identity platform app registration portal is the primary entry point for applications intending to use the platform for their authentication and associated needs. When registering and configuring your apps, follow the practices described below to minimize the damage your apps could cause if there is a security breach. For more guidance, check [Azure AD application registration security best practices](./security-best-practices-for-app-registration.md).
70+
71+
:::image type="content" source="./media/zero-trust-for-developers/app-registration-portal.png" alt-text="Azure portal screenshot showing an app registration pane":::
72+
73+
| Do | Don't |
74+
| ------------------------------------- | -------------- |
75+
| Properly define your redirect URLs | Use the same app registration for multiple apps |
76+
| Check redirect URIs used in your app registration for ownership and to avoid domain takeovers | Create your application as a multi-tenant unless you really intended to|
77+
| Ensure app and service principal owners are always defined and maintained for your apps registered in your tenant | ----- |
78+
79+
80+
## Next steps
81+
82+
- Zero Trust [Guidance Center](/security/zero-trust/)
83+
- Zero Trust for the Microsoft identity platform developer [whitepaper](https://www.microsoft.com/security/content-library/Search?SearchDataFor=OJZgGWbHnB3Ll5hblDBugaEMQAchNfvkzk5X5AmPM4tK43NHpbF5%2Bky%2Fnuivl7plZz89b%2FuLMMZsMqKeYbhPPw%3D%3D&IsKeywordSearch=evXIpssXVY6lIm6X2K9ieA%3D%3D) (downloadable PDF).
84+
- Microsoft identity platform [best practices and recommendations](./identity-platform-integration-checklist.md).

articles/active-directory/devices/howto-vm-sign-in-azure-ad-linux.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,7 @@ The following example uses [az role assignment create](/cli/azure/role/assignmen
209209

210210
```azurecli-interactive
211211
username=$(az account show --query user.name --output tsv)
212-
vm=$(az vm show --resource-group AzureADLinuxVMPreview --name myVM --query id -o tsv)
212+
vm=$(az vm show --resource-group AzureADLinuxVM --name myVM --query id -o tsv)
213213
214214
az role assignment create \
215215
--role "Virtual Machine Administrator Login" \

0 commit comments

Comments
 (0)