diff --git a/docs/modules/organization/images/enforce-sso-ui.png b/docs/modules/organization/images/enforce-sso-ui.png new file mode 100644 index 000000000..f94de9488 Binary files /dev/null and b/docs/modules/organization/images/enforce-sso-ui.png differ diff --git a/docs/modules/organization/images/pass-enforce-sso.png b/docs/modules/organization/images/pass-enforce-sso.png new file mode 100644 index 000000000..0e2031141 Binary files /dev/null and b/docs/modules/organization/images/pass-enforce-sso.png differ diff --git a/docs/modules/organization/images/user-sso-config.png b/docs/modules/organization/images/user-sso-config.png new file mode 100644 index 000000000..b58e39256 Binary files /dev/null and b/docs/modules/organization/images/user-sso-config.png differ diff --git a/docs/modules/organization/nav.adoc b/docs/modules/organization/nav.adoc index b09f45e40..16d0beb92 100644 --- a/docs/modules/organization/nav.adoc +++ b/docs/modules/organization/nav.adoc @@ -37,6 +37,7 @@ ** xref:organization:sso-authentication/use-okta.adoc[] ** xref:organization:sso-authentication/use-onelogin.adoc[] ** xref:organization:sso-authentication/use-ping.adoc[] +** xref:organization:sso-authentication/sso-enforcement-guide.adoc[] * xref:organization:other-settings.adoc[] diff --git a/docs/modules/organization/pages/sso-authentication/sso-enforcement-guide.adoc b/docs/modules/organization/pages/sso-authentication/sso-enforcement-guide.adoc new file mode 100644 index 000000000..3520b29ee --- /dev/null +++ b/docs/modules/organization/pages/sso-authentication/sso-enforcement-guide.adoc @@ -0,0 +1,183 @@ += SSO enforcement and role assignment +:description: Configure SSO login enforcement at the user and organization level, and manage role and team assignments through your identity provider + +SSO enforcement in Kobiton controls how users authenticate and how roles and teams are assigned. Three switches govern this behavior: + +- *SSO Only* — Restricts a single user to SSO login. +- *Enforce users to login to Kobiton only through SSO* — Restricts all active users in the organization to SSO login. +- *Pass role / team assignments to users in the SAML validations* — Delegates role and team assignment to the identity provider (IdP). + +These switches have dependencies: + +- The organization-level enforce switch overrides individual *SSO Only* settings. +- The role/team passthrough switch requires organization-wide SSO enforcement to be enabled first. + +== Prerequisites + +Before configuring SSO enforcement: + +- A valid SSO configuration must be added, verified, and saved in *Settings* > *SSO Settings*. +- Your account must have the required permissions for the settings being configured. + +SSO enforcement and role/team passthrough settings remain unavailable until SSO configuration is verified successfully. + +== Enforce SSO login for an individual user + +The *SSO Only* switch restricts a single user to SSO-only authentication. + +*Location:* *Org Management* > *Users* > select a user + +*Required permission:* `org_management.modify` + +image:user-sso-config.png[width=1000,alt="Where to find the users in the Org management UI"] + +=== Behavior when individual SSO enforcement is enabled + +When *SSO Only* is enabled for a user: + +- The user must log in through SSO. +- Username and password login is disabled. +- The user cannot reset their password through *Forgot Password*. + +=== Behavior when individual SSO enforcement is disabled + +When *SSO Only* is disabled for a user: + +- The user can log in through SSO, if the organization's SSO configuration is valid. +- The user can log in with a username and password. +- The user can use *Forgot Password* to create or reset a password. + +== Enforce SSO login for the organization + +The *Enforce users to login to Kobiton only through SSO* switch restricts all active users in the organization to SSO-only authentication. + +*Location:* *Settings* > *SSO Settings* + +*Required permission:* `org_setting.modify_sso_setting` + +image:enforce-sso-ui.png[width=1000,alt="Enforce SSO login in Settings > SSO Settings"] + +=== Behavior when organization-wide SSO enforcement is enabled + +When *Enforce SSO* is enabled: + +- All active users must log in through SSO unless they are on the exemption list. +- *SSO Only* is automatically enabled for all active users except exempted users. +- Users who are not exempted cannot use username/password login or *Forgot Password*. +- Individual *SSO Only* settings cannot be edited. + +=== Exemption list + +When *Enforce SSO* is enabled, the *Choose users who are allowed to login without SSO* field appears. Add users to this list to exempt them from organization-wide SSO enforcement. + +[Important] +==== +Keep at least one administrator on the exemption list. If SSO becomes unavailable, exempted users are the only accounts that can still access Kobiton Portal. +==== + +=== Behavior when organization-wide SSO enforcement is disabled + +When *Enforce SSO* is disabled: + +- Users can log in through SSO if the organization's SSO configuration is valid. +- Users can log in with a username and password. +- Users can use *Forgot Password* to create or reset a password. +- Individual *SSO Only* settings can be edited again. + +== Pass role and team assignments through SAML + +The *Pass role / team assignments to users in the SAML validations* switch delegates role and team assignment to the identity provider (IdP). + +When enabled, Kobiton synchronizes user roles and team assignments from IdP group memberships during SSO login. + +In the UI, this setting appears as *Pass role / team assignments to users in the SAML validations*. The feature maps IdP-provided SAML attribute values to Kobiton roles and teams. + +*Location:* *Settings* > *SSO Settings* + +*Required permission:* `org_setting.modify_sso_setting` + +image:pass-enforce-sso.png[width=1000,alt="Pass enforcments window in Settings > SSO Settings"] + +=== Before enabling role and team passthrough + +Ensure all of the following conditions are met: + +- *Enforce SSO* is enabled in *Settings* > *SSO Settings*. +- A valid value has been entered in the *Org Admin Team* field. +- The IdP contains a group with the same name as the *Org Admin Team* value. +- Your account belongs to that IdP group. +- The SSO configuration has been verified successfully. + +=== Behavior when role and team passthrough is enabled + +When role and team passthrough is enabled: + +- Kobiton synchronizes user roles and team assignments from IdP group memberships during SSO login. +- Users who exist in Kobiton but not in the IdP retain their current roles and teams. +- The *Invite* button in *Org Management* > *Users* is disabled. New users can only be created through the IdP. +- Manual role assignment in *Org Management* > *Users* and *Org Management* > *Roles* is disabled. + +=== Behavior when role and team passthrough is disabled + +When role and team passthrough is disabled: + +- Kobiton stops synchronizing roles and teams from the IdP during SSO login. +- Manual role assignment in *Org Management* > *Users* and *Org Management* > *Roles* is enabled for users with the appropriate permissions. +- The *Invite* button in *Org Management* > *Users* is enabled for users with the appropriate permissions. + +== Configure SSO Attribute Values + +The *SSO Attribute Value* field contains the IdP group or attribute value that Kobiton maps to a role or team. + +Example: if your IdP sends the group value `Engineering-QA`, enter `Engineering-QA` as the *SSO Attribute Value* for the corresponding Kobiton team. + +=== Configure Attribute values for a team + +1. Open *Org Management* > *Teams*. +2. Select an existing team or create a new team. +3. In the *SSO Attribute Value* field, enter the IdP group values that map to this team. +4. To add multiple values, separate them with `;` or press *Enter* after each value. +5. Save the team. + +=== Configure Attribute values for a role + +1. Open *Org Management* > *Roles*. +2. Select an existing role or create a new role. +3. In the *SSO Attribute Value* field, enter the IdP group values that map to this role. +4. To add multiple values, separate them with `;` or press *Enter* after each value. +5. Save the role. + +When role and team passthrough is disabled, the *SSO Attribute Value* field is hidden. + +== Role and team synchronization rules + +When role and team passthrough is enabled, Kobiton synchronizes roles and team assignments from IdP group memberships during SSO login. + +=== Team assignment + +==== Users in the Org Admin Team group + +- Users in the IdP group configured as *Org Admin Team* receive the predefined *ADMIN* role. +- Users with the *ADMIN* role are not assigned to additional Kobiton teams through SSO group mapping. +- Existing manual team assignments remain unchanged. + +==== All other users + +- Users are assigned to Kobiton teams when their IdP group matches a team's *SSO Attribute Value*. +- Users are removed from Kobiton teams when no current IdP group matches the team's *SSO Attribute Value*. +- All users remain assigned to *Default Team* regardless of IdP group membership. + +=== Role assignment + +- Users are assigned Kobiton roles when their IdP group matches a role's *SSO Attribute Value*. +- Users are removed from Kobiton roles when no current IdP group matches the role's *SSO Attribute Value*. +- Users who are not in the *Org Admin Team* group receive the predefined *MEMBER* role. + +=== ADMIN role and Org Admin Team synchronization + +The predefined *ADMIN* role and the *Org Admin Team* field remain synchronized: + +- The *SSO Attribute Value* for the *ADMIN* role always matches the values configured in *Org Admin Team*. +- Updating either field automatically updates the other. + +Users in an IdP group listed in *Org Admin Team* receive the *ADMIN* role at their next SSO login.