Single Sign-On (SSO)

Single Sign-On (SSO) allows your team to authenticate to define.wtf using their company credentials managed by your identity provider. From an integration perspective, SSO is about bridging define.wtf's authentication with your existing identity infrastructure.

SSO vs. SCIM: What's the Difference?

These are often confused because they're typically deployed together, but they serve different purposes:

Aspect	SSO	SCIM
What it does	Handles authentication (logging in)	Handles provisioning (creating/managing accounts)
Direction	User initiates by clicking "Sign in with Company"	Automatic sync from IdP to define.wtf
User involved?	Yes (user must log in)	No (automatic, user doesn't see it)
Credentials	User enters company credentials at IdP	Token-based API between systems
Timing	On-demand when user logs in	Scheduled or real-time syncing

Together they provide:

SSO: Your team logs in easily with company credentials
SCIM: Your team's accounts are created automatically

How SSO Works

User sees two login options:

Log in to define.wtf

[Sign in with Company]  OR  [Email/Password]

Browser redirects to your identity provider's login page.

3. User Authenticates

User enters their company credentials (email and password, plus MFA if configured).

4. IdP Grants Permission

IdP asks user: "define.wtf is requesting permission to access your profile. Allow?"

User clicks "Allow" (usually one-time only).

5. Redirect to define.wtf

User is redirected back to define.wtf with an authorization code.

6. Account Creation or Link

define.wtf checks if a user with this email exists:

Doesn't exist: Auto-create new user with profile data from IdP
Exists: Link the SSO login to existing account

7. User Logged In

User is now logged into define.wtf and sees the dashboard.

8. Next Time

Next time the user logs in, steps 2-7 repeat but faster (IdP skips re-asking for permission if it's recent).

Supported Identity Providers

SSO is implemented via Auth0, which supports:

Okta

Features:

Full OIDC support
Multi-factor authentication
Group membership (can be synced to define.wtf roles via SCIM)
Organization connections

User experience: Click "Sign in with Okta" → Enter Okta credentials → Logged in

Azure Active Directory (Azure AD / Entra ID)

Features:

Native OpenID Connect
Conditional access policies
Multi-factor authentication
Group membership sync

User experience: Click "Sign in with Azure AD" → Enter Azure credentials → Logged in

Google Workspace

Features:

OIDC via Google
Works for domain-managed Google Workspace accounts
Multi-factor authentication available

User experience: Click "Sign in with Google" → Consent screen → Logged in

OneLogin

Features:

Full OIDC support
Multi-factor authentication
Custom attributes

User experience: Click "Sign in with OneLogin" → OneLogin credentials → Logged in

Other OIDC Providers

Any OIDC-compliant provider can be configured (Ping Identity, Auth0, others).

What Gets Synced from IdP to define.wtf

When a user first logs in via SSO, these attributes are synced:

IdP Attribute	define.wtf Field	Example
email	Email	jane.doe@acme.com
given_name	First Name	Jane
family_name	Last Name	Doe
name	Full Name	Jane Doe

These attributes are stored on the user's profile and are used to display the user's name throughout define.wtf.

User Creation vs. Linking

When a user logs in via SSO for the first time:

define.wtf receives their email from IdP
Checks if a user with this email exists
If not, creates a new user account
Assigns default role (typically "Viewer")
Populates name from IdP

Result: User now has a define.wtf account and is logged in.

Existing User (Linking)

If a user already has a define.wtf account with the same email:

define.wtf receives their email from IdP
Checks if a user with this email exists
If yes, links SSO to existing account
Preserves existing role and settings
User is logged in with existing account

Result: User's existing account is now linked to their IdP identity.

User Role Assignment

When a user logs in via SSO:

First-time login — User is assigned the default role (typically Viewer)
Subsequent logins — Role remains as manually set by admin
Role changes — Admins can manually change roles in the Members section

To change a user's role:

Go to Admin → Members
Find the user
Click Actions → Change Role
Select new role and confirm

Note: Roles are not automatically assigned based on identity provider groups. Admins must manually manage role assignments.

Depending on your admin's configuration, users may see:

Option	Shown	Details
SSO only	✓ if configured; ✗ email/password hidden	Enterprise-only login
SSO + Email/Password	✓ both options visible	Flexible; users choose method
Email/Password only	✓ if SSO not configured	No SSO available

Most companies offer both SSO and email/password for flexibility and failover.

Security Features

define.wtf never sees your IdP credentials
Passwords are validated by your IdP only
define.wtf uses OpenID Connect tokens instead

Multi-Factor Authentication (MFA)

If your IdP enforces MFA:

MFA is checked at your IdP (not by define.wtf)
Users must complete MFA to log in to define.wtf
define.wtf respects your IdP's MFA policies

Session Management

define.wtf sessions are independent from IdP sessions
Logging out of define.wtf doesn't log out of IdP
IdP session timeouts don't automatically log users out of define.wtf (but next login will re-authenticate)

Audit Trail

All SSO login attempts are logged:

Timestamp
User email
IdP used
Success or failure
Login method

Use Cases

Enterprise Onboarding

New hire is added to company directory
Their email receives an onboarding email with define.wtf link
User clicks link and is taken to define.wtf login page
User clicks "Sign in with Company"
User auto-creates account if not already present
User is immediately productive without manual account creation

Compliance & Security

Your IT department manages all user access via one IdP
MFA policies are enforced at IdP level
Offboarding is automatic (when removed from IdP, next SSO attempt fails)
Audit trail shows exactly who logged in and when

Multiple Teams / Workspaces

If your organization runs multiple define.wtf workspaces:

Each workspace can be configured with SSO
Users log in to their workspace's login page with company credentials
All workspaces use the same IdP, reducing administrative overhead

Common SSO Scenarios

Scenario 1: Company Uses Okta

Admin sets up SSO in define.wtf and selects Okta
Admin enters Okta Client ID and Client Secret
Users see "Sign in with Okta" button
Users click it, enter Okta credentials
Users are logged into define.wtf
On next visit, users can click "Sign in with Okta" to log in immediately (if Okta session still valid)

Scenario 2: Company Uses Azure AD

Admin sets up SSO with Azure AD in define.wtf
Admin enters Azure app credentials
Users see "Sign in with Azure AD" button
Users click it, enter Azure credentials
If using a company device with Azure AD integration, may auto-complete
Users are logged into define.wtf

SSO is configured
Users see both "Sign in with Company" and "Email/Password" options
Some users prefer email/password (especially contractors or partners)
Some users prefer SSO (seamless experience)
Both methods work simultaneously

Troubleshooting SSO

SSO may not be configured; ask your admin
Try refreshing the login page
Try a different browser or incognito window

Check your IdP credentials (in case they changed)
Verify your IdP is working (log into the IdP directly)
If using a work device, ensure it's on your company network or VPN
Contact your admin with the error message

"I logged in but my name is wrong"

Check that your IdP profile has your full name set
Admin can manually update your profile in define.wtf if needed
Changes to your IdP profile will sync on next login

"I can't log in but my colleague can"

Check if your account exists in your IdP
If you were recently hired, wait a few minutes for SCIM provisioning to complete
If you were removed from the company, you'll see "User not found"
Contact your admin if you believe this is an error

"What if SSO doesn't work? Can I use email/password?"

If SSO is configured but unavailable, email/password option is usually still available
If you forgot your password, click "Forgot Password" to reset
Contact support if neither method works

Integrating SSO with Other Features

SCIM Provisioning

SSO and SCIM are complementary:

SCIM: Creates accounts automatically when users join
SSO: Authenticates those accounts with company credentials

Recommended setup: Enable SCIM first (auto-creates accounts), then enable SSO (users log in seamlessly).

Webhooks

When users log in via SSO, a webhook can be triggered:

{
  "event": "user.authenticated",
  "userId": "user-123",
  "email": "jane.doe@acme.com",
  "method": "sso",
  "provider": "okta"
}

Use webhooks to:

Sync login events to your SIEM
Trigger provisioning in other systems
Update activity logs in external dashboards

See: Webhooks & Automations

Migration from Email/Password to SSO

If your define.wtf workspace currently uses email/password:

Admin enables SSO (email/password remains available)
Users gradually switch to SSO
When users log in via SSO, their existing email/password accounts are linked
Eventually you can disable email/password if desired

This allows a gradual migration without disrupting existing users.

Limitations

One IdP per workspace: You can configure one identity provider per workspace
No custom attribute mapping: Only standard attributes (email, name) are synced
Session independent: Logging out of define.wtf doesn't affect your IdP session and vice versa

Security Best Practices

Keep credentials up to date — Rotate IdP client secrets regularly
Use MFA at IdP level — Enforce multi-factor authentication in your IdP
Monitor audit logs — Review SSO login attempts for suspicious activity
Audit user access — Regularly review which users have access to define.wtf
Offboard quickly — When employees leave, remove them from your IdP immediately

Single Sign-On (SSO) from an Integration Perspective

On this page