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

# Connect Okta as your IdP

> Step-by-step guide for configuring Okta as an OIDC Identity Provider for Barndoor SSO and automatic role mapping

## Overview

This guide walks you through configuring **Okta** as an OIDC Identity Provider for Barndoor. Once complete, your users will be able to sign in to Barndoor with their Okta credentials, and their group memberships will flow through for automatic role mapping.

<Note>
  **Prerequisites**:

  * Admin access to your Barndoor account
  * Admin access to your Okta org (Super Admin or an admin role that can create OIDC apps and edit groups)
  * An Okta OIDC (Web) application — you'll create one below
</Note>

<Info>
  For the generic, IdP-agnostic version of this flow (Entra ID, Google Workspace, JumpCloud, etc.), see the [Connect your IdP](/how-tos/idp-setup) overview.
</Info>

***

## Step 1: Configure IdP Connection in Barndoor

<Steps>
  <Step title="Navigate to Identity Provider Settings">
    Go [here](https://app.barndoor.ai/idp) in your Barndoor dashboard and start the **Set up single sign-on (SSO)** flow.
  </Step>

  <Step title="Complete IdP Setup Form">
    * Provide a display name, such as your domain name (e.g. `Okta — Acme Corp`).

    From your Okta OIDC application collect:

    * **Issuer URL**: Your Okta org URL, e.g. `https://<your-org>.okta.com`
    * **Client ID**: OAuth client ID from your Okta app
    * **Client Secret**: OAuth client secret from your Okta app

    <Tip>Auto discover will prefill your Authorization, Token, User Info, JWKS, and Logout URLs. If they are not autodiscovered, enter them manually.</Tip>
  </Step>

  <Step title="Test the Connection">
    Click **Test Connection** to verify that Barndoor can communicate with Okta.

    ✅ **Expected result**: "Connection successful" message
  </Step>

  <Step title="Save Configuration">
    Click **Save** to activate the IdP connection. Barndoor will reveal the **Redirect URI** for your Okta app — copy it into your Okta application's **Sign-in redirect URIs**.
  </Step>
</Steps>

***

## Step 2: Verify SSO Login Works

<Steps>
  <Step title="Log Out of Barndoor">
    Sign out of your current Barndoor session.
  </Step>

  <Step title="Attempt Login with Enterprise User">
    Try logging in with the enterprise test user from Step 1 using a user's email connected to Okta.

    You should now be redirected to Okta's login page.
  </Step>

  <Step title="Authenticate via Okta">
    Complete authentication through Okta (enter credentials, complete MFA if required).
  </Step>

  <Step title="Verify Access to Barndoor">
    After successful Okta authentication, you should be logged into Barndoor.

    ✅ **Expected result**: User is logged in but has **standard user** permissions (not admin yet).
  </Step>
</Steps>

<Check>
  SSO is now working! Users can authenticate via Okta.
</Check>

***

## Step 3: Configure Role Mapping (Auto-Provision Admins)

Now we'll set up automatic role assignment based on Okta group membership.

### Create Admin Group in Okta

<Steps>
  <Step title="Navigate to Groups in Okta">
    In the Okta Admin Console, go to **Directory** → **Groups**.
  </Step>

  <Step title="Create or Select Admin Group">
    Create a new group called **"Barndoor Admins"** (or use an existing admin group).
  </Step>

  <Step title="Assign Users to Admin Group">
    Add the test user to the **Barndoor Admins** group.

    💡 **Note**: Any user in this group will automatically receive admin permissions in Barndoor.
  </Step>
</Steps>

### Send Okta Groups to Barndoor

Barndoor can only map roles and evaluate group-based policies when Okta sends group names during login. For OIDC connections, include a claim named exactly `groups` in the ID token or UserInfo response.

<Warning>
  Role mappings are synced on login. If the mapped group claim is missing or does not match exactly, the corresponding Barndoor role can be removed the next time the user signs in.
</Warning>

<Steps>
  <Step title="Add a groups claim filter in Okta">
    In Okta, open the Barndoor OIDC application and go to **Sign On** → **OpenID Connect ID Token** → **Token claims** (if needed, expand **Show legacy configuration** and set **Group Claims**):

    * **Groups claim type**: `Filter`
    * **Groups claim filter**: `groups`
    * **Match type**: `Matches regex`
    * **Regex**: `^Barndoor Admins$`

    This emits a claim like:

    ```json theme={null}
    {
      "groups": ["Barndoor Admins"]
    }
    ```

    <Tip>
      Use `.*` as the regex if you want Okta to emit every group the user belongs to. Use a tighter regex (as above) to keep the token small and limit exposure to just the groups Barndoor needs.
    </Tip>
  </Step>

  <Step title="Verify the emitted claim">
    Use Okta's **Token Preview** tab (on the application's **Sign On** page), the System Log, or a fresh test login to confirm the token or UserInfo response contains `groups` with the exact group name you will configure in Barndoor.
  </Step>
</Steps>

### Map Okta Group to Barndoor Admin Role

<Steps>
  <Step title="Open Map groups to roles">
    On the [Identity Provider](https://app.barndoor.ai/idp) page, open the **Map groups to roles** card for your SSO connection.
  </Step>

  <Step title="Configure Admin Group Mapping">
    Set the group name that defines administrators:

    * **Admin Role Group Name**: Enter `Barndoor Admins` (exact name from Okta)
    * Optionally enable **IdP-Only Role Binding** so roles can only be assigned through IdP group mappings
  </Step>

  <Step title="Save Role Mapping">
    Click **Save Role Settings**.

    ✅ **Expected result**: "Role mapping saved successfully" message
  </Step>
</Steps>

### Verify Role Provisioning

<Steps>
  <Step title="Log Out and Back In">
    Sign out of Barndoor and log back in with the test user.
  </Step>

  <Step title="Verify Admin Access">
    After logging in, confirm:

    * ✅ User now has **Admin** role
    * ✅ Additional admin functionality is visible in the UI
    * ✅ User appears in the **Barndoor Admins** user group
  </Step>
</Steps>

<Check>
  Role mapping is working! Users in the Okta admin group automatically receive admin permissions.
</Check>

***

## Step 4: Test User Offboarding (Remove Admin Access)

<Steps>
  <Step title="Remove User from Admin Group in Okta">
    In Okta, go to **Directory** → **Groups** → **Barndoor Admins**.

    Remove the test user from the **Barndoor Admins** group.
  </Step>

  <Step title="Log Out and Back In">
    In Barndoor, sign out and log back in with the test user.
  </Step>

  <Step title="Verify Standard User Access">
    Confirm that:

    * ✅ User is now a **standard user** (no longer admin)
    * ✅ Admin-only functionality is no longer visible
    * ✅ User group reflects the change
  </Step>
</Steps>

<Info>
  Changes to Okta group membership are reflected immediately upon next login to Barndoor.
</Info>

***

## Roll out SSO enforcement

After your IdP connection is saved and SSO sign-in works, the **Roll out SSO enforcement** section on the [Identity Provider](https://app.barndoor.ai/idp) page lets you require SSO for every member of your organization. Until you enforce SSO, users can still sign in with Barndoor passwords in addition to your IdP.

<Info>
  If you don't see **Roll out SSO enforcement** controls on the Identity Provider page, organization-wide SSO enforcement may not be enabled for your workspace yet. Contact your Barndoor account team.
</Info>

<Warning>
  **Enforcing SSO is irreversible in production.** It permanently clears Barndoor passwords for all members, terminates every active session (including yours), and requires all future logins through your IdP—except the dedicated break-glass account described below.
</Warning>

### What changes when you enforce SSO

When you confirm enforcement, Barndoor:

* Requires all organization members to sign in through your IdP
* Permanently clears saved Barndoor passwords for every member
* Leaves password sign-in enabled **only** for the break-glass admin email you configure
* Terminates all active sessions, including the administrator who enabled enforcement

After enforcement succeeds, sign out and sign back in through your IdP to continue working as an administrator.

### Prerequisites

Both items in **Before you can enforce SSO** must be complete before **Enforce SSO** is enabled:

<Steps>
  <Step title="Test SSO sign-in">
    Click **Test SSO sign-in**. Barndoor opens a pop-up window and runs the full IdP login path—not just a connection preflight.

    Complete authentication in the pop-up. When the test succeeds, the row is marked complete. You can run the test again anytime to confirm sign-in still works.

    <Tip>
      If the pop-up is blocked, allow pop-ups for the Barndoor site and run the test again.
    </Tip>
  </Step>

  <Step title="Configure break-glass admin email">
    Click **Manage** on the **Break-glass admin email** row and set an emergency mailbox your security or platform team can use if your IdP is unavailable.

    * The address must use your organization's IdP email domain (shown as `@your-domain` in the dialog)
    * It must **not** already belong to an existing Barndoor user
    * You **cannot** use your own administrator email as the break-glass account

    Click **Save**. Barndoor stores the address as the configured break-glass email. The dedicated break-glass user account is created when you enforce SSO.
  </Step>
</Steps>

### Enable organization-wide SSO

<Steps>
  <Step title="Review the rollout card">
    When both prerequisites are complete, click **Enforce SSO** at the bottom of the rollout card.
  </Step>

  <Step title="Acknowledge each consequence">
    In the confirmation dialog, check every acknowledgement:

    * Future logins will be exclusively via IdP SSO
    * All Barndoor passwords will be permanently cleared
    * Only your break-glass email will be able to sign in via password going forward
    * All active sessions—including your current one—will be terminated

    The dialog also shows your IdP connection name and redirect URI for a final sanity check.
  </Step>

  <Step title="Confirm enforcement">
    Click **Confirm Enforcement**. On success, Barndoor shows **SSO enforcement is active** and prompts you to **Sign out and sign in with SSO**.

    <Note>
      If enforcement succeeds but Barndoor shows a warning that not all member passwords were cleared or sessions could not be terminated, SSO enforcement is still active. Sign out and sign in again with SSO, verify member access, and contact support if the warning persists.
    </Note>
  </Step>
</Steps>

<Check>
  SSO enforcement is active. All organization members must sign in through your Identity Provider. Password login is disabled for everyone except the break-glass account.
</Check>

### Set up the break-glass account

When enforcement completes, Barndoor provisions a dedicated **Barndoor Break Glass** administrator account at the email you configured and sends a setup email to that mailbox. The recipient must:

1. Open the setup email and follow the link to set a password
2. At first sign-in, complete the email one-time passcode (OTP) sent to that mailbox—the same second factor used during an IdP outage

Store break-glass credentials in your organization's secure emergency-access process (for example, a sealed envelope or privileged-access vault)—not in shared chat or email threads.

### Manage break-glass access after enforcement

After SSO is enforced, the rollout card shows **SSO enforcement** as active and lets you manage the break-glass email:

* **Resend invite** — If the break-glass account has not finished password setup, resend the setup email from the break-glass dialog
* **Change break-glass email** — Opens a destructive change flow. Enter the new address, check the acknowledgement that the current account will lose password sign-in, then click **Save**. The new mailbox must complete password and OTP setup before it can be used

<Warning>
  Changing the break-glass email while SSO is enforced removes the previous break-glass account's password credentials and requires the new mailbox to complete setup from scratch.
</Warning>

### Sign in with break-glass during an IdP outage

If your IdP is unavailable and you need emergency administrator access:

1. On the Barndoor sign-in page, choose password sign-in (not SSO)
2. Enter the break-glass email address and password
3. Complete the email one-time passcode sent to that mailbox

Password sign-in and email OTP at login are available **only** for the break-glass account once SSO is enforced. All other members must use IdP SSO.

### Remove the SSO connection (optional)

To disconnect IdP integration before or after enforcement, open the **actions menu** (⋯) on the rollout card and choose **Remove SSO**. Confirm when prompted.

<Warning>
  Removing the SSO connection immediately revokes IdP-based access for your organization. Only users who can still authenticate with a Barndoor password—including the break-glass account, if configured—can sign in. SSO enforcement remains on for the organization; re-connecting an IdP does not restore member password login.
</Warning>

### SSO enforcement troubleshooting

<AccordionGroup>
  <Accordion title="Test SSO sign-in pop-up blocked or closes early" icon="window-restore">
    **Common causes:**

    * Browser blocked pop-ups for the Barndoor site
    * The sign-in window was closed before authentication finished

    **Solution:** Allow pop-ups for your Barndoor portal origin, then click **Test SSO sign-in** again. If the test times out, cancel and retry.
  </Accordion>

  <Accordion title="Break-glass email rejected on Save" icon="envelope">
    **Common causes:**

    * Address is outside your organization's IdP email domain
    * Address already belongs to an existing Barndoor user
    * You entered your own administrator email

    **Solution:** Use a dedicated emergency mailbox on your IdP domain that is not yet a Barndoor user. Enter only the part before `@`—the domain is shown in the dialog.
  </Accordion>

  <Accordion title="Break-glass setup email not received" icon="paper-plane">
    **Solution:** From the break-glass **Manage** dialog after enforcement, click **Resend invite**. Check spam filters and confirm the mailbox is monitored. The recipient must complete password setup from the link before the account can sign in.
  </Accordion>

  <Accordion title="Enforcement succeeded with a warning" icon="triangle-exclamation">
    **Cause:** SSO enforcement is active, but Barndoor could not clear every member password or terminate every session.

    **Solution:** Sign out and sign back in with SSO. Verify affected members can still reach the app through your IdP. Contact Barndoor support if the warning remains or members report unexpected password login.
  </Accordion>
</AccordionGroup>

***

## Summary

You've successfully configured Okta integration with Barndoor! Here's what you accomplished:

✅ **Connected Okta** for SSO/OIDC authentication\
✅ **Enabled automatic role provisioning** based on Okta groups\
✅ **Tested user onboarding** (SSO login and admin access)\
✅ **Tested user offboarding** (removed admin access via Okta)\
✅ **(Optional) Enforced organization-wide SSO** with a break-glass emergency account

### Key Benefits

**Centralized authentication**: Users log in via Okta
**Automated role management**: No manual user provisioning needed
**Streamlined onboarding**: New employees automatically get access
**Instant offboarding**: Removing users from Okta immediately revokes access

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="SSO Login Redirects but Fails" icon="circle-xmark">
    **Common causes:**

    * Incorrect Client ID or Client Secret
    * Okta app not configured with the correct sign-in redirect URI
    * OIDC endpoints not properly discovered
    * Domain mismatch

    **Solution**: Double-check credentials in both Barndoor and Okta. Confirm the **Sign-in redirect URI** in Okta exactly matches the Redirect URI Barndoor generated. Re-test the connection and review the Okta System Log.
  </Accordion>

  <Accordion title="Role Mapping Not Working" icon="user-slash">
    **Common causes:**

    * Group name mismatch (case-sensitive)
    * User not actually in the Okta group
    * OIDC `groups` claim is missing from the ID token or UserInfo response
    * Okta sends group IDs or a different claim name instead of the group display name
    * Role mapping not saved properly

    **Solution**: Verify the exact group name in Okta matches the Barndoor configuration. Confirm user membership in the Okta group. Use Okta's **Token Preview** to confirm the token includes `groups` with the expected value, such as `Barndoor Admins`. Re-save role mapping settings and have the user sign out and back in.
  </Accordion>

  <Accordion title="Users Can't Access After Okta Connection">
    **Common causes:**

    * Users not assigned to the Okta application
    * Okta application deactivated or suspended
    * Network/firewall blocking communication

    **Solution**: Verify users are assigned to the Barndoor application in Okta (**Applications** → Barndoor app → **Assignments**). Check the Okta app status. Test the connection from Barndoor settings.
  </Accordion>
</AccordionGroup>

***

## Recap

| Value                                      | Where it comes from                          | Where it goes                              |
| :----------------------------------------- | :------------------------------------------- | :----------------------------------------- |
| Client ID                                  | Okta app → General → Client Credentials      | Barndoor Client ID                         |
| Client Secret                              | Okta app → General → Client Credentials      | Barndoor Client Secret                     |
| Issuer URL (`https://<your-org>.okta.com`) | Okta org URL                                 | Barndoor Issuer URL                        |
| Redirect URI                               | Barndoor SSO setup                           | Okta app → General → Sign-in redirect URIs |
| `groups` claim filter                      | Okta app → Sign On → OpenID Connect ID Token | Emitted in token for Barndoor role mapping |

You've now connected Okta to Barndoor for SSO and automatic role provisioning.