When an enterprise customer decided to add special Confluence permissions to every member in their Digital Transformation Office, they realized that the Regular Expressions that they were using were not enough to handle the complexity. This article shows how we automated group assignments for them using a simple Groovy script.
Note that your current settings may be different to the default Azure AD (now called Entra) configuration we are assuming in the article. If you’re unable to figure out how to tweak it to meet your needs, we recommend scheduling a screenshare session with a specialist so we can figure it out together.
Automatic Group Assignments based on complex criteria
Managing user groups in Jira and Confluence can be a time-consuming and error-prone task, especially when dealing with a large number of users and groups.
Recently we got a support case where one of our customers, a big utility company, needed to assign users to a group automatically when the user met some specific criteria.
We need your help to achieve the following in Confluence:
When a user logs in, if he has a certain value in an attribute, add the user to a specific group.
Can we use a groovy script in a “User Property” to add the user to a group?
When mapping groups between the IdP and the Atlassian application, most customers create 1:1 mappings and transformations.
But in this case we’re facing something entirely different: instead of adding users to a group because they are in a certain group, we’re adding them to a group because they meet certain conditions other than being in a group.
This article shows our response and can be used as an inspiration for any company interested in managing group memberships automatically. Spoiler: the solution is hidden in 8 lines of Groovy Code.
Note: While this article shares the configuration options of a real customer, we have modified any group names and identifiable parameters that could be used for the purpose of identifying the organization.
The Starting Point
Prerequisites
In this specific case, our customer already had an initial configuration setup with some Regular Expressions rules to manage Confluence groups. Here’s what they were using at the time
- Confluence Data Center instance with 10,000 users
- Active Directory
- Enabled Active Directory Federation Services (AD FS)
- SAML SSO for Confluence (but a solution for Jira would look identical)
Existing Group Management Configuration
The customer was already carrying over some group memberships from AD FS into Confluence. Their general approach was a 1 to many transformation, funneling multiple group memberships in the Active Directory into the group giving application access to Confluence
Existing RegEx rule
- transform all incoming groups whose names end with
ABC_Confluence_Access_XYZtoconfluence_users - drop any other group (than the above) that is returned by AD FS in the SAML response
The new (complex) requirement
Users had to be automatically assigned to a specific group called ‘GDI Internal Users’ as they logged in, but only when two conditions were met in the SAML response:
- The attribute “extensionAttribute4” was equal to “domain.com/domain/GDI”
- The username started with the character “D“ followed by numbers/digits
The Solution: Groovy Code
Faced with this requirement, our support team suggested using a simple Groovy code script to automate and simplify the new group assignment while keeping the existing RegEx rules. It was an obvious choice, since the number one reason for adding a groovy option into selected functions of the app was precisely to offer our customers the maximum flexibility for meeting their requirements without having to build custom features that wouldn’t scale.
*Groovy is a powerful, flexible, and easy-to-learn programming language that can be used to extend the functionality of Jira and Confluence. With Groovy, you can create scripts that can be run within Jira or Confluence to perform tasks such as adding or removing users from groups, or even creating new groups.
Step-by-Step Guide
This guide will take you through every step needed to complete the process using just your Atlassian stack and current apps, without the need to ask any help from a developer.
Step 1: Access the Groups Attribute Mapping
Where: In the SAML SSO Configuration → Identity Providers tab → Attribute Mappings section,
- Locate the group schemas in the attribute mapping table
- Edit the “Groups” attribute
Step 2: Add the Groovy Code script to automatically assign users to a group
- Change the Source Type to Groovy Code
- Add the following code
username = mapping.ATTR_NAMEID 2extAtr2 = mapping.extensionAttribute2 groups = mapping.'http://schemas.xmlsoap.org/claims/Group' if (extAtr2.getAt(0) == "domain.com/domain/GDI" && username.any {it ==~ /E\d+@.*/} ) {groups.addAll("GDI Internal Users") } return groups
Step 3. Edit the Regular Expressions to override the option to Clear Attribute Values
Since there were some existing transformations in the Regular Expression section, and the “Clear the attribute value“ option was chosen to drop any other group that isn’t returned by AD FS, we needed to add the group that was newly assigned by Groovy to the Regular Expression items as well. Otherwise, the group would be dropped, since it’s not returned by AD FS originally.
- Edit the existing Regular Expressions
- Adding the new group (third item in the screenshot) to include it within the groups that won’t be dropped (because that group is not returned by AD FS originally).
Regular Expression: ^Internal Users$ Replacement: $0
- Finally, save all the settings and the SAML configuration
Conclusion
Every organization has its own specific needs, some more complex than others. Therefore, there is no global solution or standardized setup that can suffice every SAML SSO user’s problems. This is the reason why we equipped our SAML SSO app with a groovy option, as it can be customized in a really simple and effective way. Overall, using Groovy to automate and streamline user group management in Jira and Confluence can save you a significant amount of time and effort, while also reducing the risk of errors.
If you need help or know anybody that needs help with Jira and Confluence groups management, groovy code, IdPs, or User Sync, please get in contact with our support team; they will be happy to help you and find the best solution for your enterprise.
References
Here are the documentation articles for the settings discussed in this guide:
- Creating Groovy Scripts
- Examples of Groovy Scripts
- Configuration guides for resolution’s SAML Single Sign On with Entra (Azure AD)
Spread the word!
This piece is part of a new series that showcases solutions to some of the most challenging problems that our enterprise customers have to face. They are based in real customers, real Atlassian environments, and real implementations, and are written for the technical folks with whom we love to work.
Reach out to us for help with implementing this solution or if you’d like us to cover any specific challenge in this series.
