Overview

With SAML 4.0, we made mapping IdP attributes easier and more powerful. We added built-in IdP specific transformation presets and common transformations can be chosen with a single click. 
For advanced use cases, we allow adding Groovy scripts that we will develop within support cases.


Highlights

Some of our new features include

  • Strip off email domains without the need for custom regular expressions
  • Convert Azure guest users email addresses to regular email addresses
  • Define alternative attributes if the primary attribute is not sent for some of the users
  • Combine multiple attributes into one
  • Groovy script-based transformers for total control about your transformations


Prerequisites 

In the following section, we will show how to map attributes with SAML 4.0, and how to apply certain transformations. Please note that there are special presets for specific identity providers which you can only see when configuring this type of SAML provider.


This tutorial assumes that you either have an existing configuration or finished the wizard.

After the initial SAML SSO configuration (or if you have an existing configuration), the following steps show you how to use our new attribute mapping.


  1. Go to the SAML SSO configuration and make that you are on the Identity Providers tab.



  2. Scroll down to User Creation and Update and make sure that Update from SAML-Attributes (Just-In-Time Provisioning) is selected.



The the reminder of this tutorial, we will use an AzureAD configuration for simplicity.


Overview


The new attribute mapping has two important parts as marked on the screenshot above. In the following, we will present part 1 and 2.


1 Find user by this attribute

With the Find user by this ... attribute option, you can specify how SAML SSO should search for the user when we try to log in the authenticated user.

With the Add Custom Authentication Attribute option of the dropdown, you can use custom attributes for authentication, e.g. a special attribute that is unique for each user. Please note that most of our installations are fine with the default settings.

Example:

When set to username, we search through all Jira users for the username sent by the identity provider. If we find the user, we log them in.
As you can see in the table, the username is taken from the Name ID of the SAML response (first row in the table).

2 Attribute Mapping Table

The attribute mapping table defines how attributes sent by the identity provider are mapped to attributes of the user of your Atlassian application. For all major identity providers like ADFS, Azure, Okta and GSuite, we have default values for all these field. 


E.g., the username of a user is taken from the Name ID field of the SAML response. The fullname is taken from an attribute called http://schemas.microsoft.com/identity/claims/displayname. The presets are based on our tutorials on this wiki. 


With Edit you change an existing mapping. For system attributes such as username, email and fullname, you can reset the mapping by clicking Clear. For a custom attribute, there is also a Delete button to delete the mapping.

Click Map to an attribute.

With Add New Attribute Mapping, you can add a new mapping for an IdP attribute. 

Depending on the Atlassian product, we have different options that can be mapped:



Presets

Depending on the identity provider, we provide templates to be used to make your life easier. In the best case, you are fine with one of the presets. But, you can still customize the presets or start from scratch

In the screenshot below, you can see the preset for the full name for an AzureAD configuration.

By default, we use the displayname attribute as sent by Azure. You can see how this works by clicking on Show Details.


Transformations

Let's examine the preset for the fullname mapping.



The fullname is taken from a single Azure AD attribute. The Source Attribute Name is name of the attribute as sent via the SAML response. Down below, you can see our standard transformers:

  1. You can use Regular Expression to modify the input.
  2. If the identity provider sends multiple attributes as a single string, you can use the Split Attribute transformer to fix this. E.g. if "A,B,C" is sent, you can define "," as the separator and the result is "A", "B" and "C".
  3. If you need your attribute value in lower case, then use the To Lower Case transformer.
  4. You can also add constant values. E.g. if you map the phone attribute and there is a personal phone number for each user but also a general number which is the same for everyone, you can add this here.


Advanced options for mappings


As you have probably seen, "A single attribute from Azure AD." is not the only possibility you can use attributes:

  1. A single attribute from ... Use a single attribute from the SAML response
  2. Define a list of attributes. The first non-empty value in the list will be used. E.g. for 9 of 10 users, the fullname is sent via attribute 1, but for 1 user, it is sent via attribute 2.
  3. Combine multiple attributes and constants into one value. Allows you to combine the value of multiple attributes into one. E.g., if the first name and last name are sent with two attributes, this allows you to combine them.
  4. Groovy Code. Allows writing custom transformations with the full power of Groovy-based scripting.



A single attribute From ...


Enter the name of the attribute from the SAML response. You can also apply any transformation below.



Define a list of attributes. The first non-empty value in the list will be used


Define a primary and alternatives attributes. The first present value in the SAML response is used. With Add Item you can add as many alternatives as you need.



Combine multiple attributes and constants into one value


This allows to combine multiple attribute values (and constants) to a single value. Use {} to reference the attribute from the SAML response.

In the example below, we use {firstname}, {lastname}. This takes the attribute firstname and lastname from the SAML response and also uses "," as constant. With firstname being John and lastname being Doe, this evaluates to "John, Doe"





Groovy Code


You can also use Groovy code to use and combine any attributes sent by the identity provider. Please contact our support at  https://www.resolution.de/go/support to explore your options with us.

As of now, we have no public documentation for this.