docs: added keycloak-oidc documentation

2026-10-15 07:35:09 +00:00 · 2024-06-20 20:25:57 +08:00
parent e0f5ecbe7b
commit e9639df8ce
18 changed files with 104 additions and 10 deletions
@@ -0,0 +1,92 @@
+---
+title: "Keycloak OIDC"
+description: "Learn how to configure Keycloak OIDC for Infisical SSO."
+---
+
+<Info>
+  Keycloak OIDC 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>
+
+<Steps>
+   <Step title="Create an OIDC client application in Keycloak">
+      1.1. In your realm, navigate to the **Clients** tab and click **Create client** to create a new client application.
+      
+      ![OIDC keycloak list of clients](../../../images/sso/keycloak-oidc/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>
+      
+      1.2. In the General Settings step, set **Client type** to **OpenID Connect**, the **Client ID** field to an appropriate identifier, and the **Name** field to a friendly name like **Infisical**.
+      
+      ![OIDC keycloak create client general settings](../../../images/sso/keycloak-oidc/create-client-general-settings.png)
+      
+      1.3. Next, in the Capability Config step, ensure that **Client Authentication** is set to On and that **Standard flow** is enabled in the Authentication flow section.
+      
+      ![OIDC keycloak create client capability config settings](../../../images/sso/keycloak-oidc/create-client-capability.png)
+      
+      1.4. In the Login Settings step, set the appropriate values for the following:
+      - Root URL (base URL of Infisical)
+      - Home URL (base URL of Infisical)
+      - Valid Redirect URIs (`${INFISICAL_BASE_URL}/api/v1/sso/oidc/callback`)
+      - Web origins (base URL of Infisical)
+
+      ![OIDC keycloak create client login settings](../../../images/sso/keycloak-oidc/create-client-login-settings.png)
+      <Info>
+         If you’re self-hosting Infisical, then you will want to replace https://app.infisical.com (base URL) with your own domain.
+      </Info>
+
+      1.5. Next, navigate to the **Client scopes** tab and select the client's dedicated scope.
+
+      ![OIDC keycloak client scopes list](../../../images/sso/keycloak-oidc/client-scope-list.png)
+
+      1.6. Next, click **Add predefined mapper**.
+
+      ![OIDC keycloak client mappers empty](../../../images/sso/keycloak-oidc/client-scope-mapper-menu.png)
+
+      1.7. Select the **email**, **given name**, **family name** attributes and click **Add**.
+
+      ![OIDC keycloak client mappers predefined 1](../../../images/sso/keycloak-oidc/scope-predefined-mapper-1.png)
+      ![OIDC keycloak client mappers predefined 2](../../../images/sso/keycloak-oidc/scope-predefined-mapper-2.png)
+
+      Once you've completed the above steps, the list of mappers should look like the following:
+      ![OIDC keycloak client mappers completed](../../../images/sso/keycloak-oidc/client-scope-complete-overview.png)
+
+   </Step>
+   <Step title="Retrieve Identity Provider (IdP) Information from Keycloak">
+      2.1. Back in Keycloak, navigate to Configure > Realm settings > General tab > Endpoints > OpenID Endpoint Configuration and copy the opened URL. This is what is to referred to as the Discovery Document URL and it takes the form: `https://keycloak-mysite.com/realms/myrealm/.well-known/openid-configuration`.
+      ![OIDC keycloak realm OIDC metadata](../../../images/sso/keycloak-oidc/realm-setting-oidc-config.png)
+
+      2.2. From the Clients page, navigate to the Credential tab and copy the value of Client secret for use in the preceding steps.
+      ![OIDC keycloak realm OIDC secret](../../../images/sso/keycloak-oidc/client-secret.png)
+
+   </Step>
+   <Step title="Finish configuring OIDC in Infisical">
+      3.1. Back in Infisical, in the Organization settings > Security > OIDC, click Manage
+      ![OIDC keycloak manage org Infisical](../../../images/sso/keycloak-oidc/manage-org-oidc.png)
+
+      3.2. For configuration type, select Discovery URL. Then, set the appropriate values for **Discovery Document URL**, **Client ID**, and **Client Secret**.
+      ![OIDC keycloak paste values into Infisical](../../../images/sso/keycloak-oidc/create-oidc.png)
+
+      Once you've done that, press **Update** to complete the required configuration.
+
+   </Step>
+   <Step title="Enable OIDC SSO in Infisical">
+      Enabling OIDC SSO allows members in your organization to log into Infisical via Keycloak.
+
+      ![OIDC keycloak enable OIDC](../../../images/sso/keycloak-oidc/enable-oidc.png)
+
+   </Step>
+</Steps>
+
+<Note>
+  If you're configuring OIDC SSO on a self-hosted instance of Infisical, make
+  sure to set the `AUTH_SECRET` and `SITE_URL` environment variable for it to
+  work: - `AUTH_SECRET`: A secret key used for signing and verifying JWT. This
+  can be a random 32-byte base64 string generated with `openssl rand -base64
+  32`. - `SITE_URL`: The URL of your self-hosted instance of Infisical - should
+  be an absolute URL including the protocol (e.g. https://app.infisical.com)
+</Note>