SSO Authentication Setup

Safeguard supports five identity provider (IdP) types for tenant sign-in: SAML 2.0, OpenID Connect (OIDC), and OAuth "social" login via Google, Microsoft, and GitHub. This page walks through configuring each, provider by provider.

Where to configure SSO

1. Sign in as a tenant Admin or Owner.
2. Go to Settings → Authentication.
3. Scroll to the Single Sign-On section.

From here you can:

• Add Provider — opens the Add Identity Provider dialog covered below.
• Test — verifies Safeguard can complete a round-trip with the provider.
• Delete — removes a provider (existing sessions created via that provider are not revoked automatically; users must sign in again on their next session).

The right-hand Policy panel controls what happens on first SSO login and whether password login stays available — see Provisioning policy below.

The URLs your IdP needs

Every provider type shares the same callback endpoint. When you save a SAML provider, Safeguard shows you:

These are generated automatically and shown in the dialog after you click Save — copy them directly from there rather than typing them by hand. For OIDC and social (Google/Microsoft/GitHub) providers, the Callback URL above is the same value you register as the "Redirect URI" / "Authorized redirect URI" on the provider's side.

If these URLs ever show http://localhost:... instead of https://api.safeguard.sh/..., do not paste them into your IdP — that means the auth service's public URL isn't configured correctly server-side. Contact Safeguard support rather than working around it.

---

SAML 2.0

Use this when your IdP is not Google, Microsoft, or GitHub, or when you specifically want a SAML (rather than OAuth) integration with one of those.

Generic steps (any SAML IdP)

1. In your IdP, create a new SAML application/integration.

2. Set the ACS URL (sometimes called Reply URL or Single Sign-On URL) to the Callback URL pattern above.

3. Set the Entity ID / Audience (SP entity ID) — Safeguard accepts any value here; most IdPs default to the ACS URL or a custom string like safeguard-sh. Use whatever your IdP proposes; you'll enter the IdP's entity ID (not this one) into Safeguard in the next step.

4. Set Name ID format to Email / EmailAddress, and map the Name ID to the user's email attribute.

5. From the IdP, collect three values: the SSO/Login URL, the Entity ID / Issuer, and the X.509 signing certificate (PEM format).

6. In Safeguard, click Add Provider → SAML 2.0 and fill in:

   Field	Value
   Alias	A short, URL-safe id, e.g. okta, entra, acme-sso (lowercase letters, numbers, hyphens only)
   Display Name	What users see on the login screen, e.g. "Sign in with Okta"
   SSO Service URL	The IdP's SSO/Login URL from step 5
   Entity ID	The IdP's Entity ID / Issuer from step 5
   X.509 Certificate	Paste the full PEM certificate, including -----BEGIN CERTIFICATE----- / -----END CERTIFICATE-----

7. Click Save. Copy the ACS URL and Metadata URL shown and paste the ACS URL back into your IdP's app configuration if you hadn't already (some IdPs let you finish setup before this URL exists — that's fine, just go back and update it now).

8. Assign users/groups to the app in your IdP.

9. Back in Safeguard, click Test next to the new provider.

Google Workspace (as SAML IdP)

Use this when you want Google Workspace itself to be the SAML identity provider (distinct from the "Sign in with Google" OAuth button — see Social login for that).

1. In Google Admin Console, go to Apps → Web and mobile apps → Add app → Add custom SAML app.
2. Name the app (e.g. "Safeguard") and click Continue.
3. On the Google IdP information screen, note the SSO URL, Entity ID, and download the Certificate. Click Continue.
4. On Service provider details, enter:
   • ACS URL: the Callback URL from Safeguard (https://api.safeguard.sh/auth/api/v1/sso/callback)
   • Entity ID: any value, e.g. safeguard-sh
   • Name ID format: EMAIL
   • Name ID: Basic Information → Primary email
5. On Attribute mapping, add rows for firstName → First name and lastName → Last name if you want those synced. Do not leave a half-filled row (an Application attribute typed in with no Google Directory attribute selected, or vice versa) — Google's admin console will reject the whole form with a generic 400 internal_error referencing schemaKey if you do. Delete any empty/incomplete row before saving.
6. Click Finish.
7. Back in Safeguard, click Add Provider → SAML 2.0 and enter the SSO URL, Entity ID, and Certificate from step 3, plus an alias/display name. Save.
8. In Google Admin Console, turn the app ON for everyone (or the specific org units you want), under User access.
9. Use Test SAML login in Google Admin, or Test in Safeguard, to confirm.

Microsoft Entra ID (Azure AD) — SAML

1. In the Microsoft Entra admin center, go to Enterprise applications → New application → Create your own application, choose "Integrate any other application you don't find in the gallery," and create it.
2. Open the app, go to Single sign-on → SAML.
3. Edit Basic SAML Configuration:
   • Identifier (Entity ID): any value, e.g. safeguard-sh
   • Reply URL (ACS URL): the Callback URL from Safeguard
4. Leave Attributes & Claims at defaults (email as the Name ID is Entra's default).
5. Under SAML Certificates, copy the Login URL, Microsoft Entra Identifier (Entity ID), and download the Certificate (Base64), or copy the App Federation Metadata URL if you'd rather import metadata directly.
6. In Safeguard, click Add Provider → SAML 2.0 and enter the Login URL, Entra Identifier, and certificate contents from step 5.
7. Back in Entra, go to Users and groups and assign the users/groups who should have access.
8. Click Test in Safeguard to confirm.

Okta — SAML

1. In the Okta admin console, go to Applications → Create App Integration → SAML 2.0.
2. Name the app and continue to Configure SAML:
   • Single sign on URL: the Callback URL from Safeguard
   • Audience URI (SP Entity ID): any value, e.g. safeguard-sh
   • Name ID format: EmailAddress
   • Application username: Email
3. Click Next, then Finish.
4. On the app's Sign On tab, click View SAML setup instructions (or download the Identity Provider metadata) to get the Identity Provider Single Sign-On URL, Identity Provider Issuer, and X.509 Certificate.
5. In Safeguard, click Add Provider → SAML 2.0 and enter those three values.
6. Back in Okta, go to the Assignments tab and assign people or groups.
7. Click Test in Safeguard to confirm.

OneLogin — SAML

1. In OneLogin, go to Applications → Add App, search for "SAML Custom Connector," and add it.
2. Under Configuration, set:
   • ACS (Consumer) URL: the Callback URL from Safeguard
   • Audience: any value, e.g. safeguard-sh
3. Under SSO, copy the SAML 2.0 Endpoint (HTTP), Issuer URL, and the X.509 Certificate.
4. In Safeguard, click Add Provider → SAML 2.0 and enter those three values.
5. In OneLogin, assign users under the app's Users tab.
6. Click Test in Safeguard to confirm.

---

OpenID Connect (OIDC)

Use this for any OIDC 1.0-compliant provider that isn't covered by the dedicated Google/Microsoft/GitHub social options below (for example, a self-hosted Keycloak, Auth0, or PingFederate instance).

1. In your IdP, register a new confidential OIDC client/application.

2. Set the Redirect URI to the Callback URL (https://api.safeguard.sh/auth/api/v1/sso/callback).

3. Collect the Authorization endpoint, Token endpoint, and UserInfo endpoint URLs (most providers publish these on a /.well-known/openid-configuration discovery document), plus the Client ID and Client Secret.

4. In Safeguard, click Add Provider → OpenID Connect and fill in:

   Field	Value
   Alias	URL-safe id, e.g. keycloak, auth0
   Display Name	Shown on the login screen
   Authorization URL	From step 3
   Token URL	From step 3
   User Info URL	From step 3
   Client ID	From step 3
   Client Secret	From step 3
   Default Scopes	Defaults to openid profile email — leave as-is unless your provider requires more

5. Click Save, then Test.

---

Social login providers (OAuth)

These use each provider's own OAuth flow (a "Sign in with Google/Microsoft/GitHub" button) rather than SAML. They're simpler to set up but give you less control over attribute mapping than SAML.

Google and Microsoft can each be connected either as a social OAuth login (below) or as a full SAML IdP (above) — pick one per provider based on whether you need SAML-specific features like Entra/Workspace group-based attribute mapping.

Google

1. In Google Cloud Console, go to APIs & Services → Credentials → Create Credentials → OAuth client ID.
2. Application type: Web application.
3. Under Authorized redirect URIs, add the Callback URL (https://api.safeguard.sh/auth/api/v1/sso/callback).
4. Create the client and copy the Client ID and Client Secret.
5. In Safeguard, click Add Provider → Google, paste in the Client ID and Client Secret, and Save.

Microsoft

1. In the Microsoft Entra admin center, go to App registrations → New registration.
2. Set Redirect URI (type Web) to the Callback URL.
3. Under Certificates & secrets, create a new client secret and copy its value immediately (it's only shown once).
4. Copy the Application (client) ID.
5. In Safeguard, click Add Provider → Microsoft, and enter:
   • Client ID
   • Client Secret
   • Azure Tenant (optional) — use common to allow any Microsoft account, organizations for any work/school account, or a specific tenant ID/domain to restrict sign-in to one organization.
6. Click Save.

GitHub

1. In GitHub, go to Settings → Developer settings → OAuth Apps → New OAuth App (for a GitHub organization, use the organization's own Developer settings instead).
2. Set Authorization callback URL to the Callback URL.
3. Click Register application, then Generate a new client secret.
4. In Safeguard, click Add Provider → GitHub, paste in the Client ID and generated Client Secret, and Save.

---

Provisioning policy

The Policy panel next to your provider list controls what happens when someone signs in via SSO for the first time:

Allow password login toggles whether users can still sign in with a password at all. Turn this off once SSO is fully rolled out to require SSO for every login.

Testing and troubleshooting

• Use the Test button next to a provider to verify Safeguard can reach it and complete a basic handshake, before rolling it out to your team.
• Google Admin shows 400. Error: internal_error mentioning schemaKey — this happens inside Google's own console, on the Attribute mapping step, and is unrelated to Safeguard. Remove any attribute-mapping row where only one side (Application attribute or Google Directory attribute) is filled in, then save again.
• The ACS/Callback/Metadata URLs shown after saving a provider point at localhost — this is a server-side misconfiguration, not something fixable from the UI. Contact Safeguard support.
• Redirected back with ?error=IDP_ERROR — the IdP itself rejected or errored on the login attempt; check the message query parameter for the IdP's error description.
• Redirected back with ?error=STATE_INVALID — the login attempt took too long, was replayed, or the browser lost its session state; have the user retry from the beginning.

Related

• RBAC, Teams & Organizations — roles, MFA, API keys, and how SSO fits into the broader identity/access model.
• Web Application — general web app login flow.