Skip to main content

OCI Registry Credentials

All of the OpenTofu features which interact with OCI Registries use a centralized mechanism for obtaining credentials to use when making requests.

Default Implicit Behavior​

By default, OpenTofu searches the following locations for "Docker-style" configuration files containing credentials, likely to have been issued by other software that interacts with OCI registries:

  • $XDG_RUNTIME_DIR/containers/auth.json (Linux only)
  • $HOME/.config/containers/auth.json (Windows and macOS only)
  • $XDG_CONFIG_HOME/containers/auth.json (XDG_CONFIG_HOME defaults to $HOME/.config)
  • $HOME/.docker/config.json
  • $HOME/.dockercfg

In these files, OpenTofu expects to find configuration following the format specified in containers-auth.json.

Although you can hand-write these configuration files, the more common way to populate them is to run the "login" command of some other OCI-integrated software, such as docker login, oras login, buildah login, skopeo login, etc. All of those commands write the resulting credentials into one of the file paths listed above.

OpenTofu selects the credentials associated with the pattern that most specifically matches the target repository address. For example, when making a request to a repository at example.com/foo/bar, OpenTofu prefers to use credentials configured for example.com/foo over credentials configured just for example.com.

When there are multiple matching credentials of equal precedence, files earlier in the list above take priority over files later in the list.

You can customize some aspects of this implicit credentials discovery behavior as part of Default Credentials Configuration.

Explicit Credentials Configuration​

OpenTofu also allows direct configuration of OCI Registry credentials as part of the CLI configuration file, using oci_credentials blocks:

Code Block
oci_credentials "example.com" {
  username = "example"
  password = "example"
}

The label of each oci_credentials block must be an OCI registry domain name followed by an optional repository path prefix. For example, example.com matches all repositories on that registry, while example.com/foo only matches repositories whose name starts with a "foo" path segment.

The content of an oci_credentials block has three forms depending on the kind of credentials and how they are specified:

  • Inline username and password: Use username and password arguments to directly specify credentials to use for authentication schemes like HTTP "Basic" authentication.

    When you specify a password directly you must protect your CLI Configuration file to avoid your secret password becoming compromised.

  • Docker-style credential helper: Use the docker_credentials_helper argument to specify the name of a program implementing the Docker Credential Helper protocol, which OpenTofu then launches to obtain credentials only when they are needed.

    For example, if you work on macOS and install the osxkeychain credential helper then you can specify docker_credentials_helper = "osxkeychain" to make OpenTofu obtain credentials from your macOS Keychain.

    OpenTofu currently uses credential helpers only on a read-only basis, so any needed credentials must first be written into the underlying credential store using other software that has been configured to write credentials through the same credential helper.

  • Inline OAuth credentials: Use access_token and refresh_token arguments to directly specify OAuth-style credentials.

    When you specify an access token and refresh token directly you must protect your CLI Configuration file to avoid your tokens becoming compromised.

When multiple oci_credentials blocks are present, OpenTofu selects the one whose block label most closely matches the target repository.

By default, OpenTofu uses explicit oci_credentials blocks in conjunction with any automatically-discovered Docker-style configuration files, taking the most specific match across all of these sources. If the same repository address prefix is specified both in an explicit oci_credentials block and in a Docker-style configuration file then the explicit configuration takes priority.

Default Credentials Configuration​

The optional oci_default_credentials block type can appear at most once in the CLI configuration. When present, it customizes the default implicit search behavior, or disables it entirely.

The following arguments may appear in an oci_default_credentials block:

  • discover_ambient_credentials: Set this to false to completely disable all of the implicit search behavior, in which case only explicit credentials configuration can be used.

    Defaults to true, which allows the implicit search behavior.

  • docker_style_config_files: A list of strings specifying filenames to treat as Docker-style configuration files, instead of the default search locations.

    Set docker_style_config_files = [] to prevent searching for any Docker-style configuration files while still allowing discovery of other "ambient" credentials. Docker-style configuration files are currently the only available ambient credentials mechanism and so this is equivalent to discover_ambient_credentials = false, but that might change in future versions of OpenTofu.

  • docker_credentials_helper: Directly specifies the name of a global Docker-style credentials helper to use for all OCI repositories that are not matched by a more specific credentials configuration.

    For example, specify docker_credentials_helper = "osxkeychain" to make OpenTofu obtain credentials from your macOS Keychain. You must install the selected credential helper first so that OpenTofu can execute it.