Suggested Claim Mapping between Azure AD and Jira
Platform Notice: Data Center - This article applies to Atlassian products on the Data Center platform.
Note that this knowledge base article was created for the Data Center version of the product. Data Center knowledge base articles for non-Data Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
These are only a recommendation based on what we most commonly see and you should work with your Azure Administrator to ensure that everything is aligned with your Organizational Policies and Requirements.
Integrating Jira with Azure AD for Single-Sign-On is usually a straight-forward process, however, the claim mapping between systems can sometimes be tricky. The content below should help you setup a SAML integration with the correct claims being released from Azure AD and mapped in Jira.
You should follow these suggestions if you use the SSO for Atlassian DC app and:
- You are setting up Single-Sign-On in Jira for the first time using Azure AD as your IDP
- You already have Single-Sign-On setup with Azure AD and you see login errors when trying to access Jira
- You would like to enable JIT User Provisioning in Jira and need to reference the right claims to release and map in Jira.
Environment
9.0.0 → 9.15.0+
Claims in Azure AD
In Azure AD, we recommend releasing the following claims:
| Claim in Azure AD | Common URL |
|---|---|
| Name ID | http://schemas.microsoft.com/ws/2005/05/identity/claims/name |
| Given Name | http://schemas.microsoft.com/ws/2005/05/identity/claims/givenname |
| Surname | http://schemas.microsoft.com/ws/2005/05/identity/claims/surname |
| http://schemas.microsoft.com/ws/2005/05/identity/claims/email | |
| Groups | http://schemas.microsoft.com/ws/2008/06/identity/claims/groups |
In Azure, it generally looks like this:
Mapping the Claims in Jira
In Jira, you will navigate to Settings > System > Authentication Methods then select to create a new SAML integration, or edit your existing SAML integration with Azure AD
Then, under the field: Username Mapping, you will want to ensure that it's mapped to Name ID. In most cases, it should look like this:
If you plan to enable JIT provisioning, then click on the checkbox "Create users on login to the application" and add the claims above to the rest of the values listed
Display name should be a combination of givenname and surname:
${http://schemas.microsoft.com/ws/2005/05/identity/claims/givenname} ${http://schemas.microsoft.com/ws/2005/05/identity/claims/surname}Email should be mapped to the email claim:
${http://schemas.microsoft.com/ws/2005/05/identity/claims/email}And groups should be mapped to groups, and you should not use the attribute mapping parameters
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
Testing:
At this point, you are ready to test the authentication flow as both an existing, and new, user. Its recommended that you use a SAML tracer app and enable additional logging in Jira (see: Troubleshooting SAML authentication failures with additional debug logging) to help debug any additional login issue, or adjust the claims based on the data contained within the SAML assertion.