Google Workspace + Relyra

Copy Markdown View Source

Tested against: Google Workspace admin console, April 2026

This is the authoritative runbook for the shipped :google_workspace preset. Use it after the local FakeIdP proof so your first hosted-provider exercise is limited to one Google Workspace path.

Tested against

  • Google Workspace custom SAML app flow
  • Relyra.Provider.GoogleWorkspace
  • Relyra.Provider.apply_defaults(:google_workspace, ...)

Relyra owns

  • Safe default assertion/response signing requirements
  • Email-style NameID defaults for the preset
  • A narrow support claim for the shipped Google Workspace path only

IdP owns

  • The Google Workspace custom SAML app configuration
  • ACS URL, SSO URL, and certificate values from the admin console
  • NameID and attribute mapping inside Google Workspace

Host owns

  • The Phoenix ACS route, sessions, and downstream authorization
  • Published entity ID, domain, and deployment-specific wiring
  • Any application-specific tenant or authorization logic

1. Create the custom SAML app

In Google Workspace, create a new custom SAML app and populate the service provider details:

  • ACS URL: your ACS endpoint
  • ACS URL also serves as the label Relyra uses for sp_entity_id in this preset's operator hints
  • SSO URL: copy from Google Workspace's IdP details
  • Certificate: export the current signing certificate
  • Name ID format: keep an email-style principal unless you have a clear reason to deviate

2. Configure Relyra

connection =
  Relyra.Provider.apply_defaults(:google_workspace, [
    sp_entity_id: "https://sp.example.com/metadata",
    acs_url: "https://sp.example.com/saml/acs",
    idp_sso_url: "https://accounts.google.com/o/saml2/idp?idpid=...",
    idp_certificates: ["-----BEGIN CERTIFICATE-----..."]
  ])

Key defaults applied by the preset:

  • allow_idp_initiated?: false
  • require_signed_assertions?: true
  • require_signed_response?: true
  • name_id_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
  • algorithm_policy.signing: :rsa_sha256

3. Proof of success

Use one concrete receipt:

  • A successful login returns through the configured ACS route.
  • The configured certificate matches the active certificate exported from Google Workspace.
  • The NameID maps to a stable email-style principal in the host app.

Proof receipt:

  • One successful Google Workspace login after the local FakeIdP proof already passed.

4. Common failures

SymptomWhy it happensFix
NameID is unstableGoogle Workspace is not returning a stable email-style principalMap the primary email to NameID and keep the preset default format.
Login redirects to the wrong placeACS or entity configuration driftedRe-check the ACS endpoint and entity ID values exposed by the host app.
Signed response rejectedThe configured certificate is stale or wrongRe-export the active certificate and update idp_certificates.

5. Day-2 notes

  • Re-check the certificate during rotation or tenant policy changes.
  • Keep metadata, auditability, telemetry, scheduled refresh, and diagnostics in the production follow-on plan after the first login works.
  • Treat any move beyond the shipped preset path as custom/generic SAML, not first-class Google Workspace support.