From 0c1873da1f280d4921b9c9b3da9126388d75e701 Mon Sep 17 00:00:00 2001
From: Ivan Kanakarakis <ivan.kanak@gmail.com>
Date: Tue, 7 Jul 2020 13:38:39 +0300
Subject: Differentiate between metadata NameIDFormat and AuthnRequest
 NameIDPolicy Format

The `name_id_format` configuration option is used to define

1. the value of the `<NameIDFormat>` metadata element
2. and the value of the `<NameIDPolicy>` `Format` attribute in an `AuthnRequest`

The configuration option to set what the value of `<NameIDFormat>` element is in the
metadata should be different from the configuration option to specify what should be
requested in an `AuthnRequest` through the `<NameIDPolicy Format="...">` attribute.

Introduce a new option (`name_id_policy_format`), or use the same name but scoped in a
specific section for metadata and AuthnRequest.

On the side of this, pysaml2 defaults to _transient_ as the `<NameIDPolicy
Format="...">` attribute value. To omit requesting a value for the `<NameIDPolicy
Format="">` attribute the value `"None"` (a string) must be set in the configuration.
This is unintuitive. It is better to be explicit and set transient to request a
transient NameID, than not setting a value and requesting transient by default. If no
value is set, no specific `<NameIDPolicy Format="...">` should be requested.

- Refactor the name_id_format usage
- Add name_id_policy_format configuration option
- Remove the "None" convention value

Signed-off-by: Ivan Kanakarakis <ivan.kanak@gmail.com>
---
 docs/howto/config.rst | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/howto/config.rst b/docs/howto/config.rst
index 70bd1bd5..6e2bb635 100644
--- a/docs/howto/config.rst
+++ b/docs/howto/config.rst
@@ -536,10 +536,26 @@ Example::
     }
 
 
+name_id_policy_format
+"""""""""""""""""""""
+
+A string value that will be used to set the ``Format`` attribute of the
+``<NameIDPolicy>`` element of an ``<AuthnRequest>``.
+
+Example::
+
+    "service": {
+        "sp": {
+            "name_id_policy_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
+        }
+    }
+
+
 name_id_format_allow_create
 """""""""""""""""""""""""""
 
-Enable AllowCreate in NameIDPolicy.
+A boolean value (``True`` or ``False``) that will be used to set the ``AllowCreate``
+attribute of the ``<NameIDPolicy>`` element of an ``<AuthnRequest>``.
 
 Example::
 
@@ -550,6 +566,24 @@ Example::
     }
 
 
+name_id_format
+""""""""""""""
+
+A list of string values that will be used to set the ``<NameIDFormat>`` element of the
+metadata of an entity.
+
+Example::
+
+    "service": {
+        "idp": {
+            "name_id_format": [
+                "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
+                "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
+            ]
+        }
+    }
+
+
 allow_unsolicited
 """""""""""""""""
 
-- 
cgit v1.2.1