PingGateway 2024.9

SecretsTrustManager

Uses the Commons Secrets API to manage trust material that verifies the credentials presented by a peer. Trust material is usually public key certificates. The configuration references the secrets store that holds the trust material.

Usage

{
  "name": string,
  "type": "SecretsTrustManager",
  "config": {
    "verificationSecretId": configuration expression<secret-id>,
    "certificateVerificationSecretId": configuration expression<secret-id>,
    "secretsProvider": SecretsProvider reference,
    "checkRevocation": configuration expression<boolean>
  }
}

Properties

"verificationSecretId": configuration expression<secret-id>, required if certificateVerificationSecretId isn’t used

Either verificationSecretId or certificateVerificationSecretId is required.

The secret ID to retrieve trusted certificates. This secret ID must point to a CryptoKey.

Consider the following requirements for using certificates with verificationSecretId:

  • Certificates loaded from keystores can be used with the following constraint:

    • The KeyUsage extension digitalSignature must be set or no KeyUsage extension must be set

  • Certificates loaded from JWKs or JWK sets can be used with the following constraints:

    • The use parameter must be set to sig or the use parameter must not be set

    • The key_ops parameter must contain verify or the key_ops parameter must not be set

  • Certificates loaded from PEM can be used without constraint.

"certificateVerificationSecretId": configuration expression<secret-id>, required if verificationSecretId isn’t used

Either verificationSecretId or certificateVerificationSecretId is required.

The secret ID to retrieve certificates for trusted certificate authorities (CA). Use this property when you trust client certificates only because they are signed by a trusted CA.

Consider the following requirements:

  • Certificates loaded from keystores can be used with the following constraint:

    • The KeyUsage extension keyCertSign must be set or no KeyUsage extension must be set

  • Certificates loaded from JWKs or JWK sets can be used with the following constraints:

    • The use parameter must not be set

    • The key_ops parameter must not be set

  • Certificates loaded from PEM can be used without constraint.

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for secrets to resolve trusted certificates.

"checkRevocation": configuration expression<boolean>, optional

Specifies whether to check for certificate revocation.

Default: true

Example

The following example trusts a list of certificates found in a given keystore:

{
  "name": "SecretsTrustManager-1",
  "type": "SecretsTrustManager",
  "config": {
    "verificationSecretId": "trust.manager.secret.id",
    "secretsProvider": {
      "type": "KeyStoreSecretStore",
      "config": {
        "file": "path/to/certs/truststore.p12",
        "storePasswordSecretId": "keystore.pass",
        "secretsProvider": "SecretsPasswords",
        "mappings": [{
          "secretId": "trust.manager.secret.id",
          "aliases": [ "alias-of-trusted-cert-1", "alias-of-trusted-cert-2" ]
        }]
      }
    }
  }
}

The following example trusts a list of CA-signed certificates found in a given keystore:

{
  "type": "SecretsTrustManager",
  "config": {
    "certificateVerificationSecretId": "ca.secret.id",
    "secretsProvider": {
      "type": "KeyStoreSecretStore",
      "config": {
        "file": "&{ig.instance.dir}/certs/truststore.p12",
        "storePassword": "keystore.pass",
        "secretsProvider": "SecretsPasswords",
        "mappings": [{
          "secretId": "ca.secret.id",
          "aliases": [ "alias-of-trusted-cacert-1", "alias-of-trusted-cacert-2" ]
        }]
      }
    }
  }
}