Use the OpenRC file for an IdP user

This article explains how to use the OpenStack CLI when your account authenticates through an external Identity Provider (IdP).

Overview

If your OpenStack account is linked to an external Identity Provider, such as the one used for Single Sign-On, you must use the dedicated OpenRC file prepared for federated users.

Unlike a standard OpenRC file, this version does not authenticate with a local OpenStack username and password. Instead, it uses a federated access token, exchanges it through the identity service, obtains an OpenStack token, and then uses that token for further CLI operations.

As a result, the workflow for an IdP user differs from the one used by a regular Keystone user.

Prerequisites

Before you begin, make sure that:

  1. You have access to the cloud through the federated login page.

  2. You have downloaded the OpenRC file intended for IdP users.

  3. The OpenStack CLI client is installed on your machine.

  4. The jq utility is installed on your machine.

  5. You have:

    • the identifier of your Federated Identity Provider,

    • an access token generated by that provider with the required scope.

How this OpenRC file works

The federated OpenRC file performs several steps automatically.

First, it clears previously exported OpenStack environment variables from your shell session. This helps avoid conflicts with credentials from another cloud or project.

Next, it sets the OpenStack authentication endpoint and other required variables, such as the Identity API version, region, protocol, and Identity Provider name.

The script then asks for two values if they are not already present in your environment:

  • OS_FEDERATED_IDP_ID

  • OS_FEDERATED_IDP_TOKEN

The first value identifies the federated identity source. The second is the access token obtained from that provider.

After that, the script sends a token exchange request to the Keycloak token endpoint. From the response, it extracts a bearer token and exports it as OS_ACCESS_TOKEN.

Using that access token, the script authenticates to OpenStack with:

export OS_AUTH_TYPE=v3oidcaccesstoken

Once the authentication succeeds, the script requests an OpenStack token:

openstack token issue

Finally, it stores the resulting Keystone token in OS_TOKEN and switches to:

export OS_AUTH_TYPE=v3token

At that point, your shell session is ready to use standard openstack CLI commands.

Procedure

Step 1. Install required tools

Make sure that both the OpenStack CLI client and jq are installed.

For example, verify them with:

openstack --version
jq --version

Step 2. Download the federated OpenRC file

Download the OpenRC file intended specifically for IdP users from the cloud dashboard or portal.

Make sure you do not use the regular username/password OpenRC file, because the federated workflow requires a different authentication method.

Step 3. Obtain the required federated token

Before sourcing the file, obtain the token required by your Identity Provider workflow.

You need:

  • the Federated Identity Provider ID,

  • the federated access token.

If these values are not already exported in your shell, the script will prompt you to enter them.

Step 4. Source the OpenRC file

Run:

source idp-openrc.sh

Replace idp-openrc.sh with the actual name of your downloaded file.

The script will then:

  • check whether jq is available,

  • prompt for the federated IdP values if needed,

  • exchange the federated token,

  • retrieve an OpenStack token,

  • configure the shell for CLI usage.

Step 5. Verify authentication

After sourcing the file, test the session with:

openstack token issue

If authentication succeeds, the CLI is ready for use.

You can then continue with commands such as:

openstack project show <project-name>
openstack server list
openstack image list

Notes

This OpenRC file is different from a traditional one in several important ways:

  • it does not rely on OS_USERNAME and OS_PASSWORD for authentication,

  • it requires a federated token obtained outside Keystone,

  • it uses v3oidcaccesstoken as an intermediate authentication method,

  • it then switches to v3token after retrieving a Keystone token.

This means that the OpenRC file acts as an authentication helper script rather than only a static list of environment variables.

Troubleshooting

jq is missing

If the script prints a message that jq could not be found, install it first and source the file again.

Token exchange fails

Check that:

  • the Federated Identity Provider ID is correct,

  • the federated token is valid,

  • the token was generated with the required scope,

  • the token has not expired.

OpenStack commands fail after sourcing

Run:

openstack token issue

If this fails, the Keystone token may not have been obtained successfully during the script execution.

Wrong OpenRC file

Make sure that you are using the OpenRC file intended for IdP users, not the standard OpenRC file for local OpenStack credentials.

What to do next

After the federated OpenRC file is loaded successfully, you can continue with standard OpenStack CLI procedures.

For example, you can:

  • list available resources,

  • manage instances, images, and volumes,

  • run automation scripts in the authenticated shell session.

If you need to repeat the procedure later, source the same OpenRC file again and provide a fresh federated token when required.