Add username attribute support for GitLab.com Group SAML SSO

Currently GitLab.com Group SAML SSO uses the local part of the
email address to determine the GitLab.com username. This change
will first look for a `username` attribute in the SAML response
and then fall back to the local part of the email address.

Changelog: added
EE: true

doc/integration/saml.md

@@ -196,15 +196,13 @@ For example configurations, see the [notes on specific providers](#providers).
 | Field           | Supported keys |
 |-----------------|----------------|
 | Email (required)| `email`, `mail` |
-| Username        | `username`, `nickname` |
 | Full Name       | `name` |
 | First Name      | `first_name`, `firstname`, `firstName` |
 | Last Name       | `last_name`, `lastname`, `lastName` |
 
-If a username is not specified, the email address is used to generate the GitLab username.
-
-See [`attribute_statements`](#attribute_statements) for examples on how the
-assertions are configured.
+See [`attribute_statements`](#attribute_statements) for examples on how custom
+assertions are configured. This section also describes how to configure custom
+username attributes.
 
 Please refer to [the OmniAuth SAML gem](https://github.com/omniauth/omniauth-saml/blob/master/lib/omniauth/strategies/saml.rb)
 for a full list of supported assertions.
@@ -443,7 +441,7 @@ SAML users has an administrator role.
 You may also bypass the auto sign-in feature by browsing to
 `https://gitlab.example.com/users/sign_in?auto_sign_in=false`.
 
-### `attribute_statements`
+### `attribute_statements` **(FREE SELF)**
 
 NOTE:
 This setting should be used only to map attributes that are part of the OmniAuth
@@ -475,11 +473,10 @@ args: {
 
 #### Set a username
 
-By default, the email in the SAML response is used to automatically generate the
-user's GitLab username. 
+By default, the local part of the email address in the SAML response is used to
+generate the user's GitLab username.
 
-If you'd like to set another attribute as the username, assign it to the `nickname` OmniAuth `info`
-hash attribute, and add the following setting to your configuration file:
+Configure `nickname` in `attribute_statements` to specify one or more attributes that contain a user's desired username:
 
 ```yaml
 args: {

doc/user/group/saml_sso/index.md

@@ -67,9 +67,8 @@ the user details need to be passed to GitLab as SAML assertions.
 
 At a minimum, the user's email address *must* be specified as an assertion named `email` or `mail`.
 See [the assertions list](../../../integration/saml.md#assertions) for other available claims.
-
-NOTE:
-The `username` assertion is not supported for GitLab.com SaaS integrations.
+In addition to the attributes in the linked assertions list, GitLab.com supports `username`
+and `nickname` attributes.
 
 ### Metadata configuration
 
@@ -268,6 +267,9 @@ convert the information to XML. An example SAML response is shown here.
       <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
          <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.email</saml2:AttributeValue>
       </saml2:Attribute>
+      <saml2:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
+        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.nickName</saml2:AttributeValue>
+      </saml2:Attribute>
       <saml2:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
          <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.firstName</saml2:AttributeValue>
       </saml2:Attribute>

ee/app/models/saml_provider.rb

@@ -24,7 +24,8 @@ class SamlProvider < ApplicationRecord
   def settings
     defaults.to_h.merge(
       idp_cert_fingerprint: certificate_fingerprint,
-      idp_sso_target_url: sso_url
+      idp_sso_target_url: sso_url,
+      attribute_statements: { nickname: %w(username nickname) }
     )
   end
 

ee/spec/models/saml_provider_spec.rb

@@ -155,6 +155,10 @@ RSpec.describe SamlProvider do
       expect(settings[:idp_sso_target_url]).to eq saml_provider.sso_url
     end
 
+    it 'includes nickname attribute statements' do
+      expect(settings[:attribute_statements][:nickname]).to match_array(%w(nickname username))
+    end
+
     context 'when saml_message_max_byte_size present in gitlab settings ' do
       before do
         stub_omniauth_setting(saml_message_max_byte_size: 1_000_000)