Skip to main content

Groups

For an OIDC or SAML application, VaultysHub can transmit the user's list of groups to the application at each login. Configured to read this list, the application places the user in the correct groups upon their first login: they gain immediate access to the content relevant to them, without an administrator needing to log into the application to assign them.

Groups are defined by a mapping between your VaultysHub folders and the application's groups:

  • a folder can provide one or more groups;
  • multiple folders can provide the same group;
  • any folder in the organization can be mapped, whether it contains the application or not.

A user receives the groups from the folders they belong to, as well as those from folders open to all users. A folder without mapping transmits nothing: the application only receives the groups you have explicitly defined.

Configure the mapping​

From the list of applications, open the application's sheet, then the Authentication tab and the Groups section. This section only appears for applications configured in OIDC or SAML, alongside their other protocol settings.

  1. Click on Add a mapping.
  2. Choose a folder, then enter the name of the group as defined in the application (respect the case).
  3. Repeat the operation for each folder, then click on Save mappings.

The Claim Name field (OIDC) or Attribute Name (SAML) indicates under what name the list is transmitted. By default, it is groups. Change it if the application expects a different name (roles, memberOf, etc.).

OIDC: allow the groups scope​

In OIDC, groups are transmitted in the configured claim (default groups), in the ID token and the userinfo response, when the application requests the groups scope.

  1. In the Groups section, check Send groups (this allows the groups scope for the application; it also appears in the list of authorized scopes in the Sharing tab).
  2. In the application, add groups to the requested scopes (for example openid email profile groups).

The list is always sent, even empty. An application that synchronizes its groups at each login therefore removes the user from the groups of the folders they have left.

Example: Grafana​

[auth.generic_oauth]
scopes = openid email profile groups
groups_attribute_path = groups
role_attribute_path = contains(groups[*], 'grafana-admins') && 'Admin' || contains(groups[*], 'grafana-editors') && 'Editor' || 'Viewer'

For example, map the Ops folder to grafana-admins and the Development folder to grafana-editors.

SAML: the groups attribute​

In SAML, groups are transmitted in a multivalued attribute of the assertion, with one value per group:

<saml:Attribute Name="groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
  <saml:AttributeValue xsi:type="xs:string">support</saml:AttributeValue>
  <saml:AttributeValue xsi:type="xs:string">billing</saml:AttributeValue>
</saml:Attribute>

In the application, specify the name of this attribute as the source of the groups or roles. When the user has no groups, the attribute is omitted from the assertion.

Good to know​

  • Groups are calculated at the time of login. A change in folder is taken into account at the user's next login to the application.
  • It is the application that decides what to do with the groups: some apply them only at account creation, others at each login. Consult the application's documentation.
  • To provision groups before the first login, use SCIM provisioning, which creates folders as groups in the application.