SAML SSO with Google Workspace¶

Step-by-step guide to integrate Faraday's SAML SSO with Google Workspace (formerly G Suite).

Prerequisites: Faraday commercial edition, Google Workspace account with super administrator privileges. See SAML for general SAML configuration reference.

Configuration Summary¶

Replace <domain> with your Faraday server's FQDN throughout.

Step-by-Step Setup¶

Step 1 — Access Google Admin Console¶

1. Navigate to Google Admin.
2. Sign in with an account that has super administrator privileges.

Step 2 — Create a Custom SAML App¶

1. In the Admin console, go to Menu → Apps → Web and mobile apps.
2. Click Add app → Add custom SAML app.

Step 3 — Set App Details¶

1. Enter a name for the app (e.g., "Faraday").
2. Optionally upload an app icon.
3. Click Continue.

Step 4 — Copy Google IdP Details¶

On the Google Identity Provider details page:

1. Copy the following values for Faraday configuration:

   Google Field	Faraday Setting
   SSO URL	sso_url (SSO URL)
   Entity ID	identity_id (Identity ID)
   Certificate	idp_certificate (IdP Certificate — download the file)

2. Click Continue.

Step 5 — Generate SP Certificates¶

On your Faraday server, generate the Service Provider certificate pair:

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 1825 -out certificate.pem

• certificate.pem → SP Certificate in Faraday settings
• key.pem → SP Private Key in Faraday settings

Step 6 — Configure Service Provider Details¶

In the Service Provider Details section:

1. Enter the following:

   Field	Value
   ACS URL	https://<domain>/_api/saml/acs
   Entity ID	https://<domain>/_api/saml/metadata.xml
   Start URL	https://<domain>/_api/saml/login

2. Check the Signed response checkbox.

3. Configure Name ID as appropriate (typically email).
4. Click Continue.

Important: The Signed response checkbox must be enabled for Faraday to validate the SAML assertion.

Step 7 — Configure Attribute Mapping¶

1. On the Attributes mapping page, add a mapping:

   Google Directory Attribute	App Attribute
   Primary email	username

2. Click Finish.

Step 8 — Enable the App for Users¶

1. In the Admin console, go to Menu → Apps → Web and mobile apps.
2. Select your SAML app.
3. Click User access.
4. Click On for everyone (or select specific organizational units).
5. Click Save.

Note: It may take up to 24 hours for changes to propagate to all users, though typically it takes effect within minutes.

Step 9 — Configure Faraday¶

Apply the settings via CLI:

faraday-manage settings -a update saml

Fill in the prompts:

Alternatively, configure via the Web UI at Preferences → Authentication → SAML.

Step 10 — Restart Faraday¶

systemctl restart faraday-server

Step 11 — Test the Integration¶

1. Open the Faraday login page.
2. Click the SSO button labeled with your display_name.
3. Authenticate with your Google Workspace account.
4. Verify you are redirected back to Faraday with an active session.

Attribute Mapping¶

Google Workspace sends SAML assertions containing user attributes. The attribute_identifier setting tells Faraday which attribute to use as the username.

The mapping configured in Step 7 sends the user's primary email as the username attribute. Ensure attribute_identifier in Faraday matches the App Attribute name.

Additional attributes can be mapped in the Google Admin console if needed:

Troubleshooting¶