credential-handling

Description#

In contrast to libraries intended for a dedicated technical environment, for example the handling of OCI images in OCI registries, the OCM ecosystem cannot provide a specialized credential management for a dedicated environment.

Because of its extensibility working with component versions could require access to any kind of technical system, either for storing the model elements in a storage backend, or for accessing content in any kind of technical storage system. There are several kinds of credential consumers with potentially completely different kinds of credentials. Therefore, a common uniform credential management is required, capable to serve all those use cases.

This credential management brings together various kinds of credential consumers, for example the access to artifacts in OCI registries or accessing Git repository content, and credential providers, like vaults or local files in the filesystem (for example a technology specific credential source like the docker config json file for accessing OCI registries).

The used credential management model is based on four elements:

• Credentials:

  Credentials are described property set (key/value pairs).

• Consumer Ids

  Because of the extensible nature of the OCM model, credential consumers must be formally identified. A consumer id described a concrete access, which must be authorized.

  This is again achieved by a set of simple named attributes. There is only one defined property, which must always be present, the type attribute. It denotes the type of the technical environment credentials are required for. For example, for accessing OCI or Git registries. Additionally, there may be any number of arbitrary attributes used to describe the concrete instance of such an environment and access paths in this environment, which should be accessed (for example the OCI registry URL to describe the instance and the repository path for the set of objects, which should be accessed)

  There are two use cases for consumer ids:

  • Credential Request. They are used by a credential consumer to issue a credential request to the credential management. Hereby, they describe the concrete element, which should accessed.
  • Credential Assignment. The credential management allows to assign credentials to consumer ids

• Credential Providers or repositories

  Credential repositories are dedicated kinds of implementations, which provide access to names sets of credentials stored in any kind of technical environment, for example a vault or a credentials somewhere on the local filesystem.

• Identity Matchers

  The credential management must resolve credential requests against a set of credential assignments. This is not necessarily a complete attribute match for the involved consumer ids. There is typically some kind of matching involved. For example, an assignment is done for an OCI registry with a dedicated server url and prefix for the repository path (type is OCIRegistry, host is ghcr.io, prefix path is open-component-model). The assigned credentials should be applicable for sub repositories. So the assignment uses a more general consumer id than the concrete credential request (for example for repository path open-component-model/ocm/ocmcli)

  This kind of matching depend on the used attribute and is therefore in general type specific. Therefore, every consumer type uses an own identity matcher, which is then used by the credential management to find the best matching assignment.

The general process for a credential management then looks as follows.

• credentials provided by credential repositories are assigned to generalized consumer ids.
• a concrete access operation for a technical environment calculates a detailed consumer id for the element, which should be accessed
• it asks the credential management for credentials for this id
• the management examines all defined assignments to find the best matching one based on the provided matching mechanism.
• it then returns the mapped credentials from the references repository.

The critical task for a user of the toolset is to define those assignments. This is basically a manual task, because the credentials stored in vault (for example) could be usable for any kind of system, which typically cannot be derived from the credential values.

But luckily, those could partly be automated:

• there may be credential providers, which are technology specific, for example the docker config json is used to describe credentials for OCI registries. Such providers can automatically assign the found credentials to appropriate consumer ids.
• If the credential store has the possibility to store custom meta data for a credential set, this metadata can be used to describe the intended consumer ids. The provider implementation then uses this info create the appropriate assignments.

Consumer Types and Matchers#

The following credential consumer types are used/supported:

• Buildcredentials.ocm.software: Gardener config credential matcher

  It matches the Buildcredentials.ocm.software consumer type and additionally acts like the hostpath type.

  Credential consumers of the consumer type Buildcredentials.ocm.software evaluate the following credential properties:

  • key: secret key use to access the credential server

• Github: GitHub credential matcher

  This matcher is a hostpath matcher.

  Credential consumers of the consumer type Github evaluate the following credential properties:

  • token: GitHub personal access token

• HashiCorpVault: HashiCorp Vault credential matcher

  This matcher matches credentials for a HashiCorp vault instance. It uses the following identity attributes:

  • hostname: vault server host
  • scheme: (optional) URL scheme
  • port: (optional) server port
  • namespace: vault namespace
  • mountPath: mount path
  • pathprefix: path prefix for secret

  Credential consumers of the consumer type HashiCorpVault evaluate the following credential properties:

  • authmeth: auth method
  • token: vault token
  • roleid: app-role role id
  • secretid: app-role secret id

  The only supported auth methods, so far, are token and approle.

• HelmChartRepository: Helm chart repository

  It matches the HelmChartRepository consumer type and additionally acts like the hostpath type.

  Credential consumers of the consumer type HelmChartRepository evaluate the following credential properties:

  • username: the basic auth user name
  • password: the basic auth password
  • certificate: TLS client certificate
  • privateKey: TLS private key
  • certificateAuthority: TLS certificate authority

• MavenRepository: MVN repository

  It matches the MavenRepository consumer type and additionally acts like the hostpath type.

  Credential consumers of the consumer type MavenRepository evaluate the following credential properties:

  • username: the basic auth user name
  • password: the basic auth password

• NpmRegistry: NPM registry

  It matches the NpmRegistry consumer type and additionally acts like the hostpath type.

  Credential consumers of the consumer type NpmRegistry evaluate the following credential properties:

  • username: the basic auth user name
  • password: the basic auth password
  • email: NPM registry, require an email address
  • token: the token attribute. May exist after login at any npm registry. Check your .npmrc file!

• OCIRegistry: OCI registry credential matcher

  It matches the OCIRegistry consumer type and additionally acts like the hostpath type.

  Credential consumers of the consumer type OCIRegistry evaluate the following credential properties:

  • username: the basic auth username
  • password: the basic auth password
  • identityToken: the bearer token used for non-basic auth authorization
  • certificateAuthority: the certificate authority certificate used to verify certificates

• S3: S3 credential matcher

  This matcher is a hostpath matcher.

  Credential consumers of the consumer type S3 evaluate the following credential properties:

  • awsAccessKeyID: AWS access key id
  • awsSecretAccessKey: AWS secret for access key id
  • token: AWS access token (alternatively)

• Signingserver.gardener.cloud: signing service credential matcher

  This matcher matches credentials for a Signing Service instance. It uses the following identity attributes:

  • hostname: signing server host
  • scheme: (optional) URL scheme
  • port: (optional) server port
  • pathprefix: path prefix for the server URL

  Credential consumers of the consumer type Signingserver.gardener.cloud evaluate the following credential properties:

  • clientCert: client certificate for authentication
  • privateKey: private key for client certificate
  • caCerts: root certificate for signing server

• wget: wget credential matcher

  It matches the wget consumer type and additionally acts like the hostpath type.

  Credential consumers of the consumer type wget evaluate the following credential properties:

  • username: the basic auth user name
  • password: the basic auth password
  • identityToken: the bearer token used for non-basic auth authorization
  • certificateAuthority: the certificate authority certificate used to verify certificates presented by the server
  • certificate: the certificate used to present to the server
  • privateKey: the private key corresponding to the certificate

Those consumer types provide their own matchers, which are often based on some standard generic matches. Those generic matchers and their behaviors are described in the following list:

• exact: exact match of given pattern set

• hostpath: Host and path based credential matcher

  This matcher works on the following properties:

  • type (required if set in pattern): the identity type
  • hostname (required if set in pattern): the hostname of a server
  • scheme (optional): the URL scheme of a server
  • port (optional): the port of a server
  • pathprefix (optional): a path prefix to match. The element with the most matching path components is selected (separator is /).

• partial: complete match of given pattern ignoring additional attributes

Credential Providers#

Credential providers offer sets of named credentials from various sources, which might be directly mapped to consumer identities (if supported by the provider type).

The type Credentials can be used to inline credentials in credential configuration objects to configure mappings of consumer identities to a credential set (see ocm configfile).

The following types are currently available:

• Credential provider Credentials

  This repository type can be used to specify a single inline credential set. The default name is the empty string or Credentials.

  The following versions are supported:

  • Version v1

    The repository specification supports the following fields:

    • properties: map[string]string: direct credential fields

• Credential provider DockerConfig

  This repository type can be used to access credentials stored in a file following the docker config json format. It take into account the credentials helper section, also. If enabled, the described credentials will be automatically assigned to appropriate consumer ids.

  The following versions are supported:

  • Version v1

    The repository specification supports the following fields:

    • dockerConfigFile: string: the file path to a docker config file
    • dockerConfig: json: an embedded docker config json
    • propagateConsumerIdentity: bool(optional): enable consumer id propagation

• Credential provider HashiCorpVault

  This repository type can be used to access credentials stored in a HashiCorp Vault.

  It provides access to list of secrets stored under a dedicated path in a vault namespace. This list can either explicitly be specified, or it is taken from the metadata of a specified secret.

  The following custom metadata attributes are evaluated:

  • secrets this attribute may contain a comma separated list of vault secrets, which should be exposed by this repository instance. The names are evaluated under the path prefix used for the repository.
  • consumerId this attribute may contain a JSON encoded consumer id , this secret should be assigned to.
  • type if no special attribute is defined this attribute indicated to use the complete custom metadata as consumer id.

  It uses the HashiCorpVault identity matcher and consumer type to requests credentials for the access.

  This matcher matches credentials for a HashiCorp vault instance. It uses the following identity attributes:

  • hostname: vault server host
  • scheme: (optional) URL scheme
  • port: (optional) server port
  • namespace: vault namespace
  • mountPath: mount path
  • pathprefix: path prefix for secret

  It requires the following credential attributes:

  • authmeth: auth method
  • token: vault token
  • roleid: app-role role id
  • secretid: app-role secret id

  The only supported auth methods, so far, are token and approle.

  The following versions are supported:

  • Version v1

    The repository specification supports the following fields:

    • serverURL: string (required): the URL of the vault instance
    • namespace: string (optional): the namespace used to evaluate secrets
    • mountPath: string (optional): the mount path to use (default: secrets)
    • path: string (optional): the path prefix used to lookup secrets
    • secrets: []string (optional): list of secrets
    • propagateConsumerIdentity: bool(optional): evaluate metadata for consumer id propagation

    If the secrets list is empty, all secret entries found in the given path is read.

• Credential provider NPMConfig

  This repository type can be used to access credentials stored in a file following the NPM npmrc format (~/.npmrc). It take into account the credentials helper section, also. If enabled, the described credentials will be automatically assigned to appropriate consumer ids.

  The following versions are supported:

  • Version v1

    The repository specification supports the following fields:

    • npmrcFile: string: the file path to a NPM npmrc file
    • propagateConsumerIdentity: bool(optional): enable consumer id propagation

See Also#