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.

  1. OpenStack CLI clients
  2. 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.

[bash]export OS_AUTH_URL=”https://hostname>/keystone/v3″
export OS_USERNAME=”
export OS_PASSWORD=”

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 ProviderPlugin
Microsoft ADFSv3pf9samladfs

Detailed information about these plugins & installation instructions may be found on GitHub at

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


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=”
“[/bash] 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.

[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


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

The browser you are using is outdated. For the best experience please download or update your browser to one of the following: