Before you start
You'll need:
• A Google Workspace admin account with permissions to manage apps and configure SAML integrations
• Access to Atlas with permission to configure Single Sign-On
• The Atlas Single Sign-On configuration page open in a separate browser tab — you'll be copying values between the two
Step 1 — Set up a SAML app in Google Workspace
Sign in to the Google Admin console
1. Go to admin.google.com and sign in with a Super Admin account (or equivalent).
Create a custom SAML app for Atlas
2. In the Admin console, go to Apps → Web and mobile apps.
3. Click Add app and select Add custom SAML app.
4. Enter an application name — for example, Atlas SAML SSO. Add a description and icon if you like.
5. Click Continue.
Copy your Google identity provider details
On the Google IdP Information step:
6. Download the IdP metadata XML file, and note the SSO URL and Entity ID that Google provides.
7. Download the certificate if provided separately — you'll need it in Atlas.
8. Click Continue when you've saved the required information.
Configure SAML settings using your Atlas values
On the Service Provider details step, use the values from your Atlas Single Sign-On configuration wizard:
9. Set ACS URL (Assertion Consumer Service URL) to the Atlas Single Sign-On URL from the Atlas wizard.
10. Set Entity ID (Audience URI) to the Atlas Audience / Entity ID from the Atlas wizard.
11. For Name ID format, select EMAIL unless your Atlas administrator specifies otherwise.
12. For Name ID, select Primary email.
13. Leave optional fields at their defaults unless instructed otherwise.
14. Click Continue.
⚠️ Important: Always use the exact values from your Atlas environment — not example values from other documentation.
Configure attribute mappings
On the Attribute mapping step, set up at least the following:
• email → Primary email
• given_name → First name
• family_name → Last name
• Phone number — optional, can be skipped
15. Click Finish to create the app.
Enable the app for your users
16. Open the newly created app in the Web and mobile apps list.
17. Go to User access and turn the app ON for the organizational units or groups whose users should access Atlas.
18. Save your changes.
Step 2 — Confirm users in Google Workspace and Atlas
Check users in Google Workspace
19. In the Admin console, go to Directory → Users.
20. Make sure the users who will sign in to Atlas exist and are active.
21. Confirm they are in an organisational unit or group where the Atlas SAML app is turned on.
Add the same users in Atlas
22. In Atlas, open the user management area.
23. Create or confirm accounts for the same users, making sure their primary email addresses match exactly.
💡 Tip: User identifiers must match between Google Workspace and Atlas for Single Sign-On to work correctly.
Step 3 — Configure Single Sign-On in Atlas
Open the Single Sign-On configuration page in Atlas and follow the wizard.
Name and protocol
24. Enter a Configuration name — for example, Google Workspace Single Sign-On.
25. Select SAML 2.0 as the protocol.
Atlas Single Sign-On endpoints
26. In the Atlas Single Sign-On endpoints step, review the values shown (Single Sign-On URL and Audience / Entity ID).
27. Confirm these match the ACS URL and Entity ID you set in Google Workspace.
Google Workspace identity provider details
In the relevant step of the Atlas wizard, paste the Google details you collected earlier:
• IdP metadata XML (or SSO URL and Entity ID)
• Certificate
• Sign-in URL (and logout URL if applicable)
28. Save the configuration step.
Map user attributes
In the attribute mapping steps, connect Google Workspace attributes to Atlas user fields:
• email → Atlas email field
• given_name → Atlas first name field
• family_name → Atlas last name field
• Phone number — optional, can be skipped
29. Confirm all required mappings are complete and save without errors.
Step 4 — Test the connection
30. In Atlas, select Test connection on the Single Sign-On configuration page.
31. Atlas will redirect you to the Google Workspace sign-in page for your domain.
You've set things up correctly if:
• You're redirected to the Google Workspace sign-in page
• You can sign in with a user who has access to the Atlas SAML app in Google Workspace
• After signing in, you're redirected back to Atlas
• Atlas shows a confirmation that the connection was successful
Troubleshooting
If the connection test fails, check the following:
• The Entity ID / Audience URI and ACS URL in Google Workspace exactly match the values in the Atlas Single Sign-On endpoints step.
• The user has access to the Atlas SAML app in Google Workspace and exists in Atlas with a matching identifier.
• The attribute names for email, given_name, and family_name in Google Workspace match the mappings in Atlas.
• Review any error messages in Atlas or in the Google Admin console (Reports → Audit → SAML) for further detail.
If you're still stuck, contact your internal administrator or reach out to Atlas support — include a description of what you've tried and any error messages you've seen.