diff --git a/docs/admin/runai-setup/authentication/accessrules.md b/docs/admin/runai-setup/authentication/accessrules.md new file mode 100644 index 0000000000..78a4e65f73 --- /dev/null +++ b/docs/admin/runai-setup/authentication/accessrules.md @@ -0,0 +1,74 @@ +This article explains the procedure to manage Access rules. + +Access rules provide users, groups, or applications privileges to system entities. + +An access rule is the assignment of a role to a subject in a scope: \ is a \ in a \. + +For example, user **user@domain.com** is a **department admin** in **department A**. + +## Access rules table + +The Access rules table can be found under **Tools & Settings** in the Run:ai platform. + +The Access rules table provides a list of all the access rules defined in the platform, and allows you to manage them. + + + +!!! Note + __Flexible management__ + + It is also possible to manage access rules directly for a specific user, application, project, or department. + +![](img/accessrulestable.png) + +The Access rules table consists of the following columns: + +| Column | Description | +| :---- | :---- | +| Type | The type of subject assigned to the access rule (user, SSO group, or application). | +| Subject | The user, SSO group, or application assigned with the role | +| Role | The role assigned to the subject | +| Scope | The scope to which the subject has access. Click the name of the scope to see the scope and its subordinates | +| Authorized by | The user who granted the access rule | +| Creation time | The timestamp for when the rule was created | +| Last updated | The last time the access rule was updated | + +### Customizing the table view + +* Filter - Click ADD FILTER, select the column to filter by, and enter the filter values +* Search - Click SEARCH and type the value to search by +* Sort - Click each column header to sort by +* Column selection - Click COLUMNS and select the columns to display in the table +* Download table - Click MORE and then Click Download as CSV + +## Adding new access rules + +To add a new access rule: + +1. Click **\+NEW ACCESS RULE** +1. Select a subject **User, SSO Group**, or **Application** +1. Select or enter the subject identifier: + * **User Email** for a local user created in Run:ai or for SSO user as recognized by the IDP + * **Group name** as recognized by the IDP + * **Application name** as created in Run:ai +1. Select a role +1. Select a scope +1. Click **SAVE RULE** + +!!!Note + An access rule consists of a single subject with a single role in a single scope. To assign multiple roles or multiple scopes to the same subject, multiple access rules must be added. + +## Editing an access rule + +Access rules cannot be edited. To change an access rule, you must delete the rule, and then create a new rule to replace it. + +## Deleting an access rule + +1. Select the access rule you want to delete +1. Click **DELETE** +1. On the dialog, click **DELETE** to confirm the deletion + +## Using API + +Go to the [Access rules](https://app.run.ai/api/docs#tag/Access-rules) API reference to view the available actions + diff --git a/docs/admin/runai-setup/authentication/applications.md b/docs/admin/runai-setup/authentication/applications.md new file mode 100644 index 0000000000..1df0ad595b --- /dev/null +++ b/docs/admin/runai-setup/authentication/applications.md @@ -0,0 +1,99 @@ +This article explains the procedure to manage applications and it’s permissions. + +Applications are used for API integrations with Run:ai. An application contains a secret key. Using the secret key you can obtain a token and use it within subsequent API calls. + +Applications are managed locally and assigned with Access Rules to manage its permissions. + +For example, application **ci-pipeline-prod** assigned with a **Researcher** role in **Cluster: A**. + +## Applications table + +The Applications table can be found under **Tools & Settings** in the Run:ai platform. + +The Applications table provides a list of all the applications defined in the platform, and allows you to manage them. + +![](img/appstable.png) + + +The Applications table consists of the following columns: + +| Column | Description | +| :---- | :---- | +| Application | The name of the application | +| Status | The status of the application | +| Access rule(s) | The access rules assigned to the application | +| Last login | The timestamp for the last time the user signed in | +| Created by | The user who created the application | +| Creation time | The timestamp for when the application was created | +| Last updated | The last time the application was updated | + +### Customizing the table view + +* Filter \- Click ADD FILTER, select the column to filter by, and enter the filter values +* Search \- Click SEARCH and type the value to search by +* Sort \- Click each column header to sort by +* Column selection \- Click COLUMNS and select the columns to display in the table +* Download table \- Click MORE and then Click Download as CSV + +## Creating an application + +To create an application: + +1. Click **\+NEW APPLICATION** +1. Enter the application’s **Name** +1. Click **CREATE** +1. Copy the credentials and store it securely: + * **Application name** + * **Secret key** +1. Click **DONE** + +!!!Note + The secret key is visible only at the time of creation, it cannot be recovered but can be regenerated. + +## Adding an access rule to an application + +To create an access rule: + +1. Select the application you want to add an access rule for +1. Click **ACCESS RULES** +1. Click **\+ACCESS RULE** +1. Select a role +1. Select a scope +1. Click **SAVE RULE** +1. Click **CLOSE** + +## Deleting an access rule from an application + +To delete an access rule: + +1. Select the application you want to remove an access rule from +1. Click **ACCESS RULES** +1. Find the access rule assigned to the user you would like to delete +1. Click on the trash icon +1. Click **CLOSE** + +## Regenerating key + +To regenerate an application’s key: + +1. Select the application you want to regenerate it’s secret key +1. Click **REGENERATE KEY** +1. Click **REGENERATE** +1. Review the user’s credentials and store it securely: + * **Application** name + * **Secret key** +1. Click **DONE** + +!!!Warning + Regenerating an application key revokes its previous key. + +## Deleting an application + +1. Select the application you want to delete +1. Click **DELETE** +1. On the dialog, click **DELETE** to confirm the deletion + +## Using API + +Go to the [Applications](https://app.run.ai/api/docs#tag/Applications), [Access rules](https://app.run.ai/api/docs#tag/Access-rules) API reference to view the available actions + diff --git a/docs/admin/runai-setup/authentication/authentication-overview.md b/docs/admin/runai-setup/authentication/authentication-overview.md index 0e28389893..f3f9ce8c62 100644 --- a/docs/admin/runai-setup/authentication/authentication-overview.md +++ b/docs/admin/runai-setup/authentication/authentication-overview.md @@ -1,64 +1,66 @@ -## Authentication Overview +# Authentication & Authorization -To access Run:ai resources, you have to authenticate. The purpose of this document is to explain how authentication works at Run:ai. +Run:ai Authentication & Authorization enables a streamlined experience for the user with precise controls covering the data each user can see and the actions each user can perform in the Run:ai platform. -## Authentication Endpoints +Authentication verifies user identity during login, and Authorization assigns the user with specific permissions according to the assigned access rules. -Generally speaking, there are two authentication endpoints: +Authenticated access is required to use all aspects of the Run:ai interfaces, including the Run:ai platform, the Run:ai Command Line Interface (CLI) and APIs. -* The Run:ai control plane. -* Run:ai GPU clusters. +## Authentication -Both endpoints are accessible via APIs as well as a user interface. +There are multiple methods to authenticate and access Run:ai. +### Single Sign-On (SSO) -## Identity Service +Single Sign-On (SSO) is the preferred authentication method by large organizations, as it avoids the need to manage duplicate sets of user identities. -Run:ai includes an internal identity service. The identity service ensures users are who they claim to be and gives them the right kind of access to Run:ai. - -## Users +Run:ai offers SSO integration, enabling users to utilize existing organizational credentials to access Run:ai without requiring dedicated credentials. -Out of the box, The Run:ai identity service provides a way to create users and associate them with access roles. +Run:ai supports three methods to setup SSO: -It is also possible to configure the Run:ai identity service to connect to a company directory using the SAML protocol. For more information see [single sign-on](sso.md). +* [SAML](sso/saml.md) +* [OpenID Connect (OIDC)](sso/openidconnect.md) +* [OpenShift](sso/openshift.md) -## Authentication Method +When using SSO, it is highly recommended to manage at least one local user, as a breakglass account (an emergency account), in case access to SSO is not possible. -Both endpoints described above are protected via time-limited oauth2-like JWT authentication tokens. +### Username and password -There are two ways of getting a token: +Username and password access can be used when SSO integration is not possible. -* Using a user/password combination. -* Using [client applications](../../../developer/overview-developer.md) for API access. +### Secret key (for Application programmatic access) +Secret is the authentication method for Applications. Applications use the Run:ai APIs to perform automated tasks including scripts and pipelines based on its assigned access rules. -## Authentication Flows +## Authorization -### Run:ai control plane +The Run:ai platform uses Role Base Access Control (RBAC) to manage authorization. -You can use the Run:ai user interface to provide user/password. These are validated against the identity service. Run:ai will return a token with the right access rights for continued operation. +Once a user or an application is authenticated, they can perform actions according to their assigned access rules. -You can also use a client application to get a token and then connect directly to the [administration API endpoint](../../../developer/admin-rest-api/overview.md). -### Run:ai GPU Clusters +### Role Based Access Control (RBAC) in Run:ai -The Run:ai GPU cluster is a _Kubernetes_ cluster. All communication into Kubernetes flows through the [Kubernetes API server](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/){target=_blank}. +While Kubernetes RBAC is limited to a single cluster, Run:ai expands the scope of Kubernetes RBAC, making it easy for administrators to manage access rules across multiple clusters. -To facilitate authentication via Run:ai the Kubernetes API server must be configured to use the Run:ai identity service to validate authentication tokens. For more information on how to configure the Kubernetes API server see _Kubernetes configuration_ under [researcher authentication](researcher-authentication.md#mandatory-kubernetes-configuration). +RBAC at Run:ai is configured using access rules. -## Inactivity timeout +An access rule is the assignment of a role to a subject in a scope: `` is a `` in a ``. -:octicons-versions-24: Version 2.10 and later. +* **Subject** + * A user, a group, or an application assigned with the role +* **Role** + * A set of permissions that can be assigned to subjects + * A permission is a set of actions (view, edit, create and delete) over a Run:ai entity (e.g. projects, workloads, users) + * For example, a role might allow a user to create and read Project, but not update or delete them + * Roles at Run:ai are system defined and cannot be created, edited or deleted +* **Scope** + * A set of resources that are accessible to a subject for a specific role + * A scope is a part of an organization that can be accessed based on assigned roles. Scopes include Projects, Departments, Clusters, Account (all clusters) -Run:ai session should timeout after 1 hour of inactivity. +Below is an example of an access rule: **username@company.com** is a **Department admin** in **Department: A** -!!! Note - Timeout settings are configured in minutes. -To configure the inactivity timeout: -1. Open `Settings | General`. -2. Set the inactivity timeout in minutes. (Default is 60) -## See also +![](img/auth-rbac.png) + -* To configure authentication for researchers [researcher authentication](researcher-authentication.md). -* To configure single sign-on, see [single sign-on](sso.md). diff --git a/docs/admin/runai-setup/authentication/img/accessrulestable.png b/docs/admin/runai-setup/authentication/img/accessrulestable.png new file mode 100644 index 0000000000..3eba34b967 Binary files /dev/null and b/docs/admin/runai-setup/authentication/img/accessrulestable.png differ diff --git a/docs/admin/runai-setup/authentication/img/appstable.png b/docs/admin/runai-setup/authentication/img/appstable.png new file mode 100644 index 0000000000..a89540d4b1 Binary files /dev/null and b/docs/admin/runai-setup/authentication/img/appstable.png differ diff --git a/docs/admin/runai-setup/authentication/img/auth-rbac.png b/docs/admin/runai-setup/authentication/img/auth-rbac.png new file mode 100644 index 0000000000..a3f57b31c2 Binary files /dev/null and b/docs/admin/runai-setup/authentication/img/auth-rbac.png differ diff --git a/docs/admin/runai-setup/authentication/img/rolestable.png b/docs/admin/runai-setup/authentication/img/rolestable.png new file mode 100644 index 0000000000..56bef5e939 Binary files /dev/null and b/docs/admin/runai-setup/authentication/img/rolestable.png differ diff --git a/docs/admin/runai-setup/authentication/img/userstable.png b/docs/admin/runai-setup/authentication/img/userstable.png new file mode 100644 index 0000000000..06f5bf80f9 Binary files /dev/null and b/docs/admin/runai-setup/authentication/img/userstable.png differ diff --git a/docs/admin/runai-setup/authentication/roles.md b/docs/admin/runai-setup/authentication/roles.md new file mode 100644 index 0000000000..9955b152c0 --- /dev/null +++ b/docs/admin/runai-setup/authentication/roles.md @@ -0,0 +1,48 @@ +This article explains the roles in the Run:ai platform. + +A role is a set of permissions that can be assigned to a subject in a scope. + +A permission is a set of actions (View, Edit, Create & Delete) over a Run:ai entity (e.g. projects, workloads, users). + +## Roles table + +The Roles table can be found under **Tools & Settings** in the Run:ai platform. + +The Roles table displays a list of predefined roles available to users in the Run:ai platform. It is not possible to create additional rules or edit or delete existing rules. + +![](img/rolestable.png) + + +The Roles table consists of the following columns: + +| Column | Description | +| :---- | :---- | +| Role | The name of the role | +| Created by | The name of the role creator | +| Creation time | The timestamp when the role was created | + +### Customizing the table view + +* Filter - Click ADD FILTER, select the column to filter by, and enter the filter values +* Search - Click SEARCH and type the value to search by +* Sort - Click each column header to sort by +* Column selection - Click COLUMNS and select the columns to display in the table +* Download table - Click MORE and then Click Download as CSV + +## Reviewing a role + +* **Role name** - The name of the role +* **Permissions** - Displays the available permissions defining the role, as follows: + +| Column | Description | +| :---- | :---- | +| Entity | A system-managed object that can be viewed, edited, created or deleted by a user based on their assigned role and scope | +| View | If checked, an assigned user with this role can view instances of this type of entity within their defined scope | +| Edit | If checked, an assigned user with this role can change the settings of an instance of this type of entity within their defined scope | +| Create | If checked, an assigned user with this role can create new instances of this type of entity within their defined scope | +| Delete | If checked, an assigned user with this role can delete instances of this type of entity within their defined scope | + +* + ## Using API + Go to the [Roles](https://app.run.ai/api/docs#tag/Roles) API reference to view the available actions + diff --git a/docs/admin/runai-setup/authentication/sso/img/openid-unexpected.png b/docs/admin/runai-setup/authentication/sso/img/openid-unexpected.png new file mode 100644 index 0000000000..92757ad29e Binary files /dev/null and b/docs/admin/runai-setup/authentication/sso/img/openid-unexpected.png differ diff --git a/docs/admin/runai-setup/authentication/sso/img/openshift-identityerror.png b/docs/admin/runai-setup/authentication/sso/img/openshift-identityerror.png new file mode 100644 index 0000000000..0636ad7c3e Binary files /dev/null and b/docs/admin/runai-setup/authentication/sso/img/openshift-identityerror.png differ diff --git a/docs/admin/runai-setup/authentication/sso/img/unauthorized-client.png b/docs/admin/runai-setup/authentication/sso/img/unauthorized-client.png new file mode 100644 index 0000000000..146a1da251 Binary files /dev/null and b/docs/admin/runai-setup/authentication/sso/img/unauthorized-client.png differ diff --git a/docs/admin/runai-setup/authentication/sso/openidconnect.md b/docs/admin/runai-setup/authentication/sso/openidconnect.md new file mode 100644 index 0000000000..03d34ac8ce --- /dev/null +++ b/docs/admin/runai-setup/authentication/sso/openidconnect.md @@ -0,0 +1,141 @@ +Single Sign-On (SSO) is an authentication scheme, allowing users to log-in with a single pair of credentials to multiple, independent software systems. + +This article explains the procedure to configure single sign-on to Run:ai using the OpenID Connect protocol. + +## Prerequisites + +Before starting, make sure you have the following available from your identity provider: + +* Discovery URL - the OpenID server where the content discovery information is published. +* ClientID - the ID used to identify the client with the Authorization Server. +* Client Secret - a secret password that only the Client and Authorization server know. +* Optional: Scopes - a set of user attributes to be used during authentication to authorize access to a user's details. + +## Setup + +Follow the steps below to setup SSO with OpenID Connect. + +### Adding the identity provider + +1. Go to **Tools & Settings** → **General** +1. Open the Security section and click **+IDENTITY PROVIDER** +1. Select **Custom OpenID Connect** +1. Enter the **Discovery URL**, **Client ID**, and **Client Secret** +1. Copy the Redirect URL to be used in your identity provider +1. Optional: Add the OIDC scopes +1. Optional: Enter the user attributes and their value in the identity provider (see the user attributes table below) +1. Click **SAVE** + User attributes + +| Attribute | Default value in Run:ai | Description | +| :---- | :---- | :---- | +| User role groups | GROUPS | If it exists in the IDP, it allows you to assign Run:ai role groups via the IDP. The IDP attribute must be a list of strings. | +| Linux User ID | UID | If it exists in the IDP, it allows Researcher containers to start with the Linux User UID. Used to map access to network resources such as file systems to users. The IDP attribute must be of type integer. | +| Linux Group ID | GID | If it exists in the IDP, it allows Researcher containers to start with the Linux Group GID. The IDP attribute must be of type integer. | +| Supplementary Groups | SUPPLEMENTARYGROUPS | If it exists in the IDP, it allows Researcher containers to start with the relevant Linux supplementary groups. The IDP attribute must be a list of integers. | +| Email | email | Defines the user attribute in the IDP holding the user's email address, which is the user identifier in Run:ai | +| User first name | firstName | Used as the user’s first name appearing in the Run:ai user interface | +| User last name | lastName | Used as the user’s last name appearing in the Run:ai user interface | + +### Testing the setup + +1. Log-in to the Run:ai platform as an admin +1. Add [Access Rules](../accessrules.md) to an SSO user defined in the IDP +1. Open the Run:ai platform in an incognito browser tab +1. On the sign-in page click **CONTINUE WITH SSO** + You are redirected to the identity provider sign in page +1. In the identity provider sign-in page, log in with the SSO user who you granted with access rules +1. If you are unsuccessful signing-in to the identity provider, follow the Troubleshooting section below + +### Editing the identity provider + +You can view the identity provider details and edit its configuration: + +1. Go to **Tools & Settings** → **General** +1. Open the Security section +1. On the identity provider box, click **Edit identity provider** +1. You can edit either the **Discovery URL**, **Client ID**, **Client Secret**, **OIDC scopes**, or the **User attributes** + + ### Removing the identity provider** + +You can remove the identity provider configuration: + +1. Go to **Tools & Settings** → **General** +1. Open the Security section +1. On the identity provider card, click **Remove identity provider** +1. In the dialog, click **REMOVE** to confirm the action + +!!! Note + To avoid losing access, removing the identity provider must be carried out by a local user. + +## Troubleshooting + +If testing the setup was unsuccessful, try the different troubleshooting scenarios according to the error you received. + +### Troubleshooting scenarios + +??? "403 - Sorry, we can’t let you see this page. Something about permissions…" + **Description:** The authenticated user is missing permissions + + **Mitigation**: + + 1. Validate either the user or its related group/s are assigned with [access rules](../accessrules.md) + 1. Validate groups attribute is available in the configured OIDC Scopes + 1. Validate the user’s groups attribute is mapped correctly + + **Advanced:** + + 1. Open the Chrome DevTools: Right-click on page → Inspect → Console tab + 1. Run the following command to retrieve and paste the user’s token: `localStorage.token;` + 1. Paste in [https://jwt.io](https://jwt.io/) + 1. Under the Payload section validate the values of the user’s attributes + +??? "401 - We’re having trouble identifying your account because your email is incorrect or can’t be found." + **Description:** Authentication failed because email attribute was not found. + + **Mitigation**: + + 1. Validate email attribute is available in the configured OIDC Scopes + 1. Validate the user’s email attribute is mapped correctly + +??? "Unexpected error when authenticating with identity provider" + + ![](img/openshift-identityerror.png) + + **Description:** User authentication failed + + **Mitigation**: + + 1. Validate that the configured OIDC Scopes exist and match the Identity Provider’s available scopes + + **Advanced:** + + 1. Look for the specific error message in the URL address + +??? "Unexpected error when authenticating with identity provider (SSO sign-in is not available)" + + ![](img/openid-unexpected.png) + + **Description:** User authentication failed + + **Mitigation**: + + 1. Validate that the configured OIDC scope exists in the Identity Provider + 1. Validate the configured Client Secret match the Client Secret in the Identity Provider + + **Advanced:** + + 1. Look for the specific error message in the URL address + +??? "Client not found" + **Description:** OIDC Client ID was not found in the Identity Provider + + **Mitigation**: + + 1. Validate that the configured Client ID matches the Identity Provider Client ID + + + + + + diff --git a/docs/admin/runai-setup/authentication/sso/openshift.md b/docs/admin/runai-setup/authentication/sso/openshift.md new file mode 100644 index 0000000000..16799fa2dd --- /dev/null +++ b/docs/admin/runai-setup/authentication/sso/openshift.md @@ -0,0 +1,136 @@ +Single Sign-On (SSO) is an authentication scheme, allowing users to log-in with a single pair of credentials to multiple, independent software systems. + +This article explains the procedure to configure single sign-on to Run:ai using the OpenID Connect protocol in OpenShift V4. + +## Prerequisites + +Before starting, make sure you have the following available from your OpenShift cluster: + +* OpenShift OAuth client - see [Registering an additional OAuth client](https://docs.openshift.com/container-platform/4.16/authentication/configuring-oauth-clients.html#oauth-register-additional-client_configuring-oauth-clients) + * ClientID - the ID used to identify the client with the Authorization Server. + * Client Secret - a secret password that only the Client and Authorization Server know. +* Base URL - the OpenShift API Server endpoint (example: [https://api.:6443](https://api.noa-ocp.runailabs.com:6443/)) + +## Setup + +Follow the steps below to setup SSO with OpenShift. + +### Adding the identity provider + +1. Go to **Tools & Settings** → **General** +1. Open the Security section and click **+IDENTITY PROVIDER** +1. Select **OpenShift V4** +1. Enter the **Base URL**, Client ID, and **Client Secret** from your OpenShift OAuth client. +1. Copy the Redirect URL to be used in your OpenShift OAuth client +1. Optional: Enter the user attributes and their value in the identity provider (see the user attributes table below) +1. Click **SAVE** + User attributes + +| Attribute | Default value in Run:ai | Description | +| :---- | :---- | :---- | +| User role groups | GROUPS | If it exists in the IDP, it allows you to assign Run:ai role groups via the IDP. The IDP attribute must be a list of strings. | +| Linux User ID | UID | If it exists in the IDP, it allows researcher containers to start with the Linux User UID. Used to map access to network resources such as file systems to users. The IDP attribute must be of type integer. | +| Linux Group ID | GID | If it exists in the IDP, it allows researcher containers to start with the Linux Group GID. The IDP attribute must be of type integer. | +| Supplementary Groups | SUPPLEMENTARYGROUPS | If it exists in the IDP, it allows researcher containers to start with the relevant Linux supplementary groups. The IDP attribute must be a list of integers. | +| Email | email | Defines the user attribute in the IDP holding the user's email address, which is the user identifier in Run:ai | +| User first name | firstName | Used as the user’s first name appearing in the Run:ai platform | +| User last name | lastName | Used as the user’s last name appearing in the Run:ai platform | + +### Testing the setup + +1. Open the Run:ai platform as an admin +1. Add [Access Rules](../accessrules.md) to an SSO user defined in the IDP +1. Open the Run:ai platform in an incognito browser tab +1. On the sign-in page click **CONTINUE WITH SSO** + You are redirected to the OpenShift IDP sign-in page +1. In the identity provider sign-in page, log-in with the SSO user who you granted with access rules +1. If you are unsuccessful signing-in to the identity provider, follow the Troubleshooting section below + +## Editing the identity provider + +You can view the identity provider details and edit its configuration: + +1. Go to **Tools & Settings** → **General** +1. Open the Security section +1. On the identity provider box, click **Edit identity provider** +1. You can edit either the **Base URL**, **Client ID**, **Client Secret**, or the **User attributes** + +### Removing the identity provider + +You can remove the identity provider configuration: + +1. Go to **Tools & Settings** → **General** +1. Open the Security section +1. On the identity provider card, click **Remove identity provider** +1. In the dialog, click **REMOVE** to confirm the action + +!!! Note + To avoid losing access, removing the identity provider must be carried out by a local user. + +## Troubleshooting + +If testing the setup was unsuccessful, try the different troubleshooting scenarios according to the error you received. + +### Troubleshooting scenarios + +??? "403 - Sorry, we can’t let you see this page. Something about permissions…" + **Description:** The authenticated user is missing permissions + + **Mitigation**: + + 1. Validate either the user or its related group/s are assigned with [access rules](../accessrules.md) + 1. Validate groups attribute is available in the configured OIDC Scopes + 1. Validate the user’s groups attribute is mapped correctly + + **Advanced:** + + 1. Open the Chrome DevTools: Right-click on page → Inspect → Console tab + 1. Run the following command to retrieve and copy the user’s token: `localStorage.token;` + 1. Paste in [https://jwt.io](https://jwt.io/) + 1. Under the Payload section validate the value of the user’s attributes + +??? "401 - We’re having trouble identifying your account because your email is incorrect or can’t be found." + **Description:** Authentication failed because e-mail attribute was not found. + + **Mitigation**: + + 1. Validate email attribute is available in the configured OIDC Scopes + 1. Validate the user’s email attribute is mapped correctly + +??? "Unexpected error when authenticating with identity provider" + ![](img/openshift-identityerror.png) + + **Description:** User authentication failed + + **Mitigation**: + + 1. Validate the the configured OIDC Scopes exist and match the Identity Provider’s available scopes + + **Advanced:** + + 1. Look for the specific error message in the URL address + +??? "Unexpected error when authenticating with identity provider (SSO sign-in is not available)" + ![](img/openid-unexpected.png) + + **Description:** User authentication failed + + **Mitigation**: + + 1. Validate that the configured OIDC scope exists in the Identity Provider + 1. Validate that the configured Client Secret matches the Client Secret value in the OAuthclient Kubernetes object. + + **Advanced:** + + 1. Look for the specific error message in the URL address + +??? "unauthorized_client" + ![](img/unauthorized-client.png) + + **Description:** OIDC Client ID was not found in the OpenShift IDP + + **Mitigation**: + + 1. Validate that the configured Client ID matches the value in the OAuthclient Kubernetes object. + + diff --git a/docs/admin/runai-setup/authentication/sso/saml.md b/docs/admin/runai-setup/authentication/sso/saml.md new file mode 100644 index 0000000000..06825127bd --- /dev/null +++ b/docs/admin/runai-setup/authentication/sso/saml.md @@ -0,0 +1,141 @@ +Single Sign-On (SSO) is an authentication scheme, allowing users to log-in with a single pair of credentials to multiple, independent software systems. + +This article explains the procedure to [configure SSO to Run:ai](../authentication-overview.md) using the SAML 2.0 protocol. + +## Prerequisites + +Before starting, ensure you have the following available from your identity provider: + +* SAML XML Metadata + +## Setup + +Follow the steps below to setup SSO with SAML. + +### Adding the identity provider + +1. Go to **Tools & Settings** → **General** +2. Open the Security section and click **+IDENTITY PROVIDER** +3. Select **Custom SAML 2.0** +4. Select either **From computer** or **From URL** + * From computer - click the Metadata XML file field, then select your file for upload + * From URL - in the Metadata XML URL field, enter the URL to the XML Metadata file +5. Copy the Redirect URL and Entity ID to be used in your identity provider +6. Optional: Enter the user attributes and their value in the identity provider (see the user attributes table below) + +| Attribute | Default value in Run:ai | Description | +| :---- | :---- | :---- | +| User role groups | GROUPS | If it exists in the IDP, it allows you to assign Run:ai role groups via the IDP. The IDP attribute must be a list of strings. | +| Linux User ID | UID | If it exists in the IDP, it allows Researcher containers to start with the Linux User UID. Used to map access to network resources such as file systems to users. The IDP attribute must be of type integer. | +| Linux Group ID | GID | If it exists in the IDP, it allows Researcher containers to start with the Linux Group GID. The IDP attribute must be of type integer. | +| Supplementary Groups | SUPPLEMENTARYGROUPS | If it exists in the IDP, it allows Researcher containers to start with the relevant Linux supplementary groups. The IDP attribute must be a list of integers. | +| Email | email | Defines the user attribute in the IDP holding the user's email address, which is the user identifier in Run:ai. | +| User first name | firstName | Used as the user’s first name appearing in the Run:ai platform. | +| User last name | lastName | Used as the user’s last name appearing in the Run:ai platform. | + +7. Click **SAVE** + + +### Testing the setup + +1. Open the Run:ai platform as an admin +1. Add [Access Rules](../accessrules.md) to an SSO user defined in the IDP +1. Open the Run:ai platform in an incognito browser tab +1. On the sign-in page click **CONTINUE WITH SSO.** + You are redirected to the identity provider sign in page +1. In the identity provider sign-in page, log-in with the SSO user who you granted with access rules +1. If you are unsuccessful signing-in to the identity provider, follow the Troubleshooting section below + +### Editing the identity provider + +You can view the identity provider details and edit its configuration: + +1. Go **Tools & Settings** → **General** +1. Open the Security section +1. On the identity provider box, click **Edit identity provider** +1. You can edit either the metadata file or the user attributes +1. You can view the identity provider URL, identity provider entity ID, and the certificate expiration date + +### Removing the identity provider + +You can remove the identity provider configuration: + +1. Go to **Tools & Settings** → **General** +1. Open the Security section +1. On the identity provider card, click **Remove identity provider** +1. In the dialog, click **REMOVE** to confirm the action + +!!! Note + To avoid losing access, removing the identity provider must be carried out by a local user. + +## Downloading the XML metadata file + +You can download the XML file to view the identity provider settings: + +1. Go to **Tools & Settings** → **General** +1. Open the Security section +1. On the identity provider card, click **Download metadata XML file** + +## Troubleshooting + +If testing the setup was unsuccessful, try the different troubleshooting scenarios according to the error you received. If an error still occurs, check the advanced troubleshooting section. + +### Troubleshooting scenarios + +??? "Invalid signature in response from identity provider" + **Description**: After trying to log-in, the following message is received in the RunLai log-in page. + **Mitigation:** + 1. Go to the Tools & Settings menu + 1. Click **General** + 1. Open the Security section + 1. In the identity provider box, check for a "Certificate expired” error + 1. If it is expired, update the SAML metadata file to include a valid certificate + +??? "401 - We’re having trouble identifying your account because your email is incorrect or can’t be found." + **Description:** Authentication failed because email attribute was not found. + + **Mitigation**: + + 1. Validate the user’s email attribute is mapped correctly + +??? "403 - Sorry, we can’t let you see this page. Something about permissions…" + + **Description:** The authenticated user is missing permissions + + **Mitigation**: + + 1. Validate either the user or its related group/s are assigned with [access rules](../accessrules.md) + 1. Validate the user’s groups attribute is mapped correctly + + **Advanced:** + + 1. Open the Chrome DevTools: Right-click on page → Inspect → Console tab + 1. Run the following command to retrieve and paste the user’s token: `localStorage.token;` + 1. Paste in [https://jwt.io](https://jwt.io) + 1. Under the Payload section validate the values of the user’s attributes + +### Advanced Troubleshooting + +??? "Validating the SAML request" + + The SAML login flow can be separated into two parts: + + * Run:ai redirects to the IDP for log-ins using a SAML Request + * On successful log-in, the IDP redirects back to Run:ai with a SAML Response + + Validate the SAML Request to ensure the SAML flow works as expected: + + 1. Go to the Run:ai login screen + 1. Open the Chrome Network inspector: Right-click → Inspect on the page → Network tab + 1. On the sign-in page click CONTINUE WITH SSO. + 1. Once redirected to the Identity Provider, search in the Chrome network inspector for an HTTP request showing the SAML Request. Depending on the IDP url, this would be a request to the IDP domain name. For example, `accounts.google.com/idp?1234`. + 1. When found, go to the Payload tab and copy the value of the SAML Request + 1. Paste the value into a SAML decoder (e.g. [https://www.samltool.com/decode.php](https://www.samltool.com/decode.php)) + 1. Validate the request: + * The content of the `` tag is the same as `Entity ID` given when adding the identity provider + * The content of the `AssertionConsumerServiceURL` is the same as the `Redirect URI` given when adding the identity provider + 1. Validate the response: + * The user email under the `` tag is the same as the logged-in user + * Make sure that under the `` tag, there is an Attribute named `email` (lowercase). This attribute is mandatory. + * If other, optional user attributes (`groups`, `firstName`, `lastName`, `uid`, `gid`) are mapped make sure they also exist under `` along with their respective values. + diff --git a/docs/admin/runai-setup/authentication/users.md b/docs/admin/runai-setup/authentication/users.md new file mode 100644 index 0000000000..2759429d69 --- /dev/null +++ b/docs/admin/runai-setup/authentication/users.md @@ -0,0 +1,102 @@ +This article explains the procedure to manage users and their permissions. + +Users can be managed locally, or via the Identity provider, while assigned with Access Rules to manage its permissions. + +For example, user **user@domain.com** is a **department admin** in **department A**. + +## Users table + +The Users table can be found under **Tools & Settings** in the Run:ai platform. + +The users table provides a list of all the users in the platform. +You can manage local users and manage user permissions (access rules) for both local and SSO users. + +!!! Note + __Single Sign-On users__ + + SSO users are managed by the identity provider and appear once they have signed in to Run:ai + +![](img/userstable.png) + +The Users table consists of the following columns: + +| Column | Description | +| :---- | :---- | +| User | The unique identity of the user (email address) | +| Type | The type of the user \- SSO / local | +| Last login | The timestamp for the last time the user signed in | +| Access rule(s) | The access rules assigned to the user | +| Created By | The user who created the user | +| Creation time | The timestamp for when the user was created | +| Last updated | The last time the user was updated | + +### Customizing the table view + +* Filter - Click ADD FILTER, select the column to filter by, and enter the filter values +* Search - Click SEARCH and type the value to search by +* Sort - Click each column header to sort by +* Column selection - Click COLUMNS and select the columns to display in the table +* Download table - Click MORE and then Click Download as CSV + +## Creating a local user + +To create a local user: + +1. Click **\+NEW LOCAL USER** +1. Enter the user’s **Email address** +1. Click **CREATE** +1. Review and copy the user’s credentials: + * **User Email** + * **Temporary password** to be used on first sign-in +1. Click **DONE** + +!!! Note + The temporary password is visible only at the time of user’s creation, and must be changed after the first sign-in + +## Adding an access rule to a user + +To create an access rule: + +1. Select the user you want to add an access rule for +1. Click **ACCESS RULES** +1. Click **\+ACCESS RULE** +1. Select a role +1. Select a scope +1. Click **SAVE RULE** +1. Click **CLOSE** + +## Deleting user’s access rule + +To delete an access rule: + +1. Select the user you want to remove an access rule from +1. Click **ACCESS RULES** +1. Find the access rule assigned to the user you would like to delete +1. Click on the trash icon +1. Click **CLOSE** + +## Resetting a user password + +To reset a user’s password: + +1. Select the user you want to reset it’s password +1. Click **RESET PASSWORD** +1. Click **RESET** +1. Review and copy the user’s credentials: + * **User Email** + * **Temporary password** to be used on next sign-in +1. Click **DONE** + +## Deleting a user + +1. Select the user you want to delete +1. Click **DELETE** +1. In the dialog, click **DELETE** to confirm the deletion + +!!!Note + To ensure administrative operations are always available, at least one local user with System Administrator role should exist. + +## Using API + +Go to the [Users](https://app.run.ai/api/docs#tag/Users), [Access rules](https://app.run.ai/api/docs#tag/Access-rules) API reference to view the available actions + diff --git a/docs/admin/runai-setup/authentication/sso.md b/graveyard/sso.md similarity index 99% rename from docs/admin/runai-setup/authentication/sso.md rename to graveyard/sso.md index 83b8c133f8..cbb1f7e038 100644 --- a/docs/admin/runai-setup/authentication/sso.md +++ b/graveyard/sso.md @@ -1,3 +1,5 @@ +Previous version of document + # Single Sign-On Single Sign-On (SSO) is an authentication scheme allowing users to log in with a single ID to other, independent, software systems. SSO solves security issues involving multiple user/password data entries, multiple compliance schemes, etc. diff --git a/mkdocs.yml b/mkdocs.yml index 1cea279e31..875bffd624 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -96,8 +96,6 @@ plugins: 'admin/runai-setup/self-hosted/k8s/ui.md' : 'admin/runai-setup/self-hosted/k8s/backend.md' 'admin/runai-setup/advanced/overview.md' : 'admin/runai-setup/config/overview.md' 'admin/runai-setup/advanced/node-roles.md' : 'admin/runai-setup/config/node-roles.md' - 'admin/runai-setup/advanced/researcher-authentication.md' : 'admin/runai-setup/authentication/sso.md' - 'admin/runai-setup/advanced/sso.md' : 'admin/runai-setup/authentication/sso.md' 'admin/runai-setup/advanced/access-roles.md' : 'admin/runai-setup/config/access-roles.md' 'admin/runai-setup/advanced/allow-external-access-to-containers.md' : 'admin/runai-setup/config/allow-external-access-to-containers.md' 'admin/runai-setup/advanced/non-root-containers.md' : 'admin/runai-setup/config/non-root-containers.md' @@ -106,11 +104,11 @@ plugins: 'admin/runai-setup/advanced/node-downtime.md' : 'admin/runai-setup/maintenance/node-downtime.md' 'admin/runai-setup/advanced/alert-monitoring.md' : 'admin/runai-setup/maintenance/alert-monitoring.md' 'admin/runai-setup/config/researcher-authentication.md' : 'admin/runai-setup/authentication/researcher-authentication.md' - 'admin/runai-setup/config/sso.md' : 'admin/runai-setup/authentication/sso.md' 'admin/runai-setup/cluster-setup/cluster-troubleshooting.md' : 'admin/troubleshooting/troubleshooting.md' 'admin/runai-setup/cluster-setup/nvidia.md' : 'admin/runai-setup/cluster-setup/cluster-prerequisites.md' 'admin/runai-setup/self-hosted/ocp/ocp-dependencies.md' : 'admin/runai-setup/self-hosted/ocp/preparations.md' - 'admin/runai-setup/cluster-setup/researcher-authentication.md' : 'admin/runai-setup/authentication/sso.md' + 'admin/runai-setup/cluster-setup/researcher-authentication.md' : 'admin/runai-setup/authentication/authentication-overview.md' + 'admin/runai-setup/authentication/sso.md' : 'admin/runai-setup/authentication/authentication-overview.md' 'admin/researcher-setup/cli-troubleshooting.md' : 'admin/troubleshooting/troubleshooting.md' 'developer/deprecated/inference/submit-via-yaml.md' : 'developer/cluster-api/other-resources.md' nav: @@ -177,11 +175,18 @@ nav: - 'Backup & Restore' : 'admin/runai-setup/config/dr.md' - 'High Availability' : 'admin/runai-setup/config/ha.md' - 'Scaling' : 'admin/runai-setup/config/large-clusters.md' - - 'Authentication' : + - 'Authentication & Authorization' : - 'Overview' : 'admin/runai-setup/authentication/authentication-overview.md' + - 'Single Sign-On' : + - 'Setup SSO with SAML' : 'admin/runai-setup/authentication/sso/saml.md' + - 'Setup SSO with OpenID Connect' : 'admin/runai-setup/authentication/sso/openidconnect.md' + - 'Setup SSO with OpenShift' : 'admin/runai-setup/authentication/sso/openshift.md' + - 'Users' : 'admin/runai-setup/authentication/users.md' + - 'Applications' : 'admin/runai-setup/authentication/applications.md' + - 'Roles' : 'admin/runai-setup/authentication/roles.md' + - 'Access Rules' : 'admin/runai-setup/authentication/accessrules.md' - 'Access control' : 'admin/runai-setup/access-control/rbac.md' - 'Researcher Authentication' : 'admin/runai-setup/authentication/researcher-authentication.md' - - 'Single Sign-On' : 'admin/runai-setup/authentication/sso.md' - 'Notifications System': - 'Email and System Notifications': 'admin/runai-setup/notifications/notifications.md' - 'Maintenance' :