To understand how SSO works and why organizations use it, see Single Sign-On (SSO).
Prerequisites
Before you begin, ensure:- Your organization has an enterprise contract that includes SSO
- Narrative has provisioned your organization and provided your 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)
- You have administrative access to your organization’s identity provider
First-time login
Before SSO is configured, you’ll use a magic link to access the admin portal.1
Access Enterprise Login
Navigate to app.narrative.io/platform/login and click Enterprise Login at the bottom of the login page.
2
Enter your organization slug
Enter your organization’s slug (provided by Narrative) to identify which organization you’re authenticating against.
3
Authenticate via magic link
Enter your email address and click Send Magic Link. Check your email for the login link and click it to complete authentication.
Configure your SSO connection
Gather IdP information
From your identity provider (Okta, Azure AD, etc.), collect:| Information | Description |
|---|---|
| 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 |
Create the connection in Narrative
1
Open SSO settings
In Narrative, go to Settings > Enterprise Login Settings.
2
Create new connection
Click New SSO Connection.
3
Enter IdP information
Enter the IdP SSO URL, Entity ID, and X.509 certificate you collected.
Configure your identity provider
In your identity provider, create a new SAML application with the following settings from Narrative:| 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 | — |
Okta configuration
In Okta, when creating the SAML application:- Check Use this for Recipient URL and Destination URL when entering the Single sign-on URL
- Set Application username to
Email - Set Update application username on to
Create and update
Basic:
| Attribute name | Value |
|---|---|
first_name | user.firstName |
last_name | user.lastName |
id | user.id |
Azure AD (Microsoft Entra ID) configuration
Configure these attribute statements:| Attribute name | Value |
|---|---|
first_name | user.givenname |
last_name | user.surname |
id | user.objectid |
OneLogin configuration
Configure these attribute statements:| Attribute name | Value |
|---|---|
first_name | {firstname} |
last_name | {lastname} |
id | {id} |
Complete the SSO connection
After creating the SAML application in your IdP:1
Locate metadata
Find the Metadata URL (or download the metadata XML) from your identity provider.
- Okta: Find the Metadata URL in the Sign On tab. Click Actions under SAML Signing Certificates and select View IdP metadata.
- Azure AD: Download the Federation Metadata XML from the SAML configuration page, or use the App Federation Metadata Url.
2
Add metadata to Narrative
Return to Narrative’s SSO Settings tab, paste the Metadata URL, and click Create.
3
Verify connection
Your SSO connection should appear in the list with status Active.
Assign users in your IdP
Users must be explicitly assigned to the Narrative SAML application in your IdP before they can authenticate. Okta: Go to Applications > Your Narrative App > Assignments. Click Assign > Assign to People (or Assign to Groups for bulk assignment). Azure AD: Go to Enterprise Applications > Your Narrative App > Users and groups. Click Add user/group and select users or groups.Enforce SSO-only authentication
By default, Narrative allows multiple authentication methods (email magic links and SSO). To require SSO for all users:1
Open organization settings
Go to Settings > Enterprise Login Settings > Organization Settings.
2
Edit authentication settings
Under Authentication settings, click Edit.
3
Disable other methods
Uncheck Allow all primary auth methods to reveal individual method checkboxes. Check only Single Sign-On and leave Email Magic Links unchecked.
4
Save changes
Click Save.
Just-in-time (JIT) provisioning
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
Managing members
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
Revoking access
To remove a user’s access:- 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
API token security
Troubleshooting
| Issue | Solution |
|---|---|
| ”User is not assigned to this application” | Add the user to the Narrative SAML application in your identity provider |
| ”This project is not authorized to call this endpoint” | Contact Narrative support—SSO products may not be enabled for your organization |
| User prompted to register after clicking invite link | This is expected for first-time users. They’ll complete a brief registration flow before accessing the platform |