Custom SSO

Set up custom Single Sign-On (SSO) authentication and SCIM user and group provisioning for Fireworks AI

Fireworks uses single sign-on (SSO) as the primary mechanism to authenticate with the platform. By default, Fireworks supports Google SSO.

If you have an enterprise account, Fireworks supports bringing your own identity provider using:

• OpenID Connect (OIDC) provider
• SAML 2.0 provider
• Optionally, the work-email domain your users sign in with, so they can start SSO by entering their email instead of your account ID

Coordinate with your Fireworks AI representative to enable the integration.

OpenID Connect (OIDC) provider

1. Create OIDC client application

   Create an OIDC client application in your identity provider, e.g. Okta.

2. Configure client

   Ensure the client is configured for “code authorization” of the “web” type (i.e. with a client_secret).

3. Set redirect URL

   Set the client’s “allowed redirect URL” to the URL provided by Fireworks. It looks like:

   https://fireworks-<your-company-name>.auth.us-west-2.amazoncognito.com/oauth2/idpresponse
   
4. Note down client details

   Note down the issuer, client_id, and client_secret for the newly created client. You will need to provide this to your Fireworks.ai representative to complete your account set up.

SAML 2.0 provider

1. Create SAML 2.0 application

   Create a SAML 2.0 application in your identity provider, e.g. Okta.

2. Set SSO URL

   Set the SSO URL to the URL provided by Fireworks. It looks like:

   https://fireworks-<your-company-name>.auth.us-west-2.amazoncognito.com/saml2/idpresponse
   
3. Configure Audience URI

   Configure the Audience URI (SP Entity ID) as provided by Fireworks. It looks like:

   urn:amazon:cognito:sp:<some-unique-identifier>
   
4. Create Attribute Statement

   Create an Attribute Statement with the name:

   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
   

   and the value user.email

   Okta: After saving the app, open Sign On → Attribute Statements (SAML) → expand Show legacy configuration → add the attribute statement there. Okta no longer configures this during app creation.

5. Keep default settings

   Leave the rest of the settings as defaults.

6. Note down metadata URL

   Note down the “metadata url” for your newly created application. You will need to provide this to your Fireworks AI representative to complete your account set up. If the metadata URL is not publicly reachable, provide the metadata XML file instead.

SAML sign-in flow

By default, Fireworks uses service provider (SP) initiated SAML: users start at app.fireworks.ai or with firectl signin and are redirected to your identity provider.

IdP-initiated SAML is supported as an opt-in for SAML identity providers. When enabled, users can also start from your identity provider’s portal (for example, the Okta app tile). Enable it with --enable-idp-initiated-sso when creating or updating the identity provider. This option is SAML-only; OIDC providers cannot use it.

Just-In-Time (JIT) user provisioning

JIT user provisioning automatically creates user accounts when they sign in through SSO for the first time. When enabled, users who authenticate through your identity provider are automatically added to your Fireworks account without requiring manual user creation.

To enable JIT user provisioning, use the --enable-jit-user-provisioning flag when creating your identity provider with firectl.

SCIM provisioning

System for Cross-domain Identity Management (SCIM) provisioning synchronizes the user and group lifecycle between your identity provider and Fireworks. Users assigned to Fireworks in your directory are added to your Fireworks account, and users are removed when they are deactivated or unassigned in the directory.

SCIM provisioning is available for enterprise accounts and works with supported directory providers, including Okta, Microsoft Entra ID, and Google Workspace. Fireworks uses WorkOS Directory Sync to connect to your directory.

SCIM manages provisioning only. Users continue to authenticate through your existing OIDC or SAML SSO integration.

Set up SCIM provisioning

1. Configure custom SSO

   Complete the OIDC or SAML setup above. Custom SSO must be configured before you can enable SCIM provisioning.

2. Request SCIM enablement

   Contact your Fireworks AI representative. Fireworks will enable Directory Sync for your account and provide a secure setup link.

3. Connect your directory

   Open the setup link, select your directory provider, and follow the provider-specific instructions to authorize the connection.

4. Assign users and groups

   In your identity provider, assign the users who should have access to Fireworks, plus any groups you want mirrored into Fireworks. Confirm that they appear on the Users and Groups tabs of the Users page.

Group provisioning

Directory groups assigned to Fireworks are synced alongside your users. Creating, renaming, or deleting a group in your directory creates, updates, or deletes the matching Fireworks group, and adding or removing someone from a directory group changes their Fireworks group membership. Deleting a group removes its memberships; the users themselves are unaffected.

Synced groups appear on the Groups tab of the Users page, marked SCIM-synced, with their member count and the time of the last sync. Directory sync is the only way to create a Fireworks group, and groups are read-only in Fireworks — your directory is the source of truth for both the group and its membership.

Synced groups have one use in Fireworks today: assigning them a group limit, which caps serverless spend for each of the group’s members. That is a Fireworks Nexus feature and is enabled separately — syncing groups does not by itself give your account spend limits.

Group-to-role mappings are not currently supported: a group’s members do not inherit a role from the group, and provisioned users receive the User role by default. Set roles per user as described in Managing users.

We recommend disabling JIT provisioning when SCIM is enabled so that your directory remains the source of truth for account membership. SSO enforcement is also recommended to prevent access outside your configured identity provider.

Enforce SSO

When SSO enforcement is enabled, account access is restricted to users with approved tenant domains only. Users with matching domains must authenticate via the identity provider, and users with other domains are blocked. API keys and service accounts are not blocked by SSO enforcement.

To enforce SSO, use the --enforce-sso flag when creating your identity provider with firectl, or toggle “Enforce SSO for all users” in the Fireworks console.

Troubleshooting

Invalid samlResponse or relayState from identity provider

This error usually means the login started from the identity provider (IdP-initiated) but IdP-initiated SAML is not enabled for your identity provider.

• For SP-initiated login, start from app.fireworks.ai instead of your IdP’s app tile.
• For IdP-initiated login, enable --enable-idp-initiated-sso on a SAML identity provider (or ask your Fireworks representative to enable it).

See Understanding SAML for SP-initiated versus IdP-initiated flows.

Required String parameter ‘RelayState’ is not present

Same cause as above: an IdP-initiated login without IdP-initiated SSO enabled.