🔐Access Control

Overview

This guide explains how to turn on Single Sign‑On (SSO) and automated user provisioning for your company in Gangmates. It’s written for admins and business owners—no developer jargon needed.

Use Security → Access Control and switch between the SSO Config and Provisioning tabs.

Company examples used below: acme.com domain, Okta trial org, and default OIDC scope openid email profile—adjust to your tenant.

Quick Start (with screenshots)

SSO Config screen

Callouts:

  • Enable SSO ➜ turn On.

  • Protocol ➜ OIDC (recommended).

  • Apply Mode ➜ Domain only if you want SSO only for certain emails.

  • Match Domains ➜ add acme.com.

  • Issuer/Authorize/Token/UserInfo ➜ paste from your IdP (Okta examples shown).

  • Client ID/Secret ➜ from the IdP app.

  • Scope ➜ openid email profile (add offline_access only if you truly need refresh tokens).

Provisioning screen

Callouts:

  • Toggle Enable Provisioning.

  • Identity Provider ➜ pick Okta API or Microsoft Entra.

  • For Okta: domain like https://trial-000000.okta.com, API Token with user‑admin rights.

  • For Entra: keep Graph URL default, add Tenant ID, Client ID, Client Secret from your app registration.

  • Behavior Settings: turn on Auto‑Sync and Suspend/Deactivate options to mirror lifecycle changes.

Part A — SSO Configuration (Sign‑In)

Where: Security → Access Control → SSO Config → Edit

1) Turn it on

  • Toggle Enable SSO to On.

2) Pick a protocol

  • OIDC (recommended) — Works today. Choose this unless your IdP only supports SAML.

  • SAML — Available for future rollout. Use OIDC if possible.

3) Choose who must use SSO (Apply Mode)

  • Domain only — SSO applies only to people whose email matches selected domains (e.g., @acme.com).

  • All users — Everyone in the company uses SSO.

4) Select allowed email domains (Match Domains)

  • If you chose Domain only, pick one or more company domains—e.g., acme.com.

5) Enter identity provider (IdP) details (OIDC)

For Okta (example values):

  • Issuer: https://trial-00000.okta.com/oauth2/default

  • Authorize URL: https://trial-00000.okta.com/oauth2/default/authorize

  • Token URL: https://trial-00000.okta.com/oauth2/default/token

  • UserInfo URL: https://trial-00000.okta.com/oauth2/default/userinfo

  • Client ID: (from your Okta OIDC app)

  • Client Secret: (from your Okta OIDC app)

  • Scope: openid email profile

  • Login Hint Key: login_hint

For SAML (when enabled):

  • IdP Entity ID, SSO URL, X.509 Certificate from your IdP.

ACME tip: Start with Domain only + acme.com. Once everyone is confirmed, switch to All users if preferred.

Part B — Provisioning (Create/Update/Suspend accounts in your IdP)

Where: Security → Access Control → Provisioning → Edit

Provisioning lets Gangmates create and update user accounts in your IdP automatically so people can sign in immediately.

1) Turn it on

  • Toggle Enable Provisioning to On.

2) Choose your Identity Provider

Select one of the following and complete the fields shown.

Option A — Okta API

  • Okta Domain — Your Okta org URL without /api/v1 (e.g., https://acme.okta.com).

  • API Token — An Okta API token with enough rights to manage users.

How to create an Okta API token

  1. Okta Admin → Security → API → Tokens → Create token.

  2. Copy and paste the token here (store it securely).

  3. Best practice: create a “service admin” Okta user with the User Administrator role (or higher) and create the token from that account.

Option B — Microsoft Entra ID (Azure AD / Microsoft 365)

  • Microsoft Graph API URL — https://graph.microsoft.com/v1.0 (default).

  • Tenant ID (Directory ID) — Your tenant GUID.

  • Client ID (Application ID) — From the app registration.

  • Client Secret — From Certificates & secrets.

Set up steps (Entra App Registration)

  1. Azure Portal → Microsoft Entra ID → App registrations → New registration (Single‑tenant).

  2. Certificates & secrets → New client secret → copy the Value now (you can’t view it later).

  3. API permissions → Add a permission → Microsoft Graph → Application permissions → add:

    • User.ReadWrite.All

    • Directory.ReadWrite.All

    • (Optional) Group.ReadWrite.All

  4. Click Grant admin consent for the tenant.

  5. Paste Tenant ID / Client ID / Client Secret into Gangmates → Provisioning.

Note: If your security team requires Conditional Access for app credentials, coordinate exclusions for the service principal.

Option C — SCIM / Google / Custom API — SCIM / Google / Custom API

  • SCIM Base URL and Bearer Token (from your IdP).

  • Google Workspace and custom APIs require the base URL and token issued by the target directory platform.

3) Behavior Settings (what Gangmates should do in your IdP)

Toggle each setting based on your policy:

  1. Activate Users After Onboarding When a user finishes onboarding in Gangmates, mark their IdP account active.

  2. Activate in IDP When User Enabled Enabling a user in Gangmates also enables them in the IdP.

  3. Force Password Change on First Login New users must change password at first sign‑in (if supported by the IdP).

  4. Auto‑Sync Profile When Fields Change Changes to name/title/department/email in Gangmates are pushed to the IdP.

  5. Suspend in IDP When User Suspended Suspends their IdP account when suspended in Gangmates.

  6. Deactivate in IDP When Offboarded Deactivates the IdP account when you offboard in Gangmates.

  7. Delete from IDP on Account Deletion Permanently deletes the IdP account when you delete the user in Gangmates. Use with extreme caution.

Recommended starter policy (ACME): 1, 2, 4, 5, 6 ON; keep 3 optional; keep 7 OFF until your legal/HR policy approves permanent deletes.

4) Buttons you’ll use

  • Test Connection — Verifies your token/secret and API access.

  • Attribute Mapping — Map Gangmates fields (e.g., first_name) to IdP fields (e.g., givenName).

  • Bulk Sync Users — Push updates for many users at once.

  • Bulk Create Users — Create multiple accounts in your IdP from existing Gangmates users.

5) Attribute mapping (required fields by provider)

  • Okta: login, email, firstName, lastName

  • Microsoft Entra: userPrincipalName, mail, givenName, surname

  • Google Workspace: primaryEmail, name.givenName, name.familyName

Tip: Start with the suggested defaults, then add optional fields like department, title, or mobilePhone.

Quick Troubleshooting

  • SSO redirect loops / login fails:

    • Check Issuer/Authorize/Token/UserInfo URLs and make sure Client ID/Secret match your IdP app.

    • Ensure the user’s email domain is covered by Match Domains (or Apply Mode = All users).

  • Provisioning “Test Connection” fails:

    • Token/secret expired or insufficient permissions. Re‑issue token/secret and confirm permissions (see steps above).

  • User not appearing in IdP:

    • Make sure Enable Provisioning is on and mapping includes the provider’s required attributes.

    • Use Bulk Create Users if you want to provision existing staff in one go.

  • Profile changes not syncing:

    • Turn on Auto‑Sync Profile When Fields Change and re‑run Bulk Sync Users if needed.

Best Practices

  • Use a service account for tokens/secrets (not a personal admin) and rotate secrets regularly.

  • Start with a pilot group (Domain only) before switching to All users.

  • Keep a break‑glass admin login outside of SSO for emergencies.

  • Document who can approve / grant admin consent in Microsoft Entra and who can create Okta tokens.

Glossary

  • SSO (Single Sign‑On): One set of credentials to access multiple apps.

  • IdP (Identity Provider): The system that authenticates your users (Okta, Microsoft Entra, Google).

  • Provisioning: Automatically creating, updating, and disabling user accounts in your IdP.

  • OIDC/SAML: Industry standards used to connect your app to the IdP.

You’re done!

After you save SSO Config and Provisioning, click Test Connection, provision a test user, and sign in to confirm everything works. If you need help mapping attributes or choosing permissions, let us know what IdP you’re using and we’ll tailor the steps.

PreviousGangmates Data Retention & Archiving — Customer GuideNextConfigurations

Last updated