Set up a trust between AD FS and Azure AD

  • Article

Updated: June 25, 2015

Applies To: Azure, Office 365, Power BI, Windows Intune

Each domain that you want to federate must either be added as a single sign-on domain or converted to be a single sign-on domain from a standard domain. Adding or converting a domain sets up a trust between AD FS and Microsoft Azure Active Directory (Microsoft Azure AD).

Important

  • If you are using a subdomain (for example, corp.contoso.com) in addition to a top-level domain (for example, contoso.com), you must add the top-level domain in your cloud service before you add any subdomains. When the top-level domain is set up for single sign-on, all subdomains are automatically set up as well.

  • Setting up a trust is a one-time operation, and you do not need to run the Microsoft Azure Active Directory Module for Windows PowerShell cmdlets again if you add more AD FS servers to your server farm.

  • If you add and verify a domain with the Microsoft Azure Active Directory Module, you need to specify several additional settings. These settings are required so that you can see the DNS records that you must configure to enable your domain to work with your cloud service.

If you need to support multiple top-level domains, you must use the SupportMultipleDomain switch with any cmdlets, such as the cmdlets used in the “Add a domain” and the “Convert a domain” procedures.

For example, to add both contoso.com and fabrikam.com as single sign-on domains, you would follow the "Add a domain" procedure for contoso.com, using the SupportMultipleDomain switch in each step that has a cmdlet. So, for step 5, you would use New-MsolFederatedDomain –DomainName contoso.com –SupportMultipleDomain. After you complete all the steps in the procedure for contoso.com, you would repeat the procedure again for your fabrikam.com domain. In step 5, you would use New-MsolFederatedDomain –DomainName fabrikam.com –SupportMultipleDomain.

For more information, see Support for Multiple Top Level Domains.

Complete one of the following procedures to set up your federated trust with Azure AD, depending on whether you need to add a new domain or convert an existing domain.

  • Add a domain

  • Convert a domain

Add a domain

  1. Open the Microsoft Azure Active Directory Module.

  2. Run $cred=Get-Credential. When the cmdlet prompts you for credentials, type your cloud service administrator account credentials.

  3. Run Connect-MsolService –Credential $cred. This cmdlet connects you to Azure AD. Creating a context that connects you to Azure AD is required before running any of the additional cmdlets installed by the tool.

  4. Run Set-MsolAdfscontext -Computer <AD FS primary server>, where <AD FS primary server> is the internal FQDN name of the primary AD FS server. This cmdlet creates a context that connects you to AD FS.

    Note

    If you have installed the Microsoft Azure Active Directory Module on the primary AD FS server, then you do not need to run this cmdlet.

  5. Run New-MsolFederatedDomain –DomainName <domain>, where <domain> is the domain to be added and enabled for single sign-on. This cmdlet adds a new top-level domain or subdomain that will be configured for federated authentication.

    Note

    Once you have used the New-MsolFederatedDomain cmdlet to add a top-level domain you will not be able to use the New-MsolDomain cmdlet to add standard domains (non-federated).

  6. Using the information provided by the results of the New-MsolFederatedDomain cmdlet, contact your domain registrar to create the required DNS record. This verifies that you own the domain. Note that this may take up to 15 minutes to propagate, depending on your registrar. It can take up to 72 hours for changes to propagate through the system. For more information, see Verify a domain at any domain name registrar.

  7. Run New-MsolFederatedDomain a second time, specifying the same domain name to finalize the process.

Convert a domain

When you convert an existing domain to a single sign-on domain, every licensed user will become a federated user, using their existing Active Directory corporate credentials (user name and password) to access your cloud services. Performing a staged rollout of single sign-on is not currently possible; however, you can pilot single sign-on with a set of production users from your production Active Directory forest. For more information, see Run a pilot to test single signon before setting it up (optional).

Note

It’s best to perform a conversion when there are the fewest users, such as on a weekend, to reduce the impact on your users.

To convert an existing domain to a single sign-on domain, follow these steps.

  1. Open the Microsoft Azure Active Directory Module.

  2. Run $cred=Get-Credential. When the cmdlet prompts you for credentials, type your cloud service administrator account credentials.

  3. Run Connect-MsolService –Credential $cred. This cmdlet connects you to Azure AD. Creating a context that connects you to Azure AD is required before running any of the additional cmdlets installed by the tool.

  4. Run Set-MsolAdfscontext -Computer <AD FS primary server>, where <AD FS primary server> is the internal FQDN name of the primary AD FS server. This cmdlet creates a context that connects you to AD FS.

    Note

    If you have installed the Microsoft Azure Active Directory Module on the primary AD FS server, then you do not need to run this cmdlet.

  5. Run Convert-MsolDomainToFederated –DomainName <domain>, where <domain> is the domain to be converted. This cmdlet changes the domain from standard authentication to single sign-on.

Note

To verify that the conversion has worked, compare the settings on the AD FS server and in Azure AD by running Get-MsolFederationProperty –DomainName <domain>, where <domain> is the domain for which you want to view settings. If they don’t match, you can run Update-MsolFederatedDomain –DomainName <domain> to sync the settings.

Next step

Now that you have set up a trust between AD FS and Azure AD, you must set up Active Directory synchronization. For more information, see Directory synchronization roadmap. After you have set up Active Directory synchronization, see Verify and manage single sign-on with AD FS.

See Also

Concepts

Checklist: Use AD FS to implement and manage single sign-on
Single sign-on roadmap