---
title: "SSO / SAML 2.0"
description: "Configure SAML 2.0 Single Sign-On for localskills.sh with Okta, Azure AD, Google Workspace, and other identity providers."
---

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

# SSO / SAML 2.0

Enterprise organizations can configure SAML 2.0 SSO for centralized
authentication.

## Overview

localskills.sh acts as a SAML Service Provider (SP). It supports any SAML
2.0–compliant identity provider, including Okta, Azure AD, Google Workspace,
and OneLogin.

Configuring SSO requires the **organization owner** role. Configuration lives
under **Organization > SSO & SCIM**.

## SP configuration

Provide the following values to your identity provider. Replace `{providerId}`
with the provider ID from the SSO settings page.

**Entity ID** (also the SP metadata URL)

```text
https://localskills.sh/api/auth/sso/saml2/sp/metadata?providerId={providerId}
```

**ACS URL**

```text
https://localskills.sh/api/auth/sso/saml2/sp/acs/{providerId}
```

The ACS URL doubles as the SAML callback: if your identity provider asks for a
separate callback or reply URL, use the ACS URL. The SSO settings page shows
both values for your organization with copy buttons.

## IdP setup

Configure an SSO provider from your organization's **SSO & SCIM** tab. Pick
your identity provider (pre-built templates cover **Okta**, **Cloudflare
Access**, and **Authentik**, plus a generic template for any other SAML 2.0
IdP) and follow that provider's guide below to create the app on the IdP side.
Each template presets the right attribute mapping and groups attribute for that
provider.

Then connect it by pasting the IdP's **metadata XML** (recommended; the issuer,
sign-in URL, and signing certificate are extracted automatically), or enter the
SSO URL, issuer, and certificate manually. Finish with one or more email
domains. The provider ID embedded in the SP URLs is assigned automatically and
never changes.

For exotic setups (encrypted assertions, signed requests, custom attribute
mapping) the **JSON (advanced)** tab still accepts the full Better Auth SAML
configuration.

## Provider guides

## Email domains

Whitelist one or more email domains for SSO (e.g. `example.com`). Only users
with matching email domains can sign in via SAML.

Each domain must be **verified** before sign-in routes to SSO: add the TXT
record shown on the SSO settings page with the record name set to the claimed
domain (host `@` for a zone apex), then click Check Now. Unverified domains
never trigger SSO auto-detection.

Multiple domains are supported; verify each one. A domain can only be verified
by one organization at a time.

## Sign-in flow

Users start SSO by entering an email address on the sign-in page. When the
domain matches a configured provider with a verified domain, localskills.sh
redirects them to your identity provider. First-time SSO users are provisioned
into the organization automatically (audit events `sso.user_created` and
`sso.login_success`).

## Group → team mapping

Map identity-provider groups to localskills.sh teams from the **SSO & SCIM**
tab. On every SSO login, the member's team membership is reconciled from the
IdP's groups attribute: they are added to teams whose mapped group they hold
and removed from mapped teams whose group is gone. Teams without a mapping are
never touched.

Because teams carry roles, this is how IdP group membership translates into
permissions; see [Organizations & Teams](/teams) and
[Roles & Permissions](/roles). Syncs are audited as `sso.team_sync` and mapping
changes as `sso.group_mappings_updated`.

> **Note**
>
> All SSO configuration changes are tracked in the organization audit log.

Source: https://docs.localskills.sh/sso/index.mdx