From a3be60c475d4934526583e6d4499194ca06874d3 Mon Sep 17 00:00:00 2001 From: Tara Charter Date: Mon, 27 Nov 2023 14:04:35 -0600 Subject: [PATCH 1/6] docs: Describe remote user management webui Describe how to manage remote users and groups via webui. Introduce concept of remote authentication and remote user group management. --- docs/manage/users-temp.rst | 98 ++++++++++++++++++++++++++++++++++++++ docs/manage/users.rst | 2 + 2 files changed, 100 insertions(+) create mode 100644 docs/manage/users-temp.rst diff --git a/docs/manage/users-temp.rst b/docs/manage/users-temp.rst new file mode 100644 index 00000000000..4699e3e5109 --- /dev/null +++ b/docs/manage/users-temp.rst @@ -0,0 +1,98 @@ +.. _users-temp: + +################################## + Managing Remote Users and Groups +################################## + +This is a temporary page for the purpose of review. Upon approval, content will be merged into +:ref:`users`. + +************************************************************ + Enabling Remote Authentication via Your IdP (Without SCIM) +************************************************************ + +You can auto manage your user provisioning and group management in Determined. Even if you do not +have SCIM enabled, you can still configure your Determined cluster to auto-provision users. With +this method, the user will be able to sign in to the Determined cluster using the email address they +use to authenticate via SSO. + +.. note:: + + This is only enabled for OIDC users. + +To begin, you'll need set the following OIDC configuration parameter to ``true`` in your master +configuration file. + +``auto_provision_users: true`` + +The system will also group sync via ``security.claim_group_assignments: match``. + +The system will also set the username of the user to the same username the user uses to sign in to +their IdP (and it cannot be set independently). + +For example here the OIDC claim is set to add the user to groups A and B. The display name is set as +well. + +.. code:: + + { + groups: ['A', 'B'], + displayName: "Cee Ray" + } + +These OIDC claims are sent in a Json Web Token from the IdP (e.g., Okta) by the admin. + +This basically defines what info the IdP shares with the application (e.g., Determined) when the +user signs in. + +For example: + +.. code:: yaml + + oidc: + enabled: true + provider: "Okta" + idp_recipient_url: "https://determined.example.com" + idp_sso_url: "https://dev-00000000.okta.com" + client_id: "xx0xx0" + client_secret: "xx0xx0" + auto_provision_users: true + +Once this is configured, to sign in via SSO, the user simply enters their SSO-enabled email address. +For example to sign in to Determined with Okta, the user performs the following steps: + +- Visit the Determined URL, e.g., https://determined.example.com. +- Under Sign in with Okta, enter your SSO email address. + +Upon successfully signing in with their SSO email address, Determined authenticates the user and +adds the user to the user table. + +Cluster admin administrators can view, manage, sort, and filter users via the user table in the +WebUI: + +- Sign in to the Determined cluster via the Determined URL, e.g., https://determined.example.com, + as a cluster admin. +- To view Admin Settings, select your profile in the upper left corner and then choose Admin. + +You can add users, set existing users as remote users, edit users, perform bulk actions, etc. + +*********************** + Managing Remote Users +*********************** + +You can allow Determined to manage remote users in your IdP in accordance with IAM best practices +and have that information passed to Determined upon each successful sign in via SSO without having +to manually modify the users or update them via SCIM. + +You can also manually manage remote users and groups. One way to do this is via the WebUI. You can +also use the CLI. + +Adding a New Remote User in the WebUI +===================================== + +Steps + +Editing an Existing User in the WebUI +===================================== + +Steps diff --git a/docs/manage/users.rst b/docs/manage/users.rst index a1478166cb4..16758bd2bf9 100644 --- a/docs/manage/users.rst +++ b/docs/manage/users.rst @@ -4,6 +4,8 @@ User Accounts ############### +:ref:`users-temp` + Initially, a Determined installation has two user accounts: ``admin`` and ``determined``. Both of these accounts have blank passwords by default. From a5ce07ea3ab541ac6925035cee014efc408033ed Mon Sep 17 00:00:00 2001 From: Tara Charter Date: Wed, 29 Nov 2023 18:16:42 -0600 Subject: [PATCH 2/6] updates --- docs/_shared/attn-enterprise-edition.txt | 3 + docs/manage/security/rbac.rst | 96 ++++++++++++------- docs/manage/users-remote.rst | 117 +++++++++++++++++++++++ docs/manage/users-temp.rst | 98 ------------------- docs/manage/users.rst | 50 +++++++--- 5 files changed, 215 insertions(+), 149 deletions(-) create mode 100644 docs/_shared/attn-enterprise-edition.txt create mode 100644 docs/manage/users-remote.rst delete mode 100644 docs/manage/users-temp.rst diff --git a/docs/_shared/attn-enterprise-edition.txt b/docs/_shared/attn-enterprise-edition.txt new file mode 100644 index 00000000000..ab905b1d339 --- /dev/null +++ b/docs/_shared/attn-enterprise-edition.txt @@ -0,0 +1,3 @@ +.. attention:: + + This feature applies only to Determined Enterprise Edition. diff --git a/docs/manage/security/rbac.rst b/docs/manage/security/rbac.rst index 3e0c1e123d1..0c0515ed231 100644 --- a/docs/manage/security/rbac.rst +++ b/docs/manage/security/rbac.rst @@ -14,8 +14,8 @@ .. warning:: - If you are looking to enable RBAC on an existing Determined installation, please see the - :ref:`migration guide below `. + If you want to enable RBAC on an existing Determined installation, consult the :ref:`migration + guide `. By default, a Determined installation comes with role-based access control disabled. To enable RBAC, set the following option in the master config: @@ -140,6 +140,8 @@ engineers will only have access to the experiments in their respective workspace det -u mle-stop-00 experiment list --all det -u mle-traffic-00 experiment list --all +.. _manage-rbac: + ************* Manage RBAC ************* @@ -150,6 +152,12 @@ Inspecting the Setup CLI --- +To get help with the ``user`` command: + +.. code:: + + det user -h + To get the current user's permission list: .. code:: bash @@ -177,6 +185,12 @@ To list existing users, group and their membership: det user-group list det user-group describe GROUP_NAME +To create a new :ref:`remote user `: + +.. code:: bash + + det -u admin user create --remote + To list the role assignments for a user or a group: .. code:: bash @@ -184,35 +198,45 @@ To list the role assignments for a user or a group: det rbac list-groups-roles GROUP_NAME det rbac list-users-roles USER_NAME +.. _manage-users-groups-webui: + WebUI ----- -To see the user and group management UI, +To manage users and groups via the WebUI: + +#. View **Admin Settings** by selecting your profile in the upper left corner and then choosing + **Admin**. -#. Click on your username in the upper left corner. -#. Click "Settings" -#. See "User Management" and "Group Management" tabs at the top. +Admin Settings displays the **Users** and **Groups** lists. -To create new users, use "New User" button at the "User Management" screen. +To create new users, select **Add User**. To set the user as a :ref:`remote user `:, +select the **Remote** option. + +.. note:: -To see or modify user roles assigned at the global scope, + You can edit any existing user and set them as a remote user to prevent password sign-on and + requiring the user to sign on via the organization's IdP. + +To manage user roles assigned at the global scope: #. Click triple-dot icon on the right of the user entry. -#. Select "Edit" option in the dropdown. +#. Choose **Edit User**. -To see or modify group roles assigned at the global scope, +To manage group roles assigned at the global scope: #. Click triple-dot icon on the right of the group entry. -#. Select "Add Roles" option in the dropdown. +#. Select **Edit Group**. +#. Click inside **Select Global Roles** and add or remove roles. -To see group membership, click on the plus icon on the left of the group entry. +To manage group membership, expand the group by selecting the plus icon. -To remove member users, open group membership list and "Remove" button next to the user entry. +To remove member users, open the group membership list and select **Remove** next to the user entry. To add member users, #. Click triple-dot icon on the right of the group entry. -#. Select "Edit/Add Users" option in the dropdown. +#. Choose **Add Members to Group**. Managing User Groups ==================== @@ -253,20 +277,20 @@ WebUI .. attention:: - Only users with the ClusterAdmin role can add/remove users and groups. + Only users with the ClusterAdmin role can add or remove users and groups. -To see user group management UI, +To manage user groups via the WebUI: -#. Click on your username in the upper left corner. -#. Click "Admin". -#. Click the "Groups" tab at the top. +#. View **Admin Settings** by selecting your profile in the upper left corner and then choosing + **Admin**. +#. Select the **Groups** tab. -To create new groups, use "New Group" button at the "Groups" screen. +To create new groups, select **New Group**. -To delete a group, +To delete a group: -#. Click triple-dot icon on the right of the group entry. -#. Select "Delete" option in the dropdown. +#. Select the triple-dot icon on the right of the group entry. +#. Choose **Delete Group**. Managing Role Assignments ========================= @@ -296,29 +320,30 @@ WORKSPACE_NAME`` switch: WebUI ----- -To assign or unassign a role for a user or a group globally, first go to user or group management -UI: +To assign or unassign a role for a user or a group globally, navigate to user or group management in +the WeUI: .. attention:: Only users with the ClusterAdmin role can add/edit global role assignments for users and groups from the "Admin" menu as described immediately below. -#. Click on your username in the upper left corner. -#. Click "Admin". -#. See "Users" and "Groups" tabs at the top. +#. View **Admin Settings** by selecting your profile in the upper left corner and then choosing + **Admin**. + +Admin Settings displays the **Users** and **Groups** lists. Then, for users: #. Click triple-dot icon on the right of the user entry. -#. Select "Edit" option in the dropdown. +#. Choose **Edit User**. For groups: #. Click triple-dot icon on the right of the group entry. -#. Select "Add Roles" option in the dropdown. +#. Choose **Edit Group**. -To assign or unassign a role for a user or a group on a particular workspace, +To assign or unassign a role for a user or a group on a particular workspace: .. attention:: @@ -326,12 +351,11 @@ To assign or unassign a role for a user or a group on a particular workspace, and groups. #. Go to the workspaces page, select the target workspace. -#. Click "Members" tab at the top. -#. To create new role assignments, click the "Add Members" button at the top right. +#. Select the **Members** tab. +#. To create new role assignments, click **Add Members**. #. To remove existing role assignments, click the triple-dot menu for a user/group and select - "Remove". -#. To edit the role, click on the dropdown in the role column for a user/group and make your - selection. + **Remove**. +#. To edit the role, click on the dropdown in the role column for a user/group and choose a role. .. _rbac-concepts: diff --git a/docs/manage/users-remote.rst b/docs/manage/users-remote.rst new file mode 100644 index 00000000000..45403e84989 --- /dev/null +++ b/docs/manage/users-remote.rst @@ -0,0 +1,117 @@ +.. _remote-users: + +####################### + Managing Remote Users +####################### + +Determined lets you manage users and user provisioning remotely. Remote user provisioning lets you +include and synchronize any information about the user stored in your IdP such as their username, +groups, and display name. Once configured, you can manage remote users without having to manually +modify the users or update them via SCIM. Each time the remote user accesses Determined, their +information is synchronized. + +.. include:: ../_shared/attn-enterprise-edition.txt + +.. note:: + + Only OIDC is supported. + +******************************* + Enable Remote User Management +******************************* + +Set the Auto Provision Option +============================= + +The first step is to configure the :ref:`master configuration file ` to +enable auto provisioning users and the remote management of any information attached to the users. + +- Set ``oidc.auto_provision_users`` option to ``true`` in your :ref:`master configuration file + `. + +.. note:: + + If ``scim_enabled`` is ``true``, then ``oidc.auto_provision_users`` must be ``false``. + +For example: + +.. code:: yaml + + oidc: + enabled: true + provider: "Okta" + idp_recipient_url: "https://determined.example.com" + idp_sso_url: "https://dev-00000000.okta.com" + client_id: "xx0xx0" + client_secret: "xx0xx0" + auto_provision_users: true + +Determined sets the username of the user to the IdP username. You cannot set the username +independently. + +Set the Groups Claim Name Option +================================ + +Determined receives OIDC claims via a JSON Web Token (JWT) that you send from your IdP. If there is +a group that does not already exist in Determined, then the system creates the group. + +To enable group membership synchronization: + +- Set the ``groups_claim_name`` option to match the claim name for group memberships from your + authenticator (i.e., ``groups_memberships``, ``usergroup_memberships``, etc.). + +For example, in the following claim, let's say the user-group information is passed through +``group_memberships`` in your IdP. + +.. code:: + + { + email: dee.ray@example.com + group_memberships: ['A', 'B'], + displayName: "Dee Ray" + } + +Then, Determined creates the following user: + +.. code:: + + { + username: dee.ray@example.com + groups: ['A', 'B'], + displayName: "Dee Ray" + } + +Each time the authenticated user accesses Determined, their information is passed to Determined, and +the changes are made. For example, when a user is assigned to a new group via your IdP, that +information is updated in Determined. + +Complete the Auto Provision Process +=================================== + +Once auto provisioning is configured, the user simply signs in with their username. + +For example, to sign in to Determined via Okta, the user performs the following steps: + +- Visit the Determined URL, e.g., https://determined.example.com. +- Under **Sign in with Okta**, the user enters their SSO-enabled email address. + +If the sign in is successful, Determined provisions the user, adds the user to the user table, and +authenticates the user to Determined. + +********************************************** + Manage Remote Users and Groups via the WebUI +********************************************** + +Admins can manage users and groups in the WebUI. To do this: + +- Sign in to the Determined cluster via the Determined URL, e.g., https://determined.example.com, + as a cluster admin. +- View **Admin Settings** by selecting your profile in the upper left corner and then choosing + **Admin**. + +Actions you can take include adding new users, switching existing users to remote users, performing +bulk actions, and more. For example, using the filters, you can select to view only active users. +You can also manage user groups. + +To find out how to manage remote users via the WebUI, including adding a new remote user, visit +:ref:`manage-users-groups-webui`. diff --git a/docs/manage/users-temp.rst b/docs/manage/users-temp.rst deleted file mode 100644 index 4699e3e5109..00000000000 --- a/docs/manage/users-temp.rst +++ /dev/null @@ -1,98 +0,0 @@ -.. _users-temp: - -################################## - Managing Remote Users and Groups -################################## - -This is a temporary page for the purpose of review. Upon approval, content will be merged into -:ref:`users`. - -************************************************************ - Enabling Remote Authentication via Your IdP (Without SCIM) -************************************************************ - -You can auto manage your user provisioning and group management in Determined. Even if you do not -have SCIM enabled, you can still configure your Determined cluster to auto-provision users. With -this method, the user will be able to sign in to the Determined cluster using the email address they -use to authenticate via SSO. - -.. note:: - - This is only enabled for OIDC users. - -To begin, you'll need set the following OIDC configuration parameter to ``true`` in your master -configuration file. - -``auto_provision_users: true`` - -The system will also group sync via ``security.claim_group_assignments: match``. - -The system will also set the username of the user to the same username the user uses to sign in to -their IdP (and it cannot be set independently). - -For example here the OIDC claim is set to add the user to groups A and B. The display name is set as -well. - -.. code:: - - { - groups: ['A', 'B'], - displayName: "Cee Ray" - } - -These OIDC claims are sent in a Json Web Token from the IdP (e.g., Okta) by the admin. - -This basically defines what info the IdP shares with the application (e.g., Determined) when the -user signs in. - -For example: - -.. code:: yaml - - oidc: - enabled: true - provider: "Okta" - idp_recipient_url: "https://determined.example.com" - idp_sso_url: "https://dev-00000000.okta.com" - client_id: "xx0xx0" - client_secret: "xx0xx0" - auto_provision_users: true - -Once this is configured, to sign in via SSO, the user simply enters their SSO-enabled email address. -For example to sign in to Determined with Okta, the user performs the following steps: - -- Visit the Determined URL, e.g., https://determined.example.com. -- Under Sign in with Okta, enter your SSO email address. - -Upon successfully signing in with their SSO email address, Determined authenticates the user and -adds the user to the user table. - -Cluster admin administrators can view, manage, sort, and filter users via the user table in the -WebUI: - -- Sign in to the Determined cluster via the Determined URL, e.g., https://determined.example.com, - as a cluster admin. -- To view Admin Settings, select your profile in the upper left corner and then choose Admin. - -You can add users, set existing users as remote users, edit users, perform bulk actions, etc. - -*********************** - Managing Remote Users -*********************** - -You can allow Determined to manage remote users in your IdP in accordance with IAM best practices -and have that information passed to Determined upon each successful sign in via SSO without having -to manually modify the users or update them via SCIM. - -You can also manually manage remote users and groups. One way to do this is via the WebUI. You can -also use the CLI. - -Adding a New Remote User in the WebUI -===================================== - -Steps - -Editing an Existing User in the WebUI -===================================== - -Steps diff --git a/docs/manage/users.rst b/docs/manage/users.rst index 16758bd2bf9..40d653e61c1 100644 --- a/docs/manage/users.rst +++ b/docs/manage/users.rst @@ -4,39 +4,59 @@ User Accounts ############### -:ref:`users-temp` +******* + About +******* -Initially, a Determined installation has two user accounts: ``admin`` and ``determined``. Both of -these accounts have blank passwords by default. +Only the ``admin`` user can create users, change users' passwords, and activate or deactivate users. +Upon initial installation, the admin should set an admin password. -The ``admin`` user has the sole privilege to create users, change other users' passwords, and -activate/deactivate users. +Default Accounts +================ -Use ``det user change-password`` via the CLI to set a password for the ``admin`` user. This is -highly encouraged for new installs. +Initially, there are two accounts: + +- ``admin`` (full privileges) +- ``determined`` (for single-user installations) + +Both have blank passwords by default. + +Setting the Admin Password +========================== + +Use the following CLI command to set the admin password: .. code:: det -u admin user change-password -The ``determined`` user is designed for ease of use on a single-user installation. However, teams -will benefit from creating a Determined user account for each individual. Namely, having individual -user accounts provides clearer authorship and improved filtering of entities. To create users in a -Determined installation, use the ``admin`` user to create user accounts for each individual that -would like to use Determined: +Creating Individual User Accounts +================================= + +You can add, edit, and manage users manually via the CLI or the WebUI. + +To create users via the CLI, use the following command: .. code:: det -u admin user create -Then, the ``determined`` user can be deactivated: +To ensure that no one can access the Determined cluster as the ``determined`` user, deactivate it. +Deactivating the ``determined`` user does not remove any objects created by the user. + +To deactivate the ``determined`` user, run the following command: .. code:: det -u admin user deactivate determined -This ensures that no one can access the Determined cluster as the ``determined`` user (any objects -that were created by this user will remain). +Creating Remote Users +===================== + +Admins can configure Determined to auto-provision users who have been added to your IdP. These users +are known as remote users. + +To find out more, visit :ref:`remote-users`. **************** Authentication From 8632af431b34cb868b215bed033762265072d9f7 Mon Sep 17 00:00:00 2001 From: Tara Charter Date: Fri, 1 Dec 2023 17:04:09 -0600 Subject: [PATCH 3/6] resolve review comments --- docs/manage/users-remote.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/manage/users-remote.rst b/docs/manage/users-remote.rst index 45403e84989..89270bb5f82 100644 --- a/docs/manage/users-remote.rst +++ b/docs/manage/users-remote.rst @@ -26,6 +26,7 @@ Set the Auto Provision Option The first step is to configure the :ref:`master configuration file ` to enable auto provisioning users and the remote management of any information attached to the users. +- Enable OIDC. - Set ``oidc.auto_provision_users`` option to ``true`` in your :ref:`master configuration file `. @@ -46,7 +47,7 @@ For example: client_secret: "xx0xx0" auto_provision_users: true -Determined sets the username of the user to the IdP username. You cannot set the username +Determined sets the username of the user to the IdP email address. You cannot set the username independently. Set the Groups Claim Name Option @@ -82,8 +83,8 @@ Then, Determined creates the following user: } Each time the authenticated user accesses Determined, their information is passed to Determined, and -the changes are made. For example, when a user is assigned to a new group via your IdP, that -information is updated in Determined. +group memberships are updated. For example, when a user is assigned to a new group via your IdP, +that information is updated in Determined. Complete the Auto Provision Process =================================== From 3bba6c753e85a742b41a597d5f8ebd0a66d71f47 Mon Sep 17 00:00:00 2001 From: Tara Charter Date: Mon, 4 Dec 2023 12:36:53 -0600 Subject: [PATCH 4/6] set up tabs for oidc and saml --- docs/manage/users-remote.rst | 61 +++++++++++++++++++++++++++--------- 1 file changed, 46 insertions(+), 15 deletions(-) diff --git a/docs/manage/users-remote.rst b/docs/manage/users-remote.rst index 89270bb5f82..fc478663491 100644 --- a/docs/manage/users-remote.rst +++ b/docs/manage/users-remote.rst @@ -26,26 +26,57 @@ Set the Auto Provision Option The first step is to configure the :ref:`master configuration file ` to enable auto provisioning users and the remote management of any information attached to the users. -- Enable OIDC. -- Set ``oidc.auto_provision_users`` option to ``true`` in your :ref:`master configuration file - `. +.. tabs:: -.. note:: + .. tab:: + + OIDC + + - Enable OIDC. + - Set ``oidc.auto_provision_users`` option to ``true`` in your :ref:`master configuration + file `. + + .. note:: + + If ``scim_enabled`` is ``true``, then ``oidc.auto_provision_users`` must be ``false``. + + For example: + + .. code:: yaml + + oidc: + enabled: true + provider: "Okta" + idp_recipient_url: "https://determined.example.com" + idp_sso_url: "https://dev-00000000.okta.com" + client_id: "xx0xx0" + client_secret: "xx0xx0" + auto_provision_users: true + + .. tab:: + + SAML + + - Enable SAML. + - Set ``saml.auto_provision_users`` option to ``true`` in your :ref:`master configuration + file `. + + .. note:: - If ``scim_enabled`` is ``true``, then ``oidc.auto_provision_users`` must be ``false``. + If ``scim_enabled`` is ``true``, then ``saml.auto_provision_users`` must be ``false``. -For example: + For example: -.. code:: yaml + .. code:: yaml - oidc: - enabled: true - provider: "Okta" - idp_recipient_url: "https://determined.example.com" - idp_sso_url: "https://dev-00000000.okta.com" - client_id: "xx0xx0" - client_secret: "xx0xx0" - auto_provision_users: true + samle: + enabled: true + provider: "Okta" + idp_recipient_url: "https://determined.example.com" + idp_sso_url: "https://dev-00000000.okta.com" + client_id: "xx0xx0" + client_secret: "xx0xx0" + auto_provision_users: true Determined sets the username of the user to the IdP email address. You cannot set the username independently. From 884b901bfe7ab07f4eb12e9c00ce783a170a1349 Mon Sep 17 00:00:00 2001 From: Tara Charter Date: Tue, 5 Dec 2023 12:05:41 -0600 Subject: [PATCH 5/6] add oidc parameters and document cli list users documents the following https://github.com/determined-ai/determined/pull/8421 https://github.com/determined-ai/determined-ee/pulls?q=is%3Apr+oidc+in%3Atitle%2Cbody --- docs/manage/security/rbac.rst | 10 +- docs/manage/users-remote.rst | 27 +++-- .../deploy/master-config-reference.rst | 105 +++++++++++++++++- 3 files changed, 125 insertions(+), 17 deletions(-) diff --git a/docs/manage/security/rbac.rst b/docs/manage/security/rbac.rst index 0c0515ed231..34eb462263e 100644 --- a/docs/manage/security/rbac.rst +++ b/docs/manage/security/rbac.rst @@ -177,14 +177,20 @@ To list all existing roles and their permissions: det rbac list-roles -To list existing users, group and their membership: +To list all users, groups, and their membership: .. code:: bash - det user list + det user list --all det user-group list det user-group describe GROUP_NAME +To list only **active** users, remove the ``--all`` (or ``--a``) option: + +.. code:: bash + + det user list + To create a new :ref:`remote user `: .. code:: bash diff --git a/docs/manage/users-remote.rst b/docs/manage/users-remote.rst index fc478663491..8d040cc6887 100644 --- a/docs/manage/users-remote.rst +++ b/docs/manage/users-remote.rst @@ -6,7 +6,7 @@ Determined lets you manage users and user provisioning remotely. Remote user provisioning lets you include and synchronize any information about the user stored in your IdP such as their username, -groups, and display name. Once configured, you can manage remote users without having to manually +display name, and groups. Once configured, you can manage remote users without having to manually modify the users or update them via SCIM. Each time the remote user accesses Determined, their information is synchronized. @@ -14,7 +14,7 @@ information is synchronized. .. note:: - Only OIDC is supported. + As of 026.4, OIDC is supported. ******************************* Enable Remote User Management @@ -47,11 +47,12 @@ enable auto provisioning users and the remote management of any information atta oidc: enabled: true provider: "Okta" - idp_recipient_url: "https://determined.example.com" + idp_recipient_url: "https://determined.example.com/oidc/sso" idp_sso_url: "https://dev-00000000.okta.com" client_id: "xx0xx0" client_secret: "xx0xx0" auto_provision_users: true + display_name_claim_name: "XYZ" .. tab:: @@ -69,14 +70,18 @@ enable auto provisioning users and the remote management of any information atta .. code:: yaml - samle: + saml: enabled: true provider: "Okta" - idp_recipient_url: "https://determined.example.com" - idp_sso_url: "https://dev-00000000.okta.com" - client_id: "xx0xx0" - client_secret: "xx0xx0" + idp_recipient_url: "https://determined.example.com/saml/sso" + idp_sso_url: "https://myorg.okta.com/app/...sso/saml" + idp_cert_path: "okta.cert" auto_provision_users: true + groups_attribute_name: "groups" + display_name_attribute_name: "disp_name" + security: + rbac_ui_enabled: true + type: rbac Determined sets the username of the user to the IdP email address. You cannot set the username independently. @@ -84,8 +89,8 @@ independently. Set the Groups Claim Name Option ================================ -Determined receives OIDC claims via a JSON Web Token (JWT) that you send from your IdP. If there is -a group that does not already exist in Determined, then the system creates the group. +Determined receives OIDC and SAML claims via a JSON Web Token (JWT) that you send from your IdP. If +there is a group that does not already exist in Determined, then the system creates the group. To enable group membership synchronization: @@ -125,7 +130,7 @@ Once auto provisioning is configured, the user simply signs in with their userna For example, to sign in to Determined via Okta, the user performs the following steps: - Visit the Determined URL, e.g., https://determined.example.com. -- Under **Sign in with Okta**, the user enters their SSO-enabled email address. +- Under **Sign in with Okta**, enter the SSO-enabled email address. If the sign in is successful, Determined provisions the user, adds the user to the user table, and authenticates the user to Determined. diff --git a/docs/reference/deploy/master-config-reference.rst b/docs/reference/deploy/master-config-reference.rst index 25a293e529d..69cdc3906a2 100644 --- a/docs/reference/deploy/master-config-reference.rst +++ b/docs/reference/deploy/master-config-reference.rst @@ -1571,12 +1571,109 @@ The username for HTTP basic authentication (only allowed with ``type: basic``). The password for HTTP basic authentication (only allowed with ``type: basic``). +********** + ``oidc`` +********** + +Applies only to Determined Enterprise Edition. The OIDC (OpenID Connect) configuration allows +administrators to integrate an OIDC provider such as Okta for authentication in Determined and is +used for :ref:`remote user ` management. + + For example: + + .. code:: yaml + + oidc: + enabled: true + provider: "Okta" + client_id: "xx0xx0" + client_secret: "xx0xx0" + idp_recipient_url: "https://determined.example.com" + idp_sso_url: "https://dev-00000000.okta.com" + authentication_claim: "string" + scim_authentication_attribute: "string" + auto_provision_users: true + groups_claim_name: "XYZ" + display_name_claim_name: "XYZ" + +``enabled`` +=========== + +Whether to enable OIDC authentication. Defaults to ``false``. + +``provider`` +============ + +The name of the OIDC provider. Officially supported: "okta". + +``client_id`` +============= + +The client identifier provided by the OIDC provider. + +``client-secret`` +================= + +The client secret provided by the OIDC provider. This should be kept confidential. + +``idp_recipient_url`` +===================== + +The URL where your IdP sends OIDC assertions. + +``idp_sso_url`` +=============== + +The Single Sign-On (SSO) URL provided by the OIDC provider. + +``authentication_claim`` +======================== + +The claim used for authentication in OIDC. + +``scim_authentication_attribute`` +================================= + +The attribute used for SCIM authentication. + +``auto_provision_users`` +======================== + +Determines if users should be automatically created in Determined upon successful OIDC authentication. + - ``true``: Automatic user provisioning is enabled. + - ``false``: Automatic user provisioning is disabled. + +``groups_claim_name`` +===================== + +The claim name that specifies group memberships in OIDC. + +``display_name_claim_name`` +=========================== + +The claim name from the OIDC provider used to set the user's display name in Determined. + ********** ``saml`` ********** -Applies only to Determined Enterprise Edition. Specifies whether SAML SSO is enabled and the -configuration to use it. +Applies only to Determined Enterprise Edition. The SAML (Security Assertion Markup Language) +configuration allows administrators to integrate a SAML provider such as Okta for authentication in +Determined. + +For example: + + .. code:: yaml + + saml: + enabled: true + provider: "Okta" + idp_recipient_url: "https://determined.example.com/saml/sso" + idp_sso_url: "https://myorg.okta.com/app/...sso/saml" + idp_cert_path: "okta.cert" + auto_provision_users: true + groups_attribute_name: "groups" + display_name_attribute_name: "disp_name" ``enabled`` =========== @@ -1591,12 +1688,12 @@ The name of the IdP. Currently (officially) supported: "okta". ``idp_recipient_url`` ===================== -The URL your IdP will send SAML assertions to. +The URL where your IdP sends SAML assertions. ``idp_sso_url`` =============== -An IdP-provided URL to redirect SAML requests to. +The Single Sign-On (SSO) URL provided by the SAML provider. ``idp_sso_descriptor_url`` ========================== From 5412a9664ea4c5121bbb97708ae3950c4c308c8d Mon Sep 17 00:00:00 2001 From: Tara Charter Date: Tue, 5 Dec 2023 21:38:37 -0600 Subject: [PATCH 6/6] resolve saml related review comments --- docs/manage/users-remote.rst | 52 +++++++++++-------- .../deploy/master-config-reference.rst | 19 ++++++- 2 files changed, 48 insertions(+), 23 deletions(-) diff --git a/docs/manage/users-remote.rst b/docs/manage/users-remote.rst index 8d040cc6887..075d8a0c96c 100644 --- a/docs/manage/users-remote.rst +++ b/docs/manage/users-remote.rst @@ -77,11 +77,6 @@ enable auto provisioning users and the remote management of any information atta idp_sso_url: "https://myorg.okta.com/app/...sso/saml" idp_cert_path: "okta.cert" auto_provision_users: true - groups_attribute_name: "groups" - display_name_attribute_name: "disp_name" - security: - rbac_ui_enabled: true - type: rbac Determined sets the username of the user to the IdP email address. You cannot set the username independently. @@ -94,29 +89,42 @@ there is a group that does not already exist in Determined, then the system crea To enable group membership synchronization: -- Set the ``groups_claim_name`` option to match the claim name for group memberships from your - authenticator (i.e., ``groups_memberships``, ``usergroup_memberships``, etc.). +.. tabs:: + + .. tab:: + + OIDC + + - Set the ``groups_claim_name`` option to match the claim name for group memberships from + your authenticator (i.e., ``groups_memberships``, ``usergroup_memberships``, etc.). -For example, in the following claim, let's say the user-group information is passed through -``group_memberships`` in your IdP. + For example, in the following claim, let's say the user-group information is passed through + ``group_memberships`` in your IdP. -.. code:: + .. code:: - { - email: dee.ray@example.com - group_memberships: ['A', 'B'], - displayName: "Dee Ray" - } + { + email: dee.ray@example.com + group_memberships: ['A', 'B'], + displayName: "Dee Ray" + } -Then, Determined creates the following user: + Then, Determined creates the following user: -.. code:: + .. code:: + + { + username: dee.ray@example.com + groups: ['A', 'B'], + displayName: "Dee Ray" + } + + .. tab:: + + SAML - { - username: dee.ray@example.com - groups: ['A', 'B'], - displayName: "Dee Ray" - } + - Set the ``groups_attribute_name`` option to match the claim name for group memberships from + your authenticator (i.e., ``groups_memberships``, ``usergroup_memberships``, etc.). Each time the authenticated user accesses Determined, their information is passed to Determined, and group memberships are updated. For example, when a user is assigned to a new group via your IdP, diff --git a/docs/reference/deploy/master-config-reference.rst b/docs/reference/deploy/master-config-reference.rst index 69cdc3906a2..2e2fe3dbcb8 100644 --- a/docs/reference/deploy/master-config-reference.rst +++ b/docs/reference/deploy/master-config-reference.rst @@ -1659,7 +1659,7 @@ The claim name from the OIDC provider used to set the user's display name in Det Applies only to Determined Enterprise Edition. The SAML (Security Assertion Markup Language) configuration allows administrators to integrate a SAML provider such as Okta for authentication in -Determined. +Determined and is used for :ref:`remote user ` management. For example: @@ -1706,6 +1706,23 @@ requests and responses. The path to the IdP's certificate, used to validate assertions. +``auto_provision_users`` +======================== + +Determines if users should be automatically created in Determined upon successful SAML authentication. + - ``true``: Automatic user provisioning is enabled. + - ``false``: Automatic user provisioning is disabled. + +``groups_attribute_name`` +========================= + +The claim name that specifies group memberships in SAML. + +``display_name_attribute_name`` +=============================== + +The claim name from the SAML provider used to set the user's display name in Determined. + ******************** ``reserved_ports`` ********************