SSO/SAML

SSO/SAML support is available for Enterprise teams. Note that this functionality first needs to be enabled for your organization by the Runway team. Get in touch if needed, and we'll get this set up.

Runway uses WorkOS to provide SSO/SAML and SCIM 2.0-based user provisioning to our teams, for a wide range of identity providers.

Signing into Runway with email and password will be disabled by default once SSO/SAML is enabled. If you’d still like to allow email and password sign in alongside SSO/SAML as an option, let us know and we’ll enable it.

Login sessions remain active for 72 hours. After that, users will be prompted to log in again for security and session management purposes.

SSO/SAML configuration

Setup

Setup and configuration are simple, and can be performed following the steps below.

The Runway user executing these steps must have the IT Admin role, which needs to be assigned by the Runway team. Let us know the email address of the person in your organization who will be completing SSO/SAML setup and we’ll assign the role.

1. Sign into Runway using existing email/password credentials for an account that has the IT Admin role

2. Navigate to your organization’s settings by clicking on your organization avatar in the main navigation bar:

3. On the organization settings page, navigate to the SSO/SAML tab. You’ll see an SSO module at the top that shows your current SSO connection status, and a button that redirects to the SSO admin portal. The status will read Not Connected until your IT admin has configured the SSO integration.

1. Click on the SSO admin portal button and follow the instructions in the WorkOS setup flow to configure your SSO connection.

2. Once you’ve completed the SSO connection setup process, you will be redirected back to Runway, where your SSO connection status should now show as Active.

Directory Sync

Directory Sync allows your organization to manage Runway users and, optionally, their Runway user groups and app membership from your company's central user directory. When enabled, your Runway organization will be automatically kept in sync with your company directory, so your directory can be the source of truth for Runway user provisioning and their access levels. Directory Sync can only be configured by a Runway user with the IT Admin permission.

If you choose to have your directory groups manage Runway user groups, any existing user groups set up in Runway will be overwritten to reflect your organization's structure in your directory provider.

Additionally, if no user group directly mapping to a Release pilot group is found, existing pilot rotations in Runway will be lost.

You choose this when you connect your directory, and you can change it at any time. See Where Runway user groups are managed for more details.

1. In the Organization settings page, navigate to the SSO/SAML tab. You’ll see a module labeled Directory Sync with an initial status of Inactive.

1. Click the button labeled Directory Sync admin portal. You can choose where your groups will be managed. Pick No, manage Runway groups separately from directory groups to keep managing user groups yourself, or Yes, update Runway groups based on your directory group changes to have your directory manage them. For more details, see Where Runway user groups are managed.

   

2. You’ll be redirected to an admin portal hosted by Runway’s SSO/SAML provider, WorkOS. Follow the instructions in the Directory Sync setup flow to configure the Directory Sync connection.

3. You will then be redirected back to Runway, where the Directory Sync status should read Connected.

1. If groups have been created in your identity provider, you’ll see them populated under the Groups to Runway user roles table.

2. If you chose Yes, update Runway groups based on your directory group changes, you can configure the mapping of Groups to Runway user roles for each group to automatically have Runway roles assigned to users that belong to each group.

Once setup is complete, Runway will automatically sync Runway user roles based on each user's configured groups. Additionally, users will be automatically provisioned and deprovisioned in Runway as needed using your directory provider as the source of truth.

Once Directory Sync has been successfully connected, managing Runway user roles from the Runway dashboard will be disabled; your directory provider should be the source of truth for Runway user roles going forward. Removing users from your Runway organization will also be disabled; removing users should be done from your directory provider, which will automatically propagate to Runway.

Where Runway user groups are managed

Directory Sync can manage your Runway user groups for you, or leave them to you:

• Managed in Runway: Directory Sync only provisions your users. You keep managing user groups yourself under Organization settings > Team, from both the Users table and the Groups table. Your Groups to Runway user roles mapping table stays visible as read-only, so an existing mapping isn't lost. To select this option, pick No, manage Runway groups separately from directory groups when activating Directory Sync for the first time.

• From my directory groups: Groups from your directory provider define Runway user groups, according to the mapping you configure under Organization settings > SSO/SAML. User group assignments that already exist in Runway will be overwritten. To select this option, pick Yes, update Runway groups based on your directory group changes when activating Directory Sync for the first time.

Either way, Directory Sync keeps creating, updating and deprovisioning users, and keeps syncing app membership if you use it.

Runway asks where your groups should be managed when you click Directory Sync admin portal to connect a directory for the first time. To change it later, check or uncheck Enable directory groups to Runway groups mapping under Organization settings > SSO/SAML.

Enabling Directory Sync before your users and groups are properly configured may cause unexpected overwrites to existing permissions in Runway, including pilot roles and rotations.

Selecting From my directory groups reapplies your directory groups across your whole directory: any user group assigned by hand in Runway that isn't part of a directory group mapping is removed. This runs in the background and may take a few moments for larger directories. Selecting Managed in Runway keeps the group assignments your users already have.

If you connect a directory from the WorkOS dashboard or straight from your identity provider rather than from Runway, your directory groups manage Runway user groups, and that can be changed afterwards under Organization settings > SSO/SAML.

Configuring Runway app membership sync with Directory Sync

By default, all new users added to Runway are automatically added as members to all apps in your Runway organization. With Directory Sync, you can optionally choose to leverage your directory provider to manage which apps in Runway new users are added to.

Setup

1. In your directory provider, add a custom attribute to your user model to represent the apps in Runway the user should be a member of (we recommend an attribute named runway_apps). The field should be an array of strings. Runway will use this field to assign users to the correct apps in Runway.

2. For each User in your directory, populate the runway_apps field with correct app IDs – note that the app IDs populated in the runway_apps field must match one of the app IDs for your organization’s apps in Runway. You can find each app’s app ID under App settings > General > App identifier for each app in Runway.

3. Alternatively, if your provider supports this, you can set up a rule at the group level to populate the runway_apps field for each user that belongs to the group.

4. Head to the Directory Sync admin portal in Work OS by navigating to Organization settings > SSO/SAML > Directory Sync admin portal. In the section titled Attribute Mapping, fill in the name of your custom attribute in the Directory Provider Value field.

Once configured, Runway will read from your custom attribute to populate the runway_apps field in Runway and sync the user's app membership to match what's defined in your directory provider. If you'd like a user to belong to all apps in Runway, set the value for runway_apps to the wild card, which is ["*"] .

If the runway_apps field is detected on any user, the setting to Add new users to all apps (found in Organization Settings > Team) will be automatically disabled — your directory provider will be considered the source of truth for app membership going forward.

Note that after step 4 is completed, any users that have an empty or missing runway_apps field will be considered as not belonging to any app in Runway, and any previous app membership will be removed, as the aforementioned field will be considered the source of truth.