Active Directory single sign-on

This article shows you how to set up single sign-on between your Active Directory environment and your Cloud Identity or Google Workspace 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 Google Workspace 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 Google Workspace can use it as an identity provider.
  • Create a claims issuance policy that matches identities between Active Directory and Cloud Identity or Google Workspace.
  • Configure your Cloud Identity or Google Workspace 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 Google Workspace.
  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 Google Cloud Directory Sync, you've already automated the creation and maintenance of users and tied their lifecycle to the users in Active Directory.

Although Google 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.

For more details on single sign-on, see Single sign-on

Configuring AD FS

Before enabling single sign-on in Cloud Identity or Google Workspace, 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 Google Workspace, 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 Google Workspace 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 Google Workspace 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 Google Workspace 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 Google Workspace, 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 Google Workspace.

      Be sure to replace DOMAIN with the primary domain of your Cloud Identity or Google Workspace 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 Google 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 Google Workspace.

      Be sure to replace DOMAIN with the primary domain of your Cloud Identity or Google Workspace 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 Google Workspace 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 Google Workspace account

With the AD FS configuration completed, you can now configure single sign-on in your Cloud Identity or Google Workspace 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 Google Workspace. 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 Google Workspace 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 go 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 Google Workspace:

  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