How it works

Storymate acts as the SAML Service Provider (SP). Your identity provider (IdP) asserts the user's identity. The flow is SP-initiated: the user clicks "Sign in with SSO" on the Storymate login page, enters their organization slug, and is redirected to the IdP. After authentication, the IdP posts a signed SAML assertion back to Storymate's Assertion Consumer Service (ACS) endpoint.

On first sign-in, Storymate automatically provisions a Storymate account for the user (using the email address from the SAML NameID) and adds them to your organization with the Member role. Subsequent sign-ins reuse the existing account.

Service Provider values

When registering Storymate as an application in your IdP, you will need the following SP values. Replace {your-org-slug} with your organization's slug (visible in Settings → Organization).

Field	Value
Entity ID / Audience URI	https://storymate.app/saml/{your-org-slug}
ACS URL / Reply URL	https://storymate.app/api/saml/acs/{your-org-slug}
Binding	HTTP-POST
NameID format	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
SP Metadata URL	https://storymate.app/api/saml/metadata/{your-org-slug}

Many IdPs (Okta, Azure AD, Google Workspace) can import the SP metadata XML directly from the metadata URL instead of requiring you to fill in fields manually.

Setup steps

1. 1

   Register Storymate in your IdP

   Create a new SAML application in your identity provider. Use the SP values from the table above. The metadata URL is the fastest way to configure most IdPs — paste it into the "Import metadata" field if your IdP supports it. Otherwise fill in the Entity ID, ACS URL, binding, and NameID format manually.

   Assign the appropriate users or groups to the application in your IdP so they can authenticate.

2. 2

   Collect your IdP values

   From your IdP's application configuration, copy the following values. You'll paste these into Storymate in the next step.

   Field	Where to find it
   IdP Entity ID	Usually labelled "Issuer" or "IdP Entity ID" in the IdP's SAML settings.
   IdP SSO URL	The URL Storymate will redirect users to for authentication. Labelled "Sign-on URL", "Login URL", or "SSO URL" depending on the IdP.
   IdP X.509 Certificate	The public certificate Storymate uses to verify signed assertions. Download the PEM-format certificate from your IdP.

3. 3

   Enter the IdP values in Storymate

   Go to Settings → Organization → SSO (SAML) and fill in:

   • IdP Entity ID — the issuer string from your IdP.
   • IdP SSO URL — the login URL from your IdP.
   • IdP Certificate — paste the full PEM certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

   Click Save. The configuration takes effect immediately.

4. 4

   Test the login flow

   Open a private browser window and go to storymate.app/auth/login. Click Sign in with SSO, enter your organization slug, and complete the authentication in your IdP. You should be redirected back to Storymate and logged in.

   If the test fails, check that:

   • The ACS URL in your IdP matches exactly https://storymate.app/api/saml/acs/{your-org-slug}.
   • The NameID value sent by the IdP is a valid email address.
   • The IdP certificate you pasted in Storymate is the signing certificate (not the encryption certificate).
   • The clock on your IdP server is accurate — SAML assertions are time-sensitive and will be rejected if the server clock is more than a few minutes off.

IdP-specific notes

Okta

1. In the Okta Admin Console, go to Applications → Create App Integration and choose SAML 2.0.
2. Set the Single sign-on URL to the ACS URL above.
3. Set the Audience URI (SP Entity ID) to the Entity ID above.
4. Under Attribute Statements, no additional attributes are required — Storymate reads the email from the NameID.
5. Under Name ID format, select EmailAddress.
6. Complete the wizard and download the IdP certificate from the Sign On tab → View SAML setup instructions.

Azure AD / Microsoft Entra ID

1. In the Azure Portal, go to Microsoft Entra ID → Enterprise applications → New application → Create your own application.
2. Choose Integrate any other application you don't find in the gallery (Non-gallery).
3. Under Single sign-on → SAML, click the pencil icon for Basic SAML Configuration.
4. Set the Identifier (Entity ID) and Reply URL (ACS URL) using the SP values above. Leave the Sign on URL blank (SP-initiated login is handled by Storymate).
5. Under Attributes & Claims, ensure the Unique User Identifier (Name ID) is set to user.mail with format emailAddress.
6. Download the Certificate (Base64) from the SAML Signing Certificate section.
7. Copy the Login URL and Azure AD Identifier — these are the IdP SSO URL and IdP Entity ID respectively.

Google Workspace

1. In the Google Admin Console, go to Apps → Web and mobile apps → Add app → Add custom SAML app.
2. Download the IdP metadata or copy the SSO URL and Certificate from step 2 of the wizard.
3. On the Service Provider Details page, set the ACS URL and Entity ID using the SP values above.
4. Set the Name ID format to EMAIL and Name ID to Basic Information > Primary email.
5. No attribute mappings are required beyond the NameID.

OneLogin

1. In the OneLogin Admin Console, go to Applications → Add App and search for SAML Custom Connector (Advanced).
2. Under Configuration, set the Audience (EntityID) and ACS (Consumer) URL using the SP values above.
3. Set the ACS URL Validator to the same ACS URL.
4. Under Parameters, ensure the NameID is mapped to the user's email address.
5. Under SSO, copy the Issuer URL (IdP Entity ID) and SAML 2.0 Endpoint (HTTP) (IdP SSO URL), and download the X.509 Certificate.

User provisioning

Storymate uses Just-in-Time (JIT) provisioning — no pre-provisioning or SCIM sync is required. On a user's first SAML login:

• A Storymate account is created with the email address from the NameID.
• The user is added to your organization with the Member role.
• Password-based login is disabled for JIT-provisioned users (they have no password set).

Role changes must be made manually in Storymate via Settings → Organization → Members. There is no automatic role mapping from IdP groups.

SSO login URL

Users can initiate SSO login directly via:

https://storymate.app/api/saml/login/{your-org-slug}

You can link to this URL from your company's intranet or app launcher to give users a one-click entry point.

Updating or removing SSO configuration

To update the IdP configuration (e.g. after certificate rotation), go to Settings → Organization → SSO (SAML) and save the new values. The change takes effect immediately — active sessions are not terminated.

To remove SSO, clear all fields and save. Users who were provisioned via SAML will not be able to log in without a password, so notify them in advance to set a password before SSO is removed.