Google Workspace enterprise connection (SAML)

You can set up SAML to work with your Google Workspace.

Getting the Google metadata into Kinde

Link to this section

Google gives you the SAML metadata as a file to download, and does not host it at a URL. You can get it into Kinde in either of two ways:

• Paste it. (recommended) Open the downloaded file and paste its contents into the IdP metadata XML field on the connection. This is the simplest option. Kinde keeps this copy until you replace it, so when Google rotates its signing certificate you download the updated file and paste it again. Kinde warns you on the home page 30 days before the newest signing certificate in pasted metadata expires.
• Host it. Upload the file to a public location Kinde can reach, such as an AWS S3 bucket, Cloudflare R2, or a public website, and enter that URL in the IdP metadata URL field. Kinde reads the file at every sign-in, so you can update the certificates just by re-uploading the file. Make sure the URL stays reachable from Kinde’s servers: a CDN rule that blocks requests by country can block Kinde too.

If you fill in both fields, Kinde uses the pasted XML and ignores the URL. This guide shows both options where they differ.

Advanced configurations

Link to this section

Depending on your SAML set up, you may need to include advanced configurations for your connection. See Advanced SAML configurations.

Step 1: Add Google Workspace SAML in Kinde

Link to this section

You can make a connection available only to a specific organization, or you can create it so it can be used across any organization in your business.

Add a connection for a specific organization

Link to this section

1. Go to Organizations and open the organization.
2. In the menu, select Authentication, then select Add connection.
3. In the Add connection window, select New enterprise connection, then click Next.
4. Select the connection type you want and then select Next.
5. Next: ‘Step 2: Configure the connection’.

Add a connection that can be shared across multiple organizations

Link to this section

1. Go to Settings > Environment > Authentication.
2. Scroll to the Enterprise connection section and select Add connection. The Add connection window opens.
3. Select the connection type you want and then select Next.
4. Next: ‘Step 2: Configure the connection’.

Step 2: Configure the connection

Link to this section

1. Enter the Connection name. This name is what will appear on the button on the authentication screen. We will call it ‘Google Workspace’ for this example.

2. Enter an Entity ID. This field can be any mix of numbers and letters, as long as it matches your IdP configuration. Copy this somewhere you can access it later.

3. If you are adding this connection to a live environment, you must provide either an IdP metadata URL or IdP metadata XML before you can save. You get the metadata from Google in Step 3, so for now either paste a placeholder URL (you will replace it later) or come back to save after Step 3.

   

4. Enter a sign in URL if your IdP requires a specific URL.

5. If you want, select the Sign request algorithm and Protocol binding. The options you choose will depend on what your identity provider prefers or requires.

6. Select a Name ID format. This helps identify and link user identities between your IdP and Kinde.

7. Enter an Email key attribute. This is the attribute in the SAML token that contains the user’s email. Setting this value ensures that the email address returned in the SAML response is correctly retrieved. We do not recommend leaving this field blank, but if you do we will set ‘email’ as the attribute.

8. (Optional) Add a first name and last name key attribute.

   

9. Enter any relevant Home realm domains. This is how SAML recognizes a user’s credentials and routes them to the correct sign in page. Note that home realm domains need to be unique across all connections in an environment. Read more about home realm domains.

10. If you use home realm domains, the sign in button is hidden on the auth screen by default. To show the SSO button, select the Always show sign-in button option.

    

11. Copy the relevant reply URL:

    1. If you don’t use a custom domain, copy the ACS URL.
    2. If you do use a custom domain, select the Use custom domain instead option and copy the custom domain URL. Later, add this URL to your identity provider configuration.

12. If you want to enable just-in-time (JIT) provisioning for users, select the Create a user record in Kinde option. This saves time adding users manually or via API later.

13. For an environment-level connection, under Email address trust, select Verify, then trust. For details about the options, see Trusting emails from providers. Organization-level connections show Auto-add users instead.

14. (Optional) In the Sign SAML request section, paste in the Signed certificate and Private key. You may have got these from your IdP or you may have generated yourself (see procedure above).

15. Enter any upstream params that you want to pass to the identity provider. Not all providers support this, so check their documentation first.

16. Select Save.

Step 3: Configure Google Workspace Admin Console

Link to this section

1. Sign in to your Google Workspace Admin Console.

2. In the main menu, go to Apps > Web and Mobile Apps.

3. Select Add App > Add custom SAML app.

   

4. Complete the App details window:

   1. Enter a name in the App name field.
   2. Enter a Description for the app.
   3. If you want, upload an icon for the app.
   4. Select Continue.

   

5. Copy the Google Identity Provider details by selecting DOWNLOAD METADATA under Option 1. This is the file you will paste into Kinde or upload to a file storage location in Step 4.

6. Select Continue.

   

7. Enter the Service provider details:

   1. Enter or paste in the ACS URL you copied from Kinde earlier.
   2. Enter or paste the Entity ID, this needs to match what was entered in Kinde earlier.
   3. Set the Name ID format as EMAIL.
   4. Select Continue.

8. On the Attribute mapping page, select Finish.

9. If you want to grant access to other users, select the chevron in the right corner of the User access panel. This opens additional options.

   

10. If you want, you can change the access to suit your organization’s needs. You can do this per Organizational unit or switch ON for everyone.

11. Select Save.

Step 4: Add the metadata to Kinde

Link to this section

Use one of the following, depending on the option you chose at the start.

Option 1: Paste the file (recommended)

1. Open the metadata file you downloaded from Google in a text editor and copy all of its contents.

2. In Kinde, open the connection’s configuration page.

3. Paste the contents into the IdP metadata XML field. Leave IdP metadata URL blank, or clear any placeholder you entered earlier.

   Kinde will warn you 30 days before the newest signing certificate in pasted metadata expires.

Option 2: Host the file

1. Upload the metadata file to your public storage location.
2. Copy the URL for the file.
3. In Kinde, open the connection’s configuration page.
4. Paste the URL into the IdP metadata URL field. Leave IdP metadata XML blank.

Step 5: Complete Kinde configuration

Link to this section

1. Switch on the connection. This will make it instantly available to users if this is your production environment.
   1. For environment-level connections, scroll down and select the apps that will use the auth method.
   2. For organization-level connections, scroll down and select if you want to switch this on for the org.
2. Select Save.

Rotate the Google signing certificate

Link to this section

Google signs SAML responses with an identity provider certificate that is valid for five years. Before it expires, you need to move the SAML app to a new certificate. Kinde trusts every signing certificate listed in the metadata and verifies each response against the one that signed it, so you can add the new certificate first and switch over whenever you are ready. See Keep IdP signing certificates current for how this works.

1. In the Google Workspace Admin Console, add a new identity provider certificate and make it available to the SAML app. Do not switch the app to it yet.
2. Download the updated metadata for the app. It lists both the current and the new certificate.
3. Get the updated metadata into Kinde:
   • If the connection uses IdP metadata XML, paste the new file over the old one and select Save.
   • If the connection uses IdP metadata URL, re-upload the file to your storage location, keeping the same URL. No change is needed in Kinde.
4. In the Google Workspace Admin Console, switch the SAML app to sign with the new certificate.
5. Test a sign-in.

If sign-in fails, switch the app back to the previous certificate in Google. It keeps working until its expiry date, as long as it is still in the metadata Kinde reads.

The downloaded metadata has a validUntil attribute that Google sets to the expiry date of the certificate the app currently uses. Kinde does not enforce it, so a file whose validUntil has passed still works. After you switch to the new certificate, download the metadata once more and update Kinde so the attribute reflects the new certificate.

Test the connection

Link to this section

Once you have completed the above steps, you should be able to see a Google Workspace sign-in button on your product’s authentication screen. Note: if you gave the enterprise connection a different name in Kinde, the button will have the name you entered.

If you can’t see the button:

• Check that the metadata URL or pasted metadata XML and other connection details are correct in Kinde.
• Check that user access is set up in your app, in the Google Workspace Console.

Try to sign in and hopefully - success!!