From a6011c3d70e0e8ac318ba6629183c44f8614c4df Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Fri, 6 Mar 2020 03:08:08 +0000 Subject: Add latest changes from gitlab-org/gitlab@master --- doc/integration/vault.md | 137 ++++++++++++++++++++++++----------------------- 1 file changed, 70 insertions(+), 67 deletions(-) (limited to 'doc/integration') diff --git a/doc/integration/vault.md b/doc/integration/vault.md index b3e77ce440d..3ba401d8b35 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -15,106 +15,109 @@ The following assumes you already have Vault installed and running. 1. **Get the OpenID Connect client ID and secret from GitLab:** - First you'll need to 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: + First you'll need to 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: - 1. On GitLab, click your avatar on the top-right corner, and select your user **Settings > Applications**. - 1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt.html#redirect-uris), - making sure to select the **OpenID** scope. - 1. Save application. - 1. Copy client ID and secret, or keep the page open for reference. - ![GitLab OAuth provider](img/gitlab_oauth_vault_v12_6.png) + 1. On GitLab, click your avatar on the top-right corner, and select your user **Settings > Applications**. + 1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt.html#redirect-uris), + making sure to select the **OpenID** scope. + 1. Save application. + 1. Copy client ID and secret, or keep the page open for reference. + + ![GitLab OAuth provider](img/gitlab_oauth_vault_v12_6.png) 1. **Enable OIDC auth on Vault:** - OpenID Connect is not enabled in Vault by default. This needs to be enabled in the terminal. + OpenID Connect is not enabled in Vault by default. This needs to be enabled in the terminal. - Open a terminal session and run the following command to enable the OpenID Connect authentication provider in Vault: + Open a terminal session and run the following command to enable the OpenID Connect authentication provider in Vault: - ```shell - vault auth enable oidc - ``` + ```shell + vault auth enable oidc + ``` - You should see the following output in the terminal: + You should see the following output in the terminal: - ```plaintext - Success! Enabled oidc auth method at: oidc/ - ``` + ```plaintext + Success! Enabled oidc auth method at: oidc/ + ``` 1. **Write the OIDC config:** - Next, Vault needs to be given the application ID and secret generated by GitLab. + Next, Vault needs to be given the application ID and secret generated by GitLab. - 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. + 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. - Replace `your_application_id` and `your_secret` in the example below with the application ID and secret generated for your app: + Replace `your_application_id` and `your_secret` in the example below with the application ID and secret generated for your app: - ```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 + $ 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" + ``` - You should see the following output in the terminal: + You should see the following output in the terminal: - ```shell - Success! Data written to: auth/oidc/config - ``` + ```shell + Success! Data written to: auth/oidc/config + ``` 1. **Write the OIDC Role Config:** - Now that Vault has a GitLab application ID and secret, it needs to know the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt.html#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: + Now that Vault has a GitLab application ID and secret, it needs to know the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt.html#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: - This configuration is saved under the name of the role you are creating. In this case, we are creating a `demo` role. Later, we'll show how you can access this role through the Vault CLI. + This configuration is saved under the name of the role you are creating. In this case, we are creating a `demo` role. Later, we'll show how you can access this role through the Vault CLI. - ```shell - vault write auth/oidc/role/demo \ - user_claim="sub" \ - allowed_redirect_uris="http://localhost:8250/oidc/callback,http://127.0.0.1:8200/ui/vault/auth/oidc/oidc/callback" \ - bound_audiences="your_application_id" \ - role_type="oidc" \ - oidc_scopes="openid" \ - policies=demo \ - ttl=1h - ``` + ```shell + vault write auth/oidc/role/demo \ + user_claim="sub" \ + allowed_redirect_uris="http://localhost:8250/oidc/callback,http://127.0.0.1:8200/ui/vault/auth/oidc/oidc/callback" \ + bound_audiences="your_application_id" \ + role_type="oidc" \ + oidc_scopes="openid" \ + policies=demo \ + ttl=1h + ``` 1. **Sign in to Vault:** - 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. Click the **Sign in With GitLab** button, which will open a modal window: - ![Sign into Vault with GitLab](img/sign_into_vault_with_gitlab_v12_6.png) + 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. Click the **Sign in With GitLab** button, which will open a modal window: + + ![Sign into Vault with GitLab](img/sign_into_vault_with_gitlab_v12_6.png) + + 1. Click **Authorize** on the modal to allow Vault to sign in through GitLab. This will redirect you back to your Vault UI as a signed-in user. - 1. Click **Authorize** on the modal to allow Vault to sign in through GitLab. This will redirect you back to your Vault UI as a signed-in user. - ![Authorize Vault to connect with GitLab](img/authorize_vault_with_gitlab_v12_6.png) + ![Authorize Vault to connect with GitLab](img/authorize_vault_with_gitlab_v12_6.png) 1. **Sign in using the Vault CLI** (optional): - Vault also allows you to sign in via their CLI. + Vault also allows you to sign in via their CLI. - 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: + 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: - ```shell - vault login -method=oidc port=8250 role=demo - ``` + ```shell + vault login -method=oidc port=8250 role=demo + ``` - Here is a short explaination of what this command does: + Here is a short explaination of what this command does: - 1. In the **Write the OIDC Role Config** (step 4), we created a role called `demo`. We set `role=demo` so Vault knows which configuration we'd like to login 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.html#redirect-uris). + 1. In the **Write the OIDC Role Config** (step 4), we created a role called `demo`. We set `role=demo` so Vault knows which configuration we'd like to login 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.html#redirect-uris). - Once you run the command above, it will present a link in the terminal. - Click the link in the terminal and a tab will open in the browser confirming you're signed into Vault via OIDC: + Once you run the command above, it will present a link in the terminal. + Click the link in the terminal and a tab will open in the browser confirming you're signed into Vault via OIDC: - ![Signed into Vault via OIDC](img/signed_into_vault_via_oidc_v12_6.png) + ![Signed into Vault via OIDC](img/signed_into_vault_via_oidc_v12_6.png) - The terminal will output: + The terminal will output: - ```plaintext - Success! You are now authenticated. The token information displayed below - is already stored in the token helper. You do NOT need to run "vault login" - again. Future Vault requests will automatically use this token. - ``` + ```plaintext + Success! You are now authenticated. The token information displayed below + is already stored in the token helper. You do NOT need to run "vault login" + again. Future Vault requests will automatically use this token. + ``` -- cgit v1.2.1