Attribute management
From Mattermost v12.0, you define an attribute once in Attribute Management, then choose which resources can use it. An attribute such as Department or Clearance has a single definition (display name, name, type, options, and an optional AD/LDAP, SAML, or OpenID Connect source) that's shared by every resource it applies to. Attribute Management replaces the User Attributes page used in earlier releases. For servers before v12.0, see User attributes.
Attributes defined here are the attributes you reference in attribute-based access control (ABAC) policies, for example user.attributes.department.
To open Attribute Management, go to System Console > System Attributes > Attribute Management. Only system admins can create, edit, or delete attributes.
Upgrade to v12.0: existing user attributes
After the conversion:
- User attribute names, IDs, and user values don't change, so existing ABAC policies that reference
user.attributes.<name>continue to work. - Options, visibility, who can set the value, and AD/LDAP or SAML mappings carry over.
- If an existing name isn't a valid attribute name, or is already used by another attribute, the new definition gets an adjusted name. The user attribute keeps its original name, so policies aren't affected.
- Attributes created by plugins and protected attributes aren't converted.
If the server isn't licensed when it starts, the conversion is skipped and runs on a later restart once a license is applied.
Review attributes
The Attribute Management page lists every attribute alphabetically by display name. Use Search attributes to filter by display name or name. Use Source to show only attributes from one source: Managed here, AD/LDAP, SAML, OpenID Connect, or Plugin. Use Resource type to show only attributes that apply to Users, Channels, or Posts; the list offers only the resource types available on your server, and is hidden when Users is the only one. Select a row to edit an attribute.
| Column | Shows |
|---|---|
| Attribute | The display name. |
| Type | The attribute type, such as Text or Select. |
| Applies to | The resources that use the attribute, such as Users or Channels. |
| Source | Where values come from: Managed here, AD/LDAP, SAML, OpenID Connect, or the name of the plugin that owns the attribute. |
| Options | The number of options, or Free Text for types without preset values. |
The Classification attribute used by classification markings is shown as Definition is read-only. Manage its levels from the Classification Markings page by selecting Open Classification Markings in its row.
Create an attribute
- Select New attribute.
- In the Definition section, enter the following details:
- Display name: The label admins and users see. Up to 40 characters.
- Unique name: Generated from the display name. Select Edit to change it. The name is the internal identifier used in access control policies and integrations, and must be unique. It must start with a letter or underscore and can contain only letters, numbers, and underscores. Reserved CEL words aren't allowed:
true,false,null,in,as,break,const,continue,else,for,function,if,import,let,loop,package,namespace,return,var,void, andwhile. - Type: Select one of the following:
- Text: A value typed in for each resource.
- Phone: A phone number.
- URL: A web address.
- Select: A single value chosen from a list of options.
- Multiselect: One or more values chosen from a list of options.
- Ranked: A single value chosen from an ordered list, where each option ranks higher or lower than the others, such as Public, Secret, and Top Secret. Because the options are ordered, access control policies can compare a ranked attribute against a threshold, for example clearance is at least Secret.
- Hierarchical: Values organized as parents and children, such as organizational units or programs. You can choose this type only when you create an attribute. See Hierarchical attributes.
- Options: For Hierarchical attributes, build the hierarchy of values. For Select, Multiselect, and Ranked attributes, enter each option and press Enter or Tab. At least one option is required, unless the attribute is linked to an external source that provides its options. Options can be up to 64 characters and must be unique. Select an option to rename it, move it to another position, or remove it. For Ranked attributes, options are shown from lowest to highest rank; select an option to change its rank.
- Optionally, link the attribute to an external source.
- In the Applies to section, select Add resource and choose the resources the attribute applies to.
- Select Save.
You can define up to 200 attributes in total, and up to 20 attributes can apply to Users.
Hierarchical attributes
From Mattermost v12.0, a Hierarchical attribute's values form a tree, where each value can have parent values above it and child values below it. Use it for values that nest, such as organizational units or programs. For example, a Programs attribute might have All Programs at the top, Air and Sea below it, and F-18 and F-35 below Air.
In access rules, holding a value also counts for every value below it. A user who holds Air covers F-18 and F-35 too, so one rule can admit everyone at or above a given level of the tree.
Plan the attribute before you create it:
- You can choose Hierarchical only when you create an attribute. An existing attribute can't be converted to Hierarchical, and a hierarchical attribute can't be converted to another type. To change the type, create a new attribute and set its values again.
- A hierarchical attribute can't be linked to AD/LDAP or SAML. Its values are managed in Mattermost.
Build the hierarchy
When you select Hierarchical as the type, the Options area shows the attribute's values as a tree. Each row has icons to add a child, open the value's parents, and delete the value. Select a value's name to open a menu where you can rename it and manage its Parents and Children.
- Add a top-level value: Enter a name in Add a top-level value at the bottom of the tree, then select Add value. For a new attribute, start by entering the first value under Add the first value.
- Add a child value: On the parent's row, select the + icon, enter the name of the new value, then select Add.
- Give a value more than one parent: Select the value's name, select Parents, then choose an existing value or type a new name to create it as a parent. A value with several parents is listed under each of them, and its row shows how many parents it has. In the same menu, Children lets you add or remove child values the same way.
- Move a value: Drag the value's handle onto another row to nest it under that value. The value moves from the parent it was listed under to the new one. The order of rows in the list has no meaning.
- Move a value to the top level: Select the value's name, select Parents, then remove each parent.
- Delete a value: Select the trash can icon on its row, or select Delete this value in its menu. You can't delete a value that's the only parent of other values. Move or delete those child values first. Child values that have another parent are kept.
When adding a parent would bring more values under it, Mattermost asks you to confirm. A value can't be placed under one of its own child values, because the hierarchy can't loop back on itself. Each value can have up to 100 parents, and the hierarchy can be up to 100 levels deep.
Select Save to save your changes.
Set hierarchical values
Users and channels can hold one or more values of a hierarchical attribute. Values are set in the same places as other attribute values:
- Users: Users set their own values in their profile when Who can set the value is Member. System admins can set any user's values. See Manage user attributes.
- Channels: Set values from Channel Info or Channel Settings > Info. See Set channel attribute values.
A user's selected values are shown in their profile popover, unless Profile display is set to Hidden.
Use hierarchical attributes in access rules
In the policy editor's Simple Mode, hierarchical attributes offer the operators covers all of, covers any of, is within all of, is within any of, has any of, and has all of. To learn how each one uses the hierarchy, see Hierarchical attributes in the policy expression reference.
Link an attribute to an external source
Synchronize an attribute's user values from your identity provider instead of managing them in Mattermost. AD/LDAP, SAML, or OpenID Connect sign-in must already be configured. See AD/LDAP groups, SAML 2.0, or OpenID Connect for details.
- In the Definition section, select Link to external source, then select AD/LDAP, SAML, or OpenID Connect.
- Enter the name of the attribute in your AD/LDAP directory or SAML response, or the claim in the OpenID Connect ID token or userinfo response, to sync the value from, then save.
You can link both AD/LDAP and SAML to the same attribute, but not together with OpenID Connect. Linked sources are listed under Synced with.
From Mattermost v12.1, you can link an attribute to an OpenID Connect claim, which is synced every time a user signs in through OpenID Connect. An attribute linked to OpenID Connect can't also be linked to AD/LDAP or SAML. See Sync user attributes from OpenID Connect claims for details.
From Mattermost v12.1, Select and Multiselect attributes keep their type when you link them:
- A Select attribute stores the first value the identity provider sends, and a Multiselect attribute stores every value, such as each group a user belongs to.
- The synchronization manages the options. Each new value it sends is added as an option, up to 500 options, and options that no user or channel holds any more are removed, including options added before the attribute was linked. While the attribute is linked, its options can't be added, renamed, or removed in Mattermost.
- The attribute must apply to Users, because its options come from the values synchronized to users. A linked Select or Multiselect attribute can't be saved until it applies to Users.
Choose the resources an attribute applies to
Each resource you add has its own settings. Select a resource to expand its settings, or select Remove resource to remove it.
Users
The Users resource also applies to bot accounts. Bots are evaluated by access control policies the same way as users, so a bot needs the attribute values a policy requires. From Mattermost v12.1, bot attribute values can be set from Integrations > Bot Accounts or through the API. See Bot attributes for details.
- Profile display: Controls whether the attribute appears on user profiles: Always, When set (default), or Hidden.
- Who can set the value: Member lets users set their own value, and system admins can still change it. From Mattermost v12.1, a bot's owner can also set Member values for the bot. System Administrator restricts the value to system admins and identity provider synchronization, for users and bots alike.
To view or update an individual user's values, see Manage user attributes.
Channels
The Channels resource requires a Mattermost Entry or Enterprise Advanced license. Only admins can set channel values. See Channel attributes for details.
- Changing the value: Controls how a channel's value can change after it's set:
- Can be changed at any time (default)
- Can only be raised, never lowered (Ranked attributes only)
- Can only be lowered, never raised (Ranked attributes only)
- Cannot be changed once set
- Display location: Where else the value is shown in the channel: Header, Banner, or both. The value is always shown in Channel Info, so Channel Info isn't a choice here.
- Required: When enabled, a channel must have a value for this attribute before it can be created. Available only when the
ChannelAttributesRequiredfeature flag is also enabled.
Edit an attribute
Select an attribute's row, or select More actions > Edit attribute, make your changes, and select Save.
- Unique name and Type can't be changed while the attribute applies to a resource. To change them, you must remove every resource and save, which permanently deletes all values stored for the attribute. Adding the resources back afterwards doesn't restore those values. Before you remove a resource, record any values you need to keep so you can set them again.
- When you change the Display name, the new name also applies to each resource that uses the attribute, unless that resource's label was customized separately.
- Changes to options apply to every resource that uses the attribute.
Delete an attribute
- In the attribute's row, select More actions > Delete attribute.
- Select Delete to confirm.
Deleting an attribute permanently removes its definition and can't be undone. You can't delete an attribute while it still applies to a resource. Edit the attribute, remove every resource from Applies to, save, then delete it.
Attribute access modes
Attributes created in Attribute Management use the public access mode, so their values are visible to every admin editing a policy that references them. Plugins can create attributes with restricted access modes. See Attribute access modes for details.