SSO with pcdctl

Before you can use pcdctl with a single sign-on (SSO) user, you must first authenticate with Private Cloud Director Identity Service using the user credentials and generate a valid token. This is done by running the saml2pf9 utility, which handles the SSO authentication process and issues the token that pcdctl requires to execute commands on behalf of the authenticated user.

Note

Currently, saml2pf9 is only supported with Microsoft Entra ID as an SSO Identity Provider (IDP).

Step 1: Download the saml2pf9 binary

Bash

sudo curl -shttps://pcdctl.s3.us-west-2.amazonaws.com/saml2pf9 -o /usr/bin/saml2pf9

# To ensure that the downloaded file is executable, run the following command:
sudo chmod +x /usr/bin/saml2pf9

Step 2: Configure SAML authentication for Entra ID

To configure authentication using CLI, execute the command saml2pf9 configure as shown below and follow the prompts to enter the required details. You can obtain the App ID directly from the Microsoft Entra ID Console.

Bash

root@host1:$ saml2pf9 configure

? Please choose a provider: AzureAD

? Please choose an MFA Auto

? PF9 URL https://<DU_FQDN>

? PF9 Tenant Id <Tenant ID>

? Username [email protected]

? IDP IDP1

? App ID <App ID>

Step 3: Generate a token

Now execute the saml2pf9 login command to log in to the identity service and generate a valid token.

Bash

root@host1:$ saml2pf9 login

Using IdP Account default to access AzureAD https://login.microsoftonline.com/04f9ccd0-810f-4516-8bd1-fb51b592b00d/saml2?SAMLRequest=pVJNj9sgFPwrFnfMh%2B0kRnGkdHNopG0bbdIe9rLCGDaoGLw83Db%2FvnayVbeXvfSEBPNm5s2wBtm7QWzHdPYP%2BmXUkLJfvfMgrg8NGqMXQYIF4WWvQSQljttP94LnVAwxpKCCQ9kWQMdkg78LHsZex6OOP6zSXx%2FuG3ROaQBBSJrIcTfi%2BWx1h4N3F1zUBS%2F4IpfDkL9IPKguH5xMJsS%2BzlXoCUAg%2B92BkePZtm1wOp3z%2BW52wcnhy%2FGEst3EaL2cDfyVc%2BHZ%2Bry3KgYIJk1q1usrJS1NrVRH8YpRg8uKLfCq7Rg2bcXaquYtpR2Z9%2Bco2%2B8a9GQMK5elYQu65FouZVEaQ1XJV11VqEKXEwxg1HsPSfrUIE55hekSF%2BzEqCi4KOpHlB1e4%2FpgfWf98%2FvZtjcQiI%2Bn0wHf1vymI1xXnABos54diqtwfNPZ%2B7TyT1Fo83%2B1fNcXmDLVa%2FLGxs3TID5PulNnwVl1ybbOhZ93UcukG8QQ2dxG%2Fv10m98%3D&RelayState=ss%3Amc%3Aa3dfb7b78b22539d4fb081ad27682455419a3d5ee95743d93ae55eafe1e42d06 To use saved password just hit enter.

? Username [email protected]

? Password ********

Authenticating as [email protected] ... 
INFO[0004] [Tenant { Name: service, UUID: 21aded64308c4fbcb43e4fdce4cbc846 } Tenant { Name: tenant2, UUID: 30df56a1356d4868abad66d2b1b8992b }] command=pf9-login Your new access key pair has been stored in the PF9 configuration. Note that it will expire at 2025-08-01 10:32:43 +0000 UTC

After this step, the issued token is stored in a file located at $HOME/.pf9/credentials.

Step 4: Export environment variables

Export the generated token along with other mandatory environment variables by running the following:

This is required before you can run pcdctl commands

Bash

export OS_AUTH_URL=https://pcd-demo.app.pcd.platform9.com/keystone/v3
export OS_AUTH_TYPE=token
export OS_TOKEN=`cat ~/.pf9/credentials | jq -r '.profiles[0].credentials.bearer_token'`
export OS_IDENTITY_API_VERSION=3
export OS_REGION_NAME=region-1
export OS_USER_DOMAIN_NAME=Default
export OS_PROJECT_DOMAIN_NAME=Default
export OS_PROJECT_NAME=service
export OS_INTERFACE=public

Now you should be able to run all pcdctl CLI commands while the token is valid.

Use saml2pf9 with automation

To automate the configuration and authentication

1. Create a file named saml2pf9 in the $HOME/.pf9/ directory.

2. Ensure that the file adheres to the required format outlined below.

When saml2pf9 is used, the system will authenticate using the settings defined in the configuration file.

Bash

root@host1:~$ cat ~/.pf9/saml2pf9

[default]

name = default

app_id = 64c14e40-1af3-4287-9817-096aeec31b52

url = https://pcd-demo.app.pcd.platform9.com

tenant_id = 21aded64308c4fbcb43e4fdce4cbc846

username = [email protected]

provider = AzureAD

domain_IDP = IDP1

mfa = Auto

skip_verify = false

timeout = 0

resource_id =

subdomain =

http_attempts_count =

http_retry_delay =

credentials_file =

saml_cache = false

saml_cache_file =

target_url =

disable_remember_device = false

disable_sessions = false

prompter =

To generate tokens in non-interactive scripts, provide the password as a command-line argument along with the --skip-prompt flag, as shown below:

Bash

saml2pf9 login --password='<your password>' --skip-prompt