AWS Security Blog

How to Enable Your Users to Access Office 365 with AWS Managed Microsoft AD

January 18, 2023: We fixed a capitalization issue in a url that was preventing ADFS from authenticating properly in most browers.

December 12, 2019: A customer reported that the architecture diagrams had a typo in it, and so we replaced the two diagrams to address the problem.


You can now enable your users to access Microsoft Office 365 with credentials that you manage in AWS Directory Service for Microsoft Active Directory, also known as AWS Microsoft AD. You can accomplish this by deploying Microsoft Azure Active Directory (AD) Connect and Active Directory Federation Services for Windows Server 2016 (AD FS 2016) with AWS Microsoft AD. AWS Microsoft AD makes it possible and easy for you to build a Windows environment in the AWS Cloud, synchronize your AWS Microsoft AD users into Microsoft Azure AD, and use Office 365, all without needing to create and manage AD domain controllers. Now you can also benefit from the broad set of AWS Cloud services for compute, storage, database, and Internet of Things (IoT) while continuing to use Office 365 business productivity apps—all with a single AD domain.

Office 365 provides different options to support user authentication with identities that come from AD. One common way to do this is to use Azure AD Connect and AD FS together with your AD directory. In this model, you use Azure AD Connect to synchronize user names from AD into Azure AD so that Office 365 can use those identities. To complete this solution, you use AD FS to enable Office 365 to authenticate the identities against your AD directory. Good news: AWS Microsoft AD now supports this model!

In this blog post, we show how to use Azure AD Connect and AD FS with AWS Microsoft AD so that your employees can access Office 365 by using their AD credentials.

Prerequisites

The instructions in this post assume that you understand how to create Amazon EC2 for Windows Server instances, know how to use Remote Desktop Protocol (RDP) to log in to the instances, and already have completed the following tasks:

  1. Create an AWS Microsoft AD directory.
  2. Join an Amazon EC2 for Windows Server instance to your AWS Microsoft AD domain to use as a management instance (Management).
  3. Install Active Directory Administration Tools on your Management instance.
  4. Join an Amazon EC2 for Windows Server 2016 instance to the AWS Microsoft AD domain to use as your ADFS server. We show you how to install AD FS later.
  5. Join an Amazon EC2 for Windows Server instance to the AWS Microsoft AD domain you use as your ADSync server. We show you how to install Azure AD Connect on this instance later.
  6. Using Active Directory Users and Computers on your Management instance, create a standard user named ADFSSVC in your AWS Microsoft AD directory. AD FS uses this user account later.
  7. Create an active Office 365 subscription.
  8. Add and verify your domain in Office 365

Note: You must use RDP and sign in with the AWS Microsoft AD admin account using the password you specified when you created your AWS Microsoft AD directory when performing Steps 3 and 6 in this “Prerequisites” section.

The following diagram illustrates the environment you must have in place to implement the solution in this blog post (the numbers in the diagram correspond to Steps 1–8 earlier in this section). We build on this configuration to install and configure Azure AD Connect and AD FS with Azure AD and Office 365.
Architecture diagram

Note: In this blog post, we use separate Microsoft Windows Server instances on which to run AD FS and Azure AD Connect. You can choose to combine these on a single server, as long as you use Windows Server 2016. Though it is technically possible to use an on-premises server as the AD FS and Azure AD host, such a configuration is counter to the idea of a Windows environment completely in the cloud. Also, this requires configuration of firewall ports and AWS security groups, which is beyond the scope of this blog. We also assume you are familiar with SSL certificates and how to obtain them.

Configuration background

When you create an AWS Microsoft AD directory, AWS exclusively retains the enterprise administrator account of the forest and domain administrator account for the root domain to deliver the directory as a managed service. When you set up your directory, AWS creates an organizational unit (OU) in the directory and delegates administrative privileges for the OU to your admin account. During directory creation, you specify the password of your admin account and then manage the directory using normal AD administrative tools. Within this OU, you administer users, groups, computers, Group Policy objects, other devices, and additional OUs as needed. You perform these actions using standard AD administration tools from a computer that is joined to an AWS Microsoft AD domain. Typically, the administration computer is an EC2 instance that you access using RDP, by logging in with your admin account credentials. From your admin account, you can also delegate permissions to other users or groups you create within your OU.

To use Office 365 with AD identities, you use Azure AD Connect to synchronize the AD identities into Azure AD. There are two commonly supported ways to use Azure AD Connect to support Office 365 use. In one model, you synchronize user names only, and you use AD FS to federate authentication from Office 365 to your AD. In the second model, you synchronize user names and passwords from your AD directory to Azure AD, and you do not have to use AD FS. The model supported by AWS Microsoft AD is the first model: synchronize user names only and use AD FS to authenticate from Office 365 to your AWS Microsoft AD. The AD FS model also enables authentication with SaaS applications that support federated authentication (this topic is beyond the scope of this blog post).

Note: Azure AD Connect now has a pass-through model of authentication. Because this was in a preview status at the time of writing this blog post, this authentication model is beyond the scope of this blog post. This post not only supports Office 365, but it also includes an AD FS deployment model that supports authentication for other SAML-based cloud applications.

In a default AD FS installation, AD FS uses two containers that require special AD permissions that your AWS Microsoft AD administrative account does not have. To address this, you will create two nested containers in your OU for AD FS to use. When you install AD FS, you tell AD FS where to find the containers through a Windows PowerShell parameter.

As described previously, we will now show you how to use Azure AD Connect and AD FS with AWS Microsoft AD with Azure AD and Office 365 in five steps, as illustrated in the following diagram.

Diagram including the five steps in this blog post

  1. Add two containers to AWS Microsoft AD for use by AD FS.
  2. Install AD FS.
  3. Integrate AD FS with Azure AD.
  4. Synchronize users from AWS Microsoft AD to Azure AD with Azure AD Connect.
  5. Sign in to Office 365 by using your Microsoft AD identities.

Important: In Steps 1, 2, and 4, we use the admin account for the AWS Microsoft AD directory for RDP sessions to the management, adfsserver, and adsync instances. If you use a different user account that you granted permissions to in the directory, you must consistently use that user in Step 1 and in Step 2.19, or you will see errors.

Step 1: Add two containers to AWS Microsoft AD for use by AD FS

The following steps show how to create the AD containers required by AD FS in your AWS Microsoft AD directory.

Perform the following steps after signing in to the Management instance using the admin user account for the AWS Microsoft AD directory:

  1. Generate a random global unique identifier (GUID) using the following Windows PowerShell command.
    (New-Guid).Guid

Screenshot of the (New-Guid).Guid Windows PowerShell command
Make a note of the GUID output because it will be required later on. In this case, the GUID is 67734c62-0805-4274-b72b-f7171110cd56.

  1. Create a container named ADFS in your OU. The OU is located in the domain root and it has the same name as the NetBIOS name you specified when you created your AWS Microsoft AD directory. In this example, our OU name is AWS, and our domain is DC=awsexample,DC=com. You create the container by running the following Windows PowerShell command. You must replace the names that are in bold text with the names from your AWS Microsoft AD directory.
    New-ADObject -Name "ADFS" -Type Container -Path “OU=YourNetBIOSName,DC=YourDomainSuffix,DC=YourDomainRoot

    Screenshot of the Windows PowerShell command

  2. Create another AD container in your new ADFS container, and use the previously generated GUID as the name. Do this by running the following Windows PowerShell command. Be sure to replace the names in bold text with the names from your AWS Microsoft AD directory and your GUID. In this example, we replace GUID with 67734c62-0805-4274-b72b-f7171110cd56. The other bold items shown match the names in our example AWS Microsoft AD directory.
    New-ADObject -Name "GUID" -Type Container -Path “CN=ADFS,OU=YourNetBIOSName,DC=YourDomainSuffix,DC=YourDomainRoot

Screenshot of the Windows PowerShell command
To verify that you successfully created the ADFS and GUID containers, open Active Directory Users and Computers and navigate to the containers you created. Your root domain, OU name, and GUID name should match your AWS Microsoft AD configuration.
Screenshot showing the successful creation of the ADFS and GUID containers

Note: If you do not see the ADFS and GUID containers, turn on Advanced Features by choosing View in the Active Directory Users and Computers tool, and then choosing Advanced Features.

Step 2: Install AD FS

In this section, we show how to install AD FS by using Windows PowerShell commands, which involves six key steps that we cover in subsections:

  1. Decide a public name for your AD FS service.
  2. Install AD FS on your adfserver.
  3. Obtain and install an SSL certificate for your AD FS service.
  4. Configure AD FS by using Windows PowerShell.
  5. Publish your AD FS service through DNS.
  6. Enable the AD FS sign-in page.

To complete the process, you must run some of the commands as the admin of your OU, and you must run others as the local administrator of your AD FS server. For this post, we use RDP to sign in to the adfsserver with the AWS Microsoft AD admin account. We use runas to switch to the local administrator, when necessary.

When switching to the local administrator, we must obtain the password by choosing Get Password on the RDP Connect Your Instance page. By specifying the privacy enhanced mail (PEM) file that we used when we created the AD FS server instance, Get Password decrypts the current password value.

Screenshot of "Get Password" option

The following steps obtain the local administrator password, and then sign you in as the OU admin:

  1. From the EC2 console, choose the AD FS Server instance, and then choose Connect.
  2. On the Connect to Your Instance page, choose Get Password. Choose Browse and find the PEM file you used to create your AD FS server instance. Then choose Decrypt Password. Copy the password for use when you use the runas command later.
  3. Choose Download Remote Desktop File. In the Open with: box, choose Remote Desktop Connection, and then choose OK.
  4. On the Windows Security page, choose More choices, choose Use a different account, and then choose OK. In the User name box, specify your AWS Microsoft AD domain name or NetBIOS name followed by a backslash, followed by admin. In our case, we use awsexample.com\admin. Then enter the admin password you specified when you created AWS Microsoft AD.

At this point, our RDP session is running as the OU admin for AWS Microsoft AD, and we have a copy of the local administrator password for use when we need to use runas.

A.  Decide a public name for your AD FS service

To get started, you must first decide a federation service name for your AD FS server. This name must be different from the host name of the AD FS server. The AD FS service must register its service principle name (SPN) in Active Directory that is distinct from your AD FS host. If you attempt to use your host name, registration will fail because the host name is already a registered SPN.

You can create your federation service name by using a short name (for example, sts) as a prefix for your domain name (for example, awsexample.com). In this example, we use sts.awsexample.com as the federation service name.

B.  Install AD FS on your adfserver

Install the Windows feature, AD FS, by running the following Windows PowerShell command. Make sure you run Windows PowerShell as a local administrator.  This command adds only the components needed to configure your ADFS server later:

Install-WindowsFeature ADFS-Federation

Screenshot of installing AD FS

Note: This step prompts you to complete post-configuration for AD FS. Similarly, if you chose to install the AD FS feature with Server Manager instead of PowerShell, Server Manager prompts you to “Configure the federation service on this server.” Do not follow the prompted process as it attempts to use the default container in the directory, which requires domain administrator permissions to access. Instead, you must use the container in your OU that you created in Step 1. The remaining items that follow complete this process and direct AD FS to use the correct OU for AWS Microsoft AD.

C.  Obtain and install an SSL certificate for your AD FS service

Now that you have installed the AD FS feature, you must obtain a certificate for use by your ADFS service. The AD FS certificate plays an important role to secure communication between the adfsserver and AD FS clients, and to secure tokens issued by the AD FS service.

To install your certificate, you must obtain the certificate as a personal information exchange (PFX) file. AWS recommends that you obtain a certificate from a trusted SSL certificate provider. Alternatively, you can install a Microsoft Enterprise CA in your AWS Microsoft AD domain, and then generate and manage your own SSL certificates. You can explore how to do this by following the Microsoft Enterprise CA installation instructions in the How to Enable LDAPS for Your Microsoft AD Directory blog post.

The AD FS instance has a public and private address. For this blog, the private IP address within my VPC has a fully qualified domain name (FQDN) of adfsserver.awsexample.com. The published DNS name for the AD FS service must use the public IP address of the adfsserver. In this blog, my AD FS service has an FQDN of sts.awsexample. It is important to note that the common name and subject alternative name (SAN) must include the federation service name you decide to use for the AD FS server. In my example, the name is sts.awsexample.com. For this blog post, we obtained a certificate from an SSL certificate provider.

Install the certificate on the AD FS server by using the Microsoft Management Console (MMC) snap-in for certificates. You must launch the MMC as the admin user. Follow these steps to install the certificate:

  1. Open a command prompt window.
  2. Type mmc and press Enter.
  3. Choose File, choose Add/Remove snap-in, and choose Add.
  4. For Add Standalone Snap-in, choose Certificates and then choose Add.
  5. For the Certificates snap-in, choose Computer account and then choose Next.
  6. Choose Finish, and then choose OK to load the Certificates snap In.
  7. Expand Certificates (Local Computer).
  8. Right-click Personal, choose All Tasks, and then choose Import.
  9. On the Certificate Import Wizard, choose Next.
  10. Choose Browse to locate and select your certificate that has been given by your CA. Choose Next.
  11. Ensure Certificate store is set to Personal, and choose Next.
  12. Choose Finish and OK to complete the installation of the certificate on the AD FS server.

Next you need to retrieve the Thumbprint value of the newly installed certificate and save it for use when you configure your ADFS server. Follow the remaining steps:

  1. In the Certificates console window, expand Personal, and choose Certificates.
  2. Right-click the certificate, and then choose Open.
  3. Choose the Details tab to locate the Thumbprint

Screenshot of the Thumbprint value
Note:
In this case, we will copy our certificate Thumbprint, d096652327cfa18487723ff61040c85c7f57f701, and save it in Windows Notepad.

D.  Configure AD FS by using Windows PowerShell

  1. Open an RDP session to your ADFS server by using the admin account for your AWS Microsoft AD directory. Install AD FS by running the following Windows PowerShell command. You must replace the bold strings in the command with the GUID you created in Step 1 and the names from your AWS Microsoft AD directory.
    $adminConfig = @{"DKMContainerDn"="CN=GUID,CN=ADFS,OU=YourNetBIOSName,DC=YourDomainSuffix,DC=YourDomainRoot"}
  1. Enter the AD FS standard user account credentials for the ADFSSVC user and save it in the script variable, $svcCred, by running the following Windows PowerShell command.
    $svcCred = (get-credential)

    Screenshot of entering the user account credentials for the ADFSSVC user

  1. Type the Microsoft AD administrator credentials of the Admin user and save it in the script variable, $localAdminCred, by running the following Windows PowerShell command.
    $localAdminCred = (get-credential)

    Screenshot of entering the credentials of the Admin user

  1. Install the AD FS server by running the following Windows PowerShell command. You must replace the bold items with the Thumbprint ID from your certificate, and replace the federation service name with the federation service name you chose earlier. For our example, the federation service name is sts.awsexample.com and we copy our certificate Thumbprint, d096652327cfa18487723ff61040c85c7f57f701, from where we saved it in Windows Notepad.

Note: Be sure to remove any empty spaces in the certificate Thumbprint value.

Install-ADFSFarm -CertificateThumbprint <Thumbprint ID> -FederationServiceName "YourFederationServiceName" -ServiceAccountCredential $svcCred -Credential $localAdminCred -OverwriteConfiguration -AdminConfiguration $adminConfig -SigningCertificateThumbprint <Thumbprint ID> -DecryptionCertificateThumbprint <Thumbprint ID>

E.  Publish your AD FS service through DNS

Create a DNS A record for use with AD FS. This record resolves the federation service name to the public IP address you assign to your ADFS instance. You must create the DNS A record at the DNS hosting provider that hosts your domain. In the following example, sts.awsexample.com is the federation service name and 54.x.x.x is the public IP address of our AD FS instance.

  • Hostname: awsexample.com
  • Record Type: A
  • IP Address: x.x.x

F.  Enable the AD FS sign-in page

Enable the AD FS sign-in page by running the following Windows PowerShell command.

Set-ADFSProperties -EnableIdpInitiatedSignonPage $true

To verify that the AD FS sign-in page works, open a browser on the AD FS instance, and sign in on the AD FS sign-in page (https://<my federation service name>/adfs/ls/IdpInitiatedSignOn.aspx) by using your AWS Microsoft AD admin account. In our example, the federation service name (<my federation service name> in the sign-in page URL) is sts.awsexample.com.

Step 3: Integrate AD FS with Azure AD

The following steps show you how to connect AD FS with Office 365 by connecting to Azure AD with Windows PowerShell and federating the custom domain. From the ADFS instance, make sure you run Windows PowerShell as a local administrator and complete the following steps:

  • Connect to Azure AD using Windows PowerShell.
    Federate the custom domain you added and verified in Azure AD by running the following two Windows PowerShell commands. You must update the items in bold text with the names from your AWS Microsoft AD directory. For our example, our AD FS instance’s Fully Qualified Domain Name (FQDN) is adfsserver.awsexample.com, and our domain name is awsexample.com.

    Set-MsolADFSContext –computer <ADFS instance FQDN>
    
    Convert-MsolDomainToFederated –domain <Domain name>

Step 4: Synchronize users from AWS Microsoft AD to Azure AD with Azure AD Connect

The following steps show you how to install and customize Azure AD Connect to synchronize your AWS Microsoft AD identities to Azure AD for use with Office 365.Open an RDP session to your ADSync instance by using your AWS Microsoft AD admin user account:

  1. Download Azure AD Connect.
  2. On the Welcome page of the Azure AD Connect Wizard, accept the license terms and privacy notice, and then choose Continue.
  3. On the Express Settings page, choose Customize.
  4. On the Install required components page, choose Install.
  5. On the User sign-in page, choose Do not configure and then choose Next.
  6. On the Connect to Azure AD page, enter your Office 365 global administrator account credentials and then choose Next.
  7. On the Connect your directories page, choose Active Directory as the Directory Type, and then choose your Microsoft AD Forest as your Forest. Choose Add Directory.
  8. At the prompt, enter your AWS Microsoft AD admin account credentials, and then choose OK.
  9. Now that you have added the AWS Microsoft AD directory, choose Next.
  10. On the Azure AD sign-in configuration page, choose Next.

Note: AWS recommends the userPrincipalName (UPN) attribute for use by AWS Microsoft AD users when they sign in to Azure AD and Office 365. The UPN attribute format combines the user’s login name and the UPN-suffix of an AWS Microsoft AD user. The UPN suffix is the domain name of your AWS Microsoft AD domain and the same domain name you added and verified with Azure AD.

In the following example from the Active Directory Users and Computers tool, the user’s UPN is awsuser@awsexample.com, which is a combination of the user’s login name, awsuser, with the UPN-suffix, @awsexample.com.
Screenshot showing the awsuser@awsexample.com UPN

  1. On the Domain and OU filtering page, choose Sync selected domains and OUs, choose the Users OU under your NetBIOS OU, and then choose Next.
    Screenshot of syncing the Users OU
  2. On the Uniquely identifying your users page, choose Next.
  3. On the Filter users and devices page, choose Next.
  4. On the Optional features page, choose Next.
  5. On the Ready to configure page, choose Start the synchronization process when configuration completes, and then choose Install.
  6. The Azure AD Connect installation has now completed. Choose Exit.

Note: By default, the Azure AD Connect sync scheduler runs every 30 minutes to synchronize your AWS Microsoft AD identities to Azure AD. You can tune the scheduler by opening a Windows PowerShell session as an administrator and running the appropriate Windows PowerShell commands. For more information, go to Azure AD Connect Sync Scheduler.

Tip: Do you need to synchronize a change immediately? You can manually start a sync cycle outside the scheduled sync cycle from the Azure AD Connect sync instance. Open a Windows PowerShell session as an administrator and run the following Windows PowerShell commands.

Import-Module ADSync
Start-ADSyncSyncCycle -PolicyType Delta

Step 5: Sign in to Office 365 by using your AWS Microsoft AD identities

The following steps show you how to sign in to Office 365 using AD FS as the authentication method with your AWS Microsoft AD user account. In this example, we assign a license to the AWS Microsoft AD user account, awsuser@awsexample.com, in the Office 365 admin center. We then sign in to Office 365 by using the AWS Microsoft AD user account UPN, awsuser@awsexample.com.

Using a computer on the internet, open a browser and complete the following steps:

  1. Access the Office 365 admin center using your global administrator account, and assign a license to a user you created in your AWS Microsoft AD directory.
    Screenshot of assigning a license to a user created in the AWS Microsoft AD directory
  2. Sign in with the AWS Microsoft AD user account at https://portal.office.com.
    Screenshot of signing in with the AWS Microsoft AD user account
    When entering the UPN of the AWS Microsoft AD user account, you will be redirected to your ADFS server sign-in page to complete user authentication.
    Screenshot of being redirected to the ADFS server sign-in page to complete user authentication
  3. On the AD FS sign-in page, enter your UPN and the password of the AWS Microsoft AD user account.
  4. You have successfully signed in to Office 365 using your AWS Microsoft AD user account!
    Screenshot of successfully signing in to Office 365 using an AWS Microsoft AD user account

Summary

In this blog post, we showed how to use Azure AD Connect and AD FS with AWS Microsoft AD so that your employees can access Office 365 using their AD credentials. Now that you have Azure AD Connect and AD FS in place, you also might want to explore how to build upon this infrastructure to add sign-in for other Software as a Service (SaaS) applications that are compatible with AD FS. For example, this blog post explains how you can provide your users single sign-on access to Amazon AppStream by using AD FS.

If you have comments or questions, post them on the Directory Service forum or contact AWS Support.

– Darryn and Ron

Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.