> For the complete documentation index, see [llms.txt](https://docs.runway.team/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.runway.team/using-runway/organization-settings/sso-saml.md).
# 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](mailto:hello@runway.team) if needed, and we'll get this set up.
Runway uses [WorkOS](https://workos.com/) to provide SSO/SAML capabilities to our teams, for a wide range of identity providers.
{% hint style="warning" %}
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](mailto:hello@runway.team) and we’ll enable it.
{% endhint %}
{% hint style="info" %}
Login sessions remain active for 72 hours. After that, users will be prompted to log in again for security and session management purposes.
{% endhint %}
## SSO/SAML configuration
### Setup
Setup and configuration are simple, and can be performed following the steps below.
{% hint style="warning" %}
The Runway user executing these steps must have the **IT Admin** role, which needs to be assigned by the Runway team. [Let us know](mailto:hello@runway.team) the email address of the person in your organization who will be completing SSO/SAML setup and we’ll assign the role.
{% endhint %}
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.
4. Click on the **SSO admin portal** button and follow the instructions in the WorkOS setup flow to configure your SSO connection.
5. 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.
{% hint style="warning" %}
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](#where-runway-user-groups-are-managed) for more details.
{% endhint %}
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.**
2. 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](#where-runway-user-groups-are-managed).
3. 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.
4. You will then be redirected back to Runway, where the Directory Sync status should read **Connected**.
4. If groups have been created in your identity provider, you’ll see them populated under the **Groups to Runway user roles** table.
5. 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.
{% hint style="warning" %}
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.
{% endhint %}
#### 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**.
{% hint style="warning" %}
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.
{% endhint %}
{% hint style="info" %}
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**.
{% endhint %}
### 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 `["*"]` .
{% hint style="warning" %}
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.
{% endhint %}