opentf/website/docs/cli/oci_registries/credentials.mdx

---
description: >-
  Central configuration of credentials for use when interacting with OCI Registries.
---

# 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`](https://github.com/containers/image/blob/22415d4f7ea9cd9ffbfc46bcf919137dabf0c3bb/docs/containers-auth.json.5.md).

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](#default-credentials-configuration).

## Explicit Credentials Configuration

OpenTofu also allows direct configuration of OCI Registry credentials as part of
[the CLI configuration file](../config/config-file.mdx), using `oci_credentials` blocks:

```hcl
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](https://github.com/docker/docker-credential-helpers)
  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](#default-implicit-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](#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](https://docs.docker.com/reference/cli/docker/#credential-store-options)
    in your Docker CLI configuration file.
    :::