Single Sign-On (SSO)

Configure enterprise Single Sign-On (SSO) to allow your team to log in to define.wtf using their company credentials. Define.wtf supports OIDC (OpenID Connect) via Auth0, enabling integration with industry-standard identity providers.

What is SSO?

Single Sign-On lets your team:

• Log in with their company email address
• Use credentials managed by your identity provider (IdP)
• Avoid managing separate passwords
• Enable IT admins to enforce security policies at the IdP level
• Automatically provision new team members

Supported Identity Providers

Define.wtf supports OIDC via Auth0, which works with:

• Okta — Full support including org-wide provisioning
• Azure AD — Native OpenID Connect support
• Google Workspace — OIDC for domain-managed accounts
• OneLogin — OIDC provider support
• Ping Identity — Enterprise identity management
• SAML — SAML-to-OIDC bridge
• OIDC — Any OIDC-compliant provider
• ADFS — Active Directory Federation Services
• PingFederate — PingFederate identity platform
• Keycloak — Open-source identity provider
• Any OIDC-compliant provider — Custom setups supported

Self-Service SSO Setup Wizard

Define.wtf includes a self-service wizard to guide admins through SSO configuration. No technical support or manual configuration files needed.

Step 1: Access the SSO Setup Wizard

1. Navigate to Settings → Single Sign-On (SSO)
2. Click Configure SSO
3. A new tab will open with the Auth0 setup wizard

Step 2: Select Your Identity Provider

In the wizard, choose from:

• Okta — Select if you use Okta for workforce identity
• Azure AD — Select if you use Azure Active Directory (Entra ID)
• Google Workspace — Select if your team uses Google Workspace
• OneLogin — Select if you use OneLogin's identity platform
• Other OIDC Provider — For custom or unlisted providers
• SAML — For SAML-based identity providers
• ADFS — For Active Directory Federation Services
• PingFederate — For PingFederate deployments
• Keycloak — For Keycloak instances

Step 3: Follow the Setup Wizard

The wizard will guide you through:

1. Copy your define.wtf callback URL — You'll paste this in your IdP settings
2. Create an OIDC application in your IdP — Set it up with the callback URL
3. Copy your IdP credentials — Client ID and Client Secret from your IdP
4. Return to the wizard — Paste credentials and test the connection
5. Activate SSO — Once testing succeeds, SSO is live immediately

Wizard Details:

• Setup link is valid for 5 days
• Can be accessed up to 10 times
• Generate a new link if it expires

Using SSO to Log In

Once SSO is configured, users see a "Sign in with [Company Name]" button on the login page.

User Login Flow

1. User clicks "Sign in with Company"
2. User is redirected to your company's login page
3. User enters their company credentials
4. User grants permission for define.wtf to access their profile (one-time)
5. User is logged into define.wtf and returned to the dashboard

Automatic User Creation

When SSO is configured:

• First-time login: Users are automatically created in define.wtf with their IdP profile data
• Existing users: Users with matching email addresses are linked to existing define.wtf accounts
• Role assignment: New users are assigned the default role (typically "Viewer") — admins can promote as needed
• Workspace access: All SSO users have access to your workspace

Role and Group Management

Automatic Group Mapping (Optional)

If your IdP sends group data during SSO login, you can configure automatic role mapping:

To set up group mapping:

1. In Settings → SSO, find Group Mappings (if your platform supports it)
2. Add a new mapping: choose IdP group → select define.wtf role
3. When users log in, their roles are automatically set based on group membership
4. If a user is in multiple groups, the highest-privilege role is assigned

Manual Role Assignment

If automatic group mapping isn't configured:

1. After users log in via SSO, admins manually assign roles
2. Go to Settings → Members
3. Find the user and adjust their role as needed

Managing SSO

View SSO Status

In Settings → SSO, you can see:

• Status — Connected or Not configured
• Provider name — Which IdP is configured (e.g., "Okta", "Azure AD")
• Connection details — Provider information when configured

Reconfigure or Update SSO

To change your IdP or update configuration:

1. Go to Settings → SSO
2. Click Reconfigure SSO (if already configured) or Configure SSO (if not)
3. The setup wizard will open in a new tab
4. Follow the setup steps again with new credentials

SSO and SCIM Together

For the most seamless experience, combine SSO with SCIM provisioning:

• SCIM creates new user accounts as team members are added to your IdP
• SSO provides frictionless authentication for those accounts
• Together they eliminate manual user management entirely

Setup order:

1. Configure SSO first (allows manual login while you set up SCIM)
2. Configure SCIM (auto-provisions new users)
3. Test: Add a new user to your IdP, verify they appear in define.wtf and can log in

Troubleshooting

"Connection failed" during setup

• Verify Client ID and Client Secret are correct (no extra spaces)
• Ensure your IdP app is enabled/active
• Check that your IdP allows the callback URL

"Users can't log in after enabling SSO"

• Verify SSO is marked as Connected in Settings
• Check that users exist in your IdP
• Try logging out and refreshing the login page

"Groups not mapping correctly"

• Ensure your IdP is sending group data during login
• Verify group names match exactly (case-sensitive in most IdPs)
• Try removing and re-adding group mappings

"How do I keep manual login available after enabling SSO?"

• Define.wtf keeps manual email/password login available by default
• Users see both manual and SSO login options

Security Best Practices

• Keep credentials secure — Never share Client ID or Client Secret via email or chat
• Rotate secrets regularly — Refresh credentials every 6-12 months
• Disable unused providers — If switching IdPs, disable the old provider to prevent login confusion
• Monitor SSO usage — Check audit logs for failed login attempts
• Enforce MFA at IdP — Use your IdP's multi-factor authentication for additional security

Compliance and Audit

SSO logins are tracked in your audit trail:

• Login timestamp
• User email
• IdP used
• Success or failure status

This audit trail supports compliance requirements (SOC 2, HIPAA, etc.).