From d10908caa9909b9f178a59551f004a80a722cf2e Mon Sep 17 00:00:00 2001 From: Colleen Murphy Date: Mon, 7 Aug 2017 14:17:20 +0200 Subject: [PATCH] Document required `type` mapping attribute In order for a federated user to be mapped to a local user that exists in the identity backend, the user object in the local mapping rule must have the property "type": "local" set, in addition to having a keystone domain provided. This was probably not the original intention of the local user mapping spec[1], but this is how it ended up being implemented. We could choose to change the behavior of the code, but it has been around long enough that it is possible that deployments are depending on this behavior, and moreover making rules explicit rather than implicit reduces the risk of bugs and mistakes. This patch updates the api-ref documentation and the standard federation documentation to include the "type" property when mapping to local users. In addition, since we now have two keywords called "local" that mean somewhat different things, we expand the context of some of the mapping examples so that both the rule name "local" and the value "local" of the attribute "type" appear in the example, for clarity. Change-Id: Ib35e57e33903de14f9cac1f919c32dfe923ef884 Closes-bug: #1673157 --- api-ref/source/v3-ext/federation.inc | 76 +++++++++++++------ .../federation/mapping_combinations.rst | 50 ++++++++---- 2 files changed, 87 insertions(+), 39 deletions(-) diff --git a/api-ref/source/v3-ext/federation.inc b/api-ref/source/v3-ext/federation.inc index eaf07c1e64..b02f973461 100644 --- a/api-ref/source/v3-ext/federation.inc +++ b/api-ref/source/v3-ext/federation.inc @@ -147,37 +147,53 @@ Required attributes: :: - { - "user": { - "name": "{0}" - } - } + [ + { + "local": [ + { + "user": { + "name": "{0}" + } + } + ], + } + ] If the ``user`` attribute is missing when processing an assertion, server tries to directly map ``REMOTE_USER`` environment variable. If this variable is also unavailable the server returns an HTTP ``401 Unauthorized`` error. - If the ``user`` has domain specified, the user is treated as existing in the - backend, hence the server will fetch user details (id, name, roles, groups). + If the ``user`` has the attribute ``type`` set to ``local`` as well as a + domain specified, the user is treated as existing in the local keystone + backend, and the server will attempt to fetch user details (id, name, roles, + groups) from the identity backend. If, however, the user does not exist in the backend, the server will respond with an appropriate HTTP error code. - If no domain is specified in the local rule, user is deemed ephemeral - and becomes a member of service domain named ``Federated``. + If the ``type`` attribute is not set to ``local`` in the local rule and no + domain is specified, the user is deemed ephemeral and becomes a member of + service identity provider's domain. - An example of user object mapping to an existing user: + An example of user object mapping to an existing local user: :: - { - "user": { - "name": "username" - "domain": { - "name": "domain_name" - } + [ + { + "local": [ + { + "user": { + "name": "username", + "type": "local", + "domain": { + "name": "domain_name" + } + } + } + ], } - } + ] For attribute type and value mapping, identify the local resource type, @@ -185,20 +201,32 @@ Required attributes: :: - { - "group": { - "id": "89678b" + [ + { + "local": [ + { + "group": { + "id": "89678b" + } + } + ], } - } + ] This assigns authorization attributes, by way of role assignments on the specified group, to ephemeral users. :: - { - "group_ids": "{0}" - } + [ + { + "local": [ + { + "group_ids": "{0}" + } + ], + } + ] It is also possible to map multiple groups by providing a list of group ids. Those group ids can also be white/blacklisted. diff --git a/doc/source/advanced-topics/federation/mapping_combinations.rst b/doc/source/advanced-topics/federation/mapping_combinations.rst index d325f9b46f..4ce67fc222 100644 --- a/doc/source/advanced-topics/federation/mapping_combinations.rst +++ b/doc/source/advanced-topics/federation/mapping_combinations.rst @@ -406,6 +406,41 @@ Group ids and names can be provided in the local section: ] } +Users can be mapped to local users that already exist in keystone's identity +backend by setting the ``type`` attribute of the user to ``local`` and providing +the domain to which the local user belongs: + +.. code-block:: json + + { + "local": [ + { + "user": { + "name": "local_user", + "type": "local", + "domain": { + "name": "local_domain" + } + } + } + ] + } + +The user is then treated as existing in the local identity backend, and the +server will attempt to fetch user details (id, name, roles, groups) from the +identity backend. The local user and domain are not generated dynamically, so +if they do not exist in the local identity backend, authentication attempts +will result in a 401 Unauthorized error. + +If you omit the ``type`` attribute or set it to ``ephemeral`` or do not provide a +domain, the user is deemed ephemeral and becomes a member of the identity +provider's domain. It will not be looked up in the local keystone backend, so +all of its attributes must come from the IdP and the mapping rules. + +.. NOTE:: + Domain ``Federated`` is a service domain - it cannot be listed, displayed, + added or deleted. There is no need to perform any operation on it prior to + federation configuration. Output ------ @@ -451,24 +486,9 @@ If a mapping is valid you will receive the following output: ] } -The ``type`` parameter specifies the type of user being mapped. The 2 possible -user types are ``local`` and ``ephemeral``.``local`` is displayed if the user -has a domain specified. The user is treated as existing in the backend, hence -the server will fetch user details (id, name, roles, groups).``ephemeral`` is -displayed for a user that does not exist in the backend. - -The ``id`` parameter in the service domain specifies the domain a user belongs -to. ``Federated`` will be displayed if no domain is specified in the local rule. -User is deemed ephemeral and becomes a member of service domain named ``Federated``. -If the domain is specified the local domain's id will be displayed. If the mapped user is local, mapping engine will discard further group assigning and return set of roles configured for the user. -.. NOTE:: - Domain ``Federated`` is a service domain - it cannot be listed, displayed, - added or deleted. There is no need to perform any operation on it prior to - federation configuration. - Regular Expressions -------------------