Credential Consumer Identities

This page is the technical reference for credential consumer identities — the key-value maps OCM uses to look up credentials for a given operation. For a high-level introduction, see Credential System.

For the credential types that go in the credentials: field of each consumer entry, see Reference: Credential Types.

Overview

Every time OCM needs credentials (accessing a registry, signing a component version), it constructs a **lookup identity ** — a map of string attributes describing what it needs credentials for. The credential system then searches configured consumers for a matching entry.

A consumer entry in .ocmconfig looks like this:

type: generic.config.ocm.software/v1
configurations:
  - type: credentials.config.ocm.software
    consumers:
      - identity:
          type: <identity-type>
          # ... type-specific attributes
        credentials:
          - type: Credentials/v1
            properties:
            # ... key-value credential properties

The consumer identity type is extensible — any string in Name or Name/Version format can be used. Plugins and integrations can introduce additional types (e.g. AWSSecretsManager, HashiCorpVault, MavenRepository). The following types are defined by the core OCM modules:

Identity Type	Used For
`OCIRegistry`	Authenticating against OCI registries
`HelmChartRepository`	Authenticating against Helm chart repositories
`RSA/v1alpha1`	Providing signing and verification keys

OCIRegistry

Used when OCM accesses an OCI registry — pushing, pulling, or resolving component versions and resources.

Identity Attributes

Attribute	Required	Description
`type`	Yes	Must be `OCIRegistry`
`hostname`	Yes	Registry hostname (e.g. `ghcr.io`, `registry.example.com`)
`path`	No	Repository path. Supports glob patterns (`*` matches one path segment). If omitted, matches any path on the hostname.
`scheme`	No	URL scheme (`https`, `http`, `oci`). If omitted, matches any scheme. If set, must match exactly.
`port`	No	Port number as string. Default ports are applied when `scheme` is set: `https` and `oci` default to `443`, `http` defaults to `80`.

Credential Properties

Property	Description
`username`	Username for basic authentication
`password`	Password for basic authentication
`accessToken`	Bearer token sent directly to the registry (Docker token flow)
`refreshToken`	OAuth2 refresh token exchanged for an access token before each request

Token fields take precedence over username/password when both are present. Use OCICredentials/v1 for the full typed field reference.

Matching Behavior

Matching runs three chained checks — all must pass:

Path matcher — compares path using path.Match (glob). * matches one segment, not across /. If the configured entry has no path, any request path is accepted.
URL matcher — compares scheme, hostname, and port. Applies default ports when a scheme is present ( https → 443, http → 80).
Equality matcher — all remaining attributes (like type) must be exactly equal.

For detailed matching examples and edge cases, see Tutorial: Understand Credential Resolution.

Examples

Hostname only — matches all paths on ghcr.io:

- identity:
    type: OCIRegistry
    hostname: ghcr.io
  credentials:
    - type: OCICredentials/v1
      username: my-user
      password: ghp_token

Hostname + path glob — matches any single-segment path under my-org/:

- identity:
    type: OCIRegistry
    hostname: ghcr.io
    path: my-org/*
  credentials:
    - type: OCICredentials/v1
      username: org-user
      password: ghp_org_token

Hostname + scheme + port — matches only HTTPS on a custom port:

- identity:
    type: OCIRegistry
    hostname: registry.internal
    scheme: https
    port: "8443"
  credentials:
    - type: OCICredentials/v1
      username: internal-user
      password: internal_pass

HelmChartRepository

Used when OCM accesses a remote Helm chart repository — pulling or resolving Helm charts referenced as resources. The identity is derived from the Helm repository URL using the same URL-based attributes as OCIRegistry.

Identity Attributes

Attribute	Required	Description
`type`	Yes	Must be `HelmChartRepository`
`hostname`	Yes	Repository hostname (e.g. `charts.example.com`, `registry.example.com`)
`path`	No	Repository path (e.g. `stable`). If omitted, matches any path on the hostname.
`scheme`	No	URL scheme (`https`, `http`, `oci`). If omitted, matches any scheme.
`port`	No	Port number as string. If omitted, matches any port.

Credential Properties

Property	Description
`username`	Repository username
`password`	Repository password or token

Examples

HTTPS Helm repository:

- identity:
    type: HelmChartRepository
    hostname: charts.example.com
    path: stable
  credentials:
    - type: HelmHTTPCredentials/v1
      username: helm-user
      password: helm-token

OCI-based Helm repository:

- identity:
    type: HelmChartRepository
    hostname: registry.example.com
    scheme: oci
  credentials:
    - type: OCICredentials/v1
      username: registry-user
      password: registry-token

RSA/v1alpha1

Used when OCM signs or verifies component versions with RSA keys.

Identity Attributes

Attribute	Required	Description
`type`	Yes	Must be `RSA/v1alpha1`
`algorithm`	Yes	Signing algorithm. Must be `RSASSA-PSS` (recommended) or `RSASSA-PKCS1-V1_5`.
`signature`	Yes	Logical signature name (e.g. `default`). Must match the `--signature` flag used with `ocm sign cv`. Defaults to `default` if not specified on the CLI.

All three attributes are required. When OCM looks up signing credentials, it always constructs a lookup identity with type, algorithm, and signature. If your consumer entry omits algorithm, the credential system will not find a match — even though the signing algorithm defaults to RSASSA-PSS internally.

If you are unsure which algorithm to use, specify algorithm: RSASSA-PSS.

Credential Properties

Property	Used For	Description
`privateKeyPEM`	Signing	Inline PEM-encoded private key
`privateKeyPEMFile`	Signing	Path to PEM-encoded private key file
`publicKeyPEM`	Verification	Inline PEM-encoded public key
`publicKeyPEMFile`	Verification	Path to PEM-encoded public key file

You can specify both privateKeyPEMFile and publicKeyPEMFile in the same entry to use it for both signing and verification.

When using the legacy Credentials/v1 properties: map instead of RSACredentials/v1, the old snake_case keys (private_key_pem, private_key_pem_file, public_key_pem, public_key_pem_file) are still accepted as a deprecated backward-compatibility fallback.

Matching Behavior

Unlike OCI identities, RSA signing identities use strict equality matching — every attribute in the lookup identity must be present in the configured consumer identity with the exact same value. There is no glob or subset matching.

Examples

Signing and verification with default settings:

- identity:
    type: RSA/v1alpha1
    algorithm: RSASSA-PSS
    signature: default
  credentials:
    - type: RSACredentials/v1
      privateKeyPEMFile: /path/to/private-key.pem
      publicKeyPEMFile: /path/to/public-key.pem

Multiple signature identities (e.g. dev and prod):

- identity:
    type: RSA/v1alpha1
    algorithm: RSASSA-PSS
    signature: dev
  credentials:
    - type: RSACredentials/v1
      privateKeyPEMFile: /path/to/dev/private-key.pem
      publicKeyPEMFile: /path/to/dev/public-key.pem
- identity:
    type: RSA/v1alpha1
    algorithm: RSASSA-PSS
    signature: prod
  credentials:
    - type: RSACredentials/v1
      privateKeyPEMFile: /path/to/prod/private-key.pem
      publicKeyPEMFile: /path/to/prod/public-key.pem

Sign with a specific identity:

ocm sign cv --signature dev <component-version>
ocm sign cv --signature prod <component-version>

Using PKCS#1 v1.5 algorithm:

- identity:
    type: RSA/v1alpha1
    algorithm: RSASSA-PKCS1-V1_5
    signature: legacy
  credentials:
    - type: RSACredentials/v1
      privateKeyPEMFile: /path/to/private-key.pem

Complete Configuration Example

A single .ocmconfig combining registry credentials (with Docker fallback) and signing credentials:

type: generic.config.ocm.software/v1
configurations:
  - type: credentials.config.ocm.software
    consumers:
      # OCI registry — hostname catch-all
      - identity:
          type: OCIRegistry
          hostname: ghcr.io
        credentials:
          - type: OCICredentials/v1
            username: my-user
            password: ghp_token
      # RSA signing — default signature
      - identity:
          type: RSA/v1alpha1
          algorithm: RSASSA-PSS
          signature: default
        credentials:
          - type: RSACredentials/v1
            privateKeyPEMFile: /path/to/private-key.pem
            publicKeyPEMFile: /path/to/public-key.pem
    # Docker config fallback for registries not matched above
    repositories:
      - repository:
          type: DockerConfig/v1
          dockerConfigFile: "~/.docker/config.json"

Discovering Credential Types at Runtime

Use ocm describe types credentials to list all credential types registered in your OCM installation — including any added by installed plugins — and ocm describe types credentials <type> to inspect the fields of a specific type.

Concept: Credential System — How the credential system works
Reference: Credential Types — All built-in typed credential types and their fields
Tutorial: Understand Credential Resolution — Step-by-step matching examples for OCI registries
How-To: Configure Credentials for Multiple Registries — Task-oriented registry credential setup
How-To: Configure Credentials for Signing — Task-oriented signing credential setup

Configure Credentials for Multiple Registries

Resource

Credential Consumer Identities

Overview#

OCIRegistry#

Identity Attributes#

Credential Properties#

Matching Behavior#

Examples#

HelmChartRepository#

Identity Attributes#

Credential Properties#

Examples#

RSA/v1alpha1#

Identity Attributes#

Credential Properties#

Matching Behavior#

Examples#

Complete Configuration Example#

Discovering Credential Types at Runtime#

Related Documentation#

Overview

OCIRegistry

Identity Attributes

Credential Properties

Matching Behavior

Examples

HelmChartRepository

Identity Attributes

Credential Properties

Examples

RSA/v1alpha1

Identity Attributes

Credential Properties

Matching Behavior

Examples

Complete Configuration Example

Discovering Credential Types at Runtime

Related Documentation