Secret Types

Secrets represent the credentials needed to connect to external systems, like a third-party REST API or AWS S3 bucket. Such systems often require different authentication formats, be it an API key, username and password, or private SSH key. Utilihive supports a variety of these requirements as typed secrets. As long as the properties on the secret match the intended type, the corresponding processor will be able to integrate with the given system.

Supported Types

ApiKey

API key/value pair to be added as header/query to the request. Secrets of type ApiKey have the following properties:

Property Description

apiKeyName

API key name. Required.

apiKeyValue

API key value. Required.

apiKeyLocation

Location of API key in the request. Required. Can be one of the following:

  • Header

  • Query

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

ApiKeys

Multiple API key/value pairs to be added as header/query to the request. Secrets of type ApiKeys have the following properties:

Property Description

apiKeys

API keys as key/value pairs presented in the following format: "apiKey1=apiValue1\napiKey2=apiValue2\napiKey3=apiValue3" where key and value delimited by "=" and pairs are delimited by new line (\n)

Required.

apiKeysLocation

Location of API keys in the request. Required. Can be one of the following:

  • Header

  • Query

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

AwsCredentials

AWS credentials for calling AWS services. Secrets of type AwsCredentials have the following properties:

Property Description

accessKeyId

AWS access key, used to identify the user interacting with AWS. Required.

secretAccessKey

AWS secret access key, used to authenticate the user interacting with AWS. Required.

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

AzureClientCertificate

Azure AD credential that acquires a token with a client secret for an AAD application. Secrets of type AzureClientCertificate have the following properties:

Property Description

tenantId

Application tenant ID. Required.

clientId

Application Client ID. Required.

clientSecret

Client secret for the authentication. Required.

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

AzureConnectionString

Azure connection string with authentication information required for access to Azure services. Secrets of type AzureConnectionString have the following properties:

Property Description

connectionString

Azure connection string with authentication information required for access to Azure services. Required.

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

GoogleServiceAccountCredentials

OAuth2 credentials representing a Service Account for calling Google services Secrets of type GoogleServiceAccountCredentials have the following properties:

Property Description

clientId

Client ID of the service account. Required.

clientEmail

Client email address of the service account. Required.

privateKeyPkcs8

RSA private key object for the service account in PKCS_8 format. Required.

privateKeyId

Private key identifier for the service account. Required.

projectId

Google Cloud project id. Required.

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

OAuth2

Authentication based on OAuth2 access token to be added as Authorization HTTP header. Secrets of type OAuth2 have the following properties:

Property Description

oauth2TokenEndpoint

The URI of the OAuth2 token endpoint. Required.

oauth2Scope

Authorisation scope.

oauth2AuthenticationConfigKey

Key of the specific type of the secret config to be used with remote OAuth2 service provider. Supported types are basic OAuth2 authentication (OAuth2BasicSecretDto), OAuth2 password authentication (OAuth2PasswordSecretDto) and signed JWT authentication (OAuth2SignedJWTSecretDto). Required.

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

OAuth2Basic

OAuth2 basic authentication based on client credentials Secrets of type OAuth2Basic have the following properties:

Property Description

oauth2ClientId

OAuth2 client ID. Required.

oauth2ClientSecret

OAuth2 client secret.

oauth2CredentialsLocation

OAuth2 credentials location. If it is set to Header (default), the client_id and client_secret will be Base64 encoded in the Authorization header and grant_type and scope will be placed in the body of the OAuth request. If it is set to Body, the client_id, client_secret, grant_type and scope will all be placed in the body of the OAuth request.Defaults to Header when it's not configured. Can be one of the following:

  • Header

  • Body

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

OAuth2Password

OAuth2 Password Grant authentication based on client credentials Secrets of type OAuth2Password have the following properties:

Property Description

oauth2ClientId

OAuth2 client ID.

oauth2ClientSecret

OAuth2 client secret.

oauth2UserName

User name. Required.

oauth2Password

Password. Required.

oauth2CredentialsLocation

OAuth2 credentials location. If it is set to Header (default), the client_id and client_secret will be Base64 encoded in the Authorization header and grant_type and scope will be placed in the body of the OAuth request. If it is set to Body, the client_id, client_secret, grant_type and scope will all be placed in the body of the OAuth request. Can be one of the following:

  • Header

  • Body

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

OAuth2SignedJWT

OAuth2 secret config based on signed JWT. The signed JWT is used to obtain an oauth2 token Secrets of type OAuth2SignedJWT have the following properties:

Property Description

jwtIssuer

Issuer claim. Required.

jwtSubject

Subject claim. Required.

jwtAudience

Audience claim. Required.

jwtExpirationTimeInMinutes

Expiration time claim. Defaults to 60 minutes if not configured.

jwtNotBeforeInMinutes

Not-before claim. Defaults to -2 minutes (to account for some clock skew) if not configured.

keyStore

Key store entry to retrieve credentials from. Required.

keyStoreType

Key store type (PKCS12 or JKS). Defaults to PKCS12 if not configured. Can be one of the following:

  • PKCS12

  • JKS

keyStorePassword

Key store password. Required.

keyAlias

Key alias to retrieve certificate from the key store by. Required.

keyPassword

Key password to generate JWT signature signer. Required.

certificateThumbprintType

Certificate thumbprint type. Defaults to SHA1 if not configured. Can be one of the following:

  • SHA1

  • SHA256

jwsAlgorithm

Algorithm to use when generating JWT signature signer. Defaults to RS256 if not configured. Can be one of the following:

  • RS256

  • RS384

  • RS512

  • ES256

  • ES384

  • ES512

  • PS256

  • PS384

  • PS512

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

SignedJWT

Signed JWT secret config used to create a signed JWT Secrets of type SignedJWT have the following properties:

Property Description

jwtKeyStore

Key store entry to retrieve credentials from. Required.

jwtKeyStoreType

Key store type (PKCS12 or JKS). Defaults to PKCS12 if not configured. Can be one of the following:

  • PKCS12

  • JKS

jwtKeyStorePassword

Key store password. Defaults to no password

keyAlias

Key alias to retrieve private key from the key store by. Required.

keyPassword

Key password to generate JWT signature signer. Defaults to no password

jwsAlgorithm

Algorithm to use when generating JWT signature signer. Defaults to RS256 if not configured. Can be one of the following:

  • RS256

  • RS384

  • RS512

  • ES256

  • ES384

  • ES512

  • PS256

  • PS384

  • PS512

jwtClaims

Comma-separated list of claims formatted as <key>=<value>. (exp, nbf, and iat will be discarded and overwritten by the explicit properties jwtExpirationTimeInMinutes, jwtNotBeforeInMinutes, and the time when the jwt was created).

jwtExpirationTimeInMinutes

Number of minutes before the jwt will expire relative to the creation time of the jwt. The value will be converted to the exp claim. Defaults to 60 minutes if not configured.

jwtNotBeforeInMinutes

Number of minutes before the jwt is valid relative to the creation time of the jwt. The value will be converted into the nbf claim. Defaults to -2 minutes (to account for some clock skew) if not configured.

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

SshPrivateKey

SSH private key authentication Secrets of type SshPrivateKey have the following properties:

Property Description

sshUserName

SSH user name. Required.

sshPassword

SSH password.

sshPrivateKey

SSH private key. Required.

sshPrivateKeyPassphrase

SSH private key passphrase.

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

Tls

Secret config for configuring SSL/TLS connections. Secrets of type Tls have the following properties:

Property Description

serverPublicKey

Base64 encoded server public key.

allowSelfSignedCertificate

Flag that configures if self-signed certificate is allowed. If not set self-signed certificate is not allowed.

allowCertificateAssociatedWithWrongHost

Flag that configures if association with wrong host is allowed. If not set association with wrong host is not allowed

clientKeyStore

Base64 encoded client keystore string.

clientKeyStoreType

Client key store type (PKCS12 or JKS). Defaults to PKCS12 if not configured. Can be one of the following:

  • PKCS12

  • JKS

clientKeyStorePassword

Client key store password.

clientKeyPassword

Client key password.

clientKeyStoreAlias

Client key store alias.

serverTrustStore

Base64 encoded server truststore string.

serverTrustStoreType

Server trust store type (PKCS12 or JKS). Defaults to PKCS12 if not configured. Can be one of the following:

  • PKCS12

  • JKS

serverTrustStorePassword

Server trust store password.

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

UserNameAndPassword

General userName/password authentication. Secrets of type UserNameAndPassword have the following properties:

Property Description

userName

User name. Required.

password

Password. Required.

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

WssSignature

WS-Signature configuration. Secrets of type WssSignature have the following properties:

Property Description

wssSignatureParts

Request parts to be signed. Required.

wssSignatureAlgorithm

WS-Security signature algorithm.

wssSignatureDigestAlgorithm

WS-Security signature digest algorithm.

wssSignatureKeyIdentifier

WS-service signature key identifier.

wssSignatureC14nAlgorithm

WS-Security signature C14N algorithm to apply to the data.

clientKeyStore

Base64 encoded client keystore string.

clientKeyStoreType

Client key store type (PKCS12 or JKS). Defaults to PKCS12 if not configured. Can be one of the following:

  • PKCS12

  • JKS

clientKeyStorePassword

Client key store password.

clientKeyPassword

Client key password.

clientKeyStoreAlias

Client key store alias.

serverTrustStore

Base64 encoded server truststore string.

serverTrustStoreType

Server trust store type (PKCS12 or JKS). Defaults to PKCS12 if not configured. Can be one of the following:

  • PKCS12

  • JKS

serverTrustStorePassword

Server trust store password.

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

WssUserNameToken

WS-Security username token Secrets of type WssUserNameToken have the following properties:

Property Description

wssUserName

WS-Security user name. Required.

wssPassword

WS-Security password.

wssPasswordType

WS-Security password type (Text, Digest, None). Defaults to Text if not configured. Can be one of the following:

  • Text

  • Digest

  • None

wssAddNonce

WS-Security nonce. If not configured, the nonce will be added.

wssAddCreated

WS-Security nonce creation time. If not configured, creation time will be added.

description

Description of secret config. Required.

changeComment

Comment explaining the reason for changes in secret config. Required.

Working with Keystores

Secret types that rely on a keystore/certificate (such as OAuth2SignedJWT and Tls) reference the keystore as a Base64 encoded string. If you already have a keystore file, then macOS and Linux users can run the following command line command to convert the file to Base64:

base64 -i certificate.p12 -o output_file

On Windows, use the following certutil command instead:

certutil -encode certificate.p12 output_file
The output of certutil includes beginning and ending lines (e.g., -----BEGIN CERTIFICATE-----) that should not be copied over.

If you need to generate a new PKCS12 keystore (i.e., a self-signed certificate), you can use the OpenSSL toolkit. This is done in two steps, first to create the key and certificate, then to create the keystore bundle. For example:

openssl req -x509 -newkey rsa:4096 -keyout myKey.pem -out cert.pem -days 365

openssl pkcs12 -export -out keyStore.p12 -inkey myKey.pem -in cert.pem

Alternatively, you can use Java’s keytool command to generate a Java KeyStore (JKS). For example:

keytool -genkey -keyalg RSA -keystore keyStore.jks -validity 360 -keysize 2048