SAML Claims - Sending Groups to Jira from AzureAD

[#1]

No secret, I've been working with AzureAD, Office365 Hybird and running Atlassian tools in Azure for some time.  I've always published my applications via AzureAD Enterprise Apps to ensure Single Sign On.  Sending groups over to Jira and confluence for instance is a bit challenging to do vs ADFS.  Partly because in AzureAD user.group is a restricted claim.   You can however use the application role claim (user.assignedroles) instead.

So, lets get some prerequisites down for this article.

1. Firefox web browser with SAML Tracer -  This nifty tool lets you dive into the saml claim to see what claims are sent and what their values are.

2. Access to AzureAD as an Administrator

3. SAML Single Sign On installed in your application and basically configured following their instructions. I, however I publish my apps as non-gallery applications and use my own custom image tile.   This app holds all the magic to convert the role into jira groups.

4. Read Microsoft's article on Application roles and Modifying the Graph. 

5. A random GUID generator.

6. Access to the Microsoft Graph Explorer website

7. Groups in AD, synced to AzureAD (or directly in AzureAD) to map user rights to.  ie, groups called jira-users, jira-admins, jira-special-role.

Ready?

Ok, there's no real easy way to get this done other than to start beating at it.  We're basically going to follow the Microsoft article and then add the magic Application sauce.

First, In the Azure portal, open up AzureAD and the Enterprise published app for Jira.  We need to copy down the Object ID under Properties.

While we're here, lets take a quick peek at the SAML claims I send to jira as well and prep it by adding the group claim.

Now, lets authenticate to the Graph Explorer website.  Make sure to login, click modify, to modify your permissions and check Directory.AccessAsUser.All, Directory.Read.All, Directory.ReadWrite.All.  Then click the modify permissions button.  

Once logged in, try a query.   Select GET, change Version from 1.0 to beta, enter the following string and click run query.

https://graph.microsoft.com/beta/servicePrincipals

If you're successful, run a new get query using the ObjectID you copied for the Jira published App.

https://graph.microsoft.com/beta/servicePrincipals/<your jira objectID>

If that worked, scroll down in the response preview result.  We're going to patch a section of the code to include the roles. 

Copy the entire block that starts with  "appRoles" into your favorite text editor, like notepad++, for instance.  Add the roles you want to it in notepad.  In this case I'll add Jira-Users and Administrators.  Here's my sample code.  Use the GUID generator to generate random GUIDs to use.  

  {
    "appRoles": [
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "User",
            "displayName": "User",
            "id": "GUID-Don't CHANGE - use the guid given",
            "isEnabled": true,
            "origin": "Application",
            "value": null
        },
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "msiam_access",
            "displayName": "msiam_access",
            "id": "GUID-Don't Change - use the guid given",
            "isEnabled": true,
            "origin": "Application",
            "value": null
        },
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "Administrators Only",
            "displayName": "Admin",
            "id": "<Generate Random Guid and paste here>",
            "isEnabled": true,
            "origin": "ServicePrincipal",
            "value": "Administrator"
        },
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "Jira Users",
            "displayName": "Jira-User",
            "id": "<Generate Random Guid and paste here>",
            "isEnabled": true,
            "origin": "ServicePrincipal",
            "value": "Jira-User"
        }
    ]
}

Ok, note, AzureAD already includes a "user".  However, it is set to pass a null value in the saml claim.  So it's worthless.

Now, take your updated code block and paste it into the graph explorer - under request body (right below the get button).  

Note - watch the brackets.  Make sure you have them like I have them in the sample code.  Remember to place a comma between roles.  The last one does not have a comma.   If you go back to add more roles, always add roles to the bottom, or you'll get errors.

Change get to Patch and click run query.

I change back to get and run a query again to verify the roles are added.

Great! you've updated the Graph.   Give it a few minutes to reflect in AzureAD.  You might need to click F5 to refresh the AzureAD page.

Now then, Let's go into the Jira Enterprise App in Azure AD and add the AD Groups and add the new roles to the app.

Almost there...

Open an icognito window with firefox, click the little yellow saml icon in the upper left to open the trace window and login to your jira instance with your AzureAD/Office365 credentials.

Check the SAML trace, you'll see the little bubble for saml, click it and click the saml tab.  You'll see the claims.   Make sure your groups are there.

Now the magic.

Go into the Resolution SAML Module and scroll down to groups.  Create the custom mapping.  

And there you go AD Groups in Jira (or Confluence or whatever).  Test your login again and see if your groups passed correctly.

If you caught on, you're probably correct, I could have just called the role the exact Jira Security group name and skipped the mapping.   That's all hindsight at this point, but a good recommendation for you to think about.

Enjoy.

[Daniel Eads]

This is great! The simplest use of SAML is to get Single Sign On with a larger stack of applications (if you're not using Crowd) and to secure the authentication process if you're using LDAP instead of LDAPS. Adding groups into the SAML claim means that you can likely just drop the AD User Directory and get the user "sync" when they log in and send a claim to Jira.

[Gregory Van Den Ham]

Correct, we tie to azuread to gain the benefits of MFA.   All of our saml apps live there.  We also use azuread instead of adfs since there is zero footprint required.  An ha environment of adfs requires 4 systems and 2 load balancers.   So it’s cheaper and you gain multi factor auth.   Win win.   

[Alex Kummer]

Hi Gregory, great article!  Do you need to update the Manifest for the Web App in App registrations?

[Cameron Gocke]

@Gregory Van Den Ham I'm wondering if anything has changed with the functionality of how this works.  We have SAML setup and working and have "Atlassian Access" and are using the Atlassian Cloud app from the Azure Enterprise App catalog, which has provisioning setup to sync Users and Groups.  This seems to work well, but has the disadvantage that Group changes only happen at the frequency with which the provisioning schedule runs.  I would _rather_ use the SAML claims so that Group/role changes take effect each time the person signs in, even for new users.  I've verifed I see the "Group" come through in my SAML claims, but it seems to have no effect on what groups the user is assigned to in Atlassian.

I opened a support case with Atlassian, but they kept referring me to the Group sync that happens during provisioning, so I'm not sure they were familiar with the use of the SAML claims.

Does this approach no longer work, or is there some combination of factors that is simply not working for me?

[Gregory Van Den Ham]

Hi Cameron, I have not looked into cloud for this.  In this case I used Resolution's Saml Signon Marketplace add-on.  This technique I've documented for server and data center use.

It is however good to push Atlassian to take saml claims as its much quicker to allow saml provisioning and rights update management through that claims process.