# SAML role sync: maintaining Workato roles in the identity provider
SAML ROLE SYNC CONFIGURATIONS
Workato supports two different SAML role sync configurations depending on your workspace setup:
Legacy permissions model: Use the
workato_role
,workato_role_test
, andworkato_role_prod
attributes to assign workspace-level roles directly through SAML.New permissions model: Use the same
workato_role
,workato_role_test
, andworkato_role_prod
attributes to assign environment roles in DEV, TEST, and PROD. Additionally, you can use theworkato_user_groups
attribute to assign users to collaborator groups for project-level access. Environment roles and project-level access are managed separately.
Managing access across multiple SaaS applications, such as Workato, can be complex and error-prone. For example, you may face challenges in the following areas:
User lifecycle
Provisioning, changing user roles, and deprovisioning become increasingly difficult as your organization scales, especially when many custom roles exist.
Security
Enforcing consistent organization-wide security policies for Workato can be challenging because of manual role configuration steps.
Lack of automation
Most applications require configuration to automate user provisioning and permissions.
To address these challenges, Workato supports SAML role sync for both workspaces using the legacy permissions model and workspaces using the new permission model. How roles and project-level access are assigned depends on your workspace configuration.
# How SAML role sync works
Workato synchronizes user roles with the SAML attributes you configure in your identity provider (IdP):
- In workspaces using the legacy permissions model, the attributes
workato_role
,workato_role_test
, andworkato_role_prod
map users to workspace-level system roles (for example, Admin, Analyst, Operator, or custom roles). - In workspaces using the new permissions model, the same attributes map users to environment roles (for example, Environment admin, Environment manager, or Member). You can also use
workato_user_groups
to assign users to collaborator groups for project-level access.
Workato automatically synchronizes these assignments whenever you update the mapped SAML attributes in your identity provider.
For example, you can change a user's workato_role
attribute from Environment admin to Member inside the IdP, and Workato automatically updates their environment permissions. Similarly, if you assign a user to the Analytics_Team
collaborator group using workato_user_groups
, Workato adds them to that group, and the user inherits the project-level permissions defined for it.
Workato supports SAML role sync for all customers who enable SSO on their identity provider. In this document, we describe how to use SAML role sync for the following identity providers:
We support SAML role sync in all regions.
Recommendation
Workato strongly recommends that you manage user role assignment through your identity provider after configuring the role sync, because the system overwrites manual role changes.
# Support for environment-specific roles
If you have environments enabled with Workato (through the Lifecycle Management feature), you can sync environment-specific user roles from your IdP. Workato defines the following custom attributes that map to specific environment roles:
- DEV
workato_role
- TEST
workato_role_test
- PROD
workato_role_prod
In workspaces using the legacy permissions model, these attributes map directly to workspace-level roles (Admin, Analyst, Operator, or custom roles).
In workspaces using the new permissions model, these attributes map to environment roles such as Environment admin, Environment manager, or Member. These attributes are still required even if you also use workato_user_groups
for project-level access.
# Project-level access through collaborator groups
In workspaces using the new permissions model, you can assign users to collaborator groups by syncing the workato_user_groups
attribute through your identity provider.
For example, if you map a user to the Analytics_Team
collaborator group in Okta, Workato automatically assigns the user to that group, and they inherit the project-level permissions configured for that group within Workato.
# Enable role sync
To use the role sync with your identity provider, you must enable the feature in the Workato interface.
Recommendation
If not already turned on, we recommend enabling the Enforce SAML authentication and Enable SAML JIT provisioning options at the same time.
Go to Workspace admin > Login methods > Settings.
Enable the Enable role sync toggle.
Enable role sync in Workato
Click Validate settings.
Click Save.
# Next steps
Complete role sync set-up on your identity provider. In this section, we describe how to connect to the following:
Last updated: 10/7/2025, 3:50:03 PM