From 2302856e5600e8e032f191b612875b05f3bd62f5 Mon Sep 17 00:00:00 2001 From: Tara Date: Wed, 23 Oct 2024 15:41:29 -0500 Subject: [PATCH] docs: Describe sso improvements (#10110) --- docs/manage/security/_index.rst | 43 +++++---- docs/manage/security/access-tokens.rst | 120 +++++++++++++++++++++++++ docs/manage/security/auto-posix.rst | 61 +++++++++++++ docs/manage/security/rbac.rst | 2 + docs/manage/users-remote.rst | 2 + 5 files changed, 210 insertions(+), 18 deletions(-) create mode 100644 docs/manage/security/access-tokens.rst create mode 100644 docs/manage/security/auto-posix.rst diff --git a/docs/manage/security/_index.rst b/docs/manage/security/_index.rst index 4dd2d06cbd7..cf7a3d22f31 100644 --- a/docs/manage/security/_index.rst +++ b/docs/manage/security/_index.rst @@ -4,25 +4,32 @@ Security ########## -These security features apply only to Determined Enterprise Edition, except for TLS. +These security features apply only to Determined Enterprise Edition, except where noted. -+-------------------+----------------------------------------------------------------------------+ -| Security Feature | Description | -+===================+============================================================================+ -| :ref:`oauth` | Enable, list, and remove OAuth clients. | -+-------------------+----------------------------------------------------------------------------+ -| :ref:`tls` | Set up the master and agents to use TLS security. | -+-------------------+----------------------------------------------------------------------------+ -| :ref:`oidc` | Integrate OpenID Connect, with and Okta example. | -+-------------------+----------------------------------------------------------------------------+ -| :ref:`saml` | Integrate Security Assertion Markup Language (SAML) authentication to use | -| | single sign-on (SSO) with your organizationidentity provider (IdP). | -+-------------------+----------------------------------------------------------------------------+ -| :ref:`scim` | Integrate System for Cross-domain Identity Management (SCIM) for | -| | administrators to easily and securely provision users and groups. | -+-------------------+----------------------------------------------------------------------------+ -| :ref:`rbac` | Configure Role-Based Access Control. | -+-------------------+----------------------------------------------------------------------------+ ++-----------------------+-------------------------------------------------------------------------+ +| Security Feature | Description | ++=======================+=========================================================================+ +| :ref:`oauth` | Enable, list, and remove OAuth clients. | ++-----------------------+-------------------------------------------------------------------------+ +| :ref:`tls` | Set up the master and agents to use TLS security. This feature is | +| | available for both Determined Open Source and Enterprise editions. | ++-----------------------+-------------------------------------------------------------------------+ +| :ref:`oidc` | Integrate OpenID Connect, with an Okta example. | ++-----------------------+-------------------------------------------------------------------------+ +| :ref:`saml` | Integrate Security Assertion Markup Language (SAML) authentication to | +| | use single sign-on (SSO) with your organization's identity provider | +| | (IdP). | ++-----------------------+-------------------------------------------------------------------------+ +| :ref:`scim` | Integrate System for Cross-domain Identity Management (SCIM) for | +| | administrators to easily and securely provision users and groups. | ++-----------------------+-------------------------------------------------------------------------+ +| :ref:`rbac` | Configure Role-Based Access Control. | ++-----------------------+-------------------------------------------------------------------------+ +| :ref:`access-tokens` | Manage access tokens to enable secure automation of workflows through | +| | API authentication. | ++-----------------------+-------------------------------------------------------------------------+ +| :ref:`auto-posix` | Configure automatic POSIX user linking based on OIDC/SAML claims. | ++-----------------------+-------------------------------------------------------------------------+ .. toctree:: :maxdepth: 1 diff --git a/docs/manage/security/access-tokens.rst b/docs/manage/security/access-tokens.rst new file mode 100644 index 00000000000..4513c685c9e --- /dev/null +++ b/docs/manage/security/access-tokens.rst @@ -0,0 +1,120 @@ +.. _access-tokens: + +############### + Access Tokens +############### + +Access tokens provide a secure way to authenticate automated workflows without requiring frequent +user login. These tokens can be created, managed, and revoked as needed, enhancing both security and +convenience for your workflows. + +************************ + Creating Access Tokens +************************ + +To create a new access token, use the following CLI command: + +.. code:: + + det token create [username] --expiration-days DAYS --description DESCRIPTION + +For example: + +.. code:: + + det token create determined --expiration-days 30 --description "Automated testing token" + +This command will output the token ID and the actual token. Make sure to save the token securely, as +it won't be displayed again. + +************************ + Managing Access Tokens +************************ + +Access Token Permissions +======================== + +The :ref:`token creator ` RBAC role allows users to create, view, and revoke +their own access tokens. The ``TokenCreator`` role can only be assigned globally. + +Users with the ``TokenCreator`` role can perform the following actions: + +- Create access tokens for themselves +- View their own active and revoked tokens +- Revoke their own tokens + +Administrators and users with appropriate permissions can manage tokens for all users. + +List Tokens +=========== + +To view all active access tokens: + +.. code:: + + det token list + +You can also use options to display revoked tokens. + +Describe Tokens +=============== + +To get detailed information about specific tokens: + +.. code:: + + det token describe TOKEN_ID [TOKEN_ID ...] + +Edit Tokens +=========== + +To update a token's description: + +.. code:: + + det token edit TOKEN_ID --description "New description" + +Revoking Tokens +=============== + +To revoke an access token: + +.. code:: + + det token revoke TOKEN_ID + +********************* + Using Access Tokens +********************* + +To authenticate using an access token: + +.. code:: + + det token login YOUR_ACCESS_TOKEN + +This will create a session authenticated with the token's associated user. + +*************** + API Endpoints +*************** + +You can also use the following API endpoints to manage access tokens: + +- ``POST /api/v1/tokens``: Create a new access token +- ``GET /api/v1/tokens``: Retrieve a list of access tokens +- ``PATCH /api/v1/tokens/{token_id}``: Edit an existing access token + +For detailed API usage, please refer to our API documentation. + +************************* + Security Considerations +************************* + +- Treat access tokens like passwords. Never share them or commit them to version control. +- Define an appropriate lifespan for your tokens based on your use case. +- Regularly audit and rotate your access tokens. +- Revoke tokens immediately if they are no longer needed or may have been compromised. + +Access tokens enhance automation while maintaining strong security protocols by allowing tighter +control over token usage and expiration. diff --git a/docs/manage/security/auto-posix.rst b/docs/manage/security/auto-posix.rst new file mode 100644 index 00000000000..d11f4b99fda --- /dev/null +++ b/docs/manage/security/auto-posix.rst @@ -0,0 +1,61 @@ +.. _auto-posix: + +############################## + Automatic POSIX User Linking +############################## + +Determined supports automatic POSIX user linking based on OIDC/SAML claims. This feature streamlines +user management by automatically associating SSO identities with POSIX users on your cluster. + +*************** + Configuration +*************** + +To enable automatic POSIX user linking, you must configure your OIDC or SAML integration to include +the necessary claims. The exact configuration depends on your identity provider. + +OIDC Configuration +================== + +For OIDC, add the following to your master configuration: + +.. code:: yaml + + oidc: + auto_provision_users: true + posix_user_claim: "preferred_username" # or the appropriate claim for your setup + +SAML Configuration +================== + +For SAML, add the following to your master configuration: + +.. code:: yaml + + saml: + auto_provision_users: true + posix_user_attribute: "uid" # or the appropriate attribute for your setup + +******* + Usage +******* + +Once configured, when a user authenticates via SSO, Determined will automatically: + +#. Check for the specified claim/attribute in the SSO response. +#. If found, use this value to link the SSO identity to a POSIX user on the cluster. +#. If the POSIX user doesn't exist, create it (if your configuration allows). + +This process happens transparently to the end-user, providing a seamless SSO experience while +maintaining proper POSIX permissions on your cluster. + +************************* + Security Considerations +************************* + +- Ensure that your SSO provider is correctly configured to provide the necessary claims/attributes. +- Regularly audit your user mappings to ensure they remain accurate and up-to-date. +- Consider implementing additional access controls or monitoring for sensitive operations. + +By leveraging automatic POSIX user linking, you can simplify user management, enhance security, and +provide a smoother experience for your users. diff --git a/docs/manage/security/rbac.rst b/docs/manage/security/rbac.rst index b0664f77fc1..f1e19029fa0 100644 --- a/docs/manage/security/rbac.rst +++ b/docs/manage/security/rbac.rst @@ -538,6 +538,8 @@ assigned globally. where ``ROLE_ID`` is the integer role identifier, as listed in ``det rbac list-roles``. To disable the assignment of any roles to the newly created workspace, set ``enabled: false``. +.. _rbac-tokencreator: + ``TokenCreator`` ================ diff --git a/docs/manage/users-remote.rst b/docs/manage/users-remote.rst index 176a8c2dae9..dd948f369b4 100644 --- a/docs/manage/users-remote.rst +++ b/docs/manage/users-remote.rst @@ -51,6 +51,7 @@ enable user auto-provisioning and the remote management of any information attac client_secret: "xx0xx0" auto_provision_users: true always_redirect: true + posix_user_claim: "preferred_username" display_name_attribute_name: "XYZ" agent_uid_attribute_name: "user_id_key" agent_gid_attribute_name: "group_id_key" @@ -81,6 +82,7 @@ enable user auto-provisioning and the remote management of any information attac idp_metadata_path: "https://myorg.okta.com/app/.../sso/saml/metadata" auto_provision_users: true always_redirect: true + posix_user_attribute: "uid" agent_uid_attribute_name: "user_id_key" agent_gid_attribute_name: "group_id_key" agent_user_name_attribute_name: "agent_user_key"