[auto] adding content to backport-56-34e884c47a295b17edc9272f19fdceee9c3f3245->release-x.56.x (#399)

Co-authored-by: Metabase Docs bot <metabase-bot@metabase.com>

Author: github-automation-metabase

_docs/v0.56/embedding/interactive-embedding-quick-start-guide.md

@@ -176,7 +176,9 @@ You'll map this string in the `groups` key to a Metabase group, so that when the
 
 In Metabase's admin section, go to **Settings** > **Authentication**. Scroll to the **JWT** card and click **Edit**.
 
-In the **Group schema** section, toggle on **Synchronize group memberships**. For each group you want to sync, add a group mapping. When you click **New mapping**, enter "Customer-Acme", the string that you included in the `groups` array in your JWT payload. You can then associate that group name with the Metabase group "Customer Acme" that we created earlier.
+In the **Group schema** section, toggle on **Synchronize group memberships**. If the names of groups in the `groups` array match Metabase group names exactly (e.g. both are `"Customer Acme"`), then the groups will be mapped automatically.
+
+If the JWT group names and Metabase group names don't match, then for each group you want to sync, add a group mapping. When you click **New mapping**, enter "Customer-Acme", the string that you included in the `groups` array in your JWT payload. You can then associate that group name with the Metabase group "Customer Acme" that we created earlier.
 
 ![Mapping user attributes to groups.](./images/sync-groups.png)
 

_docs/v0.56/people-and-groups/authenticating-with-jwt.md

@@ -29,56 +29,73 @@ Assuming your site is localhost serving on port 3000:
 5. In the event of a successful sign-in, your authentication app should issue a GET request to your Metabase endpoint with the token and the "return to" URI: `http://localhost:3000/auth/sso?jwt=TOKEN_GOES_HERE&return_to=/question/1-superb-question`.
 6. Metabase verifies the JSON Web Token, logs the person in, then redirects the person to their original destination, `/question/1-superb-question`.
 
-## Enabling JWT authentication
+## Set up JWT authentication
 
-Navigate to the **Admin**>**Settings** section of the Admin area, then click on the **Authentication** tab. Click the **Configure** button in the JWT section of this page, and you'll see this form:
+Navigate to the **Admin**>**Settings** section of the Admin area, then click on the **Authentication > JWT** tab.
 
 ![JWT form](images/JWT-auth-form.png)
 
 Here's a breakdown of each of the settings:
 
-**JWT Identity Provider URI:** This is where Metabase will redirect login requests. That is, it's where your users go to log in through your identity provider.
+- **JWT Identity Provider URI**: This is where Metabase will redirect login requests. That is, it's where your users go to log in through your identity provider.
 
-**String Used by the JWT Signing Key:** The string used to seed the private key used to validate JWT messages. Both Metabase and the authentication app should have the same JWT signing key.
+- **String Used by the JWT Signing Key**: The string used to seed the private key used to validate JWT messages. Both Metabase and the authentication app should have the same JWT signing key.
 
 ## User attribute configuration (optional)
 
 These are additional settings you can fill in to pass user attributes to Metabase.
 
 - **Email attribute:** the key to retrieve each JWT user's email address.
-- **First Name attribute:** the key to retrieve each JWT user's first name.
-- **Last Name attribute:** if you guessed that this is the key to retrieve each JWT user's last name, well then you have been paying attention.
+- **First name attribute:** the key to retrieve each JWT user's first name.
+- **Last name attribute:** if you guessed that this is the key to retrieve each JWT user's last name, well then you have been paying attention.
+- **Group assignment attribute:** the key to retrieve each JWT user's group assignments.
 
 You can send additional user attributes to Metabase by adding the attributes as key/value pairs to your JWT. These attributes will be synced on every login.
 
 ## Configure group mappings
 
-You can use your JWT to assign Metabase users to custom groups.
+You can use your JWT to assign Metabase users to custom Metabase [groups](./managing#groups) based on their attributes, e.g. automatically assign everyone with a certain JWT attribute to the `Sales` group in Metabase. This can be helpful for [permissions management](../permissions/introduction#key-points-regarding-permissions) at scale.
 
-1. Add groups to your JWT: `groups: ["group_name"]`.
-1. In Metabase, go to the Admin panel and switch to **Setting > Authentication** tab.
-1. Click the **Configure** button under JWT.
-1. Under **Group Schema**, turn on the toggle **Synchronize Group Memberships**
-1. Click **New mapping** and add the name of a JWT group.
+You can configure JWT group assignments through Metabase's Admin interface, or by setting environment variables.
+
+### Configure group mapping in Metabase
+
+1. Add groups to your JWT: `groups: ["group_name"]`. The attribute key (e.g. `groups`) should match the **Group assignment attribute** in Metabase.
+1. In Metabase JWT settings, under **Group Sync**, toggle on **Synchronize Group Memberships**
+1. If the group names in your JWT match the Metabase group names, they will be synced automatically, and you don't need to set up mappings manually.
+
+1. Otherwise, click **New mapping** and add the name of a JWT group.
 1. In the row that appears, click the dropdown to pick the Metabase group(s) that this should map to.
    ![Metabase JWT group mappings](./images/jwt-groups.png)
 1. Repeat this for each of the groups you want to map.
 
-Alternatively, you can define the mappings between JWT and Metabase groups using the [environment variable `MB_JWT_GROUP_MAPPINGS`](../configuring-metabase/environment-variables#mb_jwt_group_mappings). It accepts a JSON object where the keys are JWT groups and the values are lists of Metabase groups IDs. For example:
+### Configure group mapping through environment variables
+
+You can use the following environment variables to configure JTW group mappings instead of configuring them in Metabase's Admin settings:
+
+- [`MB_JWT_ATTRIBUTE_GROUPS`](../configuring-metabase/environment-variables#mb_jwt_attribute_groups) to specify the key to retrieve the JWT user’s groups;
+
+- [`MB_JWT_GROUP_SYNC`](../configuring-metabase/environment-variables#mb_jwt_group_sync) to turn group sync on or off (sync is off by default).
+
+  ```
+  MB_JWT_GROUP_SYNC=true
+  ```
+
+- [`MB_JWT_GROUP_MAPPINGS`](../configuring-metabase/environment-variables#mb_jwt_group_mappings) to configure group mapping. It accepts a JSON object where the keys are JWT groups and the values are lists of Metabase groups IDs. For example:
+
+  ```
+  MB_JWT_GROUP_MAPPINGS='{"extHR":[7], "extSales":[3,4]}'
+  ```
 
-```
-MB_JWT_GROUP_MAPPINGS='{"extHR":[7], "extSales":[3,4]}'
-```
+  where `extHR`, `extSales` are names of JWT groups and 3,4,7 are IDs of Metabase groups.
 
-where `extHR`, `extSales` are names of JWT groups and 3,4,7 are IDs of Metabase groups.
+  You can find Metabase Group ID in the URL for the group page, like `http://your-metabase-url/admin/people/groups/<ID>`. "All Users" group has ID 1 and "Administrators" group has ID 2.
 
-You can find Metabase Group ID in the URL for the group page, like `http://your-metabase-url/admin/people/groups/<ID>`. "All Users" group has ID 1 and "Administrators" group has ID 2.
+### If group mappings are not specified, Metabase will match groups by name
 
-You can also use the [environment variable `MB_JWT_GROUP_SYNC`](../configuring-metabase/environment-variables#mb_jwt_group_sync) to turn group sync on or off.
+If you don't specify any group mappings in Metabase's Admin settings or via `MB_JWT_GROUP_MAPPINGS` environment variables, then Metabase will try to assign Metabase groups to users based on the matching names. If the names of groups in the JWT group attribute array match Metabase group names exactly (e.g. both are `"Sales"`), then the groups will be mapped automatically.
 
-```
-MB_JWT_GROUP_SYNC=true
-```
+If you add group mappings manually, Metabase will _not_ try to also match groups by names.
 
 ## Creating Metabase accounts with SSO
 

_docs/v0.56/people-and-groups/images/JWT-auth-form.png

@@ -5064,7 +5064,9 @@ <h3 id="synchronize-groups-between-metabase-and-your-app">Synchronize groups bet
 
 <p>In Metabase’s admin section, go to <strong>Settings</strong> &gt; <strong>Authentication</strong>. Scroll to the <strong>JWT</strong> card and click <strong>Edit</strong>.</p>
 
-<p>In the <strong>Group schema</strong> section, toggle on <strong>Synchronize group memberships</strong>. For each group you want to sync, add a group mapping. When you click <strong>New mapping</strong>, enter “Customer-Acme”, the string that you included in the <code class="language-plaintext highlighter-rouge">groups</code> array in your JWT payload. You can then associate that group name with the Metabase group “Customer Acme” that we created earlier.</p>
+<p>In the <strong>Group schema</strong> section, toggle on <strong>Synchronize group memberships</strong>. If the names of groups in the <code class="language-plaintext highlighter-rouge">groups</code> array match Metabase group names exactly (e.g. both are <code class="language-plaintext highlighter-rouge">"Customer Acme"</code>), then the groups will be mapped automatically.</p>
+
+<p>If the JWT group names and Metabase group names don’t match, then for each group you want to sync, add a group mapping. When you click <strong>New mapping</strong>, enter “Customer-Acme”, the string that you included in the <code class="language-plaintext highlighter-rouge">groups</code> array in your JWT payload. You can then associate that group name with the Metabase group “Customer Acme” that we created earlier.</p>
 
 <p><img src="./images/sync-groups.png" alt="Mapping user attributes to groups."></p>
 

_docs/v0.56/people-and-groups/images/jwt-groups.png

@@ -4876,58 +4876,87 @@ <h2 id="typical-flow-for-a-jwt-based-sso-interaction-with-metabase">Typical flow
   <li>Metabase verifies the JSON Web Token, logs the person in, then redirects the person to their original destination, <code class="language-plaintext highlighter-rouge">/question/1-superb-question</code>.</li>
 </ol>
 
-<h2 id="enabling-jwt-authentication">Enabling JWT authentication</h2>
+<h2 id="set-up-jwt-authentication">Set up JWT authentication</h2>
 
-<p>Navigate to the <strong>Admin</strong>&gt;<strong>Settings</strong> section of the Admin area, then click on the <strong>Authentication</strong> tab. Click the <strong>Configure</strong> button in the JWT section of this page, and you’ll see this form:</p>
+<p>Navigate to the <strong>Admin</strong>&gt;<strong>Settings</strong> section of the Admin area, then click on the <strong>Authentication &gt; JWT</strong> tab.</p>
 
 <p><img src="images/JWT-auth-form.png" alt="JWT form"></p>
 
 <p>Here’s a breakdown of each of the settings:</p>
 
-<p><strong>JWT Identity Provider URI:</strong> This is where Metabase will redirect login requests. That is, it’s where your users go to log in through your identity provider.</p>
-
-<p><strong>String Used by the JWT Signing Key:</strong> The string used to seed the private key used to validate JWT messages. Both Metabase and the authentication app should have the same JWT signing key.</p>
+<ul>
+  <li>
+    <p><strong>JWT Identity Provider URI</strong>: This is where Metabase will redirect login requests. That is, it’s where your users go to log in through your identity provider.</p>
+  </li>
+  <li>
+    <p><strong>String Used by the JWT Signing Key</strong>: The string used to seed the private key used to validate JWT messages. Both Metabase and the authentication app should have the same JWT signing key.</p>
+  </li>
+</ul>
 
 <h2 id="user-attribute-configuration-optional">User attribute configuration (optional)</h2>
 
 <p>These are additional settings you can fill in to pass user attributes to Metabase.</p>
 
 <ul>
   <li><strong>Email attribute:</strong> the key to retrieve each JWT user’s email address.</li>
-  <li><strong>First Name attribute:</strong> the key to retrieve each JWT user’s first name.</li>
-  <li><strong>Last Name attribute:</strong> if you guessed that this is the key to retrieve each JWT user’s last name, well then you have been paying attention.</li>
+  <li><strong>First name attribute:</strong> the key to retrieve each JWT user’s first name.</li>
+  <li><strong>Last name attribute:</strong> if you guessed that this is the key to retrieve each JWT user’s last name, well then you have been paying attention.</li>
+  <li><strong>Group assignment attribute:</strong> the key to retrieve each JWT user’s group assignments.</li>
 </ul>
 
 <p>You can send additional user attributes to Metabase by adding the attributes as key/value pairs to your JWT. These attributes will be synced on every login.</p>
 
 <h2 id="configure-group-mappings">Configure group mappings</h2>
 
-<p>You can use your JWT to assign Metabase users to custom groups.</p>
+<p>You can use your JWT to assign Metabase users to custom Metabase <a href="./managing#groups">groups</a> based on their attributes, e.g. automatically assign everyone with a certain JWT attribute to the <code class="language-plaintext highlighter-rouge">Sales</code> group in Metabase. This can be helpful for <a href="../permissions/introduction#key-points-regarding-permissions">permissions management</a> at scale.</p>
+
+<p>You can configure JWT group assignments through Metabase’s Admin interface, or by setting environment variables.</p>
+
+<h3 id="configure-group-mapping-in-metabase">Configure group mapping in Metabase</h3>
 
 <ol>
-  <li>Add groups to your JWT: <code class="language-plaintext highlighter-rouge">groups: ["group_name"]</code>.</li>
-  <li>In Metabase, go to the Admin panel and switch to <strong>Setting &gt; Authentication</strong> tab.</li>
-  <li>Click the <strong>Configure</strong> button under JWT.</li>
-  <li>Under <strong>Group Schema</strong>, turn on the toggle <strong>Synchronize Group Memberships</strong></li>
-  <li>Click <strong>New mapping</strong> and add the name of a JWT group.</li>
+  <li>Add groups to your JWT: <code class="language-plaintext highlighter-rouge">groups: ["group_name"]</code>. The attribute key (e.g. <code class="language-plaintext highlighter-rouge">groups</code>) should match the <strong>Group assignment attribute</strong> in Metabase.</li>
+  <li>In Metabase JWT settings, under <strong>Group Sync</strong>, toggle on <strong>Synchronize Group Memberships</strong></li>
+  <li>
+    <p>If the group names in your JWT match the Metabase group names, they will be synced automatically, and you don’t need to set up mappings manually.</p>
+  </li>
+  <li>Otherwise, click <strong>New mapping</strong> and add the name of a JWT group.</li>
   <li>In the row that appears, click the dropdown to pick the Metabase group(s) that this should map to.
 <img src="./images/jwt-groups.png" alt="Metabase JWT group mappings"></li>
   <li>Repeat this for each of the groups you want to map.</li>
 </ol>
 
-<p>Alternatively, you can define the mappings between JWT and Metabase groups using the <a href="../configuring-metabase/environment-variables#mb_jwt_group_mappings">environment variable <code class="language-plaintext highlighter-rouge">MB_JWT_GROUP_MAPPINGS</code></a>. It accepts a JSON object where the keys are JWT groups and the values are lists of Metabase groups IDs. For example:</p>
+<h3 id="configure-group-mapping-through-environment-variables">Configure group mapping through environment variables</h3>
 
-<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>MB_JWT_GROUP_MAPPINGS='{"extHR":[7], "extSales":[3,4]}'
-</code></pre></div></div>
+<p>You can use the following environment variables to configure JTW group mappings instead of configuring them in Metabase’s Admin settings:</p>
 
-<p>where <code class="language-plaintext highlighter-rouge">extHR</code>, <code class="language-plaintext highlighter-rouge">extSales</code> are names of JWT groups and 3,4,7 are IDs of Metabase groups.</p>
+<ul>
+  <li>
+    <p><a href="../configuring-metabase/environment-variables#mb_jwt_attribute_groups"><code class="language-plaintext highlighter-rouge">MB_JWT_ATTRIBUTE_GROUPS</code></a> to specify the key to retrieve the JWT user’s groups;</p>
+  </li>
+  <li>
+    <p><a href="../configuring-metabase/environment-variables#mb_jwt_group_sync"><code class="language-plaintext highlighter-rouge">MB_JWT_GROUP_SYNC</code></a> to turn group sync on or off (sync is off by default).</p>
+
+    <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>MB_JWT_GROUP_SYNC=true
+</code></pre></div>    </div>
+  </li>
+  <li>
+    <p><a href="../configuring-metabase/environment-variables#mb_jwt_group_mappings"><code class="language-plaintext highlighter-rouge">MB_JWT_GROUP_MAPPINGS</code></a> to configure group mapping. It accepts a JSON object where the keys are JWT groups and the values are lists of Metabase groups IDs. For example:</p>
+
+    <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>MB_JWT_GROUP_MAPPINGS='{"extHR":[7], "extSales":[3,4]}'
+</code></pre></div>    </div>
+
+    <p>where <code class="language-plaintext highlighter-rouge">extHR</code>, <code class="language-plaintext highlighter-rouge">extSales</code> are names of JWT groups and 3,4,7 are IDs of Metabase groups.</p>
+
+    <p>You can find Metabase Group ID in the URL for the group page, like <code class="language-plaintext highlighter-rouge">http://your-metabase-url/admin/people/groups/&lt;ID&gt;</code>. “All Users” group has ID 1 and “Administrators” group has ID 2.</p>
+  </li>
+</ul>
 
-<p>You can find Metabase Group ID in the URL for the group page, like <code class="language-plaintext highlighter-rouge">http://your-metabase-url/admin/people/groups/&lt;ID&gt;</code>. “All Users” group has ID 1 and “Administrators” group has ID 2.</p>
+<h3 id="if-group-mappings-are-not-specified-metabase-will-match-groups-by-name">If group mappings are not specified, Metabase will match groups by name</h3>
 
-<p>You can also use the <a href="../configuring-metabase/environment-variables#mb_jwt_group_sync">environment variable <code class="language-plaintext highlighter-rouge">MB_JWT_GROUP_SYNC</code></a> to turn group sync on or off.</p>
+<p>If you don’t specify any group mappings in Metabase’s Admin settings or via <code class="language-plaintext highlighter-rouge">MB_JWT_GROUP_MAPPINGS</code> environment variables, then Metabase will try to assign Metabase groups to users based on the matching names. If the names of groups in the JWT group attribute array match Metabase group names exactly (e.g. both are <code class="language-plaintext highlighter-rouge">"Sales"</code>), then the groups will be mapped automatically.</p>
 
-<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>MB_JWT_GROUP_SYNC=true
-</code></pre></div></div>
+<p>If you add group mappings manually, Metabase will <em>not</em> try to also match groups by names.</p>
 
 <h2 id="creating-metabase-accounts-with-sso">Creating Metabase accounts with SSO</h2>