Authenticating Cloud Foundry CLI Tools
When administrating Cloud Foundry you spent quite some time on the shell leveraging various different CLI tools. Of course, all the different tools require you to authenticate differently to their backends, leaving you struggling to remember the correct way to authenticate. This blog post summarizes the authentication procedure for the most common CLI tools in the Cloud Foundry ecosystem.
The examples in this blog post are tailored to Pivotal Cloud Foundry (PCF). However, other Cloud Foundry distributions are very similar and the concepts are also applicable. On PCF you can find all of the below credentials in the OpsManager user interface in different tiles. This blog post shows how to access these credentials programmatically.
OM Tool Login
om is a CLI tool for the OpsManager API. It is very useful and provides a very convenient way to access the OpsManager tooling and configuration from the CLI.
To be able to execute any commands with om you need to provide the API target and credentials via CLI parameters. It is a common practice to export these to environment variables:
# you may put these into ~/cfenv.sh for convenient access
export OM_API="https://<OPS_MANAGER_FQDN>"
export OM_USER="<USER>"
export OM_PASSWORD="<PASSWORD>"
# executing om now boils down to
om -t $OM_API -u $OM_USER -p $OM_PASSWORD ...
BOSH CLI v1 Login
Given you are on any OpsManager VM of PCF <= 1.11.x you need to use BOSH CLI v1 (you may check your version with bosh -v).
With BOSH CLI v1 you need to target the director and then login:
# if your SSL certificate is trusted then simply:
bosh target <DIRECTOR_URL>
# otherwise explicitly define the certificate. On PCF OpsMan the default location is:
bosh --ca-cert /var/tempest/workspaces/default/root_ca_certificate target <DIRECTOR_URL>
# then login with:
bosh login <USERNAME> <PASSWORD>
In PCF, the username is usually director.
You may retrieve the credentials from the OpsManager API with the following om command:
om -t $OM_API -u $OM_USER -p $OM_PASSWORD -k curl -p /api/v0/deployed/director/credentials/director_credentials
BOSH CLI v2 Login
BOSH CLI v2 is a complete rewrite in Go (instead of Ruby as is BOSH CLI v1) and with the rewrite also a lot of the commands changed. Starting with PCF 1.11 the new BOSH CLI v2 is available on the OpsManager. The new CLI heavily supports environment variables to configure the authentication, which we will also be leveraging:
# you may put these into ~/cfenv.sh for convenient access
export BOSH_CLIENT=ops_manager
export BOSH_CLIENT_SECRET=<BOSH_CLIENT_SECRET>
export BOSH_CA_CERT=/var/tempest/workspaces/default/root_ca_certificate
export BOSH_ENVIRONMENT=<BOSH_DIRECTOR_FQDN>
You can extract the BOSH_CLIENT_SECRET for the ops_manager user from the following credential using om:
om -t $OM_API -u $OM_USER -p $OM_PASSWORD -k curl -p /api/v0/deployed/director/credentials/bosh_commandline_credentials
After setting the four environment variables you are authenticated when issuing commands with the CLI. Give it a try:
. ~/cfenv.sh
bosh deployments
Note: On PCF 1.12 you must use
bosh2instead ofboshfor full functionality. To not accidentally use BOSH CLI v1, simply addalias bosh=bosh2to your~/cfenv.shfile. BOSH CLI v1 is removed as of PCF 2.0 and the CLI v2 is then accessible withboshagain.
BOSH Director VM Login
Sometimes it might be necessary to SSH directly to the BOSH director VM. The credentials to do that are also accessible through the OpsManager API:
om -t $OM_API -u $OM_USER -p $OM_PASSWORD -k curl -p /api/v0/deployed/director/credentials/vm_credentials
# now connect with
ssh vcap@<OPS_MANAGER>
Starting with PCF 1.12 you may retrieve the BOSH director IP with the bosh_commandline_credentials in the $BOSH_ENVIRONMENT variable:
om -t $OM_API -u $OM_USER -p $OM_PASSWORD -k curl -p /api/v0/deployed/director/credentials/bosh_commandline_credentials
UAA Admin Login
UAA is the User Account and Authentication server, which is used to manage the users of a Cloud Foundry foundation.
There is a separate UAA in place for the BOSH director itself.
Both UAA instances can be used from the uaac CLI tool which needs to be installed as Ruby gem.
On the OpsManager VM the uaac tool should be preinstalled (you may check with uaac --version).
UAA Admin Login for OpsManager UAA
The OpsManager UAA manages access to the BOSH deployment and should only contain users concerned with administrating a BOSH installation. In a PCF installation, you can setup the UAA admin context as follows:
$ uaac target https://YOUR_OPSMAN_IP/uaa
$ uaac token owner get
Client name: opsman
Client secret:
User name: <UAA_ADMIN_USER>
Password: <UAA_ADMIN_PASSWORD>
$ uaac context
For UAA_ADMIN_USER and UAA_ADMIN_PASSWORD you may use the credentials you use to login to OpsManager itself.
If you don't want to use the OpsManager admin account you may use any UAA client that has the scope uaa.admin.
UAA Admin Login for CF
Cloud Foundry has a dedicated UAA instance to authenticate all users of the platform. Especially to create custom functional users (e.g. deployment users) with a special setup that is not supported by the CF UI it is necessary to access the UAA via CLI. It is also helpful to debug problems with LDAP / SAML integrations and the local user storage. To login to the CF UAA you need to first obtain the admin client credentials:
om -t $OM_API -u $OM_USER -p $OM_PASSWORD -k curl -p /api/v0/deployed/products/<CF_GUID>/credentials/.uaa.admin_client_credentials
Once you have the credentials you can authenticate with:
$ uaac target https://uaa.<CF_SYSTEM_DOMAIN>/
$ uaac token client get
Client ID: <UAA_ADMIN_CLIENT_ID>
Client secret: <UAA_ADMIN_CLIENT_SECRET>
$ uaac context
UAA Access Token
From time to time you may need the UAA access token itself.
The command uaac context shows the access token of the current session and some additional information.
You can extract the access token for scripting purposes from the current UAA context with the following line:
uaac context | grep -Po '(?<=access_token: ).*'
CF CLI Admin Login
The cf command line is used to access the Cloud Controller API and use Cloud Foundry.
By default, the CF CLI is not installed on the OpsManager VM and you may install the CF CLI by following the guide in the GitHub repository.
Alternatively, you may download a CF CLI binary from the link in the sidebar of Pivotal Apps Manager.
Next, you need to fetch the admin credentials for the CF CLI and then login:
# fetch CF CLI credentials
om -t $OM_API -u $OM_USER -p $OM_PASSWORD -k curl -p /api/v0/deployed/products/<CF_GUID>/credentials/.uaa.admin_credentials
# target CF API
cf api https://api.<CF_SYSTEM_DOMAIN>/
# and now login with
cf login
Use pcfup to Automate Logins
At mimacom we help a lot of customers manage their Cloud Foundry foundations. As retrieving credentials and authenticating with all the different tools has become a tedious task, we wrote pcfup to automate Cloud Foundry operations tasks. pcfup is easy to install, can download all the tools mentioned above and then extract the credentials for you:
# get pcfup and download tools
./pcfup download-tools
# show the most important credentials for PCF admins
./pcfup credentials
Conclusion
The Cloud Foundry eco-system has a lot of tools and credentials. It's hard to keep track where these credentials are and how the tools work with them. With the Cloud Foundry Credhub integration credentials will also frequently change in the future and change their location. If some of the above commands don't work anymore or you have other tools or authentication commands you frequently use feel free to leave a comment below this blog post.