> For the complete documentation index, see [llms.txt](https://docs.uibakery.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uibakery.io/on-premise/sso/role-syncronization.md). # Role synchronization Role synchronization allows automatic role assignment to users based on their identity provider ### Enable role syncronization By default, UI Bakery does not sync any roles provided by the Identity Provider. To enable role synchronization, set the following environment variables: ``` UI_BAKERY_SSO_SYNC_ROLES=true UI_BAKERY_SSO_SYNC_ROLES_ON_LOGIN=true ``` Out of the box, UI Bakery will attempt to match received roles by names. UI Bakery will try to retrieve the role name(s) from a claim (attribute) named `role`. If a match is found (e.g., the SSO returned a `role=support` claim, and UI Bakery has a `support` role in the workspace), the user's current roles will be replaced with the matched SSO role(s). ### Advanced settings You can fine-tune role synchronization with the variables below. #### UI\_BAKERY\_SSO\_SYNC\_ROLES\_ON\_LOGIN By default, it is set to `false`, and roles are synchronized only during sign-up. If set to `true`, roles are synchronized every time during login and sign-up. For OpenID providers, it is also possible to sync roles with every [token refresh](/on-premise/sso/openid/token-refresh.md). *** **UI\_BAKERY\_SSO\_ROLE\_MAPPING** Set up a mapping between SSO provider roles/groups and UI Bakery roles when they aren't matched by name, e.g: ```bash UI_BAKERY_SSO_ROLE_MAPPING=identityRoleName->bakeryRoleName,identityRoleName2->bakeryRoleName2 ``` *** **UI\_BAKERY\_SSO\_DEFAULT\_ROLE** Use this variable to specify the fallback UI Bakery role assigned to a new user who joins an existing workspace through OAuth/OIDC or SAML SSO. ```bash UI_BAKERY_SSO_DEFAULT_ROLE=support ``` The role must already exist in the target workspace. If the specified role does not exist, user registration fails. The fallback role is used when role synchronization is disabled, or when soft role synchronization is enabled but none of the roles received from the identity provider match a UI Bakery role. When matching roles are found, they take precedence over the default role. When hard role synchronization is enabled, registration still fails if no roles match. If the variable is omitted or empty, UI Bakery assigns the built-in `user` role. This setting applies only to newly registered SSO users. It does not change the roles of existing users, invited users, or workspace owners. *** **UI\_BAKERY\_SSO\_SYNC\_ROLES\_BY\_NAME** By default is set to `true`. You can set it to `false` to control role syncing exclusively using the mapping `UI_BAKERY_SSO_ROLE_MAPPING` variable. *** **UI\_BAKERY\_SSO\_HARD\_SYNC\_ROLES** By default, it's `false`. When set to `true`, UI Bakery overwrites all roles, removing existing ones and adding new ones received from the Identity Provider even if there are no roles provided. {% hint style="warning" %} Please note, that if no roles are matched, the user will be removed from the organization and will no longer be able to access it. {% endhint %} *** **UI\_BAKERY\_SSO\_SYNC\_ROLES\_FOR\_EDITOR\_AND\_ADMIN** By default, UI Bakery syncs roles only for end-users, leaving admin and editor roles untouched. Set it to `true` to sync roles for all users. {% hint style="warning" %} Please note, that in a case of malformed configuration, admin accounts may lose access to the system {% endhint %} *** #### UI\_BAKERY\_SSO\_ROLE\_CLAIM By default has `role` value. You can change this variable to configure which claim is used as the source for roles. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.uibakery.io/on-premise/sso/role-syncronization.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.