website/docs/cli/oci_registries/credentials.mdx
All of the OpenTofu features which interact with OCI Registries use a centralized mechanism for obtaining credentials to use when making requests.
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/.dockercfgIn 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.
OpenTofu also allows direct configuration of OCI Registry credentials as part of
the CLI configuration file, using oci_credentials blocks:
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.
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.
:::note OpenTofu does not use any credential helper unless explicitly configured to do so.
Docker CLI and some other more-closely-related software default to searching certain hard-coded credential helper names depending on your platform when no credential helper is configured and no static credentials are available.
To avoid executing third-party software without explicit consent, OpenTofu
instead requires that you directly configure any credential helper you
intend to use, either by using this OpenTofu-specific setting or by
using
the "credsStore" property
in your Docker CLI configuration file.
:::