Active Directory single sign-on

Last reviewed 2023-02-27 UTC

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

Create a new relying party trust:

  1. Log in to your AD FS server and open the AD FS Management MMC snap-in.
  2. Select AD FS > Relying Party Trusts.
  3. On the Actions pane, click Add relying party trust.
  4. On the Welcome page of the wizard, select Claims aware, and click Start.
  5. On the Select data source page, select Enter data about the relying party manually, and click Next.
  6. On the Specify display name page, enter a name such as Google Cloud and click Next.
  7. On the Configure certificate page, click Next.
  8. On the Configure URL 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.

  9. On the Configure identifiers page, add the following two identifiers:

    • google.com/a/DOMAIN, replacing DOMAIN with the primary domain of your Cloud Identity or Google Workspace account
    • google.com

    Then click Next.

    Relying party trust identifiers.

  10. On the Choose access control policy page, choose an appropriate access policy and click Next.

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

  12. 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 list of relying party trusts, select the trust that you just created and click Edit claim issuance policy.
  2. Click Add rule
  3. On the Choose rule type page of the Add transform claim rule wizard, select Transform an incoming claim, then click Next.
  4. On the Configure claim rule page, configure the following settings:

    • Claim rule name: Name Identifier
    • Incoming claim type: UPN
    • Outgoing claim type: Name ID
    • Outgoing name ID format: Email
  5. Select Pass through all claim values and click Finish.

  6. Click OK to close the claim issuance policy dialog.

UPN: domain substitution

  1. In the list of relying party trusts, select the trust that you just created and click Edit claim issuance policy.
  2. Click Add rule
  3. On the Choose rule type page of the Add transform claim rule wizard, select Transform an incoming claim, then click Next.
  4. On the Configure claim rule page, configure the following settings:

    • Claim rule name: Name Identifier
    • Incoming claim type: UPN
    • Outgoing claim type: Name ID
    • Outgoing name ID format: Email
  5. Select Replace incoming claim e-mail suffix with a new e-mail suffix and configure the following setting:

    • New e-mail suffix: A domain name used by your Cloud Identity or Google Workspace account.
  6. Click Finish, and then click OK.

Email

  1. In the list of relying party trusts, select the trust that you just created and click Edit claim issuance policy.
  2. Add a rule to lookup the email address:
    1. In the dialog, click Add Rule.
    2. Select Send LDAP Attributes as Claims, and click Next.
    3. On the next page, apply the following settings:
      1. Claim rule name: Email address
      2. Attribute Store: Active Directory
    4. Add a row to the list of LDAP attribute mappings:
      1. LDAP Attribute: E-Mail-Addresses
      2. Outgoing Claim Type: E-Mail-Address
    5. Click Finish.
  3. Add another rule to set the NameID:

    1. Click Add rule
    2. On the Choose rule type page of the Add transform claim rule wizard, select Transform an incoming claim, then click Next.
    3. On the Configure claim rule page, configure the following settings:

      • Claim rule name: Name Identifier
      • Incoming claim type: E-Mail-Address
      • Outgoing claim type: Name ID
      • Outgoing name ID format: Email
    4. Select Pass through all claim values and click Finish.

    5. Click OK to close the claim issuance policy dialog.

Email: domain substitution

  1. In the list of relying party trusts, select the trust that you just created and click Edit claim issuance policy.
  2. Add a rule to lookup the email address:
    1. In the dialog, click Add Rule.
    2. Select Send LDAP Attributes as Claims, and click Next.
    3. On the next page, apply the following settings:
      1. Claim rule name: Email address
      2. Attribute Store: Active Directory
    4. Add a row to the list of LDAP attribute mappings:
      1. LDAP Attribute: E-Mail-Addresses
      2. Outgoing Claim Type: E-Mail-Address
    5. Click Finish.
  3. Add another rule to set the NameID value:

    1. Click Add rule
    2. On the Choose rule type page of the Add transform claim rule wizard, select Transform an incoming claim, then click Next.
    3. On the Configure claim rule page, configure the following settings:

      • Claim rule name: Name Identifier
      • Incoming claim type: E-Mail-Address
      • Outgoing claim type: Name ID
      • Outgoing name ID format: Email
  4. Select Replace incoming claim e-mail suffix with a new e-mail suffix and configure the following setting:

    • New e-mail suffix: A domain name used by your Cloud Identity or Google Workspace account.
  5. Click Finish, and then click OK.single-sign-on

Exporting the AD FS token-signing certificate

After AD FS authenticates a user, it passes a SAML assertion to Cloud Identity or Google Workspace. To enable Cloud Identity and Google Workspace to verify the integrity and authenticity of that assertion, AD FS signs the assertion with a special token-signing key and provides a certificate that enables Cloud Identity or Google Workspace to check the signature.

You now export the 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. Select the Details tab.
  4. Click Copy to File to open the Certificate Export Wizard.
  5. On the Welcome to the certificate export wizard, click Next.
  6. On the Export private key page, select No, do not export the private key.
  7. On the Export file format page, select Base-64 encoded X.509 (.CER) and click Next.
  8. On the File to export page, provide a local filename, and click Next.
  9. Click Finish to close the dialog.
  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. Open the Admin Console and go to SSO with third-party IdP.

    Go to SSO with third-party IdP

  2. Click Add SSO profile.

  3. Set Setup SSO with third party identity provider to 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 then pick the token signing certificate that you downloaded previously.

  6. Click Save.

  7. Sign out of the Admin Console.

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 Google 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, you might find additional information in the AD FS admin log.

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.

Clean 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