HOWTO: Using a SAML assertion attribute as the product username

Default behavior

SAML assertion is a document issued and signed by the Identity Provider that contains authentication details. When a SAML-enabled application processes a SAML assertion, by default it uses NameID to determine the username of the user that is logging in.

<samlp:Response>
...
    <saml:Assertion>
        <saml:Subject>
            <saml:NameID>jira_user</saml:NameID>
...

Using SAML assertion attribute as the username

For some Identity Provider configurations, the username for the product might be contained in the Attribute element of the assertion instead of NameID.

<samlp:Response>
    <saml:Assertion>
...
		<saml:AttributeStatement>
    		<saml:Attribute Name="username">
        		<saml:AttributeValue>jira_user</saml:AttributeValue>
    		</saml:Attribute>
...

Procedure

1. Configure all other settings using the "SSO 2.0" admin screen
2. Click Save configuration.
3. In a terminal, run the following command to send the REST request:

curl -H "Content-Type: application/json" -X PUT -d '{"user-attribute":"<USERNAME_ATTRIBUTE>"}' \
-u <USERNAME>:<PASSWORD> <BASE_URL>/rest/authconfig/1.0/saml

Replacing the USERNAME_ATTRIBUTE with the name of the attribute from the SAML assertion to use as the application username.

The BASE URL should be the base URL for the instance, USERNAME and PASSWORD should be the administrator credentials.

If successful you will get a JSON response, containing the user-attribute field with the value you configured.

Reverting to defaults

To revert the configuration change, issue the following command in the terminal:

curl -H "Content-Type: application/json" -X PUT -d '{"user-attribute":null}' \
-u <USERNAME>:<PASSWORD> <BASE_URL>/rest/authconfig/1.0/saml