hcp iam workload-identity-providers create-cred-file

Command: hcp iam workload-identity-providers create-cred-file

The hcp iam workload-identity-providers create-cred-file command creates a credential file that allow access authenticating to HCP from a variety of external accounts.

The generated credential file contains details on how to obtain the credential from the external identity provider and how to exchange them for an HCP access token.

After creating the credential file, the HCP CLI can be authenticated by the workload by running hcp auth login --cred-file=PATH where PATH is the path to the generated credential file.

Usage

$ hcp iam workload-identity-providers create-cred-file
  WORKLOAD_IDENTITY_PROVIDER_NAME --output-file=PATH [Optional Flags]

Examples

Create a credential file for an AWS workload:

# Set the --imdsv1 flag if the AWS instance metadata service is using version 1.
$ hcp iam workload-identity-providers create-cred-file \
  iam/project/123/service-principal/my-sp/workload-identity-provider/aws \
  --aws \
  --output-file=credentials.json

Create a credential file for a GCP workload:

$ hcp iam workload-identity-providers create-cred-file \
  iam/project/123/service-principal/my-sp/workload-identity-provider/gcp \
  --gcp \
  --output-file=credentials.json

Create a credential file for an Azure workload using a User Managed Identity:

$ hcp iam workload-identity-providers create-cred-file \
  iam/project/123/service-principal/my-sp/workload-identity-provider/azure \
  --azure \
  --azure-resource=MANAGED_IDENTITY_CLIENT_ID \
  --output-file=credentials.json

Create a credential file for an Azure workload that has multiple User Managed Identities:

$ hcp iam workload-identity-providers create-cred-file \
  iam/project/123/service-principal/my-sp/workload-identity-provider/azure \
  --azure \
  --azure-resource=MANAGED_IDENTITY_CLIENT_ID \
  --azure-client-id=MANAGED_IDENTITY_CLIENT_ID \
  --output-file=credentials.json

Create a credential file for an Azure workload that is using a Managed Identity to authenticate as a Entra ID Application:

# ENTRA_ID_APP_ID_URL generally has the form "api://123-456-678-901"
$ hcp iam workload-identity-providers create-cred-file \
  iam/project/123/service-principal/my-sp/workload-identity-provider/azure \
  --azure \
  --azure-resource=ENTRA_ID_APP_ID_URI \
  --azure-client-id=MANAGED_IDENTITY_CLIENT_ID \
  --output-file=credentials.json

Create a credential file that sources the token from a file:

# Assuming the file has the following JSON payload:
# {
#   "access_token": "eyJ0eXAiOiJKV1Qi...",
#   ...
# }
$ hcp iam workload-identity-providers create-cred-file \
  iam/project/123/service-principal/my-sp/workload-identity-provider/k8s \
  --source-file=/var/run/secrets/tokens/hcp_token \
  --source-json-pointer=/access_token \
  --output-file=credentials.json

Create a credential file that sources the token from a file:

# Assuming the file only contains the access token:
$ hcp iam workload-identity-providers create-cred-file \
  iam/project/123/service-principal/my-sp/workload-identity-provider/k8s \
  --source-file \
  --output-file=credentials.json

Create a credential file that sources the token from an URL:

# Assuming the response has the following JSON payload:
# {
#   "access_token": "eyJ0eXAiOiJKV1Qi...",
#   ...
# }
$ hcp iam workload-identity-providers create-cred-file \
  iam/project/123/service-principal/my-sp/workload-identity-provider/example \
  --source-url="https://example-oidc-provider.com/token" \
  --source-json-pointer=/access_token \
  --output-file=credentials.json

Create a credential file that sources the token from an URL:

# Assuming the file only contains the access token:
$ hcp iam workload-identity-providers create-cred-file \
  iam/project/123/service-principal/my-sp/workload-identity-provider/example \
  --source-url=https://example-oidc-provider.com/token \
  --output-file=credentials.json

Create a credential file that sources the token from an URL:

# To add headers to the request, use the --source-header flag:
$ hcp iam workload-identity-providers create-cred-file \
  iam/project/123/service-principal/my-sp/workload-identity-provider/example \
  --source-url=https://example-oidc-provider.com/token \
  --source-header=Metadata=True \
  --source-header=Token=Identity \
  --output-file=credentials.json

Create a credential file that sources the token from an environment variable:

# Assuming the environment variable has the following JSON string value:
# {
#   "access_token": "eyJ0eXAiOiJKV1Qi...",
#   ...
# }
$ hcp iam workload-identity-providers create-cred-file \
  iam/project/123/service-principal/my-sp/workload-identity-provider/example \
  --source-env=ACCESS_TOKEN \
  --source-json-pointer=/access_token \
  --output-file=credentials.json

Create a credential file that sources the token from an environment variable:

# Assuming the environment variable only contains the access token:
$ hcp iam workload-identity-providers create-cred-file \
  iam/project/123/service-principal/my-sp/workload-identity-provider/example \
  --source-env=ACCESS_TOKEN \
  --output-file=credentials.json

Positional arguments

• WORKLOAD_IDENTITY_PROVIDER_NAME - The resource name of the provider for which the external identity will be exchanged against using the credential file.

Required flags

• --output-file=PATH - The path to output the credential file.

Optional flags

• --aws - Set if exchanging an AWS workload identity.

• --azure - Set if exchanging an Azure workload identity.

• --azure-client-id=ID - In the case that the workload has multiple User Assigned Managed Identities, this flag specifies which Client ID should be used to retrieve the Azure identity token.

  If the workload only has one User Assigned Managed Identity, this flag is not required.

• --azure-resource=URI - The Azure Instance Metadata Service (IMDS) allows retrieving an access token for a specific resource. The audience (aud) claim in the returned token is set to the value of the resource parameter. As such, the azure-resource flag must be set to one of the allowed audiences for the Workload Identity Provider.

  The typical values for this flag are:

  • The Client ID of the User Assigned Managed Identity (UUID)
  • The Application ID URI of the Microsoft Entra ID Application (api://123-456-678-901).

  For more details on the resource parameter, see the Azure documentation.

• --gcp - Set if exchanging an GCP workload identity.

  It is assumed the workload identity provider was created with the issuer URI set to https://accounts.google.com and the default allowed audiences.

• --imdsv1 - Set if the AWS instance metadata service is using version 1.

• --source-env=VAR - The environment variable name that contains the credential to exchange.

• --source-file=PATH - Path to file that contains the credential to exchange.

• --source-header=KEY=VALUE [Repeatable] - Headers to send to the URL when obtaining the credential.

• --source-json-pointer=/PATH/TO/CREDENTIAL - A JSON pointer that indicates how to access the credential from a JSON. If used with the source-url flag, the pointer is used to extract the credential from the JSON response from calling the URL. If used with the source-file flag, the pointer is used to extract the credential read from the JSON file. Similarly, if used with the source-env flag, the pointer is used to extract the credential from the environment variable whose value is a JSON object.

  As an example, if the JSON payload containing the credential file is:

  {
    "access_token": "credentials",
    "nested": {
      "access_token": "nested-credentials"
    }
  }
  

  You can access the top level access token using the pointer /access_token and the nested access token can be accessed using the pointer /nested/access_token.

• --source-url=URL - URL to obtain the credential from.