SSO with Okta.

A complete walkthrough from "I have an Okta tenant" to "everyone in my org signs in with SSO." Fifteen minutes if you have the Okta admin in the room.

Prerequisites

You need: Okta admin access, wrxstack workspace admin, and a domain you control. If your Okta is federated to another IdP, do this configuration in the IdP closest to your users.

Create the SAML app in Okta

In Okta, go to Applications → Create App Integration → SAML 2.0. Name the app "wrxstack."

1. Single sign-on URL: https://auth.wrxstack.com/sso/saml/<workspace>/acs
2. Audience URI (SP Entity ID): https://auth.wrxstack.com/sso/saml/<workspace>
3. Default RelayState: leave blank
4. Name ID format: EmailAddress
5. Application username: Email

Replace <workspace> with your subdomain (the part before .wrxstack.com). You'll find the exact URLs in Settings → SSO inside wrxstack.

Attribute mapping

wrxstack expects six SAML attributes. The first three are required; the last three power JIT provisioning.

email          → user.email
firstName      → user.firstName
lastName       → user.lastName
groups         → matches: regex(".*-wrxstack")  # optional
title          → user.title                     # optional
department     → user.department                # optional

The groups attribute is how role mapping happens. Create one Okta group per wrxstack role you want to grant, suffix the name with -wrxstack, and the regex above filters them in.

Paste the metadata into wrxstack

In Okta, the app's Sign On tab has an "Identity Provider metadata" link. Download the XML.

In wrxstack, Settings → SSO → SAML. Paste the metadata. Pick a default role for new users (we recommend member). Save.

Click "Test SAML" before you flip the switch. The test signs you in via Okta but only for the current session; nothing in production changes until you enable enforcement.

JIT provisioning

JIT creates a wrxstack user the first time someone signs in with a previously-unseen email. Cheap to enable, slightly harder to clean up.

If you enable JIT, configure a "default group" so new users land somewhere predictable. Don't default to admin. Ever.

Enforce SSO

When the test sign-in works, enable enforcement under Settings → SSO → Enforcement. Pick one of:

• Soft. Existing password sessions continue; new sign-ins must use SSO.
• Hard. All sessions are invalidated immediately. Users sign in fresh via Okta.

Most teams pick Soft for the first week, then Hard after every user has signed in via SSO at least once.

Break-glass admin

Always keep one admin account that bypasses SSO. We let you flag a single account in Settings → SSO as the break-glass identity. If Okta itself is down, that account still signs in with a password and a hardware token.

Next steps

• Permissions for the full identity model.