Cli Access Cli Saml Auth

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.

1. auto$

2. auto$

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.

Shell

export OS_AUTH_URL="https://hostname>/keystone/v3"
export OS_REGION_NAME="<region>"
export OS_USERNAME="<idp username>"
export OS_PASSWORD="<idp password>"
export OS_TENANT_NAME="<tenant>"
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="<plugin_name>"

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:

Shell

pip install pf9-saml-auth

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

Shell

openstack --os-auth-type v3pf9samladfs \
--os-identity-provider-url  \
--os-service-provider-endpoint  \
--os-service-provider-entity-id

Environment variables

Shell

export OS_IDENTITY_PROVIDER_URL="<idp url>"
export OS_SERVICE_PROVIDER_ENDPOINT="<sp endpoint>"
export OS_SERVICE_PROVIDER_ENTITY_ID="<sp 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

Shell

openstack --os-auth-type v3pf9samlonelogin \
--os-onelogin-client-id \
--os-onelogin-client-secret

Environment variables

Shell

export OS_ONELOGIN_CLIENT_ID="<client id>"
export OS_ONELOGIN_CLIENT_SECRET="<client secret>"

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.

Shell

# Source your authentication credentials
$ source openstack.rc
# Execute the OpenStack interactive CLI
$ openstack

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.

Shell

# 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 [email protected].