diff options
Diffstat (limited to 'doc/integration/vault.md')
| -rw-r--r-- | doc/integration/vault.md | 190 |
1 files changed, 105 insertions, 85 deletions
diff --git a/doc/integration/vault.md b/doc/integration/vault.md index f85c71a5bb3..ad807f9eb7a 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -1,137 +1,157 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vault Authentication with GitLab OpenID Connect **(FREE)** [Vault](https://www.vaultproject.io/) is a secrets management application offered by HashiCorp. -It allows you to store and manage sensitive information such as secret environment variables, encryption keys, and authentication tokens. -Vault offers Identity-based Access, which means Vault users can authenticate through several of their preferred cloud providers. +It allows you to store and manage sensitive information such as secret environment +variables, encryption keys, and authentication tokens. -This document explains how Vault users can authenticate themselves through GitLab by utilizing our OpenID authentication feature. -The following assumes you already have Vault installed and running. +Vault offers Identity-based Access, which means Vault users can authenticate +through several of their preferred cloud providers. -1. **Get the OpenID Connect client ID and secret from GitLab:** +The following content explains how Vault users can authenticate themselves through +GitLab by using our OpenID authentication feature. - First you must create a GitLab application to obtain an application ID and secret for authenticating into Vault. - To do this, sign in to GitLab and follow these steps: +## Prerequisites - 1. In the top-right corner, select your avatar. - 1. Select **Edit profile**. - 1. On the left sidebar, select **Applications**. - 1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). - 1. Select the **OpenID** scope. - 1. Select **Save application**. - 1. Copy client ID and secret, or keep the page open for reference. +1. [Install Vault](https://www.vaultproject.io/docs/install). +1. Run Vault. -  +## Get the OpenID Connect client ID and secret from GitLab -1. **Enable OIDC auth on Vault:** +First you must create a GitLab application to obtain an application ID and secret +for authenticating into Vault. To do this, sign in to GitLab and follow these steps: - OpenID Connect is not enabled in Vault by default. This needs to be enabled in the terminal. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Applications**. +1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). +1. Select the **OpenID** scope. +1. Select **Save application**. +1. Copy the **Client ID** and **Client Secret**, or keep the page open for reference. - Open a terminal session and run the following command to enable the OpenID Connect authentication provider in Vault: + - ```shell - vault auth enable oidc - ``` +## Enable OpenID Connect on Vault - You should see the following output in the terminal: +OpenID Connect (OIDC) is not enabled in Vault by default. - ```plaintext - Success! Enabled oidc auth method at: oidc/ - ``` +To enable the OIDC authentication provider in Vault, open a terminal session +and run the following command: -1. **Write the OIDC configuration:** +```shell +vault auth enable oidc +``` - Next, Vault needs to be given the application ID and secret generated by GitLab. +You should see the following output in the terminal: - In the terminal session, run the following command to give Vault access to the GitLab application you've just created with an OpenID scope. This allows Vault to authenticate through GitLab. +```plaintext +Success! Enabled oidc auth method at: oidc/ +``` - Replace `your_application_id` and `your_secret` in the example below with the application ID and secret generated for your app: +## Write the OIDC configuration - ```shell - $ vault write auth/oidc/config \ - oidc_discovery_url="https://gitlab.com" \ - oidc_client_id="your_application_id" \ - oidc_client_secret="your_secret" \ - default_role="demo" \ - bound_issuer="localhost" - ``` +To give Vault the application ID and secret generated by GitLab and allow +Vault to authenticate through GitLab, run the following command in the terminal: - You should see the following output in the terminal: +```shell +vault write auth/oidc/config \ + oidc_discovery_url="https://gitlab.com" \ + oidc_client_id="<your_application_id>" \ + oidc_client_secret="<your_secret>" \ + default_role="demo" \ + bound_issuer="localhost" +``` - ```shell - Success! Data written to: auth/oidc/config - ``` +Replace `<your_application_id>` and `<your_secret>` with the application ID +and secret generated for your app. -1. **Write the OIDC Role Configuration:** +You should see the following output in the terminal: - Now that Vault has a GitLab application ID and secret, it needs to know the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris) and scopes given to GitLab during the application creation process. The redirect URIs need to match where your Vault instance is running. The `oidc_scopes` field needs to include the `openid`. Similarly to the previous step, replace `your_application_id` with the generated application ID from GitLab: +```shell +Success! Data written to: auth/oidc/config +``` - This configuration is saved under the name of the role you are creating. In this case, we are creating a `demo` role. Later, we show how you can access this role through the Vault CLI. +## Write the OIDC role configuration - WARNING: - If you're using a public GitLab instance (GitLab.com or any other instance publicly - accessible), it's paramount to specify the `bound_claims` to allow access only to - members of your group/project. Otherwise, anyone with a public account can access - your Vault instance. +You must tell Vault the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris) +and scopes given to GitLab when you created the application. - ```shell - vault write auth/oidc/role/demo -<<EOF - { - "user_claim": "sub", - "allowed_redirect_uris": "your_vault_instance_redirect_uris", - "bound_audiences": "your_application_id", - "oidc_scopes": "openid", - "role_type": "oidc", - "policies": "demo", - "ttl": "1h", - "bound_claims": { "groups": ["yourGroup/yourSubgrup"] } - } - EOF - ``` +Run the following command in the terminal: + +```shell +vault write auth/oidc/role/demo -<<EOF +{ + "user_claim": "sub", + "allowed_redirect_uris": "<your_vault_instance_redirect_uris>", + "bound_audiences": "<your_application_id>", + "oidc_scopes": "<openid>", + "role_type": "oidc", + "policies": "demo", + "ttl": "1h", + "bound_claims": { "groups": ["<yourGroup/yourSubgrup>"] } +} +EOF +``` + +Replace: + +- `<your_vault_instance_redirect_uris>` with redirect URIs that match where your + Vault instance is running. +- `<your_application_id>` with the application ID generated for your app. -1. **Sign in to Vault:** +The `oidc_scopes` field must include `openid`. - 1. Go to your Vault UI (example: [http://127.0.0.1:8200/ui/vault/auth?with=oidc](http://127.0.0.1:8200/ui/vault/auth?with=oidc)). - 1. If the `OIDC` method is not currently selected, open the dropdown and select it. - 1. Select **Sign in With GitLab**, which opens a modal window: +This configuration is saved under the name of the role you are creating. In this +example, we are creating a `demo` role. -  +WARNING: +If you're using a public GitLab instance, such as GitLab.com, you must specify +the `bound_claims` to allow access only to members of your group or project. +Otherwise, anyone with a public account can access your Vault instance. - 1. Select **Authorize** to allow Vault to sign in through GitLab. This redirects you back to your Vault UI as a signed-in user. +## Sign in to Vault -  +1. Go to your Vault UI. For example: [http://127.0.0.1:8200/ui/vault/auth?with=oidc](http://127.0.0.1:8200/ui/vault/auth?with=oidc). +1. If the `OIDC` method is not selected, open the dropdown list and select it. +1. Select **Sign in With GitLab**, which opens a modal window: -1. **Sign in using the Vault CLI** (optional): +  - Vault also allows you to sign in via their CLI. +1. To allow Vault to sign in through GitLab, select **Authorize**. This redirects you back to your Vault UI as a signed-in user. - After writing the same configurations from above, you can run the command below in your terminal to sign in with the role configuration created in step 4 above: +  + +## Sign in using the Vault CLI (optional) + +You can also sign into Vault using the [Vault CLI](https://www.vaultproject.io/docs/commands). + +1. To sign in with the role configuration you created in the previous example, + run the following command in your terminal: ```shell vault login -method=oidc port=8250 role=demo ``` - Here's a short explanation of what this command does: + This command sets: + + - `role=demo` so Vault knows which configuration we'd like to sign in with. + - `-method=oidc` to set Vault to use the `OIDC` sign-in method. + - `port=8250` to set the port that GitLab should redirect to. This port + number must match the port given to GitLab when listing + [Redirect URIs](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). - 1. In the **Write the OIDC Role Configuration** (step 4), we created a role called - `demo`. We set `role=demo` so Vault knows which configuration we'd like to - sign in with. - 1. To set Vault to use the `OIDC` sign-in method, we set `-method=oidc`. - 1. To set the port that GitLab should redirect to, we set `port=8250` or - another port number that matches the port given to GitLab when listing - [Redirect URIs](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). + After running this command, you should see a link in the terminal. - After running the command, it presents a link in the terminal. - Select the link in the terminal and a browser tab opens that confirms you're signed into Vault via OIDC: +1. Open this link in a web browser:  - The terminal outputs: + You should see in the terminal: ```plaintext Success! You are now authenticated. The token information displayed below |