mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
Add support for keycloak saml on self-hosted infisical
This commit is contained in:
Tuan Dang
139
docs/documentation/platform/sso/keycloak-saml.mdx
Normal file
139
docs/documentation/platform/sso/keycloak-saml.mdx
Normal file
@@ -0,0 +1,139 @@
|
||||
---
|
||||
title: "Keycloak SAML"
|
||||
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 sales@infisical.com to purchase an enterprise license to use it.
|
||||
</Info>
|
||||
|
||||
<Steps>
|
||||
<Step title="Prepare the SAML SSO configuration in Infisical">
|
||||
In Infisical, head to your Organization Settings > Authentication > SAML SSO Configuration and select **Manage**.
|
||||
|
||||
|
||||
|
||||
Next, copy the **Valid redirect URI** and **SP Entity ID** to use when configuring the Keycloak SAML application.
|
||||
|
||||
|
||||
</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.
|
||||
|
||||
|
||||
|
||||
<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**.
|
||||
|
||||
|
||||
|
||||
<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**.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
- Force POST binding: On.
|
||||
- Include AuthnStatement: On.
|
||||
- Under **Signature and Encryption**:
|
||||
- Sign documents: On.
|
||||
- Sign assertions: On.
|
||||
- Signature algorithm: RSA_SHA256.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
2.3. Next, navigate to the **Client scopes** tab select the client's dedicated scope.
|
||||
|
||||
|
||||
|
||||
Next click **Add predefined mapper**.
|
||||
|
||||
|
||||
|
||||
Select the **X500 email**, **X500 givenName**, and **X500 surname** attributes and click **Add**.
|
||||
|
||||
|
||||
|
||||
Now click on the **X500 email** mapper and set the **SAML Attribute Name** field to **email**.
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
|
||||
Select **User Property**.
|
||||
|
||||
|
||||
|
||||
Set the the **Name** field to **Username**, the **Property** field to **username**, and the **SAML Attribtue Name** to **username**.
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
|
||||
Once you've completed the above steps, the list of mappers should look like this:
|
||||
|
||||
|
||||
</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`.
|
||||
|
||||
|
||||
|
||||
Also, in the **Keys** tab, locate the RS256 key and copy the certificate to use when finishing configuring Keycloak SAML in Infisical.
|
||||
|
||||
|
||||
</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.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Enable SAML SSO in Infisical">
|
||||
Enabling SAML SSO allows members in your organization to log into Infisical via Keycloak.
|
||||
|
||||
|
||||
</Step>
|
||||
<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.
|
||||
|
||||
<Warning>
|
||||
We recommend ensuring that your account is provisioned the application in Keycloak
|
||||
prior to enforcing SAML SSO to prevent any unintended issues.
|
||||
</Warning>
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
If you're configuring SAML 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>
|
||||
Reference in New Issue
Block a user