> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Okta

> Connect Okta to Rootly for single sign-on via SAML 2.0 and automated user and group provisioning via SCIM 2.0.

## Overview

Okta handles authentication and identity for most of your workforce. Wire it into Rootly and your team signs into Rootly with their Okta credentials, gets automatically provisioned when added to the Okta group, and disappears from Rootly the moment Okta deprovisions them. No shared passwords, no manual user cleanup, no orphaned accounts when someone leaves.

Rootly's SAML SSO and SCIM provisioning aren't Okta-specific — they work with any SAML 2.0 IdP — but Okta is the most common integration target, and the setup steps below are written specifically for Okta's admin UI.

<CardGroup cols={2}>
  <Card title="Sign In With Okta" icon="key">
    Replace passwords with SAML SSO. Responders authenticate to Rootly through Okta and inherit your existing MFA and session policies.
  </Card>

  <Card title="Auto-Provision Users" icon="user-plus">
    SCIM 2.0 creates Rootly accounts the moment Okta assigns the app, no manual invites or seat juggling.
  </Card>

  <Card title="Auto-Deprovision" icon="user-minus">
    When Okta unassigns a user — offboarding, role change, group removal — Rootly deactivates them automatically so access stays in sync.
  </Card>

  <Card title="Group Sync" icon="users">
    Map Okta groups to Rootly teams via SCIM. Membership changes propagate without an admin in the loop.
  </Card>
</CardGroup>

***

## Before You Begin

<Info>
  **You'll need access to both sides of the connection.**

  * **In Okta** — Super Admin or an equivalent admin role that can create applications, configure SAML, and enable SCIM provisioning.
  * **In Rootly** — an admin role so you can reach **Configuration → Integrations → SSO** and paste the values from Okta.

  SCIM provisioning requires SSO to be configured first. SCIM and [Google Directory Sync](/integrations/google-directory-sync) are mutually exclusive — you can only have one active at a time.
</Info>

***

## Rootly Service Provider Details

These are the values you'll paste into Okta when creating the Rootly application. Keep this section handy during setup.

<ParamField path="ACS URL (Single Sign-On URL)" type="URL" required>
  `https://rootly.com/users/saml/auth`
</ParamField>

<ParamField path="Audience URI (SP Entity ID)" type="URL" required>
  `https://rootly.com/users/saml/metadata`
</ParamField>

<ParamField path="SP Metadata URL" type="URL">
  `https://rootly.com/users/saml/metadata` — Okta can ingest this directly to auto-fill the SAML settings.
</ParamField>

<ParamField path="Name ID Format" type="string" required>
  `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` — the user's email goes in the NameID.
</ParamField>

<ParamField path="SAML Binding" type="string" required>
  `HTTP-POST` for both request and response.
</ParamField>

<ParamField path="SCIM Tenant URL" type="URL">
  `https://rootly.com/scim` — the SCIM endpoint Okta provisions users against.
</ParamField>

***

## Configure SAML SSO With Okta

Rootly ships a pre-built application in the Okta App Catalog. Install it instead of creating a generic SAML 2.0 app from scratch — the catalog version ships with all SAML attribute mappings, application username defaults, and SCIM endpoints pre-configured.

<Steps>
  <Step title="Install The Rootly App From Okta's Catalog">
    In the Okta Admin Console, go to **Applications → Applications → Browse App Catalog**. Search for **Rootly** and click **Add Integration**.

    Give the app a descriptive label (most teams just use `Rootly`; if you run multiple Rootly organizations, name each one after its org). Click **Next**.
  </Step>

  <Step title="Copy The Okta IdP Values">
    On the new application's **Sign On** tab, scroll to the SAML Setup section and reveal the IdP metadata. Copy:

    * **Identity Provider Single Sign-On URL** (Okta's SSO endpoint)
    * **Identity Provider Issuer** (Okta's Entity ID)
    * **X.509 Certificate** — download the PEM-encoded certificate
  </Step>

  <Step title="Configure SSO In Rootly">
    In Rootly, go to **Configuration → Integrations → SSO** as a logged-in admin user. Paste the three values from Okta into the matching Rootly fields:

    | Okta Field                           | Rootly Field         |
    | ------------------------------------ | -------------------- |
    | Identity Provider Issuer             | Identity Provider Id |
    | Identity Provider Single Sign-On URL | Identity Login Url   |
    | X.509 Certificate                    | IDP Certificate      |

    The certificate goes in as full PEM contents, including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. Add the email domains your team uses (e.g., `acme.com`) so Rootly knows which logins to route through Okta. Save.

    <Warning>
      Rootly rejects expired certificates at save time. Confirm the certificate Okta provides hasn't lapsed before saving.
    </Warning>
  </Step>

  <Step title="Assign The App To Users In Okta">
    Back in Okta, go to the Rootly application's **Assignments** tab. Assign the app to the people or groups who should have Rootly access. Users will see Rootly on their Okta dashboard once the assignment propagates.
  </Step>
</Steps>

For deeper detail on Rootly's SAML configuration options and supported IdPs beyond Okta, see [SSO](/integrations/sso).

***

## Enable SCIM Provisioning With Okta

SAML handles the sign-in flow. SCIM handles user lifecycle — creating, updating, and deactivating Rootly accounts as Okta assignments change.

<Steps>
  <Step title="Copy The Rootly SCIM Token">
    In Rootly, go back to **Configuration → Integrations → SSO** and open the **SCIM** tab. Copy the **SCIM Token** — Okta uses it as the Bearer token to authenticate SCIM API calls.

    The SCIM endpoint Okta provisions against is `https://rootly.com/scim`.
  </Step>

  <Step title="Enable API Integration In The Okta App">
    Open the Rootly application in Okta and click the **Provisioning** tab. Under **Settings → Integrations**, click **Configure API Integration** and enter the SCIM Token from Rootly. Click **Test API Credentials** to verify the connection, then save.
  </Step>

  <Step title="Enable Create And Deactivate Users">
    Go to **Provisioning → To App**, click **Edit**, and enable:

    * **Create Users** — provisions users when assigned to the Rootly app
    * **Deactivate Users** — removes users from Rootly when unassigned

    Make sure the **Default username** is set to **email**. If not, switch to the **Sign on** tab, click **Edit**, and set **Application username** format to **email** under the Credentials settings.
  </Step>

  <Step title="Push and Link Groups (Optional)">
    To sync Okta groups to Rootly teams, enable **Push Groups** on the app, then push each group with **Link Group** (not **Create Group**) — the Rootly side of the flow expects the linked variant. In Rootly, under **Configuration → Integrations → SSO → SCIM**, toggle **Sync SCIM groups to teams** on so pushed groups become Rootly teams. See [SCIM — Group Sync](/integrations/scim) for the full step-by-step.
  </Step>

  <Step title="Configure SCIM Group Role Assignment (Optional)">
    If you want a user's Rootly role to come from their Okta group membership (rather than the team default), toggle **Enable SCIM group role assignment** on under **Configuration → Integrations → SSO → SCIM**. Then, in the **Assign roles to SCIM group members** section, map each pushed SCIM group to a Rootly Role.

    New users are assigned the team default role. SCIM group members get the role configured for their group — if a user is in multiple SCIM groups, they get the role with the highest permissions.
  </Step>
</Steps>

For the full SCIM behavior — supported operations, attribute mappings, and edge cases — see [SCIM](/integrations/scim).

***

## Attribute Mapping Reference

The Rootly catalog app pre-configures these mappings for you. This section is a reference for what Rootly reads from SAML assertions and SCIM payloads — useful for verifying provisioning behavior or troubleshooting attribute gaps. Email is required (sourced from the SAML NameID); the rest are optional but recommended.

<ParamField path="Email" type="string" required>
  Sourced from the SAML NameID element (must be `emailAddress` format). Also the unique identifier Rootly uses to match SCIM provisioning calls to existing users.
</ParamField>

<ParamField path="name.givenName" type="string">
  First name. Catalog app maps from Okta's `user.firstName`.
</ParamField>

<ParamField path="name.familyName" type="string">
  Last name. Catalog app maps from Okta's `user.lastName`.
</ParamField>

<ParamField path="displayName" type="string">
  Preferred display name shown in the Rootly UI. Catalog app maps from Okta's `user.displayName`.
</ParamField>

<ParamField path="phoneNumbers.work" type="string">
  Work phone number. Used for SMS and voice notifications. Catalog app maps from Okta's `user.primaryPhone`.

  Phone number provisioning via SCIM is off by default and needs to be enabled per team by Rootly support — contact your account team if you want to sync phone numbers alongside user attributes. Without it, users add their own phone numbers in Rootly under their user settings.
</ParamField>

***

## Test the Integration

After saving SSO in Rootly and assigning the app in Okta, verify the end-to-end flow.

<Steps>
  <Step title="Sign In Via Okta">
    Open Okta's end-user dashboard (or your company's Okta tile portal) and click the Rootly app. You should be redirected to Rootly and signed in without entering a Rootly password.
  </Step>

  <Step title="Verify SCIM Provisioning">
    Assign a new test user to the Rootly app in Okta. Within a few minutes, that user should appear on Rootly's **Members** page with the attributes you mapped.
  </Step>

  <Step title="Verify Deprovisioning">
    Unassign the test user from the Okta app. Within a few minutes, the user's Rootly account should transition to deactivated and they should no longer be able to sign in.
  </Step>
</Steps>

<Check>
  A successful sign-in followed by automatic user creation and deactivation confirms both SSO and SCIM are wired correctly. Production rollout is just a matter of widening the Okta assignment to the broader user population.
</Check>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Okta redirects but Rootly returns a SAML error" icon="lock">
    The most common cause is a certificate mismatch. Confirm:

    * The certificate pasted into Rootly is the exact PEM contents Okta provided, including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines
    * The certificate isn't expired (Rootly rejects expired certificates at save time)
    * The SAML Audience URI in Okta matches `https://rootly.com/users/saml/metadata` exactly — trailing slashes and capitalization matter
  </Accordion>

  <Accordion title="Users can sign in but no profile fields populate" icon="user-large-slash">
    The catalog app maps attributes by default, but the Okta user profile itself may be missing the source values. Check the affected user in **Directory → People** and confirm First Name, Last Name, Display Name, and Primary Phone are populated. If you customized the catalog app's attribute statements, re-check the names against the [Attribute Mapping Reference](#attribute-mapping-reference) above — Rootly's SAML attribute names are case-sensitive (`name.givenName`, not `name.givenname`).
  </Accordion>

  <Accordion title="SCIM test connection fails with 401" icon="key">
    The SCIM Token in Okta doesn't match the one Rootly generated, or the token has been rotated. Re-copy the SCIM Token from the **SCIM** tab under **Configuration → Integrations → SSO** in Rootly and paste it back into Okta's API Token field.
  </Accordion>

  <Accordion title="Users provision but don't have the right role" icon="user-shield">
    Roles are assigned to SCIM groups, not to individual users. Open **Configuration → Integrations → SSO → SCIM** in Rootly and confirm **Enable SCIM group role assignment** is on, then check each pushed group's role mapping in the **Assign roles to SCIM group members** section. SCIM users start with the team default role, and users in a mapped SCIM group get the group's role instead (highest-permission role wins when a user is in multiple).
  </Accordion>

  <Accordion title="Deactivation isn't happening when users are unassigned" icon="user-minus">
    Confirm **Deactivate Users** is enabled under Okta's **Provisioning → To App** settings. Okta also has a soft-delete vs hard-delete distinction; Rootly treats deactivation as soft (user is marked inactive but data is retained).
  </Accordion>

  <Accordion title="Login works for some users but not others" icon="circle-exclamation">
    Check that the failing users' email domain is added to the **Email Domains** list on Rootly's SSO settings. Rootly only routes logins through Okta for domains explicitly listed. Users on unlisted domains fall back to password auth.
  </Accordion>
</AccordionGroup>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Do I need both SSO and SCIM?" icon="circle-question">
    SSO alone is enough to sign in via Okta — Rootly auto-creates accounts on first sign-in via just-in-time provisioning. SCIM adds proactive pre-provisioning, ongoing attribute updates, and automated deactivation when users are unassigned in Okta. Most teams enable both; SCIM requires SSO to be configured first because the SCIM Token Okta authenticates with is generated as part of your Rootly SSO account.
  </Accordion>

  <Accordion title="Can I use Okta with other Rootly integrations like Slack?" icon="layer-group">
    Yes. Okta SSO only governs login to the Rootly web app. Slack, Microsoft Teams, and other integrations have their own auth flows and are unaffected.
  </Accordion>

  <Accordion title="What happens if Okta is down?" icon="triangle-exclamation">
    Users can't sign in to Rootly via Okta during an Okta outage. For emergencies, Rootly supports **Emergency Access** — a small set of users you designate in advance (under **Configuration → Integrations → SSO → Emergency Access**) who can fall back to email and password login when SSO is unavailable.

    Designated users must have a password configured on their account. Users provisioned through SSO who have never set a password will not be able to use Emergency Access — ask them to set one via password reset before an outage happens. Set the whole thing up before you need it; contact Rootly support if you're already locked out.
  </Accordion>

  <Accordion title="Does Rootly support Okta's just-in-time provisioning without SCIM?" icon="bolt">
    Yes. With SSO alone, Rootly creates a user account the first time someone signs in via Okta (JIT). SCIM gives you proactive provisioning, attribute updates, and deactivation on top of JIT. Use SCIM if you want users to exist in Rootly before they first sign in, or if you need automated deactivation.
  </Accordion>

  <Accordion title="Can SCIM and Google Directory Sync run at the same time?" icon="ban">
    No. They're mutually exclusive — only one user-provisioning source can be active per Rootly organization. Pick whichever matches your primary IdP.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="SSO" icon="key" href="/integrations/sso">
    Full SAML 2.0 setup reference, including supported IdPs beyond Okta and the complete attribute mapping table.
  </Card>

  <Card title="SCIM" icon="users" href="/integrations/scim">
    Detailed SCIM 2.0 behavior — supported operations, attribute mappings, group sync, and edge cases.
  </Card>

  <Card title="User Permissions" icon="user-shield" href="/managing-users/user-permissions">
    Map provisioned users to Rootly roles and scope their access to teams, services, and operations.
  </Card>

  <Card title="Managing Users" icon="users-gear" href="/managing-users/managing-users">
    Day-to-day user administration — adding, editing, deactivating accounts that flow in through Okta.
  </Card>
</CardGroup>