Knowledge Base
Enterprise SSO Configuration Guide
Enterprise SSO Configuration Guide
Overview
Narrative supports SAML-based Single Sign-On (SSO) integration with identity providers such as Okta, Azure AD, and OneLogin. This guide walks enterprise administrators through configuring SSO for their organization.
Once configured, your team members can authenticate to Narrative using your corporate identity provider, and you can enforce SSO as the only permitted authentication method.
In order to get started, please reach out to your Narrative Account Manager for confirmation that your contract includes qualifying terms for Enterprise SSO, and that we have properly configured your account's pre-requisites.
Supported Features
- SAML 2.0 Authentication – Secure single sign-on via your organization's IdP
- Just-in-Time Provisioning – If configured, users are automatically created in Narrative upon first SSO login
- Self-Service Admin Portal – Designated admins can configure SSO connections and manage members
- Role-Based Access – Assign admin or standard user roles to organization members
Prerequisites
Before you begin, ensure:
- You have administrative access to your organization's identity provider
- Narrative has provisioned your organization for SSO and provided you with an Organization Slug (e.g.,
yourcompany) - You have received an email invitation from Narrative and completed initial registration
- Your Narrative account has the Stytch Admin role (contact Narrative support if unsure)
Step 1: Logging In for the First Time
1. Access Enterprise Login
Navigate to https://app.narrative.io/platform/login and click "Enterprise Login" at the bottom of the login page.
2. Enter Organization Slug
Enter your organization's slug (provided by Narrative) in the field. This identifies which organization you are authenticating against.
3. Authenticate via Magic Link
For initial login before SSO is configured, enter your email address and click "Send Magic Link". Check your email for the login link and click it to complete authentication.
Once SSO is configured, you will authenticate directly through your organization's identity provider.
Step 2: Configuring SSO (Admin Users Only)
1. Gather IdP Information
From your identity provider (e.g., Okta), you will need:
- IdP SSO URL – The endpoint where SAML requests are sent
- IdP Entity ID – Unique identifier for your IdP
- X.509 Certificate – Public certificate for signature verification
2. Configure in Admin Portal
In the Enterprise Login Settings, click "New SSO Connection" and enter the information from Step 1.
3. Configure Your IdP
In your identity provider, create a new SAML application with the following settings:
| Field | Description | Where to Find |
|---|---|---|
| ACS URL / Single Sign-On URL | The endpoint where your IdP sends SAML assertions | Narrative UI (SSO Settings → New Connection) |
| Entity ID / Audience URI | Unique identifier for Narrative as the service provider | Narrative UI (SSO Settings → New Connection) |
| Name ID Format | Must be set to EmailAddress | — |
In Okta, also check "Use this for Recipient URL and Destination URL" when entering the Single sign-on URL. Set "Application username" to Email and "Update application username on" to Create and update.
Required Attribute Statements
Your IdP must send the following three attributes in the SAML assertion:
| Name | Okta | Azure AD | OneLogin |
|---|---|---|---|
first_name | user.firstName | user.givenname | {firstname} |
last_name | user.lastName | user.surname | {lastname} |
id | user.id | user.objectid | {id} |
Attribute value syntax varies by identity provider and may change over time. If you encounter issues with attribute mapping, consult your IdP's documentation for the correct expressions to reference user first name, last name, and unique identifier. The attribute names sent to Narrative (first_name, last_name, id) must remain exactly as shown.
In Okta, set the Name format dropdown to Basic for attribute statements.
Step 3: Complete SSO Connection in Narrative
After creating the SAML application in your IdP, you need to provide Narrative with your IdP's metadata.
- Locate the Metadata URL (or download the metadata XML) from your identity provider
- Return to Narrative's SSO Settings tab
- Paste the Metadata URL and click Create
Your SSO connection should now appear in the list with status Active.
Okta: Find the Metadata URL in the Sign On tab of your application. Click "Actions" under SAML Signing Certificates and select "View IdP metadata", or look for the "Metadata URL" field.
Azure AD: Download the "Federation Metadata XML" from the SAML configuration page, or use the "App Federation Metadata Url".
Step 4: Assign Users to the SAML Application
Users must be explicitly assigned to the Narrative SAML application in your IdP before they can authenticate. The process varies by identity provider.
Go to Applications → Your Narrative App → Assignments tab. Click Assign → Assign to People (or "Assign to Groups" for bulk assignment). Select users and click Done.
Go to Enterprise Applications → Your Narrative App → Users and groups. Click Add user/group and select the users or groups.
Users not assigned to the application will receive an error similar to: "User is not assigned to this application."
Step 5: Configure Authentication Settings
By default, Narrative allows multiple authentication methods (email magic links and SSO).
To enforce SSO-only authentication:
- In Narrative, go to Settings → Enterprise Login Settings → Organization Settings
- Under Authentication settings, click Edit
- First, uncheck "Allow all primary auth methods" — this reveals the individual method checkboxes
- Check only "Single Sign-On"
- Leave "Email Magic Links" unchecked
- Click Save
All users in your organization will now be required to authenticate via SSO. Email magic links will no longer work for standard users.
Step 6: JIT Provisioning (Just-In-Time User Creation)
JIT provisioning is enabled by default. When enabled, any user assigned to your IdP's SAML application can automatically create a Narrative account on their first login — no invitation required.
To disable JIT provisioning:
- Go to Organization Settings → User onboarding
- Click Edit
- Under "JIT Provisioning", uncheck SSO connections
- Click Save
When JIT is disabled, users must be explicitly invited via the Member Management tab before they can access Narrative.
Step 7: Inviting Members
To invite a new user (when JIT is disabled, or to pre-provision users):
- Go to Member Management
- Click Invite
- Enter the user's name and email address
- Optionally assign a role (leave blank for standard user access)
- Click Invite
The user will receive an email invitation. When they click the link and authenticate via SSO, their account will be activated.
The invited email address must match the email configured in your identity provider.
Step 8: Revoking User Access
To remove a user's access to Narrative:
- In your identity provider, remove the user from the Narrative SAML application (or remove them from an assigned group)
- The user will immediately lose access and see an error on their next login attempt
Go to Applications → Your Narrative App → Assignments. Find the user and click the X or select "Unassign".
You can also archive the member in Narrative's Member Management tab to fully remove their account from the platform.
Revoking Long-Lived API Tokens
Long-lived API Tokens (provisioned under Settings → API Keys) are not tied to an individual user and are not automatically revoked when a user's access is revoked. If a user leaves your company or for another reason no longer should have access to a long-lived API token, you must manually revoke that API Token.
Troubleshooting
"User is not assigned to this application"
The user has not been assigned to the Narrative SAML application in your identity provider. Add them via your IdP's application assignment settings.
"This project is not authorized to call this endpoint"
Contact Narrative support — SSO products may not be enabled for your organization in our backend.
User prompted to register after clicking invite link
This is expected for first-time users. They will complete a brief registration flow (including accepting Terms of Service) before accessing the platform.
Security Considerations
- SSO tokens are validated on every authentication request
- User sessions follow your IdP's session lifetime policies
- All authentication traffic is encrypted via TLS
Support
For assistance with SSO configuration, contact Narrative support at support@narrative.io or reach out to your account representative.
If you use an identity provider not covered in this guide, our team can provide configuration assistance specific to your IdP.