add reference for consumer identities and link it from the other docs.

morrison-sap · morrison-sap · commit ae43a3973e20 · 2026-03-13T11:39:32.000+01:00
On-behalf-of: Gerald Morrison (SAP) &lt;gerald.morrison@sap.com&gt;
Signed-off-by: Gerald Morrison (SAP) &lt;gerald.morrison@sap.com&gt;
diff --git a/content/docs/concepts/credential-system.md b/content/docs/concepts/credential-system.md
@@ -91,3 +91,7 @@ To see resolution in action, try the [Understand Credential Resolution]({{< relr
 - [Tutorial: Credential Resolution]({{< relref "/docs/tutorials/credential-resolution.md" >}}) — Learn how OCM picks the right credentials by experimenting with a config
 - [How-To: Configure Credentials for Multiple Registries]({{< relref "/docs/how-to/configure-multiple-credentials.md" >}}) — Quick task-oriented setup
 - [Tutorial: Credentials for OCM Controllers]({{< relref "/docs/tutorials/configure-credentials-for-controllers.md" >}}) — How to provide credentials in Kubernetes environments
+
+## Related Documentation
+
+- [Reference: Consumer Identities]({{< relref "/docs/reference/credential-consumer-identities.md" >}}) — Complete list of identity types, attributes, and credential properties
diff --git a/content/docs/how-to/configure-signing-credentials.md b/content/docs/how-to/configure-signing-credentials.md
@@ -44,6 +44,9 @@ Copy the following YAML into your `.ocmconfig` file.
 We use the key pair you created in the [How-To: Generate Signing Keys]({{< relref "generate-signing-keys.md" >}}).
 If you already have a key pair that is located in a different location, simply update the file paths accordingly.
 
+All three identity attributes (`type`, `algorithm`, `signature`) are required for credential matching.
+See the [Consumer Identities Reference]({{< relref "docs/reference/credential-consumer-identities.md" >}}) for details.
+
 ```yaml
 type: generic.config.ocm.software/v1
 configurations:
@@ -111,6 +114,7 @@ configurations:
     consumers:
       - identity:
           type: RSA/v1alpha1
+          algorithm: RSASSA-PSS
           signature: dev
         credentials:
           - type: Credentials/v1
@@ -119,6 +123,7 @@ configurations:
               public_key_pem_file: /tmp/keys/dev/public-key.pem
       - identity:
           type: RSA/v1alpha1
+          algorithm: RSASSA-PSS
           signature: prod
         credentials:
           - type: Credentials/v1
@@ -141,8 +146,8 @@ The consumer identity for RSA signing/verification supports these attributes:
 | Attribute   | Required | Description                                         |
 |-------------|----------|-----------------------------------------------------|
 | `type`      | Yes      | Must be `RSA/v1alpha1`                              |
-| `algorithm` | No       | `RSASSA-PSS` (default) or `RSASSA-PKCS1V15`         |
-| `signature` | No       | Name for this key configuration (default: `default`)|
+| `algorithm` | Yes      | `RSASSA-PSS` (default) or `RSASSA-PKCS1-V1_5`. Required for credential matching — the lookup always includes this field. |
+| `signature` | Yes      | Logical name for this key configuration (default: `default`). Must match the `--signature` CLI flag. |
 
 ## Troubleshooting
 
@@ -153,6 +158,7 @@ The consumer identity for RSA signing/verification supports these attributes:
 **Fix:** Ensure:
 
 - The file path `private_key_pem_file` is correct and the file exists
+- The `algorithm` attribute is present in the identity (e.g. `algorithm: RSASSA-PSS`). See [Consumer Identities Reference]({{< relref "docs/reference/credential-consumer-identities.md" >}}).
 - The `signature` name matches what you're using (or is `default` if not specified)
 - The file is valid YAML with correct indentation
 
diff --git a/content/docs/reference/_index.md b/content/docs/reference/_index.md
@@ -2,7 +2,7 @@
 title: Reference
 description: "Browse reference documentation for the OCM CLI and OCM controllers."
 icon: "💾"
-weight: 
+weight: 60
 toc: true
 sidebar:
   collapsed: true
diff --git a/content/docs/reference/credential-consumer-identities.md b/content/docs/reference/credential-consumer-identities.md
@@ -0,0 +1,251 @@
+---
+title: "Credential Consumer Identities"
+description: "Complete reference for OCM credential consumer identity types, their attributes, and credential properties."
+icon: "🔑"
+weight: 2
+toc: true
+---
+
+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]({{< relref "docs/concepts/credential-system.md" >}}).
+
+## 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:
+
+```yaml
+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
+```
+
+OCM currently defines two consumer identity types:
+
+| Identity Type | Used For |
+|---|---|
+| [`OCIRepository`](#ocirepository) | Authenticating against OCI registries |
+| [`RSA/v1alpha1`](#rsav1alpha1) | Providing signing and verification keys |
+
+---
+
+## OCIRepository
+
+Used when OCM accesses an OCI registry — pushing, pulling, or resolving component versions and resources.
+
+### Identity Attributes
+
+| Attribute | Required | Description |
+|---|---|---|
+| `type` | Yes | Must be `OCIRepository` |
+| `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` | Registry username |
+| `password` | Registry password or token |
+
+### 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]({{< relref "docs/tutorials/credential-resolution.md" >}}).
+
+### Examples
+
+**Hostname only** — matches all paths on `ghcr.io`:
+
+```yaml
+- identity:
+    type: OCIRepository
+    hostname: ghcr.io
+  credentials:
+    - type: Credentials/v1
+      properties:
+        username: my-user
+        password: ghp_token
+```
+
+**Hostname + path glob** — matches any single-segment path under `my-org/`:
+
+```yaml
+- identity:
+    type: OCIRepository
+    hostname: ghcr.io
+    path: my-org/*
+  credentials:
+    - type: Credentials/v1
+      properties:
+        username: org-user
+        password: ghp_org_token
+```
+
+**Hostname + scheme + port** — matches only HTTPS on a custom port:
+
+```yaml
+- identity:
+    type: OCIRepository
+    hostname: registry.internal
+    scheme: https
+    port: "8443"
+  credentials:
+    - type: Credentials/v1
+      properties:
+        username: internal-user
+        password: internal_pass
+```
+
+---
+
+## 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. |
+
+{{< callout context="caution" >}}
+**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`.
+{{< /callout >}}
+
+### Credential Properties
+
+| Property | Used For | Description |
+|---|---|---|
+| `private_key_pem` | Signing | Inline PEM-encoded private key |
+| `private_key_pem_file` | Signing | Path to PEM-encoded private key file |
+| `public_key_pem` | Verification | Inline PEM-encoded public key |
+| `public_key_pem_file` | Verification | Path to PEM-encoded public key file |
+
+You can specify both `private_key_pem_file` and `public_key_pem_file` in the same entry to use it for both signing and verification.
+
+### 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:**
+
+```yaml
+- identity:
+    type: RSA/v1alpha1
+    algorithm: RSASSA-PSS
+    signature: default
+  credentials:
+    - type: Credentials/v1
+      properties:
+        private_key_pem_file: /path/to/private-key.pem
+        public_key_pem_file: /path/to/public-key.pem
+```
+
+**Multiple signature identities** (e.g. dev and prod):
+
+```yaml
+- identity:
+    type: RSA/v1alpha1
+    algorithm: RSASSA-PSS
+    signature: dev
+  credentials:
+    - type: Credentials/v1
+      properties:
+        private_key_pem_file: /path/to/dev/private-key.pem
+        public_key_pem_file: /path/to/dev/public-key.pem
+- identity:
+    type: RSA/v1alpha1
+    algorithm: RSASSA-PSS
+    signature: prod
+  credentials:
+    - type: Credentials/v1
+      properties:
+        private_key_pem_file: /path/to/prod/private-key.pem
+        public_key_pem_file: /path/to/prod/public-key.pem
+```
+
+Sign with a specific identity:
+
+```bash
+ocm sign cv --signature dev <component-version>
+ocm sign cv --signature prod <component-version>
+```
+
+**Using PKCS#1 v1.5 algorithm:**
+
+```yaml
+- identity:
+    type: RSA/v1alpha1
+    algorithm: RSASSA-PKCS1-V1_5
+    signature: legacy
+  credentials:
+    - type: Credentials/v1
+      properties:
+        private_key_pem_file: /path/to/private-key.pem
+```
+
+---
+
+## Complete Configuration Example
+
+A single `.ocmconfig` combining registry credentials (with Docker fallback) and signing credentials:
+
+```yaml
+type: generic.config.ocm.software/v1
+configurations:
+  - type: credentials.config.ocm.software
+    consumers:
+      # OCI registry — hostname catch-all
+      - identity:
+          type: OCIRepository
+          hostname: ghcr.io
+        credentials:
+          - type: Credentials/v1
+            properties:
+              username: my-user
+              password: ghp_token
+      # RSA signing — default signature
+      - identity:
+          type: RSA/v1alpha1
+          algorithm: RSASSA-PSS
+          signature: default
+        credentials:
+          - type: Credentials/v1
+            properties:
+              private_key_pem_file: /path/to/private-key.pem
+              public_key_pem_file: /path/to/public-key.pem
+    # Docker config fallback for registries not matched above
+    repositories:
+      - repository:
+          type: DockerConfig/v1
+          dockerConfigFile: "$HOME/.docker/config.json"
+```
+
+## Related Documentation
+
+- [Concept: Credential System]({{< relref "docs/concepts/credential-system.md" >}}) — How the credential system works
+- [Tutorial: Understand Credential Resolution]({{< relref "docs/tutorials/credential-resolution.md" >}}) — Step-by-step matching examples for OCI registries
+- [How-To: Configure Credentials for Multiple Registries]({{< relref "docs/how-to/configure-multiple-credentials.md" >}}) — Task-oriented registry credential setup
+- [How-To: Configure Credentials for Signing]({{< relref "docs/how-to/configure-signing-credentials.md" >}}) — Task-oriented signing credential setup
diff --git a/content/docs/reference/resolver-configuration.md b/content/docs/reference/resolver-configuration.md
@@ -2,7 +2,7 @@
 title: "Resolver Configuration"
 description: "Complete reference for OCM resolver configuration: schema, repository types, and component name patterns."
 icon: "🔍"
-weight: 10
+weight: 1
 toc: true
 ---
 
diff --git a/content/docs/tutorials/credential-resolution.md b/content/docs/tutorials/credential-resolution.md
@@ -10,6 +10,8 @@ toc: true
 
 Every time OCM accesses a registry, it resolves credentials automatically. This tutorial walks you through how that resolution works — given a config, which credentials does OCM pick for each request, and why?
 
+This tutorial focuses on OCI registry credentials. For signing credential identities (`RSA/v1alpha1`), see the [Consumer Identities Reference]({{< relref "/docs/reference/credential-consumer-identities.md" >}}).
+
 For the full concept, see [Credential System]({{< relref "/docs/concepts/credential-system.md" >}}).
 
 **Estimated time:** ~10 minutes
@@ -350,3 +352,4 @@ Then retry the OCM command.
 ## Related Documentation
 
 - [Concept: Credential System]({{< relref "/docs/concepts/credential-system.md" >}}) - Learn how the credential system automatically finds the right credentials for each operation
+- [Reference: Consumer Identities]({{< relref "/docs/reference/credential-consumer-identities.md" >}}) — Complete reference for all identity types (OCI registries and RSA signing)
