Setting Up SSO for Your AI Skills Registry

Why your team needs SSO for AI tools

AI coding tools are no longer optional infrastructure -- they are the primary way engineers write code. Cursor, Claude Code, Windsurf, and GitHub Copilot are in use across most engineering teams today. And wherever those tools go, your shared agent skills and rules go with them.

That creates a real security and governance problem. When anyone can sign up with a personal email and install your private skills, you lose control over who has access. An offboarded engineer can still pull your internal API conventions. A contractor can grab your proprietary prompt logic. There is no audit trail.

Single Sign-On (SSO) with SAML 2.0 solves this. It ties access to your skills registry directly to your existing identity provider -- Okta, Microsoft Entra ID, or Google Workspace. When an engineer joins, they get access automatically. When they leave, their access is revoked the moment IT disables their account. No manual de-provisioning step to forget.

This guide covers how to configure SAML 2.0 SSO for localskills.sh, step by step, for each major identity provider.

---

How SAML 2.0 SSO works

Before touching configuration screens, it helps to understand the flow:

1. An engineer visits localskills.sh and clicks "Sign in with SSO"
2. They enter their work email -- the domain is matched to your organization
3. They are redirected to your identity provider (Okta, Microsoft Entra ID, etc.)
4. The identity provider authenticates them and issues a SAML assertion
5. That assertion is posted back to localskills.sh, which validates it and creates a session

The key piece is the SAML assertion -- a signed XML document your IdP issues that proves the user's identity. localskills.sh validates the signature using your IdP's public certificate, so assertions cannot be forged.

Three things you need from your IdP:

• SSO URL -- where localskills.sh sends the authentication request
• Entity ID -- your IdP's unique identifier
• X.509 certificate -- for validating assertion signatures

And two things localskills.sh provides to your IdP:

• ACS URL -- where the IdP posts the SAML response (https://localskills.sh/auth/saml/callback)
• SP Entity ID -- https://localskills.sh

Understanding this exchange up front saves a lot of back-and-forth when something does not work. Most SSO configuration errors come down to a mismatch between what the IdP is sending and what localskills.sh is expecting. Keep these six values handy as you work through the setup steps below.

---

Configuring SSO with Okta

Okta is the most common enterprise IdP. Here is how to create the SAML application:

Step 1: Create a new SAML app in Okta

1. In the Okta Admin Console, go to Applications > Applications
2. Click Create App Integration
3. Select SAML 2.0 and click Next
4. Name the app "localskills.sh" and upload the logo if desired

Step 2: Configure SAML settings

In the Configure SAML tab, fill in:

Under Attribute Statements, add:

Step 3: Assign users and groups

1. Go to the Assignments tab
2. Assign the relevant groups (engineering, your entire org, or specific teams)
3. Okta will only allow assigned users to authenticate via SAML

Be deliberate about group assignments here. If you assign "Everyone," every Okta user in your org gets access to localskills.sh. For most teams, assigning specific engineering groups or a dedicated "AI Tools" group gives better control and makes it easier to audit who has access.

Step 4: Copy the IdP metadata

1. Go to the Sign On tab and click View SAML setup instructions
2. Copy:
   • Identity Provider Single Sign-On URL
   • Identity Provider Issuer (Entity ID)
   • X.509 Certificate

Step 5: Enter the details in localskills.sh

1. Go to your organization settings at https://localskills.sh/org/settings/sso
2. Select Okta as the provider
3. Paste the SSO URL, Entity ID, and certificate
4. Enter your email domain(s) -- e.g. acme.com
5. Click Test Connection -- you should see a successful authentication

Once the test passes, you can optionally enable domain enforcement so that all users with your company email are required to go through Okta instead of signing in with a password or Google OAuth.

---

Configuring SSO with Microsoft Entra ID

Microsoft Entra ID (formerly Azure AD) requires a slightly different setup because Microsoft uses a gallery-based app model.

Step 1: Create an Enterprise Application

1. In the Microsoft Entra admin center, go to Identity > Applications > Enterprise applications
2. Click New application > Create your own application
3. Name it "localskills.sh" and select Integrate any other application you don't find in the gallery (Non-gallery)

Step 2: Configure SAML

1. In the app, click Set up single sign-on and select SAML
2. Click the pencil icon on Basic SAML Configuration and fill in:

Identifier (Entity ID): https://localskills.sh
Reply URL (ACS URL):    https://localskills.sh/auth/saml/callback
Sign on URL (optional): https://localskills.sh

3. Under Attributes & Claims, click Edit. The default NameID claim uses user.userprincipalname -- change this to user.mail for email-based identity

Add additional claims:

The NameID change is important. Many Entra ID tenants have userprincipalname set to something like john.doe_contractor@tenant.onmicrosoft.com rather than the actual email address. Using user.mail ensures localskills.sh gets the right value for account matching.

Step 3: Download the certificate

Under SAML Certificates, download the Certificate (Base64).

Also copy the Login URL and Microsoft Entra Identifier from the Set up localskills.sh section.

Step 4: Assign users

1. Go to Users and groups in the app
2. Click Add user/group and assign the relevant Entra ID groups or individual users
3. Only assigned users will be able to authenticate

Step 5: Configure in localskills.sh

In your organization SSO settings, select Microsoft Entra ID, paste the Login URL, Entity ID, and certificate, and add your email domain.

---

Configuring SSO with Google Workspace

Google Workspace SSO uses a slightly different flow but the same SAML 2.0 protocol.

Step 1: Create a custom SAML app

1. In the Google Admin console, go to Apps > Web and mobile apps
2. Click Add app > Add custom SAML app
3. Name it "localskills.sh"

Step 2: Download IdP metadata

On the Google Identity Provider details screen, download the metadata XML or manually copy:

• SSO URL
• Entity ID
• Certificate

Step 3: Configure service provider details

Click Continue and fill in:

Step 4: Add attribute mapping

Click Continue and add attribute mappings:

Step 5: Turn on the app and configure in localskills.sh

Turn the app ON for the relevant organizational units. Then paste the SSO URL, Entity ID, and certificate into localskills.sh organization settings.

One note for Google Workspace: the app is off by default for all organizational units. If you have a flat org structure, you can turn it on at the top level. If you have contractors or external users in separate OUs, keep the app off for those units to avoid unintended access.

---

Email domain enforcement

Once SSO is configured, you can enforce it at the domain level. Any user signing up or signing in with an email address matching your registered domain(s) will be required to authenticate through SSO -- they cannot use a password or Google OAuth directly.

In your SSO settings:

Enforced domains: acme.com, acme.io

This closes the gap where an engineer might create a personal account before your organization was on SSO. When they next try to sign in with their @acme.com address, they will be redirected to your IdP automatically.

Domain enforcement also matters for security reviews. Auditors checking your access controls want to see that departing employees cannot retain access by logging in through an alternative method. With domain enforcement on, the only way in is through your IdP.

---

Automatic user provisioning

SSO handles authentication -- proving who someone is. But you also want provisioning -- automatically granting the right access when someone joins and revoking it when they leave.

This is where SCIM (System for Cross-domain Identity Management) comes in. With SCIM, your IdP pushes user and group changes to localskills.sh in real time:

• Engineer joins the company - account created, added to the right team
• Engineer moves to a different team - permissions updated automatically
• Engineer leaves - account deactivated, access to private skills revoked

Without SCIM, you rely on someone manually removing departed employees from your localskills.sh organization. That step gets missed. SCIM eliminates the manual process by making your IdP the single source of truth for who should have access.

See the full SCIM directory sync guide for setup instructions with Okta and Microsoft Entra ID.

---

Audit logging for compliance

With SSO in place, every authentication event flows through your identity provider and through localskills.sh's own audit log. This means you have a complete record of:

• Who authenticated and when
• What skills were installed or downloaded
• What changes were made to your organization's private skill library

This audit trail matters for SOC 2, ISO 27001, and other compliance frameworks. Your security team can export logs for review or send them to your SIEM via the localskills.sh audit logging and compliance features.

During a SOC 2 audit, you will typically need to show that access is tied to your HR system, that off-boarding removes access promptly, and that you have logs to prove it. SSO combined with SCIM and audit logging covers all three of those requirements.

---

Troubleshooting common SSO issues

"SAML response signature validation failed"

The certificate in your localskills.sh settings does not match what your IdP is currently signing with. IdPs rotate certificates periodically. Download the current certificate from your IdP and update it in your SSO settings.

"Invalid ACS URL"

Double-check that the ACS URL in your IdP is exactly https://localskills.sh/auth/saml/callback -- no trailing slash, correct protocol.

"User not found after authentication"

The email attribute in the SAML assertion does not match a localskills.sh account. Verify that your attribute mapping sends the email claim, and that the value matches what the user signed up with. This often happens with Microsoft Entra ID when userprincipalname differs from mail.

"Assigned users only" error in Okta

The user has not been assigned to the SAML app in Okta. Go to the app's Assignments tab and add the user or their group.

SSO redirect loop

This usually happens when the ACS URL is misconfigured or the SP Entity ID does not match. Use your browser's network inspector to capture the SAML POST and check the Destination attribute in the response.

Certificate expiration

X.509 certificates have expiration dates. When an IdP certificate expires, all SSO authentications will fail with a signature validation error. Set a calendar reminder to check your certificate expiration date, or configure your IdP to send renewal alerts. Most enterprise IdPs support automatic certificate rotation -- enable it if available.

---

Connecting SSO to team-level skill management

SSO is the foundation, but the full value comes when it connects to your team's skill library. With SSO enforced, you can:

• Publish private skills that only authenticated members of your org can install
• Use team namespaces so localskills install acme/api-conventions always resolves to your private registry
• Enforce team AI coding standards across Cursor, Claude Code, and Windsurf without relying on engineers to remember to authenticate

The CLI picks up your SSO session automatically after you log in once:

localskills login --sso
# Opens browser, redirects to your IdP, completes authentication
# Session persists for future CLI operations

After that, localskills install, localskills publish, and localskills pull all operate within your organization's access control -- no separate token management needed.

This is where SSO pays off beyond security. Engineers do not have to think about credentials or tokens. They log in once through the same IdP they use for everything else, and their access to your team's skills just works. New hires get the right skills on day one. Contractors get access limited to what their group is assigned. And when someone leaves, their access goes with them automatically.

---

Ready to lock down your team's AI skills with enterprise SSO? Set up your organization and connect your identity provider today.

Get started with SSO on localskills.sh

# Install the CLI
npm install -g @localskills/cli

# Log in with SSO (opens your IdP in the browser)
localskills login --sso

# Install your team's shared skills into Cursor, Claude Code, and Windsurf
localskills install your-org/coding-standards --target cursor claude windsurf