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:

OCIRegistry#

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

Identity Attributes#

Credential Properties#

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:

1. 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.
2. URL matcher — compares scheme, hostname, and port. Applies default ports when a scheme is present ( https → 443, http → 80).
3. 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#

Credential Properties#

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

Wget#

Used when OCM fetches a resource over plain HTTP or HTTPS through the Wget/v1 access type and the Wget/v1 input type. The identity is derived from the resource url; the access type and the input type derive it identically, so a single consumer entry covers both.

Identity Attributes#

Example derivation: for url: https://downloads.example.com/myapp/1.0.0/myapp.tar.gz, the lookup identity is:

The URL carries no explicit port, so no port attribute is derived. Default ports stay implicit in the identity and are applied by the URL matcher instead, so this identity matches a consumer entry with port: "443" as well as one with no port at all. A URL that names its port (https://downloads.example.com:8443/...) does derive port: "8443".

Credential Properties#

Use WgetCredentials/v1 for the typed field reference.

Basic Auth and a bearer token both set the Authorization header and are therefore mutually exclusive. When both are configured, the bearer token wins and a warning is logged. The mutual TLS certificate is a transport-layer credential and combines with either of them, but it only takes effect during a TLS handshake: supplying one for an http:// URL logs a warning and has no effect.

Matching Behavior#

The same three chained checks as OCIRegistry apply: path glob, URL (scheme, hostname, port with default-port handling), then exact equality on the remaining attributes.

Examples#

Hostname only. Matches every download from that host:

- identity:
    type: Wget
    hostname: downloads.example.com
  credentials:
    - type: WgetCredentials/v1
      username: download-user
      password: download-token

Bearer token for a single path segment (matches artifacts/build.zip, not artifacts/ci/build.zip):

- identity:
    type: Wget
    hostname: api.example.com
    scheme: https
    path: artifacts/*
  credentials:
    - type: WgetCredentials/v1
      identityToken: eyJhbGciOi...

Mutual TLS against an internal server:

- identity:
    type: Wget
    hostname: artifacts.internal
    scheme: https
    port: "8443"
  credentials:
    - type: WgetCredentials/v1
      certificate: |
        -----BEGIN CERTIFICATE-----
        MIIDdzCCAl+gAwIBAgIEbGVnYWw...
        -----END CERTIFICATE-----
      privateKey: |
        -----BEGIN PRIVATE KEY-----
        MIIEvQIBADANBgkqhkiG9w0BAQ...
        -----END PRIVATE KEY-----
      certificateAuthority: |
        -----BEGIN CERTIFICATE-----
        MIIDQTCCAimgAwIBAgITBmyf...
        -----END CERTIFICATE-----

For migrating a Wget consumer entry from OCM v1, covering the renamed identity type, the pathprefix to path conversion, and the inverted authentication precedence, see Tutorial: Work with HTTP Resources.

S3#

Used when OCM reads an object from an S3 or S3-compatible bucket. This applies to the S3/v2 access type and to the S3/v2 input type. OCM derives the identity from bucketName, objectKey and the optional endpoint. The access type and the input type derive it the same way, so one consumer entry covers both.

Credentials are optional. If no consumer entry matches, OCM gives no credentials to the AWS SDK. The SDK then uses its default credential chain:

• the environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN
• the shared AWS config files
• IAM instance roles and task roles

Use this path for in-cluster and CI setups. Short-lived role credentials are safer than static keys in .ocmconfig.

Identity Attributes#

Example derivation (AWS S3). An access or input specification sets bucketName: acme-artifacts and objectKey: datasets/reference/1.0.0/reference.parquet, and sets no endpoint. OCM derives this lookup identity:

Example derivation (S3-compatible store). Add endpoint: https://minio.internal:9000. The endpoint supplies the URL attributes. The path still names the object:

region, mediaType, version and usePathStyle take no part in credential resolution.

Credential Properties#

Use S3Credentials/v1 for the typed field reference.

If an entry sets none of the three properties, OCM treats it as no credentials, and the AWS default credential chain applies. If an entry sets any of them, OCM passes the entry to the AWS SDK unchanged. An incomplete pair therefore fails in the SDK. It does not fall back to the default chain.

Matching Behavior#

The same three chained checks as OCIRegistry apply:

1. Glob match on the path.
2. URL match on scheme, hostname and port, with default-port handling.
3. Exact match on the remaining attributes.

Two results of this are specific to S3:

• Do not set hostname in an AWS entry. The matcher compares hostnames for equality, and an AWS lookup identity has no hostname. An entry with hostname: s3.amazonaws.com therefore never matches. Scope AWS entries by path, or do not scope them at all.
• * does not cross /. Most object keys contain slashes. path: acme-artifacts/* matches acme-artifacts/build.zip, but it does not match acme-artifacts/datasets/reference.parquet. To cover a whole bucket, write the full depth (acme-artifacts/*/*/*), or omit path and scope the entry another way.

Examples#

All objects in every bucket. Use this form when one account owns everything that OCM reads:

- identity:
    type: S3
  credentials:
    - type: S3Credentials/v1
      accessKeyId: <access-key-id>
      secretAccessKey: <secret-access-key>

Temporary credentials for one object:

- identity:
    type: S3
    path: acme-artifacts/datasets/reference/1.0.0/reference.parquet
  credentials:
    - type: S3Credentials/v1
      accessKeyId: <temporary-access-key-id>
      secretAccessKey: <temporary-secret-access-key>
      sessionToken: <session-token>

A self-hosted MinIO on a custom port. The endpoint attributes separate it from AWS:

- identity:
    type: S3
    scheme: https
    hostname: minio.internal
    port: "9000"
  credentials:
    - type: S3Credentials/v1
      accessKeyId: minio-user
      secretAccessKey: minio-password

Migrating from OCM v1#

The identity type is S3 in OCM v1 and in OCM v2, but three other things changed:

# OCM v1
- identity:
    type: S3
    pathprefix: acme-artifacts/datasets
  credentials:
    - type: Credentials
      properties:
        awsAccessKeyID: <access-key-id>
        awsSecretAccessKey: <secret-access-key>

# OCM v2
- identity:
    type: S3
    path: acme-artifacts/datasets/*
  credentials:
    - type: S3Credentials/v1
      accessKeyId: <access-key-id>
      secretAccessKey: <secret-access-key>

The old property names are still accepted, but only in an untyped Credentials/v1 entry. There, OCM reads awsAccessKeyID, awsSecretAccessKey and token, and maps them to accessKeyId, secretAccessKey and sessionToken. A typed S3Credentials/v1 entry accepts the new names only.

An OCM v1 entry without pathprefix still matches every S3 object. An entry with pathprefix never matches, because the OCM v2 lookup identity has no such attribute. Replace pathprefix with path.

For the matching access specification changes, see Input and Access Types: Migrating from OCM v1.

GitHubRepository#

Used when OCM resolves or downloads a resource with a GitHub/v1 access — resolving a ref to a commit or fetching a commit’s source archive via the GitHub REST API. The identity is derived from the access’s repoUrl. Credentials are optional; see the note on anonymous access under GitHubCredentials/v1.

Identity Attributes#

Credential Properties#

Examples#

github.com:

- identity:
    type: GitHubRepository
    hostname: github.com
    path: open-component-model/open-component-model
  credentials:
    - type: GitHubCredentials/v1
      token: ghp_example_token

GitHub Enterprise host:

- identity:
    type: GitHubRepository
    hostname: git.example.corp
  credentials:
    - type: GitHubCredentials/v1
      token: ghe_example_token

Omitting path matches every repository on that host.

RSA/v1alpha1#

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

Identity Attributes#

Credential Properties#

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.

Related Documentation#

• 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