# 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
<!-- toc: 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
<!-- toc: Configure your IdP -->

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

- [Okta](#okta)
- [Microsoft Entra ID](#microsoft-entra-id)
- [Google Workspace](#google-workspace)
- [OneLogin](#onelogin)
- [JumpCloud](#jumpcloud)
- [Auth0](#auth0)
- [PingFederate](#pingfederate)
- [Other SAML 2.0 providers](#other-saml-20-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
<!-- toc: 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
<!-- toc: 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
<!-- toc: Link existing 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
<!-- toc: Setup -->

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
<!-- toc: Getting 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
<!-- toc: Assigning users -->

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
<!-- toc: Setup -->

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
<!-- toc: Getting 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
<!-- toc: Assigning users -->

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
<!-- toc: Setup -->

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
<!-- toc: 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
<!-- toc: 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
<!-- toc: Setup -->

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
<!-- toc: Getting 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
<!-- toc: Assigning users -->

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
<!-- toc: Setup -->

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
<!-- toc: Getting 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
<!-- toc: Assigning users -->

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
<!-- toc: Setup -->

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:

```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
<!-- toc: Getting 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
<!-- toc: Assigning users -->

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
<!-- toc: Setup -->

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
<!-- toc: Getting 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)