Merge pull request #416 from bajnokk/nameid-example

doc: fix name_id_format vs name_id_policy_format ambiguity

Author: c00kiemon5ter

doc/README.md

@@ -339,15 +339,25 @@ found [here](../example/plugins/backends/saml2_backend.yaml.example).
 
 #### Name ID Format
 
-The SAML backend can indicate which *Name ID* format it wants by specifying the key
-`name_id_format` in the SP entity configuration in the backend plugin configuration:
+The SAML backend has two ways to indicate which *Name ID* format it wants:
+* `name_id_format`: is a list of strings to set the `<NameIDFormat>` element in
+  SP metadata
+* `name_id_policy_format`: is a string to set the `Format` attribute in the
+  `<NameIDPolicy>` element in the authentication request.
+
+The default is to not set any of the above. Note that if the IdP can not
+provide the NameID in a format, which is requested in the `<NameIDPolicy>`, it
+must return an error.
 
  ```yaml
  config:
    sp_config:
      service:
        sp:
-        name_id_format: urn:oasis:names:tc:SAML:2.0:nameid-format:transient
+        name_id_format:
+        - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
+        - urn:oasis:names:tc:SAML:2.0:nameid-format:transient
+        name_id_policy_format: urn:oasis:names:tc:SAML:2.0:nameid-format:transient
  ```
 
 #### Use a discovery service

example/plugins/backends/saml2_backend.yaml.example

@@ -64,8 +64,10 @@ config:
           - [<base_url>/<name>/acs/post, 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST']
           discovery_response:
           - [<base_url>/<name>/disco, 'urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol']
-        name_id_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
-        # A name_id_format of 'None' will cause the authentication request to not
-        # include a Format attribute in the NameIDPolicy.
-        # name_id_format: 'None'
+
+        # name_id_format: a list of strings to set the <NameIDFormat> element in SP metadata
+        # name_id_policy_format: a string to set the Format attribute in the NameIDPolicy element
+        # of the authentication request
+        # name_id_format_allow_create: sets the AllowCreate attribute in the NameIDPolicy element
+        # of the authentication request
         name_id_format_allow_create: true