The options in this tab are used to map user attributes from an Identity Provider to the Application’s local directory. The plugin updates the user’s profile in the application’s local directory with the user’s attributes in the Identity Provider. The profile is updated after SSO is performed successfully.
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 Configure Identity Provider 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.
Each SSO attempt generates a SAML request. The plugin sends this request to the Identity Provider. The Identity Provider sends a response that contains all the user’s attributes. The user’s profile is updated with the attributes received in the SAML response to the latest SSO attempt. 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 Application user account by
This option gives the choice to use either the user’s username or email for authentication. If username is selected, then the plugin authenticates the user based on the username received in the response. If email is selected then authentication is done based on email received in the response.
This tab provides options to set the username and email attributes of a user’s profile according to the values received in a SAML response. Any user attempting SSO can be authenticated using either the username or the email address in the user’s profile.
While this allows user authentication through email, it is recommended that the option be set to username as there is no restriction on the creation of multiple user profiles having the same email attribute.
As mentioned earlier, 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. The fields for entering the attribute names are loaded with some default values. The Username and Email fields are mapped to the default SAML 2.0 attribute NameID. Irrespective of whether the SAML response from Identity Provider is configured to have additional attributes, the NameID attribute will always be returned. The fields for full name, first name and last name are left empty.
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.
Consider the earlier example of using Okta as an Identity Provider. Let’s assume we want the user’s email attribute value in Okta to be the username in the application user profile. We need to enter the attribute name, i.e. email, in the field for username. This way we can map other attribute names returned by the Identity Provider to attributes in the application. Now, when a SAML response is received the plugin will take the attribute values corresponding to the mapped attribute names and assign them to the respective user profile attributes.
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 Regular expression on username field
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.
If the username needs to be extracted from one of the attribute values, the corresponding attribute name is entered in the Username field. Then the check box for this option is checked. Once this is checked, the section to enter a regex and test it is displayed. Enter the regex in the field provided. If you need to check the output of the regex, click on the Test Regex button. This will open a new window, where you can enter a value in the field provided. Click the Test button to apply the given regex to the entered value. The extracted value is displayed in the same window next to the input 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.
To add Custom Attributes to the user’s profile in the application, first click the Add Attributes button in the Configure User Properties section in the tab. This will display two fields, one for the custom attribute name and one for the attribute name from the 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.