Set up a Google Workspace SAML Connection

Stytch's Single Sign On (SSO) product allows your customers to log into your application via third party Identity Providers, like Google Workspace. In this guide, you'll learn how to configure a Google Workspace SAML SSO connection, which is something that your customers will need to complete before their team members will be able to log into your application via SSO.

Stytch's SSO product is also compatible with Google OIDC integrations, though it's more common to use either Google Workspace SAML or Google OAuth instead.

By the end of this guide, you'll have:

  • a new Google Workspace SAML Connection that is fully configured and ready for use.
  • a new Google Workspace app that can be used to provision access to your application.
  • a Stytch B2B implementation that can use SSO for authentication.

Before you start

  • Create a Stytch B2B project via the Stytch Dashboard if you don't have one already. To do so, click on your existing project name in the top left corner of the Dashboard, click Create a new project, and then select B2B Authentication.
  • Create a new Organization by calling our Create an Organization endpoint:
curl --request POST \
	--url https://test.stytch.com/v1/b2b/organizations \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_name": "Example Org Inc.",
		"organization_slug": "example-org"
	}'

Step 1: Create a new SAML connection

Call our Create SAML Connection endpoint in order to create a new SAML Connection. Include the organization_id that you'd like the Connection to belong to and a display_name for the Connection like "Google Workspace".

curl --request POST \
	--url https://test.stytch.com/v1/b2b/sso/saml/{ORGANIZATION_ID} \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	  "display_name": "Google Workspace"
	}'

Save the acs_url, audience_uri, and connection_id values from the connection object in the Create SAML connection response for use in Step 2, where you'll use those values to configure a new Google Workspace app, and later in Step 3.

Step 2: Create and configure a new Google Workspace app

  1. Log into the Google Workspace Admin Console. Navigate to the Web and mobile apps tab under Apps:

    Web and mobile apps tab in Google Workspace

  2. Select Add custom SAML app from the Add app dropdown:

    Add custom SAML app button in Google Workspace

  3. Enter the name of your application and (optionally) a description and your application's logo. Click Continue.

  4. Under Option 2, copy the SSO URL, Entity ID, and Certificate values for use in Step 3. Click Continue.

  5. Enter the following information in the Service provider details form and then click Continue:

    • ACS URL: Enter the acs_url value from Step 1.
    • Entity ID: Enter the audience_uri value from Step 1.
    • Start URL: You can leave this field blank for the purposes of this guide.
    • Name ID format: EMAIL
    • Name ID: Basic Information > Primary email

  6. Add the following two Attributes and then click Finish:

    • Google Directory attributes: First name; App attributes: firstName
    • Google Directory attributes: Last name; App attributes: lastName

Now that you've created and configured a new Google Workspace app, you're ready to update the SSO Connection from Step 1 with the data surfaced by Google.

Step 3: Call the Update SAML Connection endpoint

In addition to the Google Workspace information from Step 2.4, you'll also need these parameters in order to call the Update SAML Connection endpoint:

  • the organization_id and connection_id from Step 1.
  • an attribute_mapping object with the following structure:
    "attribute_mapping": {
	"email": "NameID",
	"first_name": "firstName",
	"last_name": "lastName"
},

With all the necessary data, your Update SAML Connection API request should look like this:

curl --request PUT \
	--url https://test.stytch.com/v1/b2b/sso/saml/{ORGANIZATION_ID}/connections/{CONNECTION_ID} \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"idp_entity_id": "{ENTITY_ID_FROM_GOOGLE}",
		"idp_sso_url": "{SSO_URL_FROM_GOOGLE}",
		"x509_certificate": "{CERTIFICATE_FROM_GOOGLE}",
        "attribute_mapping": {
		  "email": "NameID",
		  "first_name": "firstName",
		  "last_name": "lastName"
		}
	}'

Note that you'll need to replace the newlines in the x509_certificate value with \n characters before you include that value in a cURL request.

After a successful Stytch API call, both your Google Workspace app and your SAML Connection are now fully configured. The only remaining step is to provision access.

Step 4: Provision access to your application

Navigate to the User access page for your new Google Workspace app:

User access page in Google Workspace

Grant access to the Groups or Organizational Units of your choice. For the purposes of this guide, you can also simply set the Service status to ON for everyone in the All users in this account tab:

Service status toggle in Google Workspace

You should now be able to successfully complete an SSO login flow via our Start SSO login flow and Authenticate SSO login endpoints using your new Google Workspace Connection!

What's next

Build a user interface that allows users to initiate the SSO login flow. You'll also need a page to handle the redirect back to your application at the end of the SSO flow.

Clone our B2B Next.js example app for helpful templates that can get you started quickly. Also check out our interactive B2B demo app to see the app in action.