The options in this tab are used to map user attributes from an Identity Provider to their local profile in the application. The plugin keeps the user’s application in sync with his IdP profile during SSO.
How it works?
The Identity Provider sends user attributes like email, username, first name, and last name in a SAML Response. The default attribute sent in a SAML response is the NameID attribute. Most Identity Providers allow users to choose additional attributes to be sent in the SAML response. This can be configured in the Identity Provider’s admin console. The attribute names received from Identity Provider are mapped to attributes in the user’s profile.
Let us consider a scenario in which we use Okta as an Identity Provider. A SAML response that is not configured will only contain the default NameID attribute. The value of NameID is typically the email with which the user accesses their account on Identity Provider. The Attribute Statements section of the Configure SAML tab can be configured to send more attributes in response. A basic configuration of the Attribute Statements section looks like this :
When a user attempts SSO the SAML response from Okta will contain the user’s first name, last name and email address. These are sent in addition to the default NameID attribute. The content of the response is viewed by clicking the Test Config button in the IdP Configuration tab :
The attribute names displayed in the test configuration window can be mapped to attributes in the application. The detailed procedure to do the same is explained in a later section.
Disable user profile mapping
Checking this option will ensure that the profile attributes of existing users will not be updated whenever they attempt SSO. This will not affect new users. The plugin creates a new user’s profile in the application based on the attributes received in the SAML response.
If this option is set then the user’s profile will only be updated once, after the first successful SSO attempt. The profile of existing users will not be updated, irrespective of the attributes received in a SAML response.
In case a directory is being used to as a user store, this option may need to be checked based on the type of directory permission provided to the application. The recommended setting for each permission :
Read Only or Read Only With Local Groups : With either of these permissions the user’s profile in the directory cannot be updated, so the option should be checked.
Read/Write : This permission allows the user’s profile to be updated. Here there is no restriction for this option. If left unchecked, then the user’s profile in the directory will be updated whenever SSO is performed successfully. If checked, then the user’s profile will be updated only after the first time SSO is performed successfully.
Login via user mail/email
This option is used to identify the users in Atlassian application(Jira/Confluence) based on users attribute received in the SAML response.
For example, you can use the user's username or email or any other attribute for authentication. While this allows user authentication through email, it is recommended that the option be set to username (or any other attribute which is unique for all users) as there is no restriction on the creation of multiple user profiles having the same email attribute.
The plugin allows the updating of the user’s profile in the application with attribute values in the Identity Provider. This is done by mapping the attribute names received in the SAML response to the attributes of the user’s profile.
In order to map attributes from the Identity Provider to the application, the attribute names received in the SAML response need to be entered in their corresponding fields. These attribute names can be viewed by clicking the Test Configuration button in the Configure Identity Provider tab. The plugin will assign the attribute values received in the SAML response to user profile attributes according to the attribute mappings configured.
The user profile attributes that can be configured via attribute mapping are :
Username: The attribute name that corresponds to the username of the user is entered in this field. This is a required field and cannot be left empty. The default attribute name in the field is NameID. There is an option to extract the username from the attribute value of any other attribute name returned in the SAML response. The working of this option is explained in the next section
Email ID: The attribute name with the user’s email as attribute value is entered in this field. This is a required field and cannot be empty. The default attribute name in this field is NameID.
Full Name Attribute: The attribute name that has the user’s full name as value is entered in this field. This field is left blank by default and is not a required field. If the SAML response contains attribute names for the user’s first name and last name separately then there is an option to switch from Full Name Attribute to First Name and Last Name. This option is explained in a later section.
First Name: If the Identity Provider returns the user’s first name in the SAML response, the attribute name that contains the first name value is entered in this field.
Last Name: If the Identity Provider returns the user’s last name in the SAML response, the attribute name that contains the last name value is entered in this field.
Apply regex on username
This option is used if the username value needs to be extracted from any one of the attribute values returned in the SAML response. This option takes a regular expression (or regex) pattern as input. The username value is extracted by applying the regular expression to the value corresponding to the attribute name entered in the Username field.
Let’s consider a case where the username needs to extracted from the user’s email. The attribute name containing the user’s email as value is entered in the Username field and the Apply Regular expression on username field option is checked. The regex **^.*?(?=@)** is entered in the regex field. If the email attribute value received in the SAML response is firstname.lastname@example.org, then the plugin will apply the entered regex on this value and extract abc and this will be set as the username in the user’s profile.
Separate Name Attributes
This option is used to switch between using the Full Name Attribute field or using the First Name and Last Name fields to set the user’s full name in the user profile. This can depend on how the Identity Provider being used returns the user’s full name in the SAML response.
Let’s suppose the response contains one attribute that contains the user’s full name. In this case this option need not be checked and the Full Name Attribute field can be used. But if the response contains two attribute names, one each for first name and last name then the fields First Name and Last Name need to be used. To do this the Separate Name Attributes option needs to be checked. After the option is checked the First Name and Last Name fields will get enabled and the Full Name Attribute field will get disabled.
Configure User Properties (Custom Attributes) **
This option is used to add custom user profile attributes in the application and map these to attribute values received in the SAML response. The custom user attribute can be Phone number, Address, Department etc. The Identity Provider should send custom attributes in a SAML response.
The custom attribute name will be entered in the User Property key field and the attribute name from the SAML response that corresponds to the value of the custom attribute is entered in the Custom Identity Provider Attribute Name field.
** This feature is available in JIRA and Confluence SAML SSO plugin only.