after-jamie

Author: yarongol

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

@@ -1,6 +1,5 @@
 # Authentication & Authorization
 
-
 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 verifies user identity during login, and Authorization assigns the user with specific permissions according to the assigned access rules.
@@ -17,10 +16,10 @@ Single Sign-On (SSO) is the preferred authentication method by large organizatio
 
 Run:ai offers SSO integration, enabling users to utilize existing organizational credentials to access Run:ai without requiring dedicated credentials.
 
-Run:ai supports three methods to set up SSO:
+Run:ai supports three methods to setup SSO:
 
 * [SAML](sso/saml.md) 
-* [OpenID Connect (OIDC)](sso/openidconnect.md)  
+* [OpenID Connect (OIDC)](sso/openidconnect.md) 
 * [OpenShift](sso/openshift.md)
 
 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.
@@ -45,7 +44,7 @@ While Kubernetes RBAC is limited to a single cluster, Run:ai expands the scope o
 
 RBAC at Run:ai is configured using access rules.
 
-An access rule is the assignment of a role to a subject in a scope: \<Subject\> is a \<Role\> in a \<Scope\>.
+An access rule is the assignment of a role to a subject in a scope: `<Subject>` is a `<Role>` in a `<Scope>`.
 
 * **Subject**  
   * A user, a group, or an application assigned with the role  
@@ -58,7 +57,9 @@ An access rule is the assignment of a role to a subject in a scope: \<Subject\>
   * 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)
 
-An example of an access rule: **username@company.com** is a **Department admin** in **Department: A**
+Below is an example of an access rule: **username@company.com** is a **Department admin** in **Department: A**
+
+
 
 ![](img/auth-rbac.png)
 

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

@@ -2,23 +2,23 @@ Single Sign-On (SSO) is an authentication scheme, allowing users to log-in with
 
 This article explains the procedure to configure single sign-on to Run:ai using the OpenID Connect protocol.
 
-## **Prerequisites**
+## 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.
+* 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**
+## Setup
 
 Follow the steps below to setup SSO with OpenID Connect.
 
-### **Adding the identity provider**
+### Adding the identity provider
 
 1. Go to **Tools & Settings** → **General**  
-1. Open the Security section and click **\+IDENTITY PROVIDER**  
+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  
@@ -37,89 +37,105 @@ Follow the steps below to setup SSO with OpenID Connect.
 | 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**
+### 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. 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 should be redirected to the identity provider sign in page  
+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
 
-### **Troubleshooting**
+### 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**
+### Troubleshooting scenarios
 
-**Error:** “403 \- Sorry, we can’t let you see this page. Something about permissions…”  
+??? "403 - Sorry, we can’t let you see this page. Something about permissions…"
+      **Description:** The authenticated user is missing 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  
+      **Mitigation**:
 
-__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  
+      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
 
-**Error:** “We’re having trouble identifying your account because your email is incorrect or can’t be found.”
- 
-![](img/openid-imageincorrect.png)
+      **Advanced:**
 
-**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  
+      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.
 
-**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  
+      **Mitigation**:
 
+      1. Validate email attribute is available in the configured OIDC Scopes  
+      1. Validate the user’s email attribute is mapped correctly
 
-**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  
+??? "Unexpected error when authenticating with identity provider"
 
+      ![](img/openshift-identityerror.png)
 
-**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
+      **Description:** User authentication failed
 
-### **Editing the identity provider**
+      **Mitigation**:
 
-You can view the identity provider details and edit its configuration:
+      1. Validate that the configured OIDC Scopes exist and match the Identity Provider’s available scopes
 
-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**
+      **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  
+         
 
-### **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.