first-commit

Author: yarongol

docs/admin/runai-setup/authentication/authentication-overview.md

@@ -1,64 +1,65 @@
-## 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.
 
-## Authentication Endpoints
+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.
 
-Generally speaking, there are two authentication endpoints:
+Authentication verifies user identity during login, and Authorization assigns the user with specific permissions according to the assigned access rules.
 
-* The Run:ai control plane.
-* Run:ai GPU clusters.
+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.
 
-Both endpoints are accessible via APIs as well as a user interface. 
+## **Authentication**
 
+There are multiple methods to authenticate and access Run:ai.
 
-## Identity Service
+### **Single Sign-On (SSO)**
 
-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
+Single Sign-On (SSO) is the preferred authentication method by large organizations, as it avoids the need to manage duplicate sets of user identities.
 
-Out of the box, The Run:ai identity service provides a way to create users and associate them with access roles. 
+Run:ai offers SSO integration, enabling users to utilize existing organizational credentials to access Run:ai without requiring dedicated credentials.
 
-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).
+Run:ai supports three methods to setup SSO:
 
-## Authentication Method
+* SAML  
+* OpenID Connect (OIDC)  
+* OpenShift
 
-Both endpoints described above are protected via time-limited oauth2-like JWT authentication tokens.
+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.
 
-There are two ways of getting a token:
+### **Username and password**
 
-* Using a user/password combination.
-* Using [client applications](../../../developer/overview-developer.md) for API access.
+Username and password access can be used when SSO integration is not possible.
 
+### **Secret key (for Application programmatic access)**
 
-## Authentication Flows
+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.
 
-### Run:ai control plane
+## **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. 
+The Run:ai platform uses Role Base Access Control (RBAC) to manage authorization.
 
-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
+Once a user or an application is authenticated, they can perform actions according to their assigned access rules.
 
-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}.
+### **Role Based Access Control (RBAC) in Run:ai**
 
-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).
+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.
 
-## Inactivity timeout
+RBAC at Run:ai is configured using access rules.
 
-:octicons-versions-24: Version 2.10 and later.
+An access rule is the assignment of a role to a subject in a scope: \<Subject\> is a \<Role\> in a \<Scope\>.
 
-Run:ai session should timeout after 1 hour of inactivity.
+* **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)
 
-!!! Note
-    Timeout settings are configured in minutes.
+An example of an access rule: **username@company.com** is a **Department admin** in **Department: A**
 
-To configure the inactivity timeout:
-1. Open `Settings | General`.
-2. Set the inactivity timeout in minutes. (Default is 60)
+![](img/auth-rbac.png)
 
-## See also
 
-* To configure authentication for researchers [researcher authentication](researcher-authentication.md).
-* To configure single sign-on, see [single sign-on](sso.md).

docs/admin/runai-setup/authentication/img/auth-rbac.png

@@ -0,0 +1,125 @@
+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 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 should be 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
+
+### **Troubleshooting**
+
+If testing the setup was unsuccessful, try the different troubleshooting scenarios according to the error you received.
+
+#### **Troubleshooting scenarios**
+
+**Error:** “403 \- Sorry, we can’t let you see this page. Something about permissions…”  
+
+![](img/openid-403.png)
+      
+**Description:** The authenticated user is missing permissions  
+__Mitigation__:  
+- Validate either the user or its related group/s are assigned with access rules  
+- Validate groups attribute is available in the configured OIDC Scopes  
+- Validate the user’s groups attribute is mapped correctly  
+
+__Advanced:__  
+- Open the Chrome DevTools: Right-click on page → Inspect → Console tab  
+- Run the following command to retrieve the user’s token: `localStorage.token;`  
+- Paste in [https://jwt.io](https://jwt.io/)  
+- Under the Payload section validate the value of the user’s attributes  
+
+**Error:** “We’re having trouble identifying your account because your email is incorrect or can’t be found.”
+ 
+![](img/openid-imageincorrect.png)
+
+**Description:** Authentication failed because email attribute was not found.  
+**Mitigation**:  
+- Validate email attribute is available in the configured OIDC Scopes  
+- Validate the user’s email attribute is mapped correctly  
+
+
+**Error:** “Unexpected error when authenticating with identity provider”     
+**Description:** User authentication failed  
+**Mitigation**:  
+Validate the configured OIDC Scopes exist and match the Identity Provider’s available scopes  
+**Advanced:**  
+Look for the specific error message in the URL address  
+
+
+**Error:** “Unexpected error when authenticating with identity provider” (SSO sign-in is not available)  
+![](img/openid-unexpected.png)
+   
+**Description:** User authentication failed  
+**Mitigation**:  
+- Validate the configured OIDC scope exists in the Identity Provider  
+- Validate the configured Client Secret matchs the Client Secret in the Identity Provider  
+**Advanced:**  
+Look for the specific error message in the URL address  
+
+
+**Error:** “Client not found”  
+**Description:** OIDC Client ID was not found in the Identity Provider  
+**Mitigation**:  
+Validate the configured Client ID matches the Identity Provider Client ID
+
+### **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.
+

docs/admin/runai-setup/authentication/sso/img/openid-403.png

@@ -0,0 +1,125 @@
+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.\<cluster-url\>: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 user interface |
+| User last name | lastName | Used as the user’s last name appearing in the Run:ai user interface |
+
+### **Testing the setup**
+
+1. Open the Run:ai platform as an admin  
+1. Add Access Rules 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
+
+### **Troubleshooting**
+
+If testing the setup was unsuccessful, try the different troubleshooting scenarios according to the error you received.
+
+#### **Troubleshooting scenarios**
+
+**Error:** “403 \- Sorry, we can’t let you see this page. Something about permissions…”  
+![](img/openid-403.png)
+
+**Description:** The authenticated user is missing permissions  
+**Mitigation**:  
+- Validate either the user or its related group/s are assigned with access rules.
+- Validate groups attribute is available in the configured OIDC Scopes  
+- Validate the user’s groups attribute is mapped correctly  
+**Advanced:**  
+- Open the Chrome DevTools: Right-click on page → Inspect → Console tab  
+- Run the following command to retrieve the user’s token: `localStorage.token;`  
+- Paste in [https://jwt.io](https://jwt.io/)  
+- Under the Payload section validate the value of the user’s attributes  
+
+**Error:** “We’re having trouble identifying your account because your email is incorrect or can’t be found.”
+
+![](img/openid-imageincorrect.png)
+
+**Description:** Authentication failed because email attribute was not found.  
+**Mitigation**:  
+- Validate email attribute is available in the configured OIDC Scopes  
+- Validate the user’s email attribute is mapped correctly  
+
+**Error:** “Unexpected error when authenticating with identity provider”  
+
+![](img/openshift-identityerror.png)
+
+**Description:** User authentication failed  
+**Mitigation**:  
+Validate the configured OIDC Scopes exist and match the Identity Provider’s available scopes 
+**Advanced:**  
+Look for the specific error message in the URL address  
+
+
+**Error:** “Unexpected error when authenticating with identity provider” (SSO sign-in is not available)  
+
+![](img/openshift-identityerror-ssonotavail.png)
+
+**Description:** User authentication failed  
+**Mitigation**:  
+- Validate the configured OIDC scope exists in the Identity Provider  
+- Validate the configured Client Secret match the Client Secret value in the OAuthclient Kubernetes object.  
+**Advanced:**  
+Look for the specific error message in the URL address  
+
+**Error:** “Client not found”  
+    <!-- TBD \- OpenShift screenshot   -->
+**Description:** OIDC Client ID was not found in the OpenShift IDP  
+**Mitigation**:  
+Validate the configured Client ID matches the value in the OAuthclient Kubernetes object.
+
+### **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.
+