Merge pull request #3652 from Infisical/ENG-2817

Update docs and some UI to make Admin SSO bypass more clear

docs/documentation/platform/sso/auth0-oidc.mdx

@@ -14,7 +14,7 @@ description: "Learn how to configure Auth0 OIDC for Infisical SSO."
    <Step title="Setup application in Auth0">
       1.1. From the Application's Page, navigate to the settings tab of the Auth0 application you want to integrate with Infisical.
       ![OIDC auth0 list of applications](../../../images/sso/auth0-oidc/application-settings.png)
-      
+
       1.2. In the Application URIs section, set the **Application Login URI** and **Allowed Web Origins** fields to `https://app.infisical.com` and the **Allowed Callback URL** field to `https://app.infisical.com/api/v1/sso/oidc/callback`.
       ![OIDC auth0 create application uris](../../../images/sso/auth0-oidc/application-uris.png)
       ![OIDC auth0 create application origin](../../../images/sso/auth0-oidc/application-origin.png)
@@ -70,7 +70,7 @@ description: "Learn how to configure Auth0 OIDC for Infisical SSO."
          prior to enforcing OIDC SSO to prevent any unintended issues.
       </Warning>
       <Info>
-         In case of a lockout, an organization admin can use the admin login portal in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
+         In case of a lockout, an organization admin can use the [Admin Login Portal](https://infisical.com/docs/documentation/platform/sso/overview#admin-login-portal) in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
       </Info>
    </Step>
 </Steps>

docs/documentation/platform/sso/auth0-saml.mdx

@@ -23,30 +23,30 @@ description: "Learn how to configure Auth0 SAML for Infisical SSO."
    </Step>
    <Step title="Create a SAML application in Auth0">
         2.1. In your Auth0 account, head to Applications and create an application.
-        
+
         ![Auth0 SAML app creation](../../../images/sso/auth0-saml/create-application.png)
-        
+
         Select **Regular Web Application** and press **Create**.
-        
+
         ![Auth0 SAML app creation](../../../images/sso/auth0-saml/create-application-2.png)
-        
+
         2.2. In the Application head to Settings > Application URIs and add the **Application Callback URL** from step 1 into the **Allowed Callback URLs** field.
-        
+
         ![Auth0 SAML allowed callback URLs](../../../images/sso/auth0-saml/auth0-config.png)
-        
+
         2.3. In the Application head to Addons > SAML2 Web App and copy the **Issuer**, **Identity Provider Login URL**, and **Identity Provider Certificate** from the **Usage** tab.
-        
+
         ![Auth0 SAML config](../../../images/sso/auth0-saml/auth0-config-2.png)
-        
+
         2.4. Back in Infisical, set **Issuer**, **Identity Provider Login URL**, and **Certificate** to the corresponding items from step 2.3.
-        
+
         ![Auth0 SAML Infisical config](../../../images/sso/auth0-saml/infisical-config.png)
-        
+
         2.5. Back in Auth0, in the **Settings** tab, set the **Application Callback URL** to the **Application Callback URL** from step 1
         and update the **Settings** field with the JSON under the picture below (replacing `<audience-from-infisical>` with the **Audience** from step 1).
-        
+
         ![Auth0 SAML config](../../../images/sso/auth0-saml/auth0-config-3.png)
-        
+
         ```json
         {
         "audience": "<audience-from-infisical>",
@@ -76,7 +76,7 @@ description: "Learn how to configure Auth0 SAML for Infisical SSO."
         Once you've completed this requirement, you can toggle the **Enforce SAML SSO** button to enforce SAML SSO.
 
         <Info>
-            In case of a lockout, an organization admin can use the admin login portal in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
+            In case of a lockout, an organization admin can use the [Admin Login Portal](https://infisical.com/docs/documentation/platform/sso/overview#admin-login-portal) in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
         </Info>
     </Step>
 
@@ -96,4 +96,4 @@ description: "Learn how to configure Auth0 SAML for Infisical SSO."
     32`.
     <div class="height:1px;"/>
     - `SITE_URL`: The absolute URL of your self-hosted instance of Infisical including the protocol (e.g. https://app.infisical.com)
-</Note>
+</Note>

docs/documentation/platform/sso/azure.mdx

@@ -5,7 +5,7 @@ description: "Learn how to configure Microsoft Entra ID for Infisical SSO."
 
 <Info>
    Azure SAML SSO is a paid feature.
-   
+
    If you're using Infisical Cloud, then it is available under the **Pro Tier**. If you're self-hosting Infisical,
    then you should contact [email protected] to purchase an enterprise license to use it.
 </Info>
@@ -26,7 +26,7 @@ description: "Learn how to configure Microsoft Entra ID for Infisical SSO."
       ![Azure SAML enterprise applications](../../../images/sso/azure/enterprise-applications.png)
 
       ![Azure SAML new application](../../../images/sso/azure/new-application.png)
-      
+
       On the next screen, press the **+ Create your own application** button.
       Give the application a unique name like Infisical; choose the "Integrate any other application you don't find in the gallery (Non-gallery)"
       option and hit the **Create** button.
@@ -89,9 +89,9 @@ description: "Learn how to configure Microsoft Entra ID for Infisical SSO."
    </Step>
    <Step title="Assign users in Azure to the application">
       Back in Azure, navigate to the **Users and groups** tab and select **+ Add user/group** to assign access to the login with SSO application on a user or group-level.
-      
+
       ![Azure SAML assignment](../../../images/sso/azure/assignment.png)
-   </Step>   
+   </Step>
    <Step title="Enable SAML SSO in Infisical">
       Enabling SAML SSO allows members in your organization to log into Infisical via Azure.
 
@@ -109,7 +109,7 @@ description: "Learn how to configure Microsoft Entra ID for Infisical SSO."
          prior to enforcing SAML SSO to prevent any unintended issues.
       </Warning>
       <Info>
-         In case of a lockout, an organization admin can use the admin login portal in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
+         In case of a lockout, an organization admin can use the [Admin Login Portal](https://infisical.com/docs/documentation/platform/sso/overview#admin-login-portal) in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
       </Info>
    </Step>
 </Steps>

docs/documentation/platform/sso/general-oidc/overview.mdx

@@ -70,7 +70,7 @@ Prerequisites:
          We recommend ensuring that your account is provisioned using the identity provider prior to enforcing OIDC SSO to prevent any unintended issues.
       </Warning>
       <Info>
-         In case of a lockout, an organization admin can use the admin login portal in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
+         In case of a lockout, an organization admin can use the [Admin Login Portal](https://infisical.com/docs/documentation/platform/sso/overview#admin-login-portal) in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
       </Info>
     </Step>
 

docs/documentation/platform/sso/google-saml.mdx

@@ -24,21 +24,21 @@ description: "Learn how to configure Google SAML for Infisical SSO."
    <Step title="Create a SAML application in Google">
         2.1. In your [Google Admin console](https://support.google.com/a/answer/182076), head to Menu > Apps > Web and mobile apps and
         create a **custom SAML app**.
-        
+
         ![Google SAML app creation](../../../images/sso/google-saml/create-custom-saml-app.png)
-        
+
         2.2. In the **App details** tab, give the application a unique name like Infisical.
-        
+
         ![Google SAML app naming](../../../images/sso/google-saml/name-custom-saml-app.png)
-        
+
         2.3. In the **Google Identity Provider details** tab, copy the **SSO URL**, **Entity ID** and **Certificate**.
-        
+
         ![Google SAML custom app details](../../../images/sso/google-saml/custom-saml-app-config.png)
-        
+
         2.4. Back in Infisical, set **SSO URL** and **Certificate** to the corresponding items from step 2.3.
-        
+
         ![Google SAML Infisical config](../../../images/sso/google-saml/infisical-config.png)
-        
+
         2.5. Back in the Google Admin console, in the **Service provider details** tab, set the **ACS URL** and **Entity ID** to the corresponding items from step 1.
 
         Also, check the **Signed response** checkbox.
@@ -84,7 +84,7 @@ description: "Learn how to configure Google SAML for Infisical SSO."
             prior to enforcing SAML SSO to prevent any unintended issues.
         </Warning>
         <Info>
-            In case of a lockout, an organization admin can use the admin login portal in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
+            In case of a lockout, an organization admin can use the [Admin Login Portal](https://infisical.com/docs/documentation/platform/sso/overview#admin-login-portal) in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
         </Info>
     </Step>
 

docs/documentation/platform/sso/jumpcloud.mdx

@@ -5,7 +5,7 @@ description: "Learn how to configure JumpCloud SAML for Infisical SSO."
 
 <Info>
    JumpCloud SAML SSO is a paid feature.
-   
+
    If you're using Infisical Cloud, then it is available under the **Pro Tier**. If you're self-hosting Infisical,
    then you should contact [email protected] to purchase an enterprise license to use it.
 </Info>
@@ -83,13 +83,12 @@ description: "Learn how to configure JumpCloud SAML for Infisical SSO."
 
       To enforce SAML SSO, you're required to test out the SAML connection by successfully authenticating at least one JumpCloud user with Infisical;
       Once you've completed this requirement, you can toggle the **Enforce SAML SSO** button to enforce SAML SSO.
-      
+
       <Warning>
-         We recommend ensuring that your account is provisioned the application in JumpCloud
+         We recommend ensuring that your account is provisioned in the application in JumpCloud prior to enforcing SAML SSO to prevent any unintended issues.
-         prior to enforcing SAML SSO to prevent any unintended issues.
       </Warning>
       <Info>
-         In case of a lockout, an organization admin can use the admin login portal in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
+         In case of a lockout, an organization admin can use the [Admin Login Portal](https://infisical.com/docs/documentation/platform/sso/overview#admin-login-portal) in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
       </Info>
    </Step>
 </Steps>

docs/documentation/platform/sso/keycloak-oidc/overview.mdx

@@ -97,7 +97,7 @@ description: "Learn how to configure Keycloak OIDC for Infisical SSO."
             prior to enforcing OIDC SSO to prevent any unintended issues.
         </Warning>
         <Info>
-            In case of a lockout, an organization admin can use the admin login portal in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
+            In case of a lockout, an organization admin can use the [Admin Login Portal](https://infisical.com/docs/documentation/platform/sso/overview#admin-login-portal) in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
         </Info>
     </Step>
 </Steps>

docs/documentation/platform/sso/keycloak-saml.mdx

@@ -5,7 +5,7 @@ description: "Learn how to configure Keycloak SAML for Infisical SSO."
 
 <Info>
     Keycloak SAML SSO is a paid feature.
-   
+
     If you're using Infisical Cloud, then it is available under the **Pro Tier**. If you're self-hosting Infisical,
     then you should contact [email protected] to purchase an enterprise license to use it.
 </Info>
@@ -13,36 +13,36 @@ description: "Learn how to configure Keycloak SAML for Infisical SSO."
 <Steps>
    <Step title="Prepare the SAML SSO configuration in Infisical">
       In Infisical, head to the **Single Sign-On (SSO)** page and select the **General** tab. Click **Connect** for **SAML** under the Connect to an Identity Provider section. Select **Keycloak**, then click **Connect** again.
-      
+
       ![SSO connect section](../../../images/sso/connect-saml.png)
-      
+
       Next, copy the **Valid redirect URI** and **SP Entity ID** to use when configuring the Keycloak SAML application.
-      
+
       ![Keycloak SAML initial configuration](../../../images/sso/keycloak/init-config.png)
    </Step>
    <Step title="Create a SAML client application in Keycloak">
       2.1. In your realm, navigate to the **Clients** tab and click **Create client** to create a new client application.
-      
+
       ![SAML keycloak list of clients](../../../images/sso/keycloak/clients-list.png)
-      
+
       <Info>
          You don’t typically need to make a realm dedicated to Infisical. We recommend adding Infisical as a client to your primary realm.
       </Info>
-      
+
       In the General Settings step, set **Client type** to **SAML**, the **Client ID** field to `https://app.infisical.com`, and the **Name** field to a friendly name like **Infisical**.
-      
+
       ![SAML keycloak create client general settings](../../../images/sso/keycloak/create-client-general-settings.png)
-      
+
       <Info>
          If you’re self-hosting Infisical, then you will want to replace https://app.infisical.com with your own domain.
       </Info>
-      
+
       Next, in the Login Settings step, set both the **Home URL** field and **Valid redirect URIs** field to the **Valid redirect URI** from step 1 and press **Save**.
-      
+
       ![SAML keycloak create client login settings](../../../images/sso/keycloak/create-client-login-settings.png)
-      
+
       2.2. Once you've created the client, under its **Settings** tab, make sure to set the following values:
-      
+
       - Under **SAML Capabilities**:
          - Name ID format: email (or username).
          - Force name ID format: On.
@@ -54,59 +54,59 @@ description: "Learn how to configure Keycloak SAML for Infisical SSO."
          - Signature algorithm: RSA_SHA256.
 
       ![SAML keycloak client SAML capabilities](../../../images/sso/keycloak/client-saml-capabilities.png)
-      
+
       ![SAML keycloak client signature encryption](../../../images/sso/keycloak/client-signature-encryption.png)
-      
+
       2.3. Next, navigate to the **Client scopes** tab select the client's dedicated scope.
-      
+
       ![SAML keycloak client scopes list](../../../images/sso/keycloak/client-scopes-list.png)
-      
+
       Next click **Add predefined mapper**.
-      
+
       ![SAML keycloak client mappers empty](../../../images/sso/keycloak/client-mappers-empty.png)
-      
+
       Select the **X500 email**, **X500 givenName**, and **X500 surname** attributes and click **Add**.
-      
+
       ![SAML keycloak client mappers predefined](../../../images/sso/keycloak/client-mappers-predefined.png)
-      
+
-      Now click on the **X500 email** mapper and set the **SAML Attribute Name** field to **email**. 
+      Now click on the **X500 email** mapper and set the **SAML Attribute Name** field to **email**.
 
       ![SAML keycloak client mappers email](../../../images/sso/keycloak/client-mappers-email.png)
-      
+
       Repeat the same for **X500 givenName** and **X500 surname** mappers, setting the **SAML Attribute Name** field to **firstName** and **lastName** respectively.
-      
+
       Next, back in the client scope's **Mappers**, click **Add mapper** and select **by configuration**.
-      
+
       ![SAML keycloak client mappers by configuration](../../../images/sso/keycloak/client-mappers-by-configuration.png)
-      
+
       Select **User Property**.
-      
+
       ![SAML keycloak client mappers user property](../../../images/sso/keycloak/client-mappers-user-property.png)
 
-      Set the the **Name** field to **Username**, the **Property** field to **username**, and the **SAML Attribtue Name** to **username**.
+      Set the the **Name** field to **Username**, the **Property** field to **username**, and the **SAML Attribute Name** to **username**.
-      
+
       ![SAML keycloak client mappers username](../../../images/sso/keycloak/client-mappers-username.png)
-      
+
       Repeat the same for the `id` attribute, setting the **Name** field to **ID**, the **Property** field to **id**, and the **SAML Attribute Name** to **id**.
-      
+
       ![SAML keycloak client mappers id](../../../images/sso/keycloak/client-mappers-id.png)
-      
+
       Once you've completed the above steps, the list of mappers should look like this:
-      
+
       ![SAML keycloak client mappers completed](../../../images/sso/keycloak/client-mappers-completed.png)
    </Step>
    <Step title="Retrieve Identity Provider (IdP) Information from Keycloak">
       Back in Keycloak, navigate to Configure > Realm settings > General tab > Endpoints > SAML 2.0 Identity Provider Metadata and copy the IDP URL. This should appear in various places and take the form: `https://keycloak-mysite.com/realms/myrealm/protocol/saml`.
-      
+
       ![SAML keycloak realm SAML metadata](../../../images/sso/keycloak/realm-saml-metadata.png)
-      
+
       Also, in the **Keys** tab, locate the RS256 key and copy the certificate to use when finishing configuring Keycloak SAML in Infisical.
-      
+
       ![SAML keycloak realm settings keys](../../../images/sso/keycloak/realm-settings-keys.png)
    </Step>
    <Step title="Finish configuring SAML in Infisical">
       Back in Infisical, set **IDP URL** and **Certificate** to the items from step 3. Also, set the **Client ID** to the `https://app.infisical.com`.
-      
+
       Once you've done that, press **Update** to complete the required configuration.
 
       ![SAML Okta paste values into Infisical](../../../images/sso/keycloak/idp-values.png)
@@ -119,7 +119,7 @@ description: "Learn how to configure Keycloak SAML for Infisical SSO."
    <Step title="Enforce SAML SSO in Infisical">
       Enforcing SAML SSO ensures that members in your organization can only access Infisical
       by logging into the organization via Keycloak.
- 
+
       To enforce SAML SSO, you're required to test out the SAML connection by successfully authenticating at least one Keycloak user with Infisical;
       Once you've completed this requirement, you can toggle the **Enforce SAML SSO** button to enforce SAML SSO.
 
@@ -128,7 +128,7 @@ description: "Learn how to configure Keycloak SAML for Infisical SSO."
          prior to enforcing SAML SSO to prevent any unintended issues.
       </Warning>
       <Info>
-         In case of a lockout, an organization admin can use the admin login portal in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
+         In case of a lockout, an organization admin can use the [Admin Login Portal](https://infisical.com/docs/documentation/platform/sso/overview#admin-login-portal) in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
       </Info>
    </Step>
 </Steps>
@@ -147,4 +147,4 @@ description: "Learn how to configure Keycloak SAML for Infisical SSO."
     32`.
     <div class="height:1px;"/>
     - `SITE_URL`: The absolute URL of your self-hosted instance of Infisical including the protocol (e.g. https://app.infisical.com)
-</Note>
+</Note>

docs/documentation/platform/sso/okta.mdx

@@ -93,13 +93,12 @@ description: "Learn how to configure Okta SAML 2.0 for Infisical SSO."
       Once you've completed this requirement, you can toggle the **Enforce SAML SSO** button to enforce SAML SSO.
 
       <Warning>
-         We recommend ensuring that your account is provisioned the application in Okta
+         We recommend ensuring that your account is provisioned for the application in Okta prior to enforcing SAML SSO to prevent any unintended issues.
-         prior to enforcing SAML SSO to prevent any unintended issues.
       </Warning>
-      <Info>
-         In case of a lockout, an organization admin can use the admin login portal in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
-      </Info>
 
+      <Info>
+         In case of a lockout, an organization admin can use the [Admin Login Portal](https://infisical.com/docs/documentation/platform/sso/overview#admin-login-portal) in the `/login/admin` path e.g. https://app.infisical.com/login/admin.
+      </Info>
    </Step>
 </Steps>
 

docs/documentation/platform/sso/overview.mdx

@@ -39,18 +39,30 @@ If your required identity provider is not shown in the list above, please reach
   For enhanced security, Infisical enforces PKCE (Proof Key for Code Exchange) with the OAuth 2.0-based SSO providers and OIDC. This provides additional protection against authorization code interception attacks and strengthens your authentication flow security.
 </Info>
 
+## SSO Break Glass
+
+In the event your SSO provider experiences downtime, and you need to access Infisical, Organization Admins can utilize the Admin Login Portal to bypass SSO enforcement.
+
+This portal is accessible at `/login/admin` (e.g., https://app.infisical.com/login/admin).
+
+<Note>
+    To bypass SSO for an organization, you must be an **Organization Admin** for that specific organization. This **Organization Admin** role is independent of **Server Admin** status. Being a **Server Admin** alone does not grant permission to use this bypass feature.
+</Note>
+
 ## FAQ
 
 <AccordionGroup>
-  <Accordion title="Why does Infisical require additional email verification for users connected via SAML?">
+    <Accordion title="Why does Infisical require additional email verification for users connected via SAML?">
-    By default, Infisical Cloud is configured to not trust emails from external
+        By default, Infisical Cloud is configured to not trust emails from external
-    identity providers to prevent any malicious account takeover attempts via
+        identity providers to prevent any malicious account takeover attempts via
-    email spoofing. Accordingly, Infisical creates a new user for anyone provisioned
+        email spoofing. Accordingly, Infisical creates a new user for anyone provisioned
-    through an external identity provider and requires an additional email
+        through an external identity provider and requires an additional email
-    verification step upon their first login.
+        verification step upon their first login.
 
-    If you're running a self-hosted instance of Infisical and would like it to trust emails from external identity providers,
+        If you're running a self-hosted instance of Infisical and would like it to trust emails from external identity providers,
-    you can configure this behavior in the Server Admin Console.
+        you can configure this behavior in the Server Admin Console.
-
+    </Accordion>
-  </Accordion>
+    <Accordion title="Why do I get redirected to SSO when trying to use the Admin Login Portal?">
+        You are likely being redirected because you do not have email authentication mode enabled, or you're not an **Organization Admin**. This portal requires **Organization Admin** status and direct credential login (email and password). **Server Admin** status alone is insufficient.
+    </Accordion>
 </AccordionGroup>

frontend/src/pages/organization/SsoPage/components/OrgSsoTab/OrgGeneralAuthSection.tsx

@@ -129,7 +129,16 @@ export const OrgGeneralAuthSection = () => {
                       level.
                     </span>
                     <p className="mt-4">
-                      In case of a lockout, admins can use the admin login portal at{" "}
+                      In case of a lockout, admins can use the{" "}
+                      <a
+                        target="_blank"
+                        className="underline underline-offset-2 hover:text-mineshaft-300"
+                        href="https://infisical.com/docs/documentation/platform/sso/overview#admin-login-portal"
+                        rel="noreferrer"
+                      >
+                        Admin Login Portal
+                      </a>{" "}
+                      at{" "}
                       <a
                         target="_blank"
                         rel="noopener noreferrer"

frontend/src/pages/organization/SsoPage/components/OrgSsoTab/OrgOIDCSection.tsx

@@ -212,7 +212,16 @@ export const OrgOIDCSection = (): JSX.Element => {
                       level.
                     </span>
                     <p className="mt-4">
-                      In case of a lockout, admins can use the admin login portal at{" "}
+                      In case of a lockout, admins can use the{" "}
+                      <a
+                        target="_blank"
+                        className="underline underline-offset-2 hover:text-mineshaft-300"
+                        href="https://infisical.com/docs/documentation/platform/sso/overview#admin-login-portal"
+                        rel="noreferrer"
+                      >
+                        Admin Login Portal
+                      </a>{" "}
+                      at{" "}
                       <a
                         target="_blank"
                         rel="noopener noreferrer"