Single Sign-On and SCIM

Freeplay offers enterprise-grade authentication options to help organizations manage access at scale. This page covers Single Sign-On (SSO) via SAML and automated user provisioning through SCIM.

​

Default Authentication Options

By default, Freeplay supports two authentication methods:

• Email and password — Standard username/password authentication
• Google Workspace SSO — Sign in with your Google account

​

Single Sign-On (SSO) via SAML

Enterprise customers can enable SAML-based Single Sign-On to authenticate users through their organization’s Identity Provider (IdP). This allows your team to use their existing corporate credentials to access Freeplay.

​

Supported Identity Providers

Thanks to our authentication partner WorkOS, Freeplay supports most major Identity Providers including:

• Okta
• Microsoft Entra ID (Azure AD)
• Cisco Duo
• OneLogin
• JumpCloud
• And many others

​

Enabling SSO

To enable SSO for your organization:

1. Contact Freeplay — Reach out to support@freeplay.ai to request SSO enablement
2. Self-serve configuration — We’ll send your IT/auth administrator an email invite to configure SSO through WorkOS
3. Complete setup — Your admin completes the SAML configuration in your IdP
4. Activation — Once SSO is enabled, other authentication methods (email/password, Google) are disabled for your account
5. Account creation & role management — You will continue to add/remove users and update roles manually via the Freeplay UI unless you choose to additioanlly enable SCIM (see below)

​

Automated User Provisioning with SCIM

Freeplay offers SCIM (System for Cross-domain Identity Management) support for Enterprise customers to automate the provisioning and deprovisioning of user accounts. This allows you to manage Freeplay user access directly from your Identity Provider (IdP).

​

Overview

Enabling SCIM/Directory Sync streamlines your user management by treating your directory as the single source of truth.

• Automated Onboarding — New users assigned to Freeplay groups in your IdP are automatically created in Freeplay
• Automated Offboarding — Deactivating a user in your IdP immediately revokes their access to Freeplay
• Centralized Role Management — User roles are determined solely by their group membership in your directory

​

Prerequisites and Setup

To enable SCIM for your account:

1. Contact Support — Reach out to the Freeplay team to request SCIM enablement. Please provide the email address of the person who will handle the configuration. This should be somebody that is appropriately permissioned to manage your IdP.
2. Configuration — We will send an invite link to configure your directory sync via WorkOS (our third-party auth provider). This link will be in the form of https://setup.freeplay.ai/init?setupLinkToken=<token>.
3. Integration — Once the configuration is done, either synchronously or async, let us know that you’re ready to schedule a cutover time. We’ll verify the details and prep your account for the switch for that time.
4. Transition/Cutover — Once SCIM is enabled for your account, it will no longer be possible to add or manage users in the UI. We recommend being ready to test quickly with a few sample users to verify that roles are mapping correctly.

​

Role Mapping

Freeplay uses a strict 1:1 mapping between your directory groups and Freeplay user roles. To assign a role to a user, you must add them to one and only one of the specific groups listed below.

​

Default Supported Group Names

If you want a more seamless setup for role management, you can name your IdP groups like the following and we will directly sync the users into Freeplay via a strict string match on these values.

​

Custom Group Names

If you prefer to define your own group names, the 1:1 mapping still applies. You will need to provide us with a list of your relevant IdP groups and how each one should map to Freeplay’s user roles (Admin, User, Analyst, Guest). This is a manual process today. Changes to your group/group names without informing us may result in users being demoted to the Analyst (default role). Use support@freeplay.ai for any desired changes here. For example:

​

Managing Access and Limitations

Once Directory Sync is enabled for your account, user management behaviors change significantly. Please review the following rules to ensure a smooth workflow.

​

Pre-existing Users

• When first setting up the directory to sync with Freeplay, if you already have users in the Freeplay system they will be retained. As noted below, they will no longer be editable via the Freeplay app.
• Existing users will retain their assigned role. In order to ensure your IdP is in sync with what’s in Freeplay, you should manually add those existing users to the appropriate group in your IdP.
  • To get a list of the users with their roles: You can either get them from the UI or from the API. A call to GET /api/v2/<project-id>/users will return all active users in the account. Note that to call this endpoint the API key must be associated with a user with the Account Admin role.
  • Their role will change if they’re added to other groups, or updated.

​

Directory as Source of Truth

• No UI Creation — You will no longer be able to create new users inside the Freeplay app UI. All users must be provisioned via SCIM.
• Locked Profile Data — Users’ First Name, Last Name, and Email are set during provisioning and cannot be edited within Freeplay.
• Permissions — User roles are locked to their directory group. You cannot change a user’s role manually in the Freeplay UI.

​

Changing User Roles

Freeplay determines a user’s role based on the most recent event received from your directory (i.e. “last event wins”). We do not support mapping multiple groups to a single user. To change a user’s role (e.g., from User to Admin): Role changes are no longer allowed inside the app. This is to prevent out-of-sync issues. Roles are now handled like so:

1. Remove the user from the old group (freeplay_user) first
2. Add the user to the new group (freeplay_admin) second

​

Project Membership

SCIM manages Roles (system-level permissions), but it does not manage Freeplay Project membership.

• Private Projects — Access to private projects must still be granted manually within the Freeplay UI by a Project admin.
• Guest Users — Since the Guest role usually implies restricted access (e.g., for contractors), you must explicitly add them to specific Projects in the Freeplay UI for them to see any content.

​

Technical Limitations

• Timing — We process events on a 5-minute interval. This means that role changes can take up to 5 minutes to process. Please be aware that role changes will not be instantaneous.
• Single Group Only — Users should belong to only one Freeplay-mapped group at a time. If a user is added to multiple groups, the role will reflect the most recent “Add” event received. This can also be fixed on your side by removing and re-adding the user to the highest privileged group that’s desired. (e.g. if a user is added to IdP-User and IdP-Admin, but the user event arrived later, they’ll be set as IdP-User. Simply re-add them to IdP-Admin to re-grant the admin permissions here).
• No memberOf Support — We do not support the use of memberOf SAML assertions to update permissions on login. Permissions are updated only via SCIM directory events.