Merge pull request #232187 from omondiatieno/signin-logs-faqs-update

add information on how to access sign-in logs for service principals

Author: v-stsavell

articles/active-directory/develop/howto-restrict-your-app-to-a-set-of-users.md

@@ -8,10 +8,11 @@ ms.service: active-directory
 ms.subservice: develop
 ms.workload: identity
 ms.topic: how-to
-ms.date: 12/19/2022
+ms.date: 03/28/2023
 ms.author: cwerner
 ms.reviewer: jmprieur, kkrishna
 ms.custom: aaddev, engagement-fy23
+
 #Customer intent: As a tenant administrator, I want to restrict an application that I have registered in Azuren-e AD to a select set of users available in my Azure AD tenant
 ---
 
@@ -21,17 +22,17 @@ Applications registered in an Azure Active Directory (Azure AD) tenant are, by d
 
 Similarly, in a [multi-tenant](howto-convert-app-to-be-multi-tenant.md) application, all users in the Azure AD tenant where the application is provisioned can access the application once they successfully authenticate in their respective tenant.
 
-Tenant administrators and developers often have requirements where an application must be restricted to a certain set of users. There are two ways to restrict an application to a certain set of users or security groups:
+Tenant administrators and developers often have requirements where an application must be restricted to a certain set of users or apps (services). There are two ways to restrict an application to a certain set of users, apps or security groups:
 
 - Developers can use popular authorization patterns like [Azure role-based access control (Azure RBAC)](howto-implement-rbac-for-apps.md).
 - Tenant administrators and developers can use built-in feature of Azure AD.
 
 ## Supported app configurations
 
-The option to restrict an app to a specific set of users or security groups in a tenant works with the following types of applications:
+The option to restrict an app to a specific set of users, apps or security groups in a tenant works with the following types of applications:
 
 - Applications configured for federated single sign-on with SAML-based authentication.
-- Application proxy applications that use Azure AD pre-authentication.
+- Application proxy applications that use Azure AD preauthentication.
 - Applications built directly on the Azure AD application platform that use OAuth 2.0/OpenID Connect authentication after a user or admin has consented to that application.
 
 ## Update the app to require user assignment
@@ -41,28 +42,60 @@ To update an application to require user assignment, you must be owner of the ap
 1. Sign in to the [Azure portal](https://portal.azure.com/)
 1. If you have access to multiple tenants, use the **Directories + subscriptions** filter :::image type="icon" source="./media/common/portal-directory-subscription-filter.png" border="false"::: in the top menu to switch the tenant in which you want to register an application.
 1. Search for and select **Azure Active Directory**.
-1. Under **Manage**, select **Enterprise Applications** > **All applications**.
+1. Under **Manage**, select **Enterprise Applications** then select **All applications**.
 1. Select the application you want to configure to require assignment. Use the filters at the top of the window to search for a specific application.
 1. On the application's **Overview** page, under **Manage**, select **Properties**.
 1. Locate the setting **Assignment required?** and set it to **Yes**. When this option is set to **Yes**, users and services attempting to access the application or services must first be assigned for this application, or they won't be able to sign-in or obtain an access token.
 1. Select **Save** on the top bar.
 
 When an application requires assignment, user consent for that application isn't allowed. This is true even if users consent for that app would have otherwise been allowed. Be sure to [grant tenant-wide admin consent](../manage-apps/grant-admin-consent.md) to apps that require assignment.
 
-## Assign the app to users and groups
+## Assign the app to users and groups to restrict access
 
 Once you've configured your app to enable user assignment, you can go ahead and assign the app to users and groups.
 
-1. Under **Manage**, select the **Users and groups** > **Add user/group** .
+1. Under **Manage**, select the **Users and groups** then select **Add user/group**.
 1. Select the **Users** selector.
 
-   A list of users and security groups will be shown along with a textbox to search and locate a certain user or group. This screen allows you to select multiple users and groups in one go.
+   A list of users and security groups are shown along with a textbox to search and locate a certain user or group. This screen allows you to select multiple users and groups in one go.
 
 1. Once you're done selecting the users and groups, select **Select**.
 1. (Optional) If you have defined app roles in your application, you can use the **Select role** option to assign the app role to the selected users and groups.
 1. Select **Assign** to complete the assignments of the app to the users and groups.
 1. Confirm that the users and groups you added are showing up in the updated **Users and groups** list.
 
+## Restrict access to an app (resource) by assigning other services (client apps)
+
+Follow the steps in this section to secure app-to-app authentication access for your tenant.
+
+1.	Navigate to Service Principal sign-in logs in your tenant to find services authenticating to access resources in your tenant.
+1.	Check using app ID if a Service Principal exists for both resource and client apps in your tenant that you wish to manage access.
+      ```powershell
+      Get-MgServicePrincipal `
+      -Filter "AppId eq '$appId'"
+      ```
+1.	Create a Service Principal using app ID, if it doesn't exist:
+      ```powershell
+      New-MgServicePrincipal `
+      -AppId $appId
+      ```
+1.	Explicitly assign client apps to resource apps (this functionality is available only in API and not in the Azure AD Portal):
+      ```powershell
+      $clientAppId = “[guid]”
+                     $clientId = (Get-MgServicePrincipal -Filter "AppId eq '$clientAppId'").Id
+      New-MgServicePrincipalAppRoleAssignment `
+      -ServicePrincipalId $clientId `
+      -PrincipalId $clientId `
+      -ResourceId (Get-MgServicePrincipal -Filter "AppId eq '$appId'").Id `
+      -AppRoleId "00000000-0000-0000-0000-000000000000"
+      ```
+1.	Require assignment for the resource application to restrict access only to the explicitly assigned users or services.
+      ```powershell
+      Update-MgServicePrincipal -ServicePrincipalId (Get-MgServicePrincipal -Filter "AppId eq '$appId'").Id -AppRoleAssignmentRequired:$true
+      ```
+   > [!NOTE]
+   > If you don't want tokens to be issued for an application or if you want to block an application from being accessed by users or services in your tenant, create a service principal for the application and [disable user sign-in](../manage-apps/disable-user-sign-in-portal.md) for it.
+
 ## More information
 
 For more information about roles and security groups, see:

articles/active-directory/reports-monitoring/reports-faq.yml

@@ -29,7 +29,7 @@ sections:
       - question: |
           How soon should I see activities data after getting a premium license?
         answer: |
-          If you already have activities data as a free license, then you can see it immediately. If you don't have any data, then it will take up to three days for the data to show up in the reports.
+          If you already have activities data as a free license, then you can see it immediately. If you don't have any data, then it takes up to three days for the data to show up in the reports.
 
       - question: |
           Can I see last month's data after getting an Azure AD premium license?
@@ -101,20 +101,55 @@ sections:
       - question: |
           Why do my non-interactive sign-ins appear to have the same time stamp?
         answer: |
-          Non-interactive sign-ins can trigger a large volume of events every hour, so they are grouped together in the logs.
+          Non-interactive sign-ins can trigger a large volume of events every hour, so they're grouped together in the logs.
           
-          In many cases, non-interactive sign-ins have all the same characteristics, except for the date and time of the sign-in. If the time aggregate is set to 24 hours, the logs will appear to show the sign-ins at the same time. Each of these grouped rows can be expanded to view the exact time stamp.
+          In many cases, non-interactive sign-ins have all the same characteristics, except for the date and time of the sign-in. If the time aggregate is set to 24 hours, the logs appear to show the sign-ins at the same time. Each of these grouped rows can be expanded to view the exact time stamp.
 
       - question: |
-          I am seeing User IDs in the username field of my sign-ins log. Why is this happening?
+          I'm seeing User IDs in the username field of my sign-ins log. Why is this happening?
         answer: |
-          With passwordless authentication, User IDs appear as the username. To confirm this scenario, look at the details of the sign-in event in question. The *authenticationDetail* field will say *passwordless*.
+          With passwordless authentication, User IDs appear as the username. To confirm this scenario, look at the details of the sign-in event in question. The *authenticationDetail* field says *passwordless*.
 
       - question: |
           I see a 90025 error in the sign in logs. Does this mean my user failed to sign in? Has my tenant hit a throttling limit?
         answer: |
-          No, in general 90025 errors are resolved by an automatic retry without the user noticing the error. This error can occur when an internal Azure AD subservice hits its retry allowance and does not indicate your tenant is being throttled. These errors are usually resolved by Azure AD internally without any user impact. If the user is unable to sign in due to this error, manually trying again should resolve the issue. 
+          No, in general 90025 errors are resolved by an automatic retry without the user noticing the error. This error can occur when an internal Azure AD subservice hits its retry allowance and doesn't indicate your tenant is being throttled. These errors are usually resolved by Azure AD internally without any user impact. If the user is unable to sign in due to this error, manually trying again should resolve the issue. 
 
+      - question: |
+          In Service Principal sign-in logs, what does it mean if I see “00000000-0000-0000-0000-000000000000” or “” for Service Principal ID or Resource Service Principal ID in my sign-in logs?
+        answer: |
+          If the Service Principal ID has the value “0000000-0000-0000-0000-000000000000", it means that there's no Service Principal for the client application in that instance of authentication (Azure AD no longer issues access tokens without a client Service Principal except for a few Microsoft and third party applications).
+
+          If the Resource Service Principal ID has the value “0000000-0000-0000-0000-000000000000", it means that there's no Service Principal for the resource application in that instance of authentication.
+
+          > [!NOTE]
+          > Authentication without a client Service Principal is a deprecated behavior in Azure AD and isn't commonly expected. This behavior is currently allowed only for a limited number of resource apps.
+ 
+      - question: |
+          In Service Principal sign-in logs, how can I query for instances of authentication without a client or resource Service Principal in my tenant? (That is, Service Principal ID or Resource Service Principal ID is “00000000-0000-0000-0000-000000000000” or “”)
+        answer: |
+          - To find instances of sign-in logs for your tenant where a client Service Principal is missing, use the following query:
+            ```http
+            https://graph.microsoft.com/beta/auditLogs/signIns?$filter=signInEventTypes/any(t: t eq 'servicePrincipal') and servicePrincipalId eq '00000000-0000-0000-0000-000000000000'
+            ```
+          - To find instances of sign-in logs for your tenant where a resource Service Principal is missing, use the following query:
+            ```http
+            https://graph.microsoft.com/beta/auditLogs/signIns?$filter=signInEventTypes/any(t: t eq 'servicePrincipal') and resourceServicePrincipalId eq '00000000-0000-0000-0000-000000000000'
+            ```
+          
+          You can also find these sign-in logs in Azure AD Portal.
+
+          - Sign in to the [Azure portal](https://portal.azure.com) and go to **Azure Active Directory**.
+          - Navigate to Sign in Logs under **Monitoring**,
+          - Select the **Service Principal Sign ins**. 
+          - Make sure you select an appropriate time frame in the Date field (last 24 hours, 7 days etc.).
+          -	Add a filter and select **Service Principal ID** and provide the value ‘00000000-0000-0000-0000-000000000000' to get instances of authentication with no client Service Principal.
+            
+      - question: |
+          How can I restrict sign-in (authentication) for various apps that I see in the Service Principal sign-in logs?
+        answer:
+          If you wish to control how authentication works in your tenant for specific client or resource apps, follow instructions in the [Restrict Azure AD app to a set of users](../develop/howto-restrict-your-app-to-a-set-of-users.md) article.
+                  
   - name: Conditional Access
     questions:
       - question: |
@@ -124,29 +159,29 @@ sections:
 
           To get started:
           
-          * Sign in to the [Azure portal](https://portal.azure.com) and got to **Azure AD** > **Sign-ins log**.
-          * Select the sign-in that you want to troubleshoot.
-          * Navigate to the **Conditional Access** tab.
+          - Sign in to the [Azure portal](https://portal.azure.com) and go to **Azure Active Directory** then select **Sign-ins log**.
+          - Select the sign-in that you want to troubleshoot.
+          - Navigate to the **Conditional Access** tab.
           Here, you can view all the policies that impacted the sign-in and the result for each policy. 
               
       - question: |
           What are all possible values for the Conditional Access status?
         answer: |
           Conditional Access status can have the following values:
           
-          * **Not Applied**: There was no CA policy with the user and app in scope. 
-          * **Success**: There was a CA policy with the user and app in scope and CA policies were successfully satisfied. 
-          * **Failure**: The sign-in satisfied the user and application condition of at least one CA policy and grant controls are either not satisfied or set to block access.
+          - **Not Applied**: There was no CA policy with the user and app in scope. 
+          - **Success**: There was a CA policy with the user and app in scope and CA policies were successfully satisfied. 
+          - **Failure**: The sign-in satisfied the user and application condition of at least one CA policy and grant controls are either not satisfied or set to block access.
               
       - question: |
           What are all possible values for the Conditional Access policy result?
         answer: |
           A CA policy can have the following results:
           
-          * **Success**: The policy was successfully satisfied.
-          * **Failure**: The policy wasn't satisfied.
-          * **Not applied**: The policy conditions may not have been met.
-          * **Not enabled**: The policy may be in a disabled state. 
+          - **Success**: The policy was successfully satisfied.
+          - **Failure**: The policy wasn't satisfied.
+          - **Not applied**: The policy conditions may not have been met.
+          - **Not enabled**: The policy may be in a disabled state. 
               
       - question: |
           The policy name in the sign-ins log doesn't match the policy name in Conditional Access. Why?