Single Sign-On (SSO)

Oh Dear supports SAML 2.0 Single Sign-On so your team can authenticate through your organization's identity provider (IdP). This means your team members sign in with their existing corporate credentials, and you can manage access centrally from your IdP.

SSO is available on all plans. Each team can connect one identity provider.

Overview #

Here's how SSO works in Oh Dear:

1. Verify your domain - Prove you own your email domain by adding a DNS TXT record
2. Configure your IdP - Connect your identity provider to Oh Dear using SAML 2.0
3. Test the connection - Verify everything works with a test login
4. Enable SSO - Turn on SSO for your team
5. Link existing members - Team members connect their accounts through a one-time email link

Once enabled, your team members will see an email-first login flow. They enter their email address, and Oh Dear automatically redirects them to your IdP. After authenticating there, they're signed into Oh Dear.

Getting started #

Step 1: Verify your domain #

Before configuring SSO, you need to prove that your organization owns the email domain you want to use.

1. Go to Team Settings > Single Sign-On
2. Enter your domain (e.g., yourcompany.com) and click Add domain
3. Copy the DNS TXT verification token shown on screen
4. Add a TXT record to your domain's DNS with that token
5. Click Verify to check the record

DNS changes can take a few minutes to propagate. If verification fails, wait a bit and try again.

A few things to keep in mind about domain verification:

• Each domain can only be verified by one team across all of Oh Dear
• Public email domains (gmail.com, outlook.com, yahoo.com, etc.) cannot be used
• You can verify multiple domains if your organization uses more than one

Step 2: Configure your identity provider #

After verifying your domain, click Configure to set up your identity provider. Oh Dear provides guided setup instructions for these providers:

• Okta
• Microsoft Entra ID
• Google Workspace
• OneLogin
• JumpCloud
• Auth0
• PingFederate
• Other SAML 2.0 providers

Select your provider on the configuration page to see step-by-step instructions. Oh Dear displays all the values you need to enter in your IdP, with copy buttons for convenience.

Your IdP will need these values from Oh Dear:

• ACS URL (Assertion Consumer Service URL) - Where your IdP sends the SAML response
• Entity ID (also called Audience URI or SP Entity ID) - Oh Dear's unique identifier
• NameID format - Use EmailAddress (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)

You can configure your IdP in two ways:

• Metadata URL - If your IdP provides a metadata URL, paste it in Oh Dear and we'll import the configuration automatically. This is the easiest option and keeps the configuration in sync.
• Manual configuration - Enter the IdP Entity ID, SSO URL, and X.509 certificate directly.

Step 3: Test the connection #

Before enabling SSO for your team, you must test the connection. Click Test connection on the configuration page. This initiates an SSO login flow for you (the team owner). If the test succeeds, you'll see a confirmation.

Testing is required before you can enable SSO. This ensures your IdP is correctly configured.

Step 4: Enable SSO #

After a successful test, go to the Settings tab and click Enable SSO. When you enable SSO:

• Existing team members with a matching verified domain who don't have an SSO identity linked will receive an account linking email
• The email-first login flow activates for your domain
• Team members can still log in with their password until you enforce SSO

Step 5: Link existing team members #

When SSO is enabled, team members with email addresses matching your verified domains receive an email with a one-time link. Clicking that link redirects them through your IdP. After authenticating, their Oh Dear account is linked to their IdP identity.

These linking links expire after 72 hours. You can resend linking emails from the SSO settings page if needed.

Okta #

Setting up Oh Dear in Okta #

1. In the Okta Admin Console, go to Applications > Applications and click Create App Integration
2. Select SAML 2.0 and click Next
3. Enter "Oh Dear" as the app name and click Next
4. Fill in the SAML settings using the values from Oh Dear's configuration page:
   • Single sign-on URL: Paste the ACS URL from Oh Dear. Leave Use this for Recipient URL and Destination URL checked.
   • Audience URI (SP Entity ID): Paste the Entity ID from Oh Dear
   • Name ID format: Select EmailAddress
   • Leave Default RelayState, Application username, and Update application username on at their defaults
5. Click Next, select "I'm an Okta customer adding an internal app" and click Finish

Getting your Okta metadata #

After creating the app:

1. Go to the Sign On tab of your Oh Dear app in Okta
2. Click More details to expand the metadata section
3. Copy the Metadata URL and paste it in Oh Dear's configuration page

Alternatively, you can manually copy the Identity Provider Issuer, SSO URL, and download the signing certificate.

Assigning users in Okta #

Users must be assigned to the Oh Dear app in Okta before they can use SSO:

1. Go to the Assignments tab in your Oh Dear Okta app
2. Click Assign and select the users or groups that should have access
3. Click Done

Users not assigned in Okta will see an "access denied" error when attempting to sign in.

Microsoft Entra ID #

Setting up Oh Dear in Microsoft Entra ID #

1. In the Azure portal, go to Microsoft Entra ID > Enterprise applications
2. Click New application > Create your own application
3. Enter "Oh Dear" as the name, select Integrate any other application you don't find in the gallery (Non-gallery), and click Create
4. Go to Single sign-on and select SAML
5. In the Basic SAML Configuration section, click Edit:
   • Identifier (Entity ID): Paste the Entity ID from Oh Dear
   • Reply URL (Assertion Consumer Service URL): Paste the ACS URL from Oh Dear
6. Click Save

Getting your Entra ID metadata #

1. In the SAML Signing Certificate section, copy the App Federation Metadata Url
2. Paste it in Oh Dear's configuration page as the Metadata URL

Assigning users in Microsoft Entra ID #

1. Go to Users and groups in your Oh Dear enterprise application
2. Click Add user/group
3. Select the users or groups that should have access
4. Click Assign

By default, Entra ID requires user assignment. Users not assigned will see an error when attempting to authenticate.

Google Workspace #

Setting up Oh Dear in Google Workspace #

1. In the Google Admin Console, go to Apps > Web and mobile apps
2. Click Add app > Add custom SAML app
3. Enter "Oh Dear" as the app name and click Continue
4. On the Google Identity Provider details page, copy the SSO URL, Entity ID, and download the Certificate. Alternatively, copy the metadata URL. Click Continue
5. Fill in the Service Provider details:
   • ACS URL: Paste the ACS URL from Oh Dear
   • Entity ID: Paste the Entity ID from Oh Dear
   • Name ID format: Select EMAIL
   • Name ID: Select Basic Information > Primary email
6. Click Continue and then Finish

Turning on access #

By default, the app is turned off for everyone:

1. Click on the Oh Dear app you just created
2. Click User access
3. Select ON for everyone (or configure specific organizational units)
4. Click Save

Changes may take up to 24 hours to propagate, though it's typically much faster.

Configuring Oh Dear #

1. Enter the metadata URL or manually provide the SSO URL, Entity ID, and certificate from Step 4
2. Click Save and then Test connection

OneLogin #

Setting up Oh Dear in OneLogin #

1. In the OneLogin Admin panel, go to Applications > Applications and click Add App
2. Search for "SAML Custom Connector (Advanced)" and select it
3. Enter "Oh Dear" as the display name and click Save
4. Go to the Configuration tab:
   • Audience (EntityID): Paste the Entity ID from Oh Dear
   • ACS (Consumer) URL: Paste the ACS URL from Oh Dear
   • ACS (Consumer) URL Validator: Enter the ACS URL as a regex (escape dots with backslash)
   • SAML nameID format: Select Email
5. Click Save

Getting your OneLogin metadata #

1. Go to the SSO tab
2. Copy the Issuer URL - this serves as your metadata URL
3. Paste it in Oh Dear's configuration page

Assigning users in OneLogin #

1. Go to the Users tab of your Oh Dear app
2. Add the users who should have access

JumpCloud #

Setting up Oh Dear in JumpCloud #

1. In the JumpCloud Admin Console, go to SSO Applications and click Add New Application
2. Select Custom SAML App
3. Enter "Oh Dear" as the display label
4. In the SSO tab, configure:
   • IdP Entity ID: Leave the default or customize
   • SP Entity ID: Paste the Entity ID from Oh Dear
   • ACS URL: Paste the ACS URL from Oh Dear
   • SAMLSubject NameID Format: Select email
   • SAMLSubject NameID: Select email
5. Click Activate

Getting your JumpCloud metadata #

1. After activating, go back to the SSO tab
2. Click Export Metadata to download the metadata XML
3. Alternatively, copy the IdP URL, IdP Entity ID, and download the certificate
4. Enter these values in Oh Dear's configuration page

Assigning users in JumpCloud #

1. Go to the User Groups tab of your Oh Dear app
2. Bind the user groups that should have access

Auth0 #

Setting up Oh Dear in Auth0 #

1. In the Auth0 Dashboard, go to Applications > Applications
2. Click Create Application, select Regular Web Applications, and click Create
3. Go to Addons and enable SAML2 Web App
4. In the Settings tab of the SAML2 addon:
   • Application Callback URL: Paste the ACS URL from Oh Dear
   • Add the following to the Settings JSON:

{
  "audience": "YOUR_ENTITY_ID_FROM_OH_DEAR",
  "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "nameIdentifierProbes": ["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
}

5. Click Save

Getting your Auth0 metadata #

1. In the Usage tab of the SAML2 addon, find the Identity Provider Metadata link
2. Copy that URL and paste it in Oh Dear's configuration page

Assigning users in Auth0 #

Auth0 does not restrict access by default. To control which users can access Oh Dear, use Auth0 Rules or Actions to restrict login based on user attributes.

PingFederate #

Setting up Oh Dear in PingFederate #

1. In the PingFederate Admin Console, go to SP Connections and click Create New
2. Select Browser SSO Profiles and configure:
   • Partner's Entity ID: Paste the Entity ID from Oh Dear
   • ACS URL: Add the ACS URL from Oh Dear as an endpoint with binding POST
   • NameID format: Configure to use the user's email address
3. Configure Attribute Contracts to include emailAddress
4. Complete the wizard and activate the connection

Getting your PingFederate metadata #

1. Export the connection metadata from PingFederate
2. Provide the metadata URL or enter the SSO URL, Entity ID, and signing certificate manually in Oh Dear

Other SAML 2.0 providers #

Oh Dear works with any SAML 2.0 compliant identity provider. Here's what you need regardless of which provider you use:

What to configure in your IdP #

• ACS URL: The Assertion Consumer Service URL from Oh Dear (where your IdP sends the SAML response)
• Entity ID / Audience URI: Oh Dear's SP Entity ID
• NameID format: Use urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
• NameID value: The user's email address
• Signature algorithm: RSA-SHA256 or stronger (SHA-1 is not accepted)

What to provide to Oh Dear #

You can either provide:

• A Metadata URL from your IdP (recommended, keeps config in sync)

Or manually enter:

• IdP Entity ID
• SSO URL (HTTP-Redirect binding)
• X.509 signing certificate (PEM format)

SP Metadata #

Oh Dear provides a SAML SP metadata endpoint that some IdPs can use for automatic configuration. You'll find the metadata URL on the SSO configure page.

Settings reference #

Enable SSO #

Turns SSO on for your team. Requires a verified domain and a successful test connection. When enabled, team members with matching email domains see the SSO login flow.

Require SSO (enforcement) #

When enabled, non-owner team members must authenticate through your IdP. They cannot use password-based login. Team owners always retain password access as a break-glass mechanism.

Before enabling enforcement, Oh Dear shows you which members are linked (ready for SSO) and which are unlinked (will lose access until they complete account linking).

Just-in-Time (JIT) provisioning #

When enabled, users who authenticate through your IdP but don't have an Oh Dear account are automatically created and added to your team. This saves you from manually inviting each team member.

JIT-provisioned users are added as members. You can change their role to admin or guest afterwards from the team members page.

Auto-join existing users #

When enabled, existing Oh Dear users who authenticate through your IdP but aren't members of your team are automatically added as members. When disabled, they need to be invited first.

IdP-initiated SSO #

By default, SSO must be initiated from Oh Dear's login page (SP-initiated). If you enable IdP-initiated SSO, users can also start the login flow from your IdP's app dashboard (e.g., clicking "Oh Dear" in the Okta dashboard).

IdP-initiated SSO is less secure because the authentication flow isn't tied to a request from Oh Dear. Only enable this if your organization requires it.

Account linking #

SSO in Oh Dear uses explicit account linking. We don't silently match accounts by email address, because that could be a security risk if someone gains control of an email address.

Here's how linking works:

• New users (via JIT provisioning): A new Oh Dear account is created and automatically linked to their IdP identity. No extra steps needed.
• Existing team members: When SSO is enabled, they receive an email with a one-time link. Clicking it redirects them through the IdP. After authenticating, their account is linked.
• Manual re-linking: If a linking email expires (after 72 hours), you can resend linking emails from the SSO settings page.

Once linked, a user's Oh Dear account is connected to their IdP identity (issuer + NameID). They'll be automatically recognized on future SSO logins.

Certificate management #

Your IdP uses an X.509 certificate to sign SAML assertions. These certificates expire, and if they do, SSO will break. Oh Dear helps you stay ahead of this:

• Certificate health status is visible on the SSO settings page (healthy, expiring soon, or expired)
• Expiry notifications are sent to the team owner at 30, 14, and 7 days before the certificate expires
• Certificate rotation is supported: you can upload both a primary and secondary certificate. During rotation, Oh Dear accepts signatures from either certificate

When your IdP is configured via a metadata URL, you can click Refresh metadata in the SSO settings to pull the latest certificate automatically.

Security #

Why email-first login? #

Oh Dear uses an email-first login flow: users enter their email, and we check if their domain has SSO configured. This approach keeps the login page simple for everyone while automatically directing SSO users to their IdP.

If the SSO check fails for any reason (network issues, rate limiting), the password field appears immediately. Non-SSO users always see the password field.

Owner break-glass access #

Team owners always retain password-based login, even when SSO enforcement is enabled. This prevents lockout scenarios where an IdP outage or misconfiguration could leave your team without access to Oh Dear.

If you're a team owner using break-glass access, two-factor authentication still applies when configured.

Session management #

SSO sessions in Oh Dear have a 24-hour maximum lifetime. After 24 hours, team members on SSO-enforced teams are redirected to re-authenticate through their IdP.

SSO sessions are team-scoped. If a user is a member of multiple teams, authenticating via SSO for one team doesn't satisfy SSO requirements for another team.

API tokens #

API tokens (used for the Oh Dear API and integrations) work independently of SSO sessions. Existing API tokens remain valid when SSO is enabled or enforced. This ensures your CI/CD pipelines and automation are not disrupted.

When a user is removed from a team, their team-scoped API tokens are automatically revoked.

SAML security #

Oh Dear enforces several security measures on SAML responses:

• Signature algorithm: SHA-1 signatures are rejected. RSA-SHA256 or stronger is required.
• Replay protection: SAML assertions cannot be reused (assertion IDs are cached for 15 minutes after use).
• Audience validation: Assertions must be addressed to Oh Dear's SP Entity ID.
• NameID format: Transient NameIDs are rejected. The subject must have a stable identifier.

Two-factor authentication #

When a user authenticates via SSO, Oh Dear's local two-factor authentication is skipped for that team's session. Your IdP is responsible for enforcing MFA.

Users who log in with a password (including team owners using break-glass access) still need to complete local 2FA when configured.

FAQ and troubleshooting #

"You do not have access" or "Application not assigned" #

This means the user hasn't been assigned to the Oh Dear application in your IdP. Check your IdP's user or group assignments and make sure the user is included.

"Your organization requires SSO" message on login #

This appears when a user tries to log in with a password but their team has SSO enforcement enabled. They should click the SSO login button shown on that page, or navigate directly to their IdP's app dashboard if IdP-initiated SSO is enabled.

DNS verification is not working #

DNS changes can take time to propagate. After adding the TXT record:

1. Wait at least 5 minutes
2. Verify the TXT record exists using a tool like dig TXT yourdomain.com or an online DNS checker
3. Make sure the record value matches exactly what Oh Dear shows
4. Click Verify again

Metadata URL is not loading #

If Oh Dear can't fetch your IdP's metadata URL:

• Check that the URL is publicly accessible (not behind a firewall or VPN)
• Try opening the URL in your browser to confirm it returns valid XML
• Use manual configuration as a fallback: enter the Entity ID, SSO URL, and certificate directly

Certificate is expiring or expired #

Oh Dear sends notifications at 30, 14, and 7 days before your IdP certificate expires. To rotate:

1. Generate a new certificate in your IdP
2. Upload the new certificate as the secondary certificate in Oh Dear (so both old and new are accepted)
3. Update your IdP to use the new certificate
4. Once confirmed, remove the old certificate

If using a metadata URL, click Refresh metadata after updating the certificate in your IdP.

Team members didn't receive the linking email #

Linking emails are only sent to non-owner members whose email domain matches a verified domain and who don't already have an SSO identity linked. Check that:

1. The member's email domain matches one of your verified domains
2. They haven't already linked their account
3. Check spam/junk folders

You can resend linking emails from the SSO settings page.

Linking email has expired #

Linking links expire after 72 hours. Go to SSO Settings and click Resend linking emails to send fresh links.

Users are getting logged out after 24 hours #

SSO sessions have a 24-hour maximum lifetime. After that, users on SSO-enforced teams need to re-authenticate through the IdP. This is by design for security. Most IdPs maintain their own sessions, so the re-authentication is usually seamless.

A user left the organization but still has access #

Remove the user from the Oh Dear app in your IdP. If SSO enforcement is enabled, they won't be able to sign in via SSO anymore. You should also remove them from your Oh Dear team to revoke any API tokens.

Login loops or redirect issues #

If users experience redirect loops:

1. Clear browser cookies for Oh Dear
2. Verify the ACS URL in your IdP matches the one shown in Oh Dear exactly
3. Verify the Entity ID matches exactly
4. Check your IdP's logs for more specific error messages
5. Make sure your IdP's clock is synchronized (SAML has time-based validity windows)