openstack/openstack-manuals
Code Issues Proposed changes

[config ref] Adding token and federation info

Browse Source 
Also updates patch to include previous accidentally deleted file

Change-Id: I10395567a7c0b810378837665b9aa282633c9f3e
Closes-bug: #1598686
This commit is contained in:
Alexandra 2016-07-19 10:57:23 +01:00 committed by Alexandra Settle
parent 2c0ff4c806
commit 7e1ecdeaef
6 changed files with 602 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/config-reference/source/identity.rst
View File

@ -5,6 +5,9 @@ Identity service
.. toctree:: .. toctree::
identity/options.rst identity/options.rst
identity/token-provider.rst
identity/federated-identity.rst
identity/sample-configuration-files.rst
identity/samples/index.rst identity/samples/index.rst
identity/caching.rst identity/caching.rst
tables/conf-changes/keystone.rst tables/conf-changes/keystone.rst

499
doc/config-reference/source/identity/federated-identity.rst Normal file
View File

@ -0,0 +1,499 @@
==================
Federated Identity
==================
You can use federation for the Identity service (keystone) in two ways:
* Supporting keystone as a :abbr:`SP (Service Provider)`: consuming identity
assertions issued by an external Identity Provider, such as SAML
assertions or OpenID Connect claims.
* Supporting keystone as an :abbr:`IdP (Identity Provider)`: fulfilling
authentication requests on behalf of Service Providers.
.. note::
It is also possible to have one keystone act as an SP that
consumes Identity from another keystone acting as an IdP.
There is currently support for two major federation protocols:
* `SAML <https://en.wikipedia.org/wiki/SAML_2.0>`_
* `OpenID Connect <https://en.wikipedia.org/wiki/OpenID_Connect>`_
.. figure:: figures/keystone-federation.png
:width: 100%
Keystone federation
To enable federation:
#. Run keystone under Apache. See `Configure the Apache HTTP server <http://docs.openstack.org/mitaka/install-guide-obs/keystone-install.html>`_
for more information.
.. note::
Other application servers, such as `nginx <https://www.nginx.com/resources/wiki>`_,
have support for federation extensions that may work but are not tested
by the community.
#. Configure Apache to use a federation capable module.
We recommend Shibboleth, see `the Shibboleth documentation <http://docs.openstack.org/developer/keystone/federation/shibboleth.html>`_
for more information.
.. note::
Another option is ``mod_auth_melon``, see `the mod's github repo <https://github.com/UNINETT/mod_auth_mellon>`_
for more information.
#. Configure federation in keystone.
.. note::
The external IdP is responsible for authenticating users and communicates
the result of authentication to keystone using authentication assertions.
Keystone maps these values to keystone user groups and assignments
created in keystone.
Supporting keystone as a SP
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To have keystone as an SP, you will need to configure
keystone to accept assertions from external IdPs. Examples of external
IdPs are:
* :abbr:`ADFS (Active Directory Federation Services)`
* FreeIPA
* Tivoli Access Manager
* Keystone
Configuring federation in keystone
----------------------------------
#. Configure authentication drivers in ``keystone.conf`` by adding the
authentication methods to the ``[auth]`` section in ``keystone.conf``.
Ensure the names are the same as to the protocol names added via Identity
API v3.
For example:
.. code-block:: ini
[auth]
methods = external,password,token,mapped,openid
.. note::
``mapped`` and ``openid`` are the federation specific drivers.
The other names in the example are not related to federation.
#. Create local keystone groups and assign roles.
.. important::
The keystone requires group-based role assignments to authorize
federated users. The federation mapping engine maps federated users into
local user groups, which are the actors in keystone's role assignments.
#. Create an IdP object in keystone. The object must represent the
IdP you will use to authenticate end users:
.. code:: ini
PUT /OS-FEDERATION/identity_providers/{idp_id}
More configuration information for IdPs can be found `<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#register-an-identity-provider>`_.
#. Add mapping rules:
.. code:: ini
PUT /OS-FEDERATION/mappings/{mapping_id}
More configuration information for mapping rules can be found `<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#create-a-mapping>`_.
.. note::
The only keystone API objects that support mapping are groups and users.
#. Add a protocol object and specify the mapping ID you want to use with the
combination of the IdP and protocol:
.. code:: ini
PUT /OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}
More configuration information for protocols can be found `<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#add-a-protocol-and-attribute-mapping-to-an-identity-provider>`_.
Performing federated authentication
-----------------------------------
#. Authenticate externally and generate an unscoped token in keystone:
.. note::
Unlike other authentication methods in keystone, the user does
not issue an HTTP POST request with authentication data in the request body.
To start federated authentication a user must access the dedicated URL with
IdP's and orotocol’s identifiers stored within a protected URL.
The URL has a format of:
``/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth``.
.. code:: ini
GET/POST /OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth
#. Determine accessible resources. By using the previously returned token, the
user can issue requests to the list projects and domains that are
accessible.
* List projects a federated user can access: GET /OS-FEDERATION/projects
* List domains a federated user can access: GET /OS-FEDERATION/domains
.. code:: ini
GET /OS-FEDERATION/projects
#. Get a scoped token. A federated user can request a scoped token using
the unscoped token. A project or domain can be specified by either ID or
name. An ID is sufficient to uniquely identify a project or domain.
.. code:: ini
POST /auth/tokens
Supporting keystone as an IdP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When acting as an IdP, the primary role of keystone is
to issue assertions about users owned by keystone. This is done using PySAML2.
Configuring federation in keystone
----------------------------------
There are certain settings in ``keystone.conf`` that must be set up, prior
to attempting to federate multiple keystone deployments.
#. Within ``keystone.conf``, assign values to the ``[saml]``
related fields, for example:
.. code:: ini
[saml]
certfile=/etc/keystone/ssl/certs/ca.pem
keyfile=/etc/keystone/ssl/private/cakey.pem
idp_entity_id=https://keystone.example.com/v3/OS-FEDERATION/saml2/idp
idp_sso_endpoint=https://keystone.example.com/v3/OS-FEDERATION/saml2/sso
idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml
#. We recommend the following `Organization` configuration options.
Ensure these values contain not special characters that may cause
problems as part of a URL:
.. code:: ini
idp_organization_name=example_company
idp_organization_display_name=Example Corp.
idp_organization_url=example.com
#. As with the `Organization` options, the `Contact` options are not
necessary, but it is advisable to set these values:
.. code:: ini
idp_contact_company=example_company
idp_contact_name=John
idp_contact_surname=Smith
idp_contact_email=jsmith@example.com
idp_contact_telephone=555-55-5555
idp_contact_type=technical
Generate metadata
-----------------
Metadata must be exchanged to create a trust between the IdP and the SP.
#. Create metadata for your keystone IdP, run the ``keystone-manage`` command
and pipe the output to a file. For example:
.. code:: console
$ keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml
.. note::
The file location must match the value of the ``idp_metadata_path``
configuration option assigned previously.
Create a SP
-----------
To setup keystone-as-a-Service-Provider properly, you will need to
understand what protocols are supported by external IdPs.
For example, keystone as an SP can allow identities to federate in from a
ADFS IdP but it must be configured to understand the SAML v2.0 protocol.
ADFS issues assertions using SAML v2.0. Some examples
of federated protocols include:
* SAML v2.0
* OpenID Connect
The following instructions are an example of how you can configure
keystone as an SP.
#. Create a new SP with an ID of BETA.
#. Create a ``sp_url`` of `<http://beta.example.com/Shibboleth.sso/SAML2/ECP>`_.
#. Create a ``auth_url`` of `<http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth>`_.
.. note::
Use the ``sp_url`` when creating a SAML assertion for BETA and signed by
the current keystone IdP. Use the ``auth_url`` when retrieving the token
for BETA once the SAML assertion is sent.
#. Set the ``enabled`` field to ``true``. It is set to
``false`` by default.
#. Your output should reflect the following example:
.. code:: console
$ curl -s -X PUT \
-H "X-Auth-Token: $OS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"service_provider": {"auth_url": "http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth", "sp_url": "https://example.com:5000/Shibboleth.sso/SAML2/ECP", "enabled": true}}' \
http://localhost:5000/v3/OS-FEDERATION/service_providers/BETA | python -mjson.tool
keystone-to-keystone
~~~~~~~~~~~~~~~~~~~~
Keystone acting as an IdP is known as :abbr:`k2k (keystone-2-keystone)`
or k2k federation, where a keystone somewhere is acting as the SP
and another keystone is acting as the IdP. All IdPs issue
assertions about the identities it owns using a `Protocol`.
Mapping rules
~~~~~~~~~~~~~
Mapping adds a set of rules to map federation attributes to keystone users
or groups. An IdP has exactly one mapping specified per protocol.
A mapping is a translation between assertions provided from an IdP and
the permission and roles applied by an SP. Given an assertion from an IdP, an
SP applies a mapping to translate attributes from the
IdP to known roles. A mapping is typically
owned by an SP.
Mapping objects can be used multiple times by different combinations
of IdP and protocol.
A rule hierarchy is as follows:
.. code:: ini
{
"rules": [
{
"local": [
{
"<user> or <group>"
}
],
"remote": [
{
"<condition>"
}
]
}
]
}
* ``rules``: top-level list of rules.
* ``local``: a rule containing information on what local attributes
will be mapped.
* ``remote``: a rule containing information on what remote attributes will
be mapped.
* ``condition``: contains information on conditions that allow a rule, can
only be set in a remote rule.
For more information on mapping rules, see `<http://docs.openstack.org/developer/keystone/federation/federated_identity.html#mapping-rules>`_.
Mapping creation
----------------
Mapping creation starts with the communication between the IdP and SP.
The IdP usually provides a set of assertions that their users
have in their assertion document. The SP will have to map
those assertions to known groups and roles.
For example:
.. code:: ini
Identity Provider 1:
name: jsmith
groups: hacker
other: <assertion information>
The Service Provider may have 3 groups:
Admin Group
Developer Group
User Group
The mapping created by the Service Provider might look like:
Local:
Group: Developer Group
Remote:
Groups: hackers
The ``Developer Group`` may have a role assignment on the
``Developer Project``. When `jsmith` authenticates against IdP 1, it
presents that assertion to the SP.The SP maps the `jsmith` user to the
``Developer Group`` because the assertion says `jsmith` is a member of
the ``hacker`` group.
Mapping examples
----------------
A bare bones mapping is sufficient if you would like all federated users to
have the same authorization in the SP cloud. However, mapping is
quite powerful and flexible. You can map different remote
users into different user groups in keystone, limited only by the number of
assertions your IdP makes about each user.
A mapping is composed of a list of rules, and each rule is further composed of
a list of remote attributes and a list of local attributes. If a rule is
matched, all of the local attributes are applied in the SP. For a
rule to match, all of the remote attributes it defines must match.
In the base case, a federated user simply needs an assertion containing
an email address to be identified in the SP cloud. To achieve that, only
one rule is needed that requires the presence of one remote attribute:
.. code:: javascript
{
"rules": [
{
"remote": [
{
"type": "Email"
}
],
"local": [
{
"user": {
"name": "{0}"
}
}
]
}
]
}
However, that is not particularly useful as the federated user would receive no
authorization. To rectify it, you can map all federated users with email
addresses into a ``federated-users`` group in the ``default`` domain. All
federated users will then be able to consume whatever role assignments that
user group has already received in keystone:
.. note::
In this example, there is only one rule requiring one remote attribute.
.. code:: javascript
{
"rules": [
{
"remote": [
{
"type": "Email"
}
],
"local": [
{
"user": {
"name": "{0}"
}
},
{
"group": {
"domain": {
"id": "0cd5e9"
},
"name": "federated-users"
}
}
]
}
]
}
This example can be expanded by adding a second rule that conveys
additional authorization to only a subset of federated users. Federated users
with a `title` attribute that matches either ``Manager`` or
``Supervisor`` are granted the hypothetical ``observer`` role, which would
allow them to perform any read-only API call in the cloud:
.. code:: javascript
{
"rules": [
{
"remote": [
{
"type": "Email"
},
],
"local": [
{
"user": {
"name": "{0}"
}
},
{
"group": {
"domain": {
"id": "default"
},
"name": "federated-users"
}
}
]
},
{
"remote": [
{
"type": "Title",
"any_one_of": [".*Manager$", "Supervisor"],
"regex": "true"
},
],
"local": [
{
"group": {
"domain": {
"id": "default"
},
"name": "observers"
}
}
]
}
]
}
.. note::
``any_one_of`` and ``regex`` in the rule above map federated users into
the ``observers`` group when a user's ``Title`` assertion matches any of
the regular expressions specified in the ``any_one_of`` attribute.
Keystone also supports the following:
* ``not_any_of``, matches any assertion that does not include one of
the specified values
* ``blacklist``, matches all assertions of the specified type except
those included in the specified value
* ``whitelist`` does not match any assertion except those listed in the
specified value.

BIN
doc/config-reference/source/identity/figures/keystone-federation.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

2
doc/config-reference/source/identity/figures/keystone-federation.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 5.8 KiB

49
doc/config-reference/source/identity/sample-configuration-files.rst Normal file
View File

@ -0,0 +1,49 @@
===========================================
Identity service sample configuration files
===========================================
The files described in this section are in the ``/etc/keystone`` directory.
keystone.conf
~~~~~~~~~~~~~
Use the ``keystone.conf`` file to configure most Identity service
options:
.. remote-code-block:: ini
https://git.openstack.org/cgit/openstack/keystone/plain/etc/keystone.conf.sample?h=stable/mitaka
keystone-paste.ini
~~~~~~~~~~~~~~~~~~
Use the ``keystone-paste.ini`` file to configure the
:abbr:`WSGI (Web Service Gateway Interface)` middleware pipeline for
the Identity service:
.. remote-code-block:: ini
https://git.openstack.org/cgit/openstack/keystone/plain/etc/keystone-paste.ini?h=stable/mitaka
logging.conf
~~~~~~~~~~~~
You can specify a special logging configuration file in the ``keystone.conf``
configuration file. For example, ``/etc/keystone/logging.conf``.
For details, see the `Python logging module documentation
<http://docs.python.org/2/howto/logging.html#configuring-logging>`__.
.. remote-code-block:: ini
https://git.openstack.org/cgit/openstack/keystone/plain/etc/logging.conf.sample?h=stable/mitaka
policy.json
~~~~~~~~~~~
Use the ``policy.json`` file to define access controls that apply to
the Identity service:
.. remote-code-block:: json
https://git.openstack.org/cgit/openstack/keystone/plain/etc/policy.json?h=stable/mitaka

49
doc/config-reference/source/identity/token-provider.rst Normal file
View File

@ -0,0 +1,49 @@
==============
Token provider
==============
OpenStack Identity supports customizable token providers. This is specified
in the ``[token]`` section of the configuration file. The token provider
controls the token construction, validation, and revocation operations.
You can register your own token provider by configuring the following property:
.. note::
More commonly, you can use this option to change the token provider to one
of the ones built in. Alternatively, you can use it to configure your own
token provider.
* ``provider`` - token provider driver.
Defaults to ``uuid``.
Implemented by :class:`keystone.token.providers.uuid.Provider`. This is the
entry point for the token provider in the ``keystone.token.provider``
namespace.
Each token format uses different technologies to achieve various performance,
scaling, and architectural requirements. The Identity service includes
``fernet``, ``pkiz``, ``pki``, and ``uuid`` token providers.
Below is the detailed list of the token formats:
UUID
``uuid`` tokens must be persisted (using the back end specified in the
``[token] driver`` option), but do not require any extra configuration
or setup.
PKI and PKIZ
``pki`` and ``pkiz`` tokens can be validated offline, without making HTTP
calls to keystone. However, this format requires that certificates be
installed and distributed to facilitate signing tokens and later validating
those signatures.
Fernet
``fernet`` tokens do not need to be persisted at all, but require that you run
``keystone-manage fernet_setup`` (also see the
``keystone-manage fernet_rotate`` command).
.. warning::
UUID, PKI, PKIZ, and Fernet tokens are all bearer tokens. They
must be protected from unnecessary disclosure to prevent unauthorized
access.