Enhance authn sections in federation guide

Modernize the examples on using the CLI to authenticate with an external
IdP or keystone IdP, add tips on how to get needed information, and add
examples on authenticating with horizon.

Partial-bug: #1793374

Change-Id: Ieec899a1551be69da232196c59b9aeed0e85f5f5
This commit is contained in:
Colleen Murphy 2018-12-21 15:48:50 -08:00 committed by Colleen Murphy
parent 94b3ba6310
commit fc3dcc8071
3 changed files with 96 additions and 100 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.1 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 16 KiB

View File

@ -328,109 +328,90 @@ referred to as the ``protocol_id``.
Read more about `federation protocols
<https://developer.openstack.org/api-ref/identity/v3-ext/#protocols>`__
Performing federated authentication
-----------------------------------
Authenticating
--------------
.. NOTE::
Use the CLI to authenticate with a SAML2.0 Identity Provider
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Authentication with keystone-to-keystone federation does not follow these steps.
See `Testing it all out`_ to authenticate with keystone-to-keystone.
.. FIXME(cmurphy): Include examples for OpenID Connect authentication with the CLI
1. Authenticate externally and generate an unscoped token in keystone
2. Determine accessible resources
3. Get a scoped token
The ``python-openstackclient`` can be used to authenticate a federated user in a
SAML Identity Provider to keystone.
Get an unscoped token
.. note::
The SAML Identity Provider must be configured to support the ECP
authentication profile.
To use the CLI tool, you must have the name of the Identity Provider
resource in keystone, the name of the federation protocol configured in
keystone, and the ECP endpoint for the Identity Provider. If you are the cloud
administrator, the name of the Identity Provider and protocol was configured in
`Identity Provider`_ and `Protocol`_ respectively. If you are not the
administrator, you must obtain this information from the administrator.
The ECP endpoint for the Identity Provider can be obtained from its metadata
without involving an administrator. This endpoint is the
``urn:oasis:names:tc:SAML:2.0:bindings:SOAP`` binding in the metadata document:
.. code-block:: console
$ curl -s https://samltest.id/saml/idp | grep urn:oasis:names:tc:SAML:2.0:bindings:SOAP
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://samltest.id/idp/profile/SAML2/SOAP/ECP"/>
~~~~~~~~~~~~~~~~~~~~~
Find available scopes
~~~~~~~~~~~~~~~~~~~~~
Unlike other authentication methods in the Identity Service, 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
Identity Provider's and Protocol's identifiers stored within a protected URL.
The URL has a format of:
``/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth``.
If you are a new user and are not aware of what resources you have access to,
you can use an unscoped query to list the projects or domains you have been
granted a role assignment on:
In this instance we follow a standard SAML2 authentication procedure, that is,
the user will be redirected to the Identity Provider's authentication webpage
and be prompted for credentials. After successfully authenticating the user
will be redirected to the Service Provider's endpoint. If using a web browser,
a token will be returned in JSON format, with the ID in the X-Subject-Token
header.
.. code-block:: bash
In the returned unscoped token, a list of Identity Service groups the user
belongs to will be included.
Read more about `getting an unscoped token
<https://developer.openstack.org/api-ref/identity/v3-ext/#request-an-unscoped-os-federation-token>`__.
~~~~~~~~~~~~
Example cURL
~~~~~~~~~~~~
Note that the request does not include a body. The following url would be
considered protected by ``mod_shib`` and Apache, as such a request made
to the URL would be redirected to the Identity Provider, to start the
SAML authentication procedure.
.. code-block:: console
$ curl -X GET -D - https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/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``
Read more about `listing resources
<https://developer.openstack.org/api-ref/identity/v3-ext/#list-projects-a-federated-user-can-access>`__.
~~~~~~~
Example
~~~~~~~
.. code-block:: console
$ export OS_IDENTITY_API_VERSION=3
$ export OS_TOKEN=<unscoped token>
$ export OS_URL=https://sp.keystone.example.org/v3
$ openstack federation project list
or
.. code-block:: console
$ export OS_IDENTITY_API_VERSION=3
$ export OS_TOKEN=<unscoped token>
$ export OS_URL=https://sp.keystone.example.org/v3
$ openstack federation domain list
export OS_AUTH_TYPE=v3samlpassword
export OS_IDENTITY_PROVIDER=samltest
export OS_IDENTITY_PROVIDER_URL=https://samltest.id/idp/profile/SAML2/SOAP/ECP
export OS_PROTOCOL=saml2
export OS_USERNAME=morty
export OS_PASSWORD=panic
export OS_AUTH_URL=https://sp.keystone.example.org/v3
export OS_IDENTITY_API_VERSION=3
openstack federation project list
openstack federation domain list
~~~~~~~~~~~~~~~~~~
Get a scoped token
~~~~~~~~~~~~~~~~~~
A federated user may request a scoped token, by using the unscoped token. A
project or domain may be specified by either ``id`` or ``name``. An ``id`` is
sufficient to uniquely identify a project or domain.
If you already know the project, domain or system you wish to scope to, you can
directly request a scoped token:
Read more about `getting a scoped token
<https://developer.openstack.org/api-ref/identity/v3-ext/#request-a-scoped-os-federation-token>`__.
.. code-block:: bash
~~~~~~~
Example
~~~~~~~
export OS_AUTH_TYPE=v3samlpassword
export OS_IDENTITY_PROVIDER=samltest
export OS_IDENTITY_PROVIDER_URL=https://samltest.id/idp/profile/SAML2/SOAP/ECP
export OS_PROTOCOL=saml2
export OS_USERNAME=morty
export OS_PASSWORD=panic
export OS_AUTH_URL=https://sp.keystone.example.org/v3
export OS_IDENTITY_API_VERSION=3
export OS_PROJECT_NAME=federated_project
export OS_PROJECT_DOMAIN_NAME=Default
openstack token issue
.. code-block:: console
Use horizon to authenticate with an external Identity Provider
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ export OS_AUTH_TYPE=token
$ export OS_IDENTITY_API_VERSION=3
$ export OS_TOKEN=<unscoped token>
$ export OS_AUTH_URL=https://sp.keystone.example.org/v3
$ export OS_PROJECT_DOMAIN_NAME=federated_domain
$ export OS_PROJECT_NAME=federated_project
$ openstack token issue
When horizon is configured to enable WebSSO, a dropdown menu will appear on the
login screen before the user has authenticated. Select an authentication method
from the menu to be redirected to your Identity Provider for authentication.
.. image:: ../../_static/horizon-login-sp.png
:height: 400px
:alt: Horizon login screen using external authentication
--------------------------------------
Keystone as an Identity Provider (IdP)
@ -555,8 +536,7 @@ a ``sp_url`` of ``https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP`` and
``auth_url`` of ``https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth``
. The ``sp_url`` will be used when creating a SAML assertion for ``mysp`` and
signed by the current keystone IdP. The ``auth_url`` is used to retrieve the
token for ``mysp`` once the SAML assertion is sent. The auth_url has the format
described in `Get an unscoped token`_.
token for ``mysp`` once the SAML assertion is sent.
.. code-block:: console
@ -564,24 +544,40 @@ described in `Get an unscoped token`_.
--service-provider-url 'https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP' \
--auth-url https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth mysp
Testing it all out
------------------
Authenticating
--------------
Use the CLI to authenticate with Keystone-to-Keystone
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use ``python-openstackclient`` to authenticate with the IdP and then get a
scoped token from the SP.
.. NOTE::
ECP stands for Enhanced Client or Proxy, an extension from the SAML2
protocol used in non-browser interfaces, like in the following example.
.. code-block:: console
$ openstack \
--os-service-provider mysp \
--os-remote-project-name federated_project \
--os-remote-project-domain-name federated_domain \
token issue
export OS_USERNAME=demo
export OS_PASSWORD=nomoresecret
export OS_AUTH_URL=https://idp.keystone.example.org/v3
export OS_IDENTITY_API_VERSION=3
export OS_PROJECT_NAME=federated_project
export OS_PROJECT_DOMAIN_NAME=Default
export OS_SERVICE_PROVIDER=keystonesp
export OS_REMOTE_PROJECT_NAME=federated_project
export OS_REMOTE_PROJECT_DOMAIN_NAME=Default
openstack token issue
Use Horizon to switch clouds
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
No additional configuration is necessary to enable horizon for
Keystone to Keystone. Log into the horizon instance for the Identity Provider
using your regular local keystone credentials. Once logged in, you will see a
Service Provider dropdown menu which you can use to switch your dashboard view
to another cloud.
.. image:: ../../_static/horizon-login-idp.png
:height: 175px
:alt: Horizon dropdown menu for switching between keystone providers
.. include:: openidc.rst
.. include:: mellon.rst