Skip to content

Latest commit

 

History

History
180 lines (108 loc) · 7.76 KB

configuring-the-deploy-cli.md

File metadata and controls

180 lines (108 loc) · 7.76 KB
Raw

Configuring the Deploy CLI

Configuring the Deploy’s CLI is essential for establishing Auth0 credentials as well as generally modifying the behavior of the tool to your specific needs. There are two ways the Deploy CLI can be configured:

  • Configuration file (config.json)
  • Environment variables

Configuration file

A standalone JSON file can be used to configure Deploy CLI. This file will usually reside in the root directory of your project and be called config.json.

Example config.json file:

{
  "AUTH0_DOMAIN": "<YOUR_TENANT_DOMAIN>",
  "AUTH0_CLIENT_ID": "<YOUR_CLIENT_ID>",
  "AUTH0_ALLOW_DELETE": false
}

⚠️ NOTE: Hard-coding credentials is not recommended, and risks secret leakage should this file ever be committed to a public version control system. Instead, passing credentials as environment variables is considered best practice.

Environment variables

By default, the Deploy CLI ingests environment variables, providing the ability to pass credentials and other configurations to the tool without needing to publish to the config.json file. Environment variables can either be used to augment the config.json file or replace it altogether depending on the project needs.

Non-primitive configuration values like AUTH0_KEYWORD_REPLACE_MAPPINGS and AUTH0_EXCLUDED can also be passed in through environment variables so long as these values are properly serialized JSON.

To disable the consumption of environment variables for either the import or export commands, pass the --env=false argument.

Examples

# Deploying configuration for YAML formats without a config.json file
export AUTH0_DOMAIN=<YOUR_AUTH0_DOMAIN>
export AUTH0_CLIENT_ID=<YOUR_CLIENT_ID>
export AUTH0_CLIENT_SECRET=<YOUR_CLIENT_SECRET>

a0deploy import --input_file=local/tenant.yaml

# Disable environment variable ingestion
a0deploy export -c=config.json --format=yaml --output_folder=local --env=false

# Non-primitive configuration values
export AUTH0_EXCLUDED='["actions","organizations"]'
export AUTH0_KEYWORD_REPLACE_MAPPINGS='{"ENVIRONMENT":"dev"}'
a0deploy export -c=config.json --format=yaml --output_folder=local

Free Tier

Certain Auth0 resources require a paid plan with a verified credit card on file to manage. On free tier tenants, logStreams need to be excluded in config.json. You can also exclude customDomains, if you don't want to add credit card information.

"AUTH0_EXCLUDED": ["logStreams", "customDomains"]

Available Configuration Properties

AUTH0_DOMAIN

String. The domain of the target Auth0 tenant.

AUTH0_CLIENT_ID

String. The ID of the designated Auth0 application used to make API requests.

AUTH0_CLIENT_SECRET

String. The secret of the designated Auth0 application used to make API requests.

AUTH0_ACCESS_TOKEN

String. Short-lived access token for Management API from designated Auth0 application. Can be used in replacement to client ID and client secret combination.

AUTH0_CLIENT_SIGNING_KEY_PATH

String. The path to the private key used by the client when facilitating Private Key JWT authentication. Path relative to the working directory. Also note AUTH0_CLIENT_SIGNING_ALGORITHM for specifying signing algorithm.

AUTH0_CLIENT_SIGNING_ALGORITHM

String. Specifies the JWT signing algorithms used by the client when facilitating Private Key JWT authentication. Only used in combination with AUTH0_CLIENT_SIGNING_KEY_PATH. Accepted values: RS256, RS384, PS256.

AUTH0_ALLOW_DELETE

Boolean. When enabled, will allow the tool to delete resources. Default: false.

AUTH0_EXCLUDED

Array of strings. Excludes entire resource types from being managed, bi-directionally. See also: excluding resources from management. Possible values: actions, attackProtection, branding, clientGrants, clients, connections, customDomains, databases, emailProvider, emailTemplates, guardianFactorProviders, guardianFactorTemplates, guardianFactors, guardianPhoneFactorMessageTypes, guardianPhoneFactorSelectedProvider, guardianPolicies, logStreams, migrations, organizations, pages, prompts, resourceServers, roles, tenant, triggers.

Cannot be used simultaneously with AUTH0_INCLUDED_ONLY.

Example

{
  "AUTH0_EXCLUDED": ["organizations", "connections", "hooks"]
}

AUTH0_INCLUDED_ONLY

Array of strings. Dictates which resource types to only manage, bi-directionally. See also: excluding resources from management. Possible values: actions, attackProtection, branding, clientGrants, clients, connections, customDomains, databases, emailProvider, emailTemplates, guardianFactorProviders, guardianFactorTemplates, guardianFactors, guardianPhoneFactorMessageTypes, guardianPhoneFactorSelectedProvider, guardianPolicies, logStreams, migrations, organizations, pages, prompts, resourceServers, roles, tenant, triggers

Example

{
  "AUTH0_INCLUDED_ONLY": ["clients", "connections", "tenant", "branding"]
}

Cannot be used simultaneously with AUTH0_EXCLUDED.

AUTH0_KEYWORD_REPLACE_MAPPINGS

Mapping of specific keywords to facilities dynamic replacement. See also: keyword replacement.

Example

{
  "ENVIRONMENT": "DEV",
  "ALLOWED_ORIGINS": ["https://dev.test-site.com", "localhost"]
}

AUTH0_PRESERVE_KEYWORDS

Boolean. When enabled, will attempt to preserve keyword replacement markers in local resource files during export. Otherwise, the remote values will overwrite those manually-placed keyword markers.

This configuration requires the presence of local configuration files and defined keyword replace mappings via the AUTH0_KEYWORD_REPLACE_MAPPINGS configuration property.

See also: Preserving Keywords on Export.

AUTH0_EXPORT_IDENTIFIERS

Boolean. When enabled, will return identifiers of all resources. May be useful for certain debugging or record-keeping scenarios within a single-tenant context. Default: false.

EXCLUDED_PROPS

Provides ability to exclude any unwanted properties from management.

Example

{
  "connections": ["options.twilio_token"]
}

AUTH0_AUDIENCE

String. Separate value from audience value while retrieving an access token for management API. Useful when default Management API endpoints are not publicly exposed.

AUTH0_EXCLUDED_RULES

Array of strings. Excludes the management of specific rules by ID. Note: This configuration may be subject to deprecation in the future. See: excluding resources from management.

AUTH0_EXCLUDED_CLIENTS

Array of strings. Excludes the management of specific clients by name. Note: This configuration may be subject to deprecation in the future. See: excluding resources from management.

AUTH0_EXCLUDED_DATABASES

Array of strings. Excludes the management of specific databases by name. Note: This configuration may be subject to deprecation in the future. See: excluding resources from management.

AUTH0_EXCLUDED_CONNECTIONS

Array of strings. Excludes the management of specific connections by name. Note: This configuration may be subject to deprecation in the future. See: excluding resources from management.

AUTH0_EXCLUDED_RESOURCE_SERVERS

Array of strings. Excludes the management of specific resource servers by name. Note: This configuration may be subject to deprecation in the future. See: excluding resources from management.

[table of contents]