Merge branch 'dblessing_group_saml_assertions' into 'master'

Allow GitLab.com to use the assertion "nickname" and "username" when integrating with SAML

See merge request gitlab-org/gitlab!72134

doc/integration/saml.md

@@ -197,15 +197,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.
@@ -444,7 +442,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
@@ -476,11 +474,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)