Using OpenStack CLI with SAML authentication
This tutorial describes how to utilize the OpenStack CLI (Command Line Interface) clients with SAML single-sign on user credentials.
Platform9 managed OpenStack supports integration with federated identity management systems that implement the Security Assertion Markup Language (SAML) standard. OpenStack's CLI tools provide authentication plugins which enable authentication against SAML identity providers (IdP) supporting the Enhanced Client or Proxy (ECP) standard.
Before we begin you must have the following installed & configured.
- OpenStack CLI clients
- OpenStack Keystone preconfigured with SAML federation
Step 1: Create an OpenStack RC file
The OpenStack RC file captures the configuration parameters necessary for the OpenStack CLIs to communicate with the REST API endpoints exposed by your OpenStack services. An example file for Platform9 managed OpenStack is below.
Copy and save this into a new file (e.g., openstack.rc).
(Remember to secure the file since it contains the password to login to your private cloud.)
Step 2: Select your authentication plugin
OS_AUTH_TYPE is the name of the driver plugin you are using for authentication.
The SAML authentication plugin bundled with the OpenStack CLI is called v3samlpassword works with identity providers supporting SAML ECP. Skip to Step 3 if your IdP supports ECP.
The SAML ECP standard is relatively new, and has yet to see major adoption amongst many commercial SSO providers. To help bridge this gap, Platform9 has written Keystone authentication plugins which add support for the following identity providers:
Detailed information about these plugins & installation instructions may be found on GitHub at github.com/platform9/pf9-saml-auth.
If you require these plugins, they can easily be installed using Python Pip. Simply run:
Additional requirements for AD FS auth plugin
The AD FS authentication plugin utilizes WS-Federation / WS-Trust 1.3 to obtain a SAML 1.0 assertion. Both AD FS & Platform9 utilize different endpoints when receiving WS-Fed assertions. You must manually specify these endpoints before utilizing the plugin. For example, on Platform9 these would be:
Identity Provider URL: https://ADFS HOSTNAME/adfs/services/trust/13/usernamemixed Service Provider Endpoint: https://PF9 hostname/Shibboleth.sso/ADFS Service Provider Entity ID: https://PF9 hostname/keystone
Once you have this information you will need to provide them to the AD FS authentication plugin as either arguments to the OpenStack CLI utility, or environment variables in your OpenStack RC file.
Additional requirements for OneLogin auth plugin
Platform9's OneLogin authentication plugin leverages the OneLogin API to programmatically authenticate a user, and obtain a SAML assertion. OneLogin requires users to first authenticate with their API & obtain an OAuth token before generating a SAML assertion (or issuing any API call).
You must first obtain API credentials from your OneLogin administrator before you may utilize this authentication plugin. Refer to OneLogin's Working with API credentials documentation for more information on creating the necessary API credentials.
Once you have these credentials you will need to provide them to the OneLogin authentication plugin as either arguments to the OpenStack CLI utility, or environment variables in your OpenStack RC file.
Tip: For more information on discovering installed authentication plugins & their configuration options, please check out this excellent blog post by Jamie Lennox, Loading Authentication Plugins.
Step 3: Authenticate & access the OpenStack CLI
Once you have selected your authentication plugin, and updated your OpenStack RC with the necessary authentication parameters you are ready to use the CLI with SAML authentication.
Then, execute one of the available CLI commands such as "server list". The OpenStack client with attempt to authenticate with your IdP using the supplied credentials, and obtain a SAML assertion. If successful, it will pass this assertion to OpenStack which will issue a Keystone token, and then fulfill your API request.
You have now successfully configured the OpenStack client to authenticate to your cloud using SAML authentication.
If you experience issues using the Platform9-developed SAML auth drivers, contact us at email@example.com.
January 23, 2017