The Attributes coming from the SAML Identity Provider can be transformed using Groovy-scripts.

The same transformations also work in UserSync-connector. There may be slight differences between SAML-attributes and Connector-attributes that are described below. 

Migration

General Information

General information about Groovy can be found here: https://groovy-lang.org/documentation.html

In the IdP's Attribute Mapping configuration, select Groovy Code as the Source type and you can enter the script code:

h

Logging

There is an SLF4j-logger available as logger:

will occur in the logs log this:

StructuredData

The incoming data is represented as StructuredData (see ReTransform APIDocs). 

StructuredData allows representing hierarchical data structures in a simplified way.

A StructuredData-object is either MapStructuredData, ListStructuredData or StringStructuredData

MapStructuredData behaves like a Map with Strings as keys and StructuredData as values (in fact, it implements Map<String,StructuredData>).

ListStructuredData implements List<StructuredData>.

StringStructuredData behaves like a String (at least mostly) and encapsulates a String-value.

When comparing another value to a StringStructuredData, this other value is converted to a String (using Java's String.valueOf()-method) and compared to the encapsulated value.

This has the effect that when comparing it to a numeric value, a lexicographical comparison happens.

When StructuredData is created from JSON using StructuredData.parseJson(jsonString), the jsonString is parsed using Groovy's JsonSluper (see https://docs.groovy-lang.org/latest/html/gapi/groovy/json/JsonSlurper.html) and all values are converted to Strings using String.valueOf()

Comparing StructuredData with Strings

With this data:

the value "Erwin" is available under con.name. But as this Object is if type StringStructuredData and not String, comparing it to a String could produce unexpected results:

Access attribute values

SAML

The Groovy Script's binding (in a Groovy-script, the Binding is the set of the Script's variables) contains a MapStructuredData-object mapping which is containing the attributes.

When transforming attributes from the SAML Identity Provider in the SAML SingleSignOn-configuration, the attributes are ListStructuredData-Objects (because the SAML-assertions contain a value list for each attribute).

Here you can see an example. 

After a successful login, the following info is sent in the SAML response.

Above you see the SAML Assertion which contains the attributes att1, att2, and att3 as well as the NameID value. These attributes are transformed into ListStructuredData-Objects as shown below. This is a log excerpt that came from the logger.warn(asJson(mapping)) statement explained earlier.

The SAML NameID-value can be accessed under the special attribute ATTR_NAMEID.

This expression returns the SAML NameID:

In case the attribute contains special characters it needs to be enclosed in '':

Returning data

The value returned from the script is used as the value for the mapped attribute. Some conversion automatically happens:

• If the returned value is a list, all entries are converted to Strings. This conversion is done using String.valueOf() (see https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html)

• If the returned value is not a list, it is converted to a String and added as a single attribute to a list.

In a Groovy-Script, the last statement's result is returned automatically, so 

can just be written as

In our example above we returned the attribute att1 for the Jira user property attribute demo.

There are some special values that can be returned. DROP, EMPTY, and DROP_ALL. 

Remove the attribute

If the script returns null or the special value EMPTY, the attribute on an existing user is removed.

Taking the example above the IdP now sends the following attributes in the SAML response. 

Att1 is not present anymore but it is still mapped to the Jira attribute Demo.

When the user now logs in via SAML with the attributes att12, att2, and att3 being sent by the IdP an empty list will be returned for the Jira Attribute Demo. If the script returns null, the attribute on an existing user is removed.

You can also return the special value EMPTY which has the same effect.

The attribute is removed from the user's profile page.

Ignore an attribute

If the script returns the special value DROP, the mapped attribute is not used to create or update the user. If an existing user already has this attribute, it is kept as it is.

We are doing the same test as in the previous section. Att1 was there before and updated the user's profile page.

The user logs in again via SAML but this time the attribute att1 is again not present.

When you now check the attribute transformations in the Tracker you see the "drop" is now true for this Jira attribute. 

This means the attribute remains unchanged for the user. 

Filter the user

If a user should be filtered, return the special value DROP_ALL.

UserSync

When transforming attributes in a UserSync-connector, mapping contains three MapStructuredData-Objects:

• The data delivered from the Connector is available under con. The structure depends on the Connector.

• If there is an existing user to be updated, this user's attributes are available under existing

• If the connector is called during a SAML-authentication (because the update-method "update from Usersync-Connector" is configured for the IdP), the data from the SAML assertion is available under saml

Load another user

It's possible to load data from another user during the transformation. A possible use case for this is to store relationships between users, e.G. who the manager of the synced user is.

There are some helper method to be used in the script:

These methods return the user-key as String or null of no user is found:

findUserKeyByUsername(username) loads the user-key by the given username. This returns null if there is no user with that username. This may happen if the user to be found is not synced yet.

findUserKeyByEmail(email)  loads the user-key by the given email-address. This returns null if there is no user with that username. This may happen if the user to be found is not synced yet. The transformation will fail if the email-address is not unique.

findUserKey(attribute_name,attributeValue) loads the user-key by another attribute

These method return a Map<String,Set<String>> with all attributes:

findUser(attribute_name,attributeValue)

Special Implementation - Distinguish whether a user has logged into the JSM portal or into Jira

In SAML 5 we have implemented an additional attribute ATTR_SD_CUSTOMER. This attribute is not coming from the IdP but is set to "true" or "false" depending on the relative URL used by the user to sign into Jira.

To use the attribute you first need to add a new User Property in the Attribute mapping table of the Identity Provider tab.

Set the Jira attribute name and click Next

Enter the name of the attribute in the SAML response and click Apply

When you now log in you will see this value being returned in the SAML response based on whether the user logs in as a service desk customer or a regular user. In the example below the user logged in as a regular user. 

Migrate Groovy-Transformations from version 4.x

The way to write transformation-scripts has changed with SAML 5.0. "old-style"-script should still work, but we strongly recommend to update them to the new way.

Attributes are available without mapping-prefix

The attributes are accessible directly in the script's Binding, so e.g. instead of mapping.ATTR_NAMEID you can write ATTR_NAMEID

Return value instead of setting mapping.groovyResult

Instead of setting mapping.groovyResult = <valueToSet>, just return the value. It is no longer necessary to create a list for this value. 

Return DROP_ALL instead of setting mapping.drop = true

When a user should be dropped, return the predefined variable DROP_ALL instead of setting mapping.drop = true