openstack
/
keystone
Code Issues Proposed changes

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
This commit is contained in:
Colleen Murphy 2017-08-07 14:17:20 +02:00
parent 9cbd6bc0eb
commit d10908caa9
2 changed files with 87 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
api-ref/source/v3-ext/federation.inc
View File

@ -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.

50
doc/source/advanced-topics/federation/mapping_combinations.rst
View File

@ -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
-------------------