mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
151 lines
7.7 KiB
Plaintext
151 lines
7.7 KiB
Plaintext
---
|
||
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 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.
|
||
|
||
|
||
|
||
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 Attribute 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>
|
||
<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>
|
||
|
||
<Tip>
|
||
If you are only using one organization on your Infisical instance, you can configure a default organization in the [Server Admin Console](../admin-panel/server-admin#default-organization) to expedite SAML login.
|
||
</Tip>
|
||
|
||
<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:
|
||
<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 Infisical including the protocol (e.g. https://app.infisical.com)
|
||
</Note>
|