Merge pull request #230846 from MicrosoftDocs/main

3/15 AM Publish

Author: huypub

articles/active-directory/app-provisioning/use-scim-to-provision-users-and-groups.md

@@ -8,7 +8,7 @@ ms.service: active-directory
 ms.subservice: app-provisioning
 ms.workload: identity
 ms.topic: tutorial
-ms.date: 03/14/2023
+ms.date: 03/15/2023
 ms.author: kenwith
 ms.reviewer: arvinh
 ---
@@ -1202,7 +1202,7 @@ In the example of a request, to retrieve the current state of a user, the values
 
 ***Example 4. Query the value of a reference attribute to be updated*** 
 
-If a reference attribute is to be updated, then Azure AD queries the service to determine whether the current value of the reference attribute in the identity store fronted by the service already matches the value of that attribute in Azure AD. For users, the only attribute of which the current value is queried in this way is the manager attribute. Here's an example of a request to determine whether the manager attribute of a user object currently has a certain value: 
+Azure AD checks the current attribute value in the identity store before updating it. However, only the manager attribute is the checked first for users. Here's an example of a request to determine whether the manager attribute of a user object currently has a certain value: 
 In the sample code, the request is translated into a call to the QueryAsync method of the service’s provider. The value of the properties of the object provided as the value of the parameters argument are as follows: 
 
 * parameters.AlternateFilters.Count: 2
@@ -1304,7 +1304,7 @@ Check with your application provider, or your application provider's documentati
 
 ### Getting started
 
-Applications that support the SCIM profile described in this article can be connected to Azure AD using the "non-gallery application" feature in the Azure AD application gallery. Once connected, Azure AD runs a synchronization process every 40 minutes where it queries the application's SCIM endpoint for assigned users and groups, and creates or modifies them according to the assignment details.
+Applications that support the SCIM profile described in this article can be connected to Azure AD using the "non-gallery application" feature in the Azure AD application gallery. Once connected, Azure AD runs a synchronization process. The process runs every 40 minutes. The process queries the application's SCIM endpoint for assigned users and groups, and creates or modifies them according to the assignment details.
 
 **To connect an application that supports SCIM:**
 
@@ -1398,7 +1398,7 @@ The provisioning service supports the [authorization code grant](https://tools.i
 > [!NOTE]
 > OAuth v1 is not supported due to exposure of the client secret. OAuth v2 is supported.  
 
-It is recommended, but not required, that you support multiple secrets for easy renewal without downtime.
+It's recommended, but not required, that you support multiple secrets for easy renewal without downtime.
 
 #### How to set up OAuth code grant flow
 

articles/active-directory/develop/TOC.yml

@@ -37,6 +37,8 @@
           href: permissions-consent-overview.md
         - name: Delegated access
           href: delegated-access-primer.md
+        - name: App-only access
+          href: app-only-access-primer.md
         - name: Scopes and permissions
           href: scopes-oidc.md
         - name: "Authorization options: ACLs, RBAC, ABAC"

articles/active-directory/develop/app-only-access-primer.md

@@ -0,0 +1,88 @@
+---
+title: Microsoft identity platform app-only access scenario
+description: Learn about when and how to use app-only access in the Microsoft identity platform endpoint.
+services: active-directory
+author: omondiatieno
+manager: celesteDG
+ms.service: active-directory
+ms.subservice: develop
+ms.workload: identity
+ms.topic: conceptual
+ms.date: 03/15/2023
+ms.author: jomondi
+ms.reviewer: jawoods, ludwignick, phsignor
+
+---
+
+# Understanding application-only access
+
+When an application directly accesses a resource, like Microsoft Graph, its access isn't limited to the files or operations available to any single user. The app calls APIs directly using its own identity, and a user or app with admin rights must authorize it to access the resources. This scenario is application-only access.
+
+> [!VIDEO https://www.youtube.com/embed/6R3W9T01gdE]
+
+## When should I use application-only access?
+
+In most cases, application-only access is broader and more powerful than [delegated access](delegated-access-primer.md), so you should only use app-only access where needed. It’s usually the right choice if:
+
+- The application needs to run in an automated way, without user input. For example, a daily script that checks emails from certain contacts and sends automated responses.
+- The application needs to access resources belonging to multiple different users. For example, a backup or data loss prevention app might need to retrieve messages from many different chat channels, each with different participants.
+- You find yourself tempted to store credentials locally and allow the app to sign in "as" the user or admin.
+
+In contrast, you should never use application-only access where a user would normally sign in to manage their own resources. These types of scenarios must use delegated access to be least privileged.
+
+![Diagram shows illustration of application permissions vs delegated permissions.](./media/permissions-consent-overview/delegated-app-only-permissions.png)
+
+
+
+## Authorizing an app to make application-only calls
+
+To make app-only calls, you need to assign your client app the appropriate app roles. App roles are also referred to as application-only permissions. They're *app* roles because they grant access only in the context of the resource app that defines the role.
+
+For example, to read a list of all teams created in an organization, you need to assign your application the Microsoft Graph `Team.ReadBasic.All` app role. This app role grants the ability to read this data when Microsoft Graph is the resource app. This assignment doesn't assign your client application to a Teams role that might allow it to view this data through other services.
+
+As a developer, you need to configure all required app-only permissions, also referred to as app roles on your application registration. You can configure your app's requested app-only permissions through the Azure portal or Microsoft Graph. App-only access doesn't support dynamic consent, so you can't request individual permissions or sets of permissions at runtime.
+
+Once you've configured all the permissions your app needs, it must get admin consent [admin consent](../manage-apps/grant-admin-consent.md) for it to access the resources. For example, only users with the global admin role can grant app-only permissions (app roles) for the Microsoft Graph API. Users with other admin roles, like application admin and cloud app admin, are able to grant app-only permissions for other resources. 
+
+Admin users can grant app-only permissions by using the Azure portal or by creating grants programmatically through the Microsoft Graph API. You can also prompt for interactive consent from within your app, but this option isn't preferable since app-only access doesn't require a user.
+
+Consumer users with Microsoft Accounts, like Outlook.com or Xbox Live accounts, can never authorize application-only access.
+Always follow the principle of least privilege: you should never request app roles that your app doesn’t need. This principle helps limit the security risk if your app is compromised and makes it easier for administrators to grant your app access. For example, if your app-only needs to identify users without reading their detailed profile information, you should request the more limited Microsoft Graph `User.ReadBasic.All` app role instead of `User.Read.All`.
+ 
+## Designing and publishing app roles for a resource service
+
+If you're building a service on Azure AD that exposes APIs for other clients to call, you may wish to support automated access with app roles (app-only permissions). You can define the app roles for your application in the **App roles** section of your app registration in Azure AD portal. For more information on how to create app roles, see [Declare roles for an application](howto-add-app-roles-in-azure-ad-apps.md#declare-roles-for-an-application).
+
+When exposing app roles for others to use, provide clear descriptions of the scenario to the admin who is going to assign them. App roles should generally be as narrow as possible and support specific functional scenarios, since app-only access isn't constrained by user rights. Avoid exposing a single role that grants full `read` or full `read/write` access to all APIs and resources your service contains.
+
+> [!NOTE]
+> App roles (app-only permissions) can also be configured to support assignment to users and groups. Be sure that you configure your app roles correctly for your intended access scenario. If you intend for your API’s app roles to be used for app-only access, select applications as the only allowed member types when creating the app roles.
+
+## How does application-only access work?
+
+The most important thing to remember about app-only access is that the calling app acts on its own behalf and as its own identity. There's no user interaction. If the app has been assigned to a given app role for a resource, then the app has fully unconstrained access to all resources and operations governed by that app role.
+
+Once an app has been assigned to one or more app roles (app-only permissions), it can request an app-only token from Azure AD using the [client credentials flow](v2-oauth2-client-creds-grant-flow.md) or any other supported authentication flow. The assigned roles are added to the `roles` claim of the app's access token.
+ 
+In some scenarios, the application identity may determine whether access is granted, similarly to user rights in a delegated call. For example, the `Application.ReadWrite.OwnedBy` app role grants an app the ability to manage service principals that the app itself owns. 
+
+## Application-only access example - Automated email notification via Microsoft Graph
+
+The following example illustrates a realistic automation scenario.
+
+Alice wants to notify a team by email every time the division reporting folder that resides in a Windows file share registers a new document. Alice creates a scheduled task that runs a PowerShell script to examine the folder and find new files. The script then sends an email using a mailbox protected by a resource API, Microsoft Graph.
+
+The script runs without any user interaction, therefore the authorization system only checks the application authorization. Exchange Online checks whether the client making the call has been granted the application permission (app role), `Mail.Send` by the administrator. If `Mail.Send` isn’t granted to the app, then Exchange Online fails the request.
+
+| POST /users/{id}/{userPrincipalName}/sendMail | Client app granted Mail.Send | Client app not granted Mail.Send |
+| ----- | ----- | ----- |
+| The script uses Alice’s mailbox to send emails. | 200 – Access granted. Admin allowed the app to send mail as any user. |403 - Unauthorized. Admin hasn’t allowed this client to send emails. |
+| The script creates a dedicated mailbox to send emails. | 200 – Access granted. Admin allowed the app to send mail as any user. | 403 - Unauthorized. Admin hasn’t allowed this client to send emails. |
+ 
+The example given is a simple illustration of application authorization. The production Exchange Online service supports many other access scenarios, such as limiting application permissions to specific Exchange Online mailboxes. 
+
+## Next steps
+
+- [Learn how to create and assign app roles in Azure AD](howto-add-app-roles-in-azure-ad-apps.md)
+- [Overview of permissions in Microsoft Graph](/graph/permissions-overview)
+- [Microsoft Graph permissions reference](/graph/permissions-reference)

articles/active-directory/develop/delegated-access-primer.md

@@ -1,17 +1,17 @@
 ---
 title: Microsoft identity platform delegated access scenario
-description: Learn about delegated access in the Microsoft identity platform endpoint.
+description: Learn about when and how to use delegated access in the Microsoft identity platform endpoint.
 services: active-directory
 author: omondiatieno
 manager: celesteDG
 ms.service: active-directory
 ms.subservice: develop
 ms.workload: identity
 ms.topic: conceptual
-ms.date: 11/01/2022
+ms.date: 03/15/2023
 ms.author: jomondi
 ms.reviewer: jawoods, ludwignick, phsignor
-ms.custom: aaddev, fasttrack-edit, contperf-fy21q1, identityplatformtop40, has-adal-ref
+
 ---
 # Understanding delegated access
 
@@ -25,6 +25,8 @@ People frequently use different applications to access their data from cloud ser
 
 Use delegated access whenever you want to let a signed-in user work with their own resources or resources they can access. Whether it’s an admin setting up policies for their entire organization or a user deleting an email in their inbox, all scenarios involving user actions should use delegated access.
 
+![Diagram shows illustration of delegated permissions vs application permissions.](./media/permissions-consent-overview/delegated-app-only-permissions.png)
+
 In contrast, delegated access is usually a poor choice for scenarios that must run without a signed-in user, like automation. It may also be a poor choice for scenarios that involve accessing many users’ resources, like data loss prevention or backups. Consider using [application-only access](permissions-consent-overview.md) for these types of operations.
 
 ## Requesting scopes as a client app

articles/active-directory/develop/media/permissions-consent-overview/delegated-app-only-permissions.png

@@ -17,7 +17,7 @@ ms.reviewer: jawoods, ludwignick, phsignor
 ---
 # Introduction to permissions and consent
 
-To _access_ a protected resource like email or calendar data, your application needs the resource owner's _authorization_. The resource owner can _consent_ to or deny your app's request. Understanding these foundational concepts will help you build more secure and trustworthy applications that request only the access they need, when they need it, from its users and administrators.
+To *access* a protected resource like email or calendar data, your application needs the resource owner's *authorization*. The resource owner can *consent* to or deny your app's request. Understanding these foundational concepts will help you build more secure and trustworthy applications that request only the access they need, when they need it, from users and administrators.
 
 ## Access scenarios
 
@@ -35,7 +35,7 @@ For the user, the authorization relies on the privileges that the user has been
 
 ### App-only access (Access without a user)
 
-In this access scenario, the application acts on its own with no user signed in. Application access is used in scenarios such as automation, and backup. This scenario includes apps that run as background services or daemons. It's appropriate when it's undesirable to have a specific user signed in, or when the data required can't be scoped to a single user.
+In this access scenario, the application acts on its own with no user signed in. Application access is used in scenarios such as automation, and backup. This scenario includes apps that run as background services or daemons. It's appropriate when it's undesirable to have a specific user signed in, or when the data required can't be scoped to a single user. For more information about the app-only access scenario, see [App-only-access](app-only-access-primer.md).
 
 App-only access uses app roles instead of delegated scopes. When granted through consent, app roles may also be called applications permissions. For app-only access, the client app must be granted appropriate app roles of the resource app it's calling in order to access the requested data. For more information about assigning app roles to client applications, see [Assigning app roles to applications](howto-add-app-roles-in-azure-ad-apps.md#assign-app-roles-to-applications).
 
@@ -61,10 +61,11 @@ There are other ways in which applications can be granted authorization for app-
 | Result of consent (specific to Microsoft Graph)  | [oAuth2PermissionGrant](/graph/api/resources/oauth2permissiongrant) | [appRoleAssignment](/graph/api/resources/approleassignment) |
 
 ## Consent
+
 One way that applications are granted permissions is through consent. Consent is a process where users or admins authorize an application to access a protected resource. For example, when a user attempts to sign into an application for the first time, the application can request permission to see the user's profile and read the contents of the user's mailbox. The user sees the list of permissions the app is requesting through a consent prompt. Other scenarios where users may see a consent prompt include:
 
 - When previously granted consent is revoked.
-- When the application is coded to specifically prompt for consent during every sign-in.
+- When the application is coded to specifically prompt for consent during sign-in.
 - When the application uses dynamic consent to ask for new permissions as needed at run time. 
 
 The key details of a consent prompt are the list of permissions the application requires and the publisher information. For more information about the consent prompt and the consent experience for both admins and end-users, see [application consent experience](application-consent-experience.md).
@@ -82,6 +83,7 @@ Depending on the permissions they require, some applications might require an ad
 Preauthorization allows a resource application owner to grant permissions without requiring users to see a consent prompt for the same set of permissions that have been preauthorized. This way, an application that has been preauthorized won't ask users to consent to permissions. Resource owners can preauthorize client apps in the Azure portal or by using PowerShell and APIs, like Microsoft Graph.
 
 ## Next steps
+
 - [Delegated access scenario](delegated-access-primer.md)
 - [User and admin consent overview](../manage-apps/consent-and-permissions-overview.md)
 - [OpenID connect scopes](scopes-oidc.md)