docs: Describe sso improvements (#10110)

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

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-tokencreator>` 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.

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.

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``
 ================
 

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"