mirror of
https://github.com/hanzoai/kms.git
synced 2026-11-03 01:10:24 +00:00
zeekay
0ebffbd529
- Fix 381 files where branding script corrupted variable names (e.g. isHanzo KMSTemplate -> isKmsTemplate) - Rebrand from "Hanzo KMS" to just "KMS" for white-label support (allows Lux KMS, Hanzo KMS, etc. via configuration) - 856 files, purely string replacements, no logic changes
120 lines
6.2 KiB
Plaintext
120 lines
6.2 KiB
Plaintext
---
|
||
title: "Keycloak OIDC Overview"
|
||
sidebarTitle: "Overview"
|
||
description: "Learn how to configure Keycloak OIDC for KMS SSO."
|
||
---
|
||
|
||
<Info>
|
||
Keycloak OIDC SSO is a paid feature. If you're using KMS Cloud, then it
|
||
is available under the **Pro Tier**. If you're self-hosting KMS, then
|
||
you should contact [email protected] to purchase a self-hosted 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.
|
||
|
||
|
||
|
||
<Info>
|
||
You don’t typically need to make a realm dedicated to KMS. We recommend adding KMS 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 **KMS**.
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
1.4. In the Login Settings step, set the following values:
|
||
- Root URL: `https://kms.hanzo.ai`.
|
||
- Home URL: `https://kms.hanzo.ai`.
|
||
- Valid Redirect URIs: `https://kms.hanzo.ai/api/v1/sso/oidc/callback`.
|
||
- Web origins: `https://kms.hanzo.ai`.
|
||
|
||
|
||
<Info>
|
||
If you’re self-hosting KMS, then you will want to replace https://kms.hanzo.ai (base URL) with your own domain.
|
||
</Info>
|
||
|
||
1.5. Next, navigate to the **Client scopes** tab and select the client's dedicated scope.
|
||
|
||
|
||
|
||
1.6. Next, click **Add predefined mapper**.
|
||
|
||
|
||
|
||
1.7. Select the **email**, **given name**, **family name** attributes and click **Add**.
|
||
|
||
|
||
|
||
|
||
Once you've completed the above steps, the list of mappers should look like the following:
|
||
|
||
|
||
</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`.
|
||
|
||
|
||
2.2. From the Clients page, navigate to the Credential tab and copy the **Client Secret** to be used in the next steps.
|
||
|
||
|
||
</Step>
|
||
<Step title="Finish configuring OIDC in KMS">
|
||
3.1. Back in KMS, head to the **Single Sign-On (SSO)** page and select the **General** tab. Click **Connect** for **OIDC**.
|
||
|
||
|
||
3.2. For configuration type, select Discovery URL. Then, set the appropriate values for **Discovery Document URL**, **JWT Signature Algorithm**, **Client ID**, and **Client Secret**.
|
||
|
||
|
||
<Info>
|
||
Currently, the following JWT signature algorithms are supported: RS256, RS512, HS256, and EdDSA
|
||
</Info>
|
||
|
||
Once you've done that, press **Update** to complete the required configuration.
|
||
|
||
</Step>
|
||
<Step title="Enable OIDC SSO in KMS">
|
||
Enabling OIDC SSO allows members in your organization to log into KMS via Keycloak.
|
||
|
||
|
||
|
||
</Step>
|
||
<Step title="Enforce OIDC SSO in KMS">
|
||
Enforcing OIDC SSO ensures that members in your organization can only access KMS
|
||
by logging into the organization via Keycloak.
|
||
|
||
To enforce OIDC SSO, you're required to test out the OpenID connection by successfully authenticating at least one Keycloak user with KMS.
|
||
Once you've completed this requirement, you can toggle the **Enforce OIDC SSO** button to enforce OIDC SSO.
|
||
|
||
<Warning>
|
||
We recommend ensuring that your account is provisioned using the application in Keycloak
|
||
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](https://kms.hanzo.ai/docs/documentation/platform/sso/overview#admin-login-portal) in the `/login/admin` path e.g. https://kms.hanzo.ai/login/admin.
|
||
</Info>
|
||
</Step>
|
||
</Steps>
|
||
|
||
<Tip>
|
||
If you are only using one organization on your KMS instance, you can configure a default organization in the [Server Admin Console](/documentation/platform/admin-panel/server-admin#default-organization) to expedite OIDC login.
|
||
</Tip>
|
||
|
||
<Note>
|
||
If you're configuring OIDC SSO on a self-hosted instance of KMS, make
|
||
sure to set the `AUTH_SECRET` and `SITE_URL` environment variable for it to
|
||
work:
|
||
<div class="height:1px;"/>
|
||
- `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`.
|
||
<div class="height:1px;"/>
|
||
- `SITE_URL`: The absolute URL of your self-hosted instance of KMS including the protocol (e.g. https://kms.hanzo.ai)
|
||
</Note>
|