Browse Source

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
tags/15.0.0.0rc1
Colleen Murphy 1 year ago
committed by Colleen Murphy
parent
commit
fc3dcc8071
3 changed files with 91 additions and 95 deletions
  1. BIN
      doc/source/_static/horizon-login-idp.png
  2. BIN
      doc/source/_static/horizon-login-sp.png
  3. +91
    -95
      doc/source/admin/federation/configure_federation.rst

BIN
doc/source/_static/horizon-login-idp.png View File

Before After
Width: 239  |  Height: 132  |  Size: 6.1 KiB

BIN
doc/source/_static/horizon-login-sp.png View File

Before After
Width: 432  |  Height: 446  |  Size: 16 KiB

+ 91
- 95
doc/source/admin/federation/configure_federation.rst 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
-----------------------------------

.. NOTE::

Authentication with keystone-to-keystone federation does not follow these steps.
See `Testing it all out`_ to authenticate with keystone-to-keystone.
Authenticating
--------------

1. Authenticate externally and generate an unscoped token in keystone
2. Determine accessible resources
3. Get a scoped token
Use the CLI to authenticate with a SAML2.0 Identity Provider
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get an unscoped token
~~~~~~~~~~~~~~~~~~~~~

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``.
.. FIXME(cmurphy): Include examples for OpenID Connect authentication with the CLI

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.
The ``python-openstackclient`` can be used to authenticate a federated user in a
SAML Identity Provider to keystone.

In the returned unscoped token, a list of Identity Service groups the user
belongs to will be included.
.. note::

Read more about `getting an unscoped token
<https://developer.openstack.org/api-ref/identity/v3-ext/#request-an-unscoped-os-federation-token>`__.
The SAML Identity Provider must be configured to support the ECP
authentication profile.

~~~~~~~~~~~~
Example cURL
~~~~~~~~~~~~
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.

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.
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 -X GET -D - https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth

Determine accessible resources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ 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"/>

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
~~~~~~~~~~~~~~~~~~~~~
Find available scopes
~~~~~~~~~~~~~~~~~~~~~

or
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:

.. code-block:: console
.. code-block:: bash

$ 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.

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


Loading…
Cancel
Save