Upraviť

Configure sign-in behavior using Home Realm Discovery

  • Článok

This article provides an introduction to configuring Microsoft Entra authentication behavior for federated users using Home Realm Discovery (HRD) policy. It covers using auto-acceleration sign-in to skip the username entry screen and automatically forward users to federated login endpoints. To learn more about HRD policy, check out the Home Realm Discovery article.

Auto-acceleration sign-in

Some organizations configure domains in their Microsoft Entra tenant to federate with another identity provider (IDP), such as AD FS for user authentication. When a user signs into an application, they're first presented with a Microsoft Entra sign-in page. After they've typed their UPN, if they are in a federated domain they're then taken to the sign-in page of the IDP serving that domain. Under certain circumstances, administrators might want to direct users to the sign-in page when they're signing in to specific applications. As a result users can skip the initial Microsoft Entra ID page. This process is referred to as "sign-in auto-acceleration."

For federated users with cloud-enabled credentials, such as SMS sign-in or FIDO keys, you should prevent sign-in auto-acceleration. See Disable auto-acceleration sign-in to learn how to prevent domain hints with HRD.

Important

Starting April 2023, organizations who use auto-acceleration or smartlinks might begin to see a new screen added to the sign-in UI. This screen, termed the Domain Confirmation Dialog, is part of Microsoft's general commitment to security hardening and requires the user to confirm the domain of the tenant in which they are signing in to. If you see the Domain Confirmation Dialog and do not recognize the tenant domain listed, you should cancel the authentication flow and contact your IT Admin.

For more information, please visit Domain Confirmation Dialog.

Prerequisites

To configure HRD policy for an application in Microsoft Entra ID, you need:

  • An Azure account with an active subscription. If you don't already have one, you can create an account for free.
  • One of the following roles: Global Administrator, or owner of the service principal.
  • The latest Azure AD PowerShell cmdlet preview.

Set up an HRD policy on an application

We'll use Azure AD PowerShell cmdlets to walk through a few scenarios, including:

We'll use Microsoft Graph to walk through a few scenarios, including:

  • Setting up HRD policy to do auto-acceleration for an application in a tenant with a single federated domain.

  • Setting up HRD policy to do auto-acceleration for an application to one of several domains that are verified for your tenant.

  • Setting up HRD policy to enable a legacy application to do direct username/password authentication to Microsoft Entra ID for a federated user.

  • Listing the applications for which a policy is configured.

In the following examples, you create, update, link, and delete HRD policies on application service principals in Microsoft Entra ID.

Note

Azure AD and MSOnline PowerShell modules are deprecated as of March 30, 2024. To learn more, read the deprecation update. After this date, support for these modules are limited to migration assistance to Microsoft Graph PowerShell SDK and security fixes. The deprecated modules will continue to function through March, 30 2025.

We recommend migrating to Microsoft Graph PowerShell to interact with Microsoft Entra ID (formerly Azure AD). For common migration questions, refer to the Migration FAQ. Note: Versions 1.0.x of MSOnline may experience disruption after June 30, 2024.

  1. Before you begin, run the Connect command to sign in to Microsoft Entra ID with your admin account:

    Connect-AzureAD -Confirm

  2. Run the following command to see all the policies in your organization:

    Get-AzureADPolicy

If nothing is returned, it means you have no policies created in your tenant.

Create an HRD policy

In this example, you create a policy that when it's assigned to an application either:

  • Auto-accelerates users to a federated identity provider sign-in screen when they're signing in to an application when there's a single domain in your tenant.
  • Auto-accelerates users to a federated identity provider sign-in screen if there's more than one federated domain in your tenant.
  • Enables non-interactive username/password sign-in directly to Microsoft Entra ID for federated users for the applications the policy is assigned to.

The following policy auto-accelerates users to a federated identity provider sign-in screen when they're signing in to an application when there's a single domain in your tenant.

New-AzureADPolicy 
    -Definition @("{`"HomeRealmDiscoveryPolicy`":{`"AccelerateToFederatedDomain`":true}}") -DisplayName BasicAutoAccelerationPolicy 
    -Type HomeRealmDiscoveryPolicy

POST /policies/homeRealmDiscoveryPolicies

"HomeRealmDiscoveryPolicy": {
    "AccelerateToFederatedDomain": true
}

The following policy auto-accelerates users to a federated identity provider sign-in screen when there's more than one federated domain in your tenant. If you've more than one federated domain that authenticates users for applications, you need to specify the domain to auto-accelerate.

New-AzureADPolicy 
    -Definition @("{`"HomeRealmDiscoveryPolicy`":{`"AccelerateToFederatedDomain`":true, `"PreferredDomain`":`"federated.example.edu`"}}") 
    -DisplayName MultiDomainAutoAccelerationPolicy 
    -Type HomeRealmDiscoveryPolicy

POST /policies/homeRealmDiscoveryPolicies

"HomeRealmDiscoveryPolicy": {
    "AccelerateToFederatedDomain": true,
    "PreferredDomain": [
      "federated.example.edu"
    ]
}

The following policy enables username/password authentication for federated users directly with Microsoft Entra ID for specific applications:

New-AzureADPolicy 
    -Definition @("{`"HomeRealmDiscoveryPolicy`":{`"AllowCloudPasswordValidation`":true}}") 
    -DisplayName EnableDirectAuthPolicy 
    -Type HomeRealmDiscoveryPolicy

POST /policies/homeRealmDiscoveryPolicies

"EnableDirectAuthPolicy": {
    "AllowCloudPasswordValidation": true
}

To see your new policy and get its ObjectID, run the following command:

Get-AzureADPolicy

To apply the HRD policy after you've created it, you can assign it to multiple application service principals.

Locate the service principal to which to assign the policy

You need the ObjectID of the service principals to which you want to assign the policy. There are several ways to find the ObjectID of service principals.

You can use the Microsoft Entra admin center, or you can query Microsoft Graph. You can also go to the Graph Explorer Tool and sign in to your Microsoft Entra account to see all your organization's service principals.

Because you're using PowerShell, you can use the following cmdlet to list the service principals and their IDs.

Get-AzureADServicePrincipal

Assign the policy to your service principal

After you have the ObjectID of the service principal of the application for which you want to configure auto-acceleration, run the following command. This command associates the HRD policy that you created in step 1 with the service principal that you located in step 2.

Add-AzureADServicePrincipalPolicy 
    -Id <ObjectID of the Service Principal> 
    -RefObjectId <ObjectId of the Policy>

You can repeat this command for each service principal to which you want to add the policy.

In the case where an application already has a HomeRealmDiscovery policy assigned, you won't be able to add a second one. In that case, change the definition of the HRD policy that is assigned to the application to add extra parameters.

Check which application service principals your HRD policy is assigned to

To check which applications have HRD policy configured, use the Get-AzureADPolicyAppliedObject cmdlet. Pass it the ObjectID of the policy that you want to check on.

Get-AzureADPolicyAppliedObject -id <ObjectId of the Policy>

Try the application to check that the new policy is working.

List the applications for which HRD policy is configured

  1. List all policies that were created in your organization

    Get-AzureADPolicy

Note the ObjectID of the policy that you want to list assignments for.

  1. List the service principals to which the policy is assigned

    Get-AzureADPolicyAppliedObject -id <ObjectId of the Policy>

Remove an HRD policy from an application

  1. Get the ObjectID

Use the previous example to get the ObjectID of the policy, and that of the application service principal from which you want to remove it.

  1. Remove the policy assignment from the application service principal

    Remove-AzureADServicePrincipalPolicy -id <ObjectId of the Service Principal>  -PolicyId <ObjectId of the policy>

  2. Check removal by listing the service principals to which the policy is assigned

    Get-AzureADPolicyAppliedObject -id <ObjectId of the Policy>

Configuring policy through Graph Explorer

From the Microsoft Graph explorer window:

  1. Sign in with one of the roles listed in the prerequisites section.

  2. Grant consent to the Policy.ReadWrite.ApplicationConfiguration permission.

  3. Use the Home realm discovery policy to create a new policy.

  4. POST the new policy, or PATCH to update an existing policy.

    PATCH /policies/homeRealmDiscoveryPolicies/{id}
    {
        "definition": [
        "{\"HomeRealmDiscoveryPolicy\":
        {\"AccelerateToFederatedDomain\":true,
        \"PreferredDomain\":\"federated.example.edu\",
        \"AlternateIdLogin\":{\"Enabled\":true}}}"
    ],
        "displayName": "Home Realm Discovery auto acceleration",
        "isOrganizationDefault": true
    }

  5. To view your new policy, run the following query:

    GET /policies/homeRealmDiscoveryPolicies/{id}

  6. To delete the HRD policy you created, run the query:

    DELETE /policies/homeRealmDiscoveryPolicies/{id}

Next steps