From 42f7e36bdab4f64a56902aaf865ad6a420a7091a Mon Sep 17 00:00:00 2001
From: Mattis Haase <accounts@mattis-haase.de>
Date: Mon, 11 Nov 2024 15:29:26 +0100
Subject: [PATCH 1/2] Add external group documentation for vault

Signed-off-by: Mattis Haase <accounts@mattis-haase.de>
---
 .../services/hashicorp-vault/index.md         | 58 ++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/website/integrations/services/hashicorp-vault/index.md b/website/integrations/services/hashicorp-vault/index.md
index 84888261e477..540cb92f7c3e 100644
--- a/website/integrations/services/hashicorp-vault/index.md
+++ b/website/integrations/services/hashicorp-vault/index.md
@@ -88,8 +88,64 @@ vault write auth/oidc/role/reader \
       policies="reader"
 ```
 
+## External Groups
+
+If you wish to manage group membership in vault via Authentik you have to use [external groups](https://developer.hashicorp.com/vault/tutorials/auth-methods/oidc-auth#create-an-external-vault-group).
+
 :::note
-If you intend to create [external groups](https://developer.hashicorp.com/vault/tutorials/auth-methods/oidc-auth#create-an-external-vault-group) in Vault to manage user access the OIDC role will need to specifically request a custom scope using the `oidc_scopes` option when creating the OIDC role.
+This assumes that the steps above have already been completed and tested.
 :::
+
+### Step 1
+
+In authentik, edit the oidc provider created above. Unser "Advanced protocol settings" add "authentik default OAuth Mapping: OpenID 'profile'". This includes the "groups" mapping.
+
+### Step 2
+
+In hashicorp vault, change the reader role
+
+```
+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" ]
+```
+
+Add a group
+
+```
+vault write identity/group/reader \
+    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"`

From 37a5e34c084563679918809824f426dbe55dc998 Mon Sep 17 00:00:00 2001
From: mzhaase <mattis@mattis-haase.de>
Date: Tue, 12 Nov 2024 12:41:22 +0100
Subject: [PATCH 2/2] Spelling changes, linting

---
 .../services/hashicorp-vault/index.md           | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/website/integrations/services/hashicorp-vault/index.md b/website/integrations/services/hashicorp-vault/index.md
index 540cb92f7c3e..489c7807b0b9 100644
--- a/website/integrations/services/hashicorp-vault/index.md
+++ b/website/integrations/services/hashicorp-vault/index.md
@@ -90,7 +90,7 @@ vault write auth/oidc/role/reader \
 
 ## External Groups
 
-If you wish to manage group membership in vault via Authentik you have to use [external groups](https://developer.hashicorp.com/vault/tutorials/auth-methods/oidc-auth#create-an-external-vault-group).
+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).
 
 :::note
 This assumes that the steps above have already been completed and tested.
@@ -98,11 +98,11 @@ This assumes that the steps above have already been completed and tested.
 
 ### Step 1
 
-In authentik, edit the oidc provider created above. Unser "Advanced protocol settings" add "authentik default OAuth Mapping: OpenID 'profile'". This includes the "groups" mapping.
+In authentik, edit the OIDC provider created above. Under **Advanced protocol settings** add `authentik default OAuth Mapping: OpenID 'profile'` This includes the groups mapping.
 
 ### Step 2
 
-In hashicorp vault, change the reader role
+In Vault, change the reader role to have the following settings:
 
 ```
 vault write auth/oidc/role/reader \
@@ -116,7 +116,7 @@ vault write auth/oidc/role/reader \
       oidc_scopes=[ "openid profile email" ]
 ```
 
-Add a group
+Add a group.
 
 ```
 vault write identity/group/reader \
@@ -125,20 +125,19 @@ vault write identity/group/reader \
     type="external"
 ```
 
-Get the canonical id of the group
+Get the canonical ID of the group.
 
 ```
 vault list identity/group/id
 ```
 
-Get the id of the oidc accessor
+Get the ID of the OIDC accessor.
 
 ```
 vault auth list
 ```
 
-
-Add a group alias, this maps the group to the oidc backend
+Add a group alias, this maps the group to the OIDC backend.
 
 ```
 vault write identity/group-alias \
@@ -147,5 +146,5 @@ vault write identity/group-alias \
     name="group name in authentik"
 ```
 
-You should then be able to sign in via OIDC
+You should then be able to sign in via OIDC.
 `vault login -method=oidc role="reader"`