> ## Documentation Index
> Fetch the complete documentation index at: https://docs.golf.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO Connections

> Configure platform SSO and user management for your organization

Golf provides flexible options for managing user access to your organization. You can use Golf's built-in user management or connect to your existing identity provider for enterprise SSO and automatic group synchronization.

## User Management Options

### Option 1: Golf User Management

Use Golf's built-in user management to invite and manage users directly:

1. Navigate to **Settings** > **Users**
2. Click **Invite user**
3. Enter the user's email address
4. Select a role (Admin or Member)
5. Click **Send invitation**

The user receives an email invitation and can join your organization after accepting.

**Roles:**

| Role   | Permissions                                  |
| ------ | -------------------------------------------- |
| Admin  | Manage users, gateways, and all settings     |
| Member | View and use MCP servers from the dev portal |

### Option 2: Connect to Your Identity Provider

For enterprise SSO, connect your organization to an external identity provider. This enables:

* Single sign-on with your corporate credentials
* Automatic user provisioning
* Group synchronization for RBAC policies

To configure SSO:

1. Navigate to **Settings** > **Organization**
2. Find the **SSO Configuration** section
3. Click **Configure SSO** to open the setup portal
4. Follow the guided setup to connect your identity provider

Supported identity providers include SAML-based providers and OAuth/OIDC providers like Microsoft Entra ID, Okta, and Google Workspace.

## Identity and NameID

Golf identifies and authorizes every SSO user by their **email address**. When a user authenticates, Golf reads the email claim from the SSO assertion and uses it as the canonical identity: it is the key for organization membership and for resolving the security groups that authorize access (whether groups come from Directory Sync or your identity provider's directory).

### Recommended NameID

Configure your identity provider to send the user's **email address** as the SSO NameID.

The value Golf receives as the email claim must exactly match the email recorded for that user in the directory that supplies their group membership (matching is case-insensitive). Golf does **not** authorize on `userPrincipalName` (UPN), object ID, or any alternate identifier — only the email claim is used for group resolution.

### Attribute mapping

Golf consumes the standard SSO profile attribute mapping. All four attributes are **required**. Map each Golf attribute to the corresponding claim your identity provider emits.

| Golf attribute | Microsoft Entra ID (SAML claim URI)                                  | Okta                  | Google Workspace      |
| -------------- | -------------------------------------------------------------------- | --------------------- | --------------------- |
| `idpId`        | `http://schemas.microsoft.com/identity/claims/objectidentifier`      | *Details coming soon* | *Details coming soon* |
| `email`        | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | *Details coming soon* | *Details coming soon* |
| `firstName`    | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`    | *Details coming soon* | *Details coming soon* |
| `lastName`     | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`      | *Details coming soon* | *Details coming soon* |

<Note>
  For OIDC providers, the equivalent claims are `email` (→ `email`), `given_name` (→ `firstName`), `family_name` (→ `lastName`), and `sub` or `oid` (→ `idpId`). Authorization always keys on the resolved email regardless of protocol.
</Note>

## Group Synchronization

When connected to an identity provider, Golf Gateway can automatically sync user groups for use in RBAC policies.

### How Group Sync Works

1. Users authenticate via your identity provider
2. Gateway retrieves the user's group memberships
3. Groups are available for Server RBAC and Capability RBAC policies

### Configuring Group Sync

Group sync configuration depends on your identity provider:

<Tabs>
  <Tab title="Microsoft Entra ID">
    When using Microsoft Entra ID for SSO, group synchronization is automatic via directory sync (SCIM). Groups are synced in real-time as changes occur in your directory.

    **Setup:**

    1. Navigate to **Settings** > **Organization**
    2. Click **Configure SSO** and complete the Entra ID setup
    3. Enable directory sync in the setup portal
    4. Select which groups to sync

    Groups appear automatically in RBAC policy dropdowns.
  </Tab>

  <Tab title="Auth0 / Descope">
    For Auth0 or Descope, configure Management API credentials to enable group fetching:

    1. Navigate to **Settings** > **Organization**
    2. Find **Group Sync Configuration**
    3. Enter your Management API credentials:
       * **Auth0**: M2M application Client ID and Secret
       * **Descope**: Management Key
    4. Click **Save**

    The gateway fetches groups on-demand during user authentication.
  </Tab>
</Tabs>

### Using Groups in RBAC

Once group sync is configured, use groups in your access policies:

**Server RBAC:**

* Set `allowed_groups` to restrict server access to specific groups
* Set `denied_groups` to block specific groups from accessing a server

**Capability RBAC:**

* Assign groups to individual tools, prompts, or resources
* Use annotation-based policies to apply group restrictions based on tool characteristics (read-only, destructive, etc.)

See [Set Up Server RBAC](/gateway/guides/security/setup-server-rbac) and [Set Up Capability RBAC](/gateway/guides/security/setup-capability-rbac) for detailed configuration.

## Troubleshooting

### Users can't sign in with SSO

* Verify SSO is correctly configured in **Settings** > **Organization**
* Check that the user exists in your identity provider
* Ensure the user's email domain matches your organization's verified domain

### Groups not appearing in RBAC policies

* For Entra ID: Verify directory sync is enabled and the groups are selected for sync
* For Auth0/Descope: Check that Management API credentials are correctly configured
* Allow a few minutes for group changes to propagate

### User has wrong permissions

* Verify the user's group memberships in your identity provider
* Check that RBAC policies reference the correct group names (case-sensitive)
* Review the policy hierarchy: organization → gateway → server

## Next Steps

* [Configure Identity Provider](/gateway/guides/identity-providers/configure-idp) - Set up IdP for MCP client authentication
* [Set Up Server RBAC](/gateway/guides/security/setup-server-rbac) - Control server access based on groups
* [Set Up Capability RBAC](/gateway/guides/security/setup-capability-rbac) - Fine-grained tool permissions