diff --git a/website/integrations/security/hashicorp-vault/index.md b/website/integrations/security/hashicorp-vault/index.md index 7c5bd9043f..f31df5dab4 100644 --- a/website/integrations/security/hashicorp-vault/index.md +++ b/website/integrations/security/hashicorp-vault/index.md @@ -4,22 +4,18 @@ sidebar_label: HashiCorp Vault support_level: authentik --- -## What is Vault? +## What is HashiCorp Vault? -> Secure, store and tightly control access to tokens, passwords, certificates, encryption keys for protecting secrets and other sensitive data using a UI, CLI, or HTTP API. +> HashiCorp Vault secures, stores, and controls access to tokens, passwords, certificates, encryption keys, and other sensitive data. > -> -- https://vaultproject.io - -:::info -This is based on authentik 2022.2.1 and Vault 1.9.3. Instructions may differ between versions. This guide does not cover Vault policies. See https://learn.hashicorp.com/tutorials/vault/oidc-auth?in=vault/auth-methods for a more in-depth Vault guide -::: +> -- https://developer.hashicorp.com/vault ## Preparation The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. -- `vault.company` is the FQDN of the Vault installation. +- `vault.company` is the FQDN of the HashiCorp Vault installation. :::info This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application. @@ -27,107 +23,113 @@ This documentation lists only the settings that you need to change from their de ## authentik configuration -To support the integration of HashiCorp Vault with authentik, you need to create an application/provider pair in authentik. +To support the integration of HashiCorp Vault with authentik, you need to create an application and provider pair in authentik. -### Create an application and provider in authentik +### Create an application and provider 1. Log in to authentik as an administrator and open the authentik Admin interface. 2. Navigate to **Applications** > **Applications** and click **New Application** to open the application wizard. - -- **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. -- **Choose a Provider type**: select **OAuth2/OpenID Connect** as the provider type. -- **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. - - Note the **Client ID**, **Client Secret**, and **slug** values because they will be required later. - - Add three `Strict` redirect URIs and set them to `https://vault.company/ui/vault/auth/oidc/oidc/callback`, `https://vault.company/oidc/callback`, and `http://localhost:8250/oidc/callback`. - - Select any available signing key. -- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/bindings-overview/) (policy, group, or user) to manage the listing and access to applications on a user's **Application Dashboard** page. - + - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. + - **Choose a Provider type**: select **OAuth2/OpenID Connect** as the provider type. + - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. + - Note the **Client ID**, **Client Secret**, and **slug** values because they will be required later. + - Set two `Strict` redirect URIs to `https://vault.company/ui/vault/auth/oidc/oidc/callback` and `http://localhost:8250/oidc/callback`. + - Select any available signing key. + - **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/bindings-overview/) (policy, group, or user) to manage the listing and access to applications on a user's **Application Dashboard** page. 3. Click **Submit** to save the new application and provider. ## HashiCorp Vault configuration -Enable the OIDC auth method. -`vault auth enable oidc` +This guide assumes that the Vault OIDC auth method is mounted at `oidc`, which is the path used by `vault auth enable oidc`. If you mount the auth method at a different path, replace `oidc` in the Vault paths and in the Vault UI redirect URI. -Configure the OIDC auth method. The OIDC discovery URL is the OpenID Configuration Issuer in your provider. +:::info[Vault policies] +This guide configures OIDC authentication only. Create the Vault policies that you reference, such as `reader`, according to your Vault access model before assigning them to roles or identity groups. +::: -``` -vault write auth/oidc/config \ - oidc_discovery_url="https://authentik.company/application/o//" \ - oidc_client_id="Client ID" \ - oidc_client_secret="Client Secret" \ - default_role="reader" -``` +1. Enable the OIDC auth method. -Create the reader role. + ```bash + vault auth enable oidc + ``` -``` -vault write auth/oidc/role/reader \ - bound_audiences="Client ID" \ - allowed_redirect_uris="https://vault.company/ui/vault/auth/oidc/oidc/callback" \ - allowed_redirect_uris="https://vault.company/oidc/callback" \ - allowed_redirect_uris="http://localhost:8250/oidc/callback" \ - user_claim="sub" \ - policies="reader" -``` +2. Configure the OIDC auth method with the authentik provider details. + + ```bash + vault write auth/oidc/config \ + oidc_discovery_url="https://authentik.company/application/o//" \ + oidc_client_id="" \ + oidc_client_secret="" \ + default_role="reader" + ``` + +3. Create a Vault OIDC role named `reader`. + + ```bash + vault write auth/oidc/role/reader \ + bound_audiences="" \ + allowed_redirect_uris="https://vault.company/ui/vault/auth/oidc/oidc/callback" \ + allowed_redirect_uris="http://localhost:8250/oidc/callback" \ + user_claim="sub" \ + token_policies="reader" + ``` ## External groups -If you wish to manage group membership in HashiCorp Vault via authentik, you have to use [external groups](https://developer.hashicorp.com/vault/tutorials/auth-methods/oidc-auth#create-an-external-vault-group). +You can optionally use Vault external identity groups to assign Vault policies based on authentik group membership. -:::info -This assumes that the steps above have already been completed and tested. -::: +This example maps an authentik group named `vault-reader` to a Vault external group that grants the `reader` policy. The authentik default `profile` scope mapping supplies the `groups` claim used by Vault. -### Step 1 +1. Update the `reader` role to request the `profile` scope and read group membership from the `groups` claim. -In authentik, edit the OIDC provider created above. Under **Advanced protocol settings** add `authentik default OAuth Mapping: OpenID 'profile'` This includes the groups mapping. + ```bash + vault write auth/oidc/role/reader \ + bound_audiences="" \ + allowed_redirect_uris="https://vault.company/ui/vault/auth/oidc/oidc/callback" \ + allowed_redirect_uris="http://localhost:8250/oidc/callback" \ + user_claim="sub" \ + groups_claim="groups" \ + oidc_scopes="profile" + ``` -### Step 2 +2. Create an external Vault group for the `vault-reader` authentik group. -In Vault, change the reader role to have the following settings: + ```bash + vault write identity/group/name/vault-reader \ + policies="reader" \ + type="external" -``` -vault write auth/oidc/role/reader \ - bound_audiences="Client ID" \ - allowed_redirect_uris="https://vault.company/ui/vault/auth/oidc/oidc/callback" \ - allowed_redirect_uris="https://vault.company/oidc/callback" \ - allowed_redirect_uris="http://localhost:8250/oidc/callback" \ - user_claim="sub" \ - policies="reader" \ - groups_claim="groups" \ - oidc_scopes="openid,profile,email" + VAULT_GROUP_ID=$(vault read -field=id identity/group/name/vault-reader) + ``` + +3. Get the OIDC auth method mount accessor. + + ```bash + OIDC_ACCESSOR=$(vault read -field=accessor sys/auth/oidc) + ``` + +4. Create a group alias that maps the authentik group name to the Vault group. + + ```bash + vault write identity/group-alias \ + name="vault-reader" \ + mount_accessor="$OIDC_ACCESSOR" \ + canonical_id="$VAULT_GROUP_ID" + ``` + +## Configuration verification + +To confirm that authentik is properly configured with HashiCorp Vault, open Vault and select **OIDC** from the authentication method list. Sign in through the OIDC flow and confirm that Vault redirects you to authentik for authentication and then back to Vault. + +You can also verify the CLI flow with the following command: + +```bash +vault login -method=oidc role="reader" ``` -Add a group. +## Resources -``` -vault write identity/group \ - name="reader" \ - policies="reader" \ - type="external" -``` - -Get the canonical ID of the group. - -``` -vault list identity/group/id -``` - -Get the ID of the OIDC accessor. - -``` -vault auth list -``` - -Add a group alias, this maps the group to the OIDC backend. - -``` -vault write identity/group-alias \ - mount_accessor="auth_oidc_xxxxxx" \ - canonical_id="group_id" \ - name="group name in authentik" -``` - -You should then be able to sign in via OIDC. -`vault login -method=oidc role="reader"` +- [HashiCorp Developer - Vault](https://developer.hashicorp.com/vault) +- [HashiCorp Developer - Use JWT/OIDC authentication](https://developer.hashicorp.com/vault/docs/auth/jwt) +- [HashiCorp Developer - JWT/OIDC auth method API](https://developer.hashicorp.com/vault/api-docs/auth/jwt) +- [HashiCorp Developer - Identity group API](https://developer.hashicorp.com/vault/api-docs/secret/identity/group) +- [HashiCorp Developer - Identity group alias API](https://developer.hashicorp.com/vault/api-docs/secret/identity/group-alias)