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.
Prerequisites
Before we begin you must have the following installed & configured.
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.
[bash]export OS_AUTH_URL=”https://hostname>/keystone/v3″export OS_REGION_NAME=”
export OS_USERNAME=”
export OS_PASSWORD=”
export OS_TENANT_NAME=”
export OS_PROJECT_DOMAIN_ID=${OS_PROJECT_DOMAIN_ID:-“default”}
export OS_IDENTITY_API_VERSION=3
export OS_IDENTITY_PROVIDER=${OS_IDENTITY_PROVIDER:-“IDP1”}
export OS_PROTOCOL=saml2
export OS_AUTH_TYPE=[/bash]
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:
| Identity Provider | Plugin |
|---|---|
| Microsoft ADFS | v3pf9samladfs |
| Okta | v3pf9samlokta |
| OneLogin | v3pf9samlonelogin |
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:
[bash]pip install pf9-saml-auth[/bash]
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.
CLI arguments
[bash]openstack –os-auth-type v3pf9samladfs \–os-identity-provider-url \
–os-service-provider-endpoint \
–os-service-provider-entity-id [/bash]
Environment variables
[bash]export OS_IDENTITY_PROVIDER_URL=”export OS_SERVICE_PROVIDER_ENDPOINT=”
export OS_SERVICE_PROVIDER_ENTITY_ID=”
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.
CLI arguments
[bash]openstack –os-auth-type v3pf9samlonelogin \–os-onelogin-client-id \
–os-onelogin-client-secret [/bash]
Environment variables
[bash]export OS_ONELOGIN_CLIENT_ID=”export OS_ONELOGIN_CLIENT_SECRET=”
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.
[bash]# Source your authentication credentials$ source openstack.rc
# Execute the OpenStack interactive CLI
$ openstack[/bash]
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.
# List available servers
(openstack) server list
Conclusion
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 support@platform9.com.