Merge pull request #888 from run-ai/new-auth-articles

new-auth-articles

Author: yarongol

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: \<Subject\> is a \<Role\> in a \<Scope\>.
+
+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
+

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
+

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: `<Subject>` is a `<Role>` in a `<Scope>`.
 
-: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).

docs/admin/runai-setup/authentication/img/accessrulestable.png

@@ -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
+