idp setup.md

Connect your IdP

Overview

This guide demonstrates how to integrate an Identity Provider (IdP) such as Okta or Entra ID with Barndoor to enable:

• SSO Login: Allow all users in your organization to authenticate via your IdP
• Automatic Role Mapping: Provision users as admins or standard users based on IdP group membership
• Centralized User Management: Onboard and offboard users directly from your IdP

Barndoor works with any OIDC or SAML 2.0 compatible IdP. If you use Okta or Microsoft Entra ID, follow the dedicated provider guide below for screenshots and provider-specific gotchas. Otherwise, use the generic flow on this page.

Choose your provider

• Okta (custom app): Manual Okta OIDC app registration, groups claim filter, and role mapping.
• Okta (OIN): Official Okta Integration Network app with SCIM provisioning.
• Microsoft Entra ID: Entra (Azure AD) app registration, issuer URL gotcha, and group claims.

Using a different IdP (Google Workspace, JumpCloud, OneLogin, Ping, etc.)? The generic OIDC / SAML 2.0 flow below applies to all of them.

Video Walkthrough

Prerequisites

• Admin access to your Barndoor account
• Admin access to your IdP (Okta, Entra, etc.)
• An IdP application configured with OIDC/OAuth or SAML 2.0

How it works

At a high level, connecting any IdP follows the same stages:

1. Configure the connection in Barndoor with your IdP's Issuer URL, Client ID, and Client Secret.
2. Verify SSO login works for a standard user.
3. Configure role mapping so IdP group membership provisions Barndoor admins automatically.
4. Test offboarding by removing a user from the admin group.
5. (Optional) Enforce organization-wide SSO and configure a break-glass emergency administrator.
6. (Optional) Remove the SSO connection when you need to disconnect.

The rest of this page walks through each stage generically. For provider-specific UI and screenshots, use the Okta custom app, Okta OIN, or Entra ID guides above.

Step 1: Configure IdP Connection in Barndoor

1. Navigate to Identity Provider Settings: Go here in your Barndoor dashboard.
2. Complete IdP Setup Form:
   • Provide a display name, such as your domain name.
   • From your IdP application collect:
     • Issuer URL: Your organization's Issuer URL
     • Client ID: OAuth client ID from your IdP app
     • Client Secret: OAuth client secret from your IdP app
       Auto discover will prefill your Authorization, Token, User Info, JWKS, and Logout URLs. If they are not autodiscovered, enter them manually.
3. Test the Connection: Click Test Connection to verify that Barndoor can communicate with your IdP.
   ✅ Expected result: "Connection successful" message
4. Save Configuration: Click Save to activate the IdP connection.

Step 2: Verify SSO Login Works

1. Log Out of Barndoor: Sign out of your current Barndoor session.
2. Attempt Login with Enterprise User: Try logging in with the enterprise test user from Step 1 using a user's email connected to your IdP.
   You should now be redirected to your IdP's login page.
3. Authenticate via IdP: Complete authentication through your IdP (enter credentials, complete MFA if required).
4. Verify Access to Barndoor: After successful IdP authentication, you should be logged into Barndoor.
   ✅ Expected result: User is logged in but has standard user permissions (not admin yet).

SSO is now working! Users can authenticate via your IdP.

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

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

Create Admin Group in IdP

1. Navigate to Groups in IdP: In your IdP (Okta/Entra ID), go to Directory → Groups.
2. Create or Select Admin Group: Create a new group called "Barndoor Admins" (or use an existing admin group).
3. 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.

Send IdP Groups to Barndoor

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

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.

1. Configure the groups claim: In your IdP application, add a groups claim with:
   • Claim name: groups
   • Claim values: Group display names, not group IDs
   • Included groups: At minimum, the group you want to map to Barndoor admin access, such as Barndoor Admins
2. Use your provider's exact steps: The way you emit the groups claim differs per IdP. Follow the dedicated guide for the precise UI:
   • Okta: add a groups claim filter
   • Entra ID: add a groups claim and set the group identifier
3. Verify the emitted claim: Use your IdP's token preview, logs, or a fresh test login to confirm the token or UserInfo response contains groups with the exact group name you will configure in Barndoor.

Map IdP Group to Barndoor Admin Role

1. Open Map groups to roles: On the Identity Provider page, open the Map groups to roles card for your SSO connection.
2. Configure Admin Group Mapping: Set the group name that defines administrators:
   • Admin Role Group Name: Enter Barndoor Admins (exact name from your IdP)
     Optionally enable IdP-Only Role Binding so roles can only be assigned through IdP group mappings (recommended for production SSO rollouts)
3. Save Role Mapping: Click Save Role Settings.
   ✅ Expected result: Role mapping saved successfully

Verify Role Provisioning

1. Log Out and Back In: Sign out of Barndoor and log back in with the test user.
2. 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

Role mapping is working! Users in the IdP admin group automatically receive admin permissions.

Step 4: Test User Offboarding (Remove Admin Access)

1. Remove User from Admin Group in IdP: In your IdP, go to Directory → Groups → Barndoor Admins.
   Remove the test user from the Barndoor Admins group.
2. Log Out and Back In: In Barndoor, sign out and log back in with the test user.
3. 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

Changes to IdP group membership are reflected immediately upon next login to Barndoor.

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 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.

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.

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:

1. 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.
2. 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.

Enable organization-wide SSO

1. Review the rollout card: When both prerequisites are complete, click Enforce SSO at the bottom of the rollout card.
2. Acknowledge each consequence: In the confirmation dialog, check every acknowledgement:
3. Confirm enforcement: Click Confirm Enforcement. On success, Barndoor shows SSO enforcement is active and prompts you to Sign out and sign in with SSO.

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.

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:

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.

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.

Troubleshooting

1. Test SSO sign-in pop-up blocked or closes early:
   Common causes:

   • Browser blocked pop-ups for the Barndoor site
     Solution: Allow pop-ups for your Barndoor portal origin, then click Test SSO sign-in again.

2. Break-glass email rejected on Save:
   Common causes:

   • Address is outside your organization's IdP email domain
     Solution: Use a dedicated emergency mailbox on your IdP domain that is not yet a Barndoor user.

3. Break-glass setup email not received:
   Solution: From the break-glass Manage dialog after enforcement, click Resend invite. Check spam filters and confirm the mailbox is monitored.

4. Enforcement succeeded with a warning:
   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.

Summary

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

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

Key Benefits

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