Federating Google Cloud with Active Directory: Configuring single sign-on

This article shows you how to set up single sign-on between your Active Directory environment and your Cloud Identity or G Suite account by using Microsoft Active Directory Federation Services (AD FS), and SAML Federation.

The article assumes that you understand how Active Directory identity management can be extended to Google Cloud and have already configured user provisioning. The article also assumes that you have a working AD FS 4.0 server that is running on Windows Server 2016 or a later version of Windows Server.

To follow this guide, knowledge of Active Directory Domain Services and AD FS is required. You also need a user in Cloud Identity or G Suite that has super-admin privileges and a user in Active Directory that has administrative access to your AD FS server.

Objectives

  • Configure your AD FS server so that Cloud Identity or G Suite can use it as an identity provider.
  • Create a claims issuance policy that matches identities between Active Directory and Cloud Identity or G Suite.
  • Configure your Cloud Identity or G Suite account so that it delegates authentication to AD FS.

Costs

If you're using the free edition of Cloud Identity, following this article will not use any billable components of Google Cloud.

Before you begin

  1. Verify that your AD FS server runs Windows Server 2016 or later. While you can also configure single sign-on by using previous versions of Windows Server and AD FS, the necessary configuration steps might be different from what this article describes.
  2. Make sure you understand how Active Directory identity management can be extended to Google Cloud.
  3. Configure user provisioning between Active Directory and Cloud Identity or G Suite.
  4. Ensure that your AD FS server uses a valid Secure Sockets Layer (SSL) certificate that the browsers of your corporate users recognize.
  5. Consider setting up AD FS in a server farm configuration in order to avoid it becoming a single point of failure. After you've enabled single sign-on, the availability of AD FS determines whether users can log in to the Cloud Console.

Understanding single sign-on

By using Cloud Directory Sync, you've already automated the creation and maintenance of users and tied their lifecycle to the users in Active Directory.

Although Cloud Directory Sync provisions user account details, it doesn't synchronize passwords. Whenever a user needs to authenticate in Google Cloud, the authentication must be delegated back to Active Directory, which is done by using AD FS and the Security Assertion Markup Language (SAML) protocol. This setup ensures that only Active Directory has access to user credentials and is enforcing any existing policies or multi-factor authentication (MFA) mechanisms. Moreover, it establishes a single sign-on experience between your on-premises environment and Google.

SAML 2.0 defines a protocol and an XML dialect that you can use to implement single sign-on between two parties, which are called the identity provider (IdP) and the service provider (SP):

  • The SP is the party that must authenticate a user. Because it is not configured to perform this authentication itself, the SP delegates the responsibility of performing the authentication to the IdP.
  • The IdP is the party that performs the user authentication. It identifies facts about the user and relays these facts back to the SP. The collection of facts is called an assertion.

To implement single sign-on between Active Directory and Google, you configure AD FS to act as the IdP and your Cloud Identity or G Suite account to act as the SP. With this setup in place, signing in to the Cloud Console works as follows:

Signing in to the Cloud Console.

  1. The user opens the Cloud Console with a browser.
  2. Because the user has not been authenticated yet, the Cloud Console redirects the browser to Google Sign-In.
  3. The user sees a sign-in page that asks them to enter an email address.
  4. After the user submits the email address, Google Sign-In recognizes that the email address belongs to a Cloud Identity or G Suite account that has been configured for federated authentication by using AD FS. Consequently, it redirects the browser to AD FS.
  5. Depending on how AD FS is configured, AD FS might return the user to the sign-in page and require that a username and password be provided. If Kerberos-based authentication is used, the user is authenticated automatically without having to enter credentials.
  6. If the user has to enter credentials, AD FS interacts with the Active Directory Key Distribution Center by using Kerberos to validate username and password.
  7. After successfully validating credentials, AD FS directs the browser back to Google Sign-In.
  8. Google Sign-In establishes a session and sends the browser back to the Cloud Console, which now grants access.

Configuring AD FS

Before enabling single sign-on in Cloud Identity or G Suite, you must first configure AD FS.

Creating the relying party trust

AD FS requires that you create a relying party trust for each SP that is supposed to use AD FS for authentication. You start by creating a relying party trust for Cloud Identity or G Suite, which involves the following:

  1. Log in to your AD FS server and open the AD FS MMC snap-in.
  2. In the menu at left, right-click the Relying Party Trusts folder. In the context menu, select Add Relying Party Trust.
  3. On the first page of the wizard, select Claims aware, and click Start.

    Relying Party Trust Wizard.

  4. On the next page, select Enter data about the relying party manually, and click Next.

  5. On the next page, enter a display name such as Cloud Identity, and click Next.

  6. The next page prompts you for a token encryption certificate. This step is not required in order to connect with your Cloud Identity or G Suite account, so click Next.

  7. On the following page, select Enable support for the SAML 2.0 WebSSO protocol, and enter the following SSO service URL:

    https://www.google.com/a/[DOMAIN]/acs
    

    Replace [DOMAIN] with the primary domain of your Cloud Identity or G Suite account, and click Next.

    Enable support for the SAML 2.0 WebSSO protocol.

  8. The next wizard page prompts you for relying party trust identifiers. Add the following identifiers to the list:

    • google.com/a/[DOMAIN], replacing [DOMAIN] with the primary domain of your Cloud Identity or G Suite account
    • google.com

    Relying party trust identifiers.

    Click Next.

  9. On the next page, choose an access policy. Configuring MFA is beyond the scope of this article, so click Permit everyone for now, and then click Next.

  10. On the Ready to Add Trust page, review your settings, and then click Next.

  11. On the final page, clear the Configure claims issuance policy checkbox and close the wizard. In the list of relying party trusts, you now see a new entry.

Configuring the logout URL

When you're enabling users to use single sign-on across multiple applications, it's important to allow them to sign out across multiple applications:

  1. In the AD FS Management console, under Relying Party Trusts, right-click the trust that you just created, and click Properties.
  2. On the Endpoints tab, click Add SAML.
  3. In the Add an Endpoint dialog, configure the following settings:

    1. Endpoint type: SAML Logout
    2. Binding: POST
    3. Trusted URL: https://[ADFS]/adfs/ls/?wa=wsignout1.0

      Replace [ADFS] with the fully qualified domain name of your AD FS server.

      Add an endpoint.

  4. Click OK.

  5. Click OK to close the dialog.

Configuring the claims mapping

After AD FS has authenticated a user, it issues a SAML assertion. This assertion serves as proof that authentication has successfully taken place. The assertion must identify who has been authenticated, which is the purpose of the NameID claim.

To enable Google Sign-In to associate the NameID with a user, the NameID must contain the primary email address of that user. Depending on how you are mapping users between Active Directory and Cloud Identity or G Suite, the NameID must contain the UPN or the email address from the Active Directory user, with domain substitutions applied as necessary.

UPN

  1. In the AD FS Management console, under Relying Party Trusts, right-click the newly created trust, and click Edit Claim Issuance Policy.
  2. In the dialog, click Add Rule.
  3. Select Send LDAP Attributes as Claims, and click Next.
  4. On the next page, apply the following settings:
    1. Claim rule name: Map Email and Name ID
    2. Attribute Store: Active Directory
  5. Add a row to the list of LDAP attribute mappings:
    1. LDAP Attribute: User-Principal-Name
    2. Outgoing Claim Type: Name ID
  6. Click Finish, and then click OK.

UPN: domain substitution

  1. In the AD FS Management console, under Relying Party Trusts, right-click the newly created trust, and then click Edit Claim Issuance Policy.
  2. In the dialog, click Add Rule.
  3. Select Send Claims Using a Custom Rule, and click Next.
  4. On the next page, apply the following settings:

    1. Claim rule name: Load UPN
    2. Custom Rule:

      c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
       => add(store = "Active Directory", types = ("http://temp.google.com/upn"), query = ";userPrincipalName;{0}", param = c.Value);
      

      This rule loads the User Principal Name (UPN) for the associated user from Active Directory and saves it in a temporary claim.

  5. Click Finish.

  6. Click Add Rule to create a second rule.

  7. Select Send Claims Using a Custom Rule, and click Next.

  8. On the next page, apply the following settings:

    1. Claim rule name: Transform UPN
    2. Custom Rule:

      c:[Type == "http://temp.google.com/upn"]
       => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Value = RegexReplace(c.Value, "@(.*?)$", "@[DOMAIN]"));
      

      This rule opens the temporary claim that contains the UPN and replaces the UPN suffix domain with [DOMAIN]. The resulting claim will be issued to Google Sign-In and used to associate the user with their user in Cloud Identity or G Suite.

      Be sure to replace [DOMAIN] with the primary domain of your Cloud Identity or G Suite account.

  9. Click Finish, and then click OK.

    Depending on the original UPN, you might need to apply different substitutions. If so, you need to create additional rules, one per possible substitution, and use conditions to qualify which rule should apply and when. For example, the following rule replaces the UPN domain with corp.example.com, but only if the original domain was corp.local:

    c:[Type == "http://temp.google.com/upn", value =~ "^.+@corp.local$"]
     => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Value = RegexReplace(c.Value, "@(.*?)$", "corp.example.com"));
    

    If you need to apply different substitutions, you must run separate Cloud Directory Sync configurations, one per substitution.

Email

  1. In the AD FS Management console, under Relying Party Trusts, right-click the newly created trust, and click Edit Claim Issuance Policy.
  2. In the dialog, click Add Rule.
  3. Select Send LDAP Attributes as Claims, and click Next.
  4. On the next page, apply the following settings:
    1. Claim rule name: Map Email and Name ID
    2. Attribute Store: Active Directory
  5. Add a row to the list of LDAP attribute mappings:
    1. LDAP Attribute: E-Mail-Addresses
    2. Outgoing Claim Type: Name ID
  6. Click Finish, and then click OK.

Email: domain substitution

  1. In the AD FS Management console, under Relying Party Trusts, right-click the newly created trust, and click Edit Claim Issuance Policy.
  2. In the dialog, click Add Rule.
  3. Select Send Claims Using a Custom Rule, and click Next.
  4. On the next page, apply the following settings:

    1. Claim rule name: Load email address
    2. Custom Rule:

      c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
       => add(store = "Active Directory", types = ("http://temp.google.com/mail"), query = ";mail;{0}", param = c.Value);
      

      This rule loads the email address for the respective user from Active Directory and saves it in a temporary claim.

  5. Click Finish.

  6. Click Add Rule to create a second rule.

  7. Select Send Claims Using a Custom Rule, and click Next.

  8. On the next page, apply the following settings:

    1. Claim rule name: Transform email address
    2. Custom Rule:

      c:[Type == "http://temp.google.com/mail"]
       => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Value = RegexReplace(c.Value, "@(.*?)$", "@[DOMAIN]"));
      

      This rule reads the temporary claim that contains the email address and replaces the domain with [DOMAIN]. The resulting claim will be issued to Google Sign-In and used to identify the user in Cloud Identity or G Suite.

      Be sure to replace [DOMAIN] with the primary domain of your Cloud Identity or G Suite account.

  9. Click Finish, and then click OK.

Exporting the AD FS token-signing certificate

When AD FS issues a SAML assertion, Google Sign-In must verify the integrity and authenticity of the assertion. For this purpose, SAML requires that the assertion be signed using a special token-signing key, which is the private key of a designated public/private key pair. The public key of this pair is made available to SPs in the form of a token-signing certificate and enables SPs to verify the signature of an assertion.

Before configuring your Cloud Identity or G Suite account, you must export the token-signing certificate from AD FS:

  1. In the AD FS Management console, click Service > Certificates.
  2. Right-click the certificate that is listed under Token-signing, and click View Certificate.
  3. Click the Details tab.
  4. Click Copy to File to open the Certificate Export Wizard.
  5. Click Next.
  6. Select Base-64 encoded X.509 (.CER) as format, and click Next.
  7. Provide a local filename, and click Next.
  8. Confirm the export by clicking Finish.
  9. Click OK to dismiss the message box confirming that the export was successful.
  10. Copy the exported certificate to your local computer.

Configuring your Cloud Identity or G Suite account

With the AD FS configuration completed, you can now configure single sign-on in your Cloud Identity or G Suite account:

  1. In the Admin console, click Security > Settings.
  2. Click Set up single sign-on (SSO) with a third party IdP.
  3. Ensure that Setup SSO with third party identity provider is enabled.
  4. Enter the following settings. In all URLs, replace [ADFS] with the fully qualified domain name of your AD FS server:
    1. Sign-in page URL: https://[ADFS]/adfs/ls/
    2. Sign-out page URL: https://[ADFS]/adfs/ls/?wa=wsignout1.0
    3. Change password URL: https://[ADFS]/adfs/portal/updatepassword/
  5. Under Verification certificate, click Upload certificate, and pick the AD FS token-signing certificate that you downloaded previously.
  6. Click Save.
  7. On the next page, confirm that you intend to enable single sign-on, and click I understand and agree.
  8. To sign out of the Admin console, at the upper right, click the avatar, and then click Sign out.

Testing single sign-on

You've now completed the single sign-on configuration in both AD FS and Cloud Identity or G Suite. To check if single sign-on works as intended, run the following test:

  1. Choose an Active Directory user that has previously been provisioned to Cloud Identity or G Suite and does not have super-admin privileges assigned. Users that have super-admin privileges must always sign in by using Google credentials, so they aren't suitable for testing single sign-on.
  2. Open a new browser window and navigate to https://console.cloud.google.com/.
  3. On the Google Sign-In page that appears, enter the email address of the user, and click Next. If you use domain substitution, you must apply the substitution to the email address.

    enter the email address of the user

    You are redirected to AD FS. If you configured AD FS to use forms-based authentication, you now see the sign-in page.

  4. Enter your UPN and password for the Active Directory user, and click Sign in.

    Enter your UPN and password for the Active Directory user.

  5. After successful authentication, AD FS redirects you back to Google Identity Platform. Because this is the first login for this user, you're asked to accept the Google terms of service and privacy policy.

  6. If you agree to the terms, click Accept.

  7. You are redirected to the Cloud Console, which asks you to confirm preferences and accept the Google Cloud terms of service. If you agree to the terms, click Yes, and then click Agree and Continue.

  8. At the upper left, click the avatar icon, and click Sign out.

    You are then redirected to an AD FS page confirming that you've been successfully signed out.

If you have trouble signing in, enabling the AD FS debug log on the AD FS server can help you diagnose the issue. If you're using Integrated Windows Authentication, consider temporarily switching to forms-based authentication so that you can perform tests with different users more easily.

Keep in mind that users that have super-admin privileges are exempted from single sign-on, so you can still use the Admin console to verify or change settings.

Cleaning up

If you don't intend to keep single sign-on enabled for your organization, follow these steps to disable single sign-on in Cloud Identity or G Suite:

  1. In the Admin console, click Security > Settings.
  2. Click Set up single sign-on (SSO) with a third party IdP.
  3. Clear the Setup SSO with third party identity provider checkbox.
  4. Click Save.

To clean up configuration in AD FS, follow these steps:

  1. Log in to your AD FS server and open the AD FS MMC snap-in.
  2. In the menu at left, right-click the Relying Party Trusts folder.
  3. In the list of relying party trusts, right-click Cloud Identity, and click Delete.
  4. Confirm the deletion by clicking Yes.

What's next