Keys and Credentials

Mosaic Orchestration integrates with external resources using keys, certificates, and credentials to maintain secure interactions and data integrity. These elements play a critical role in authenticating, signing, and encrypting communications, ensuring that operations remain secure. This article outlines the purpose of keys, certificates, and credentials, along with the supported integrations for each.

These components are centrally managed within the platform and can be updated or replaced as needed, ensuring secure and efficient handling across the platform. Periodic updates or rotations are supported through automatic versioning, with the system applying the latest version unless otherwise specified. This approach ensures seamless updates without interrupting ongoing operations, streamlining integration with external services while maintaining high security.

To manage keys and credentials, go to Orchestration > Keys and Credentials.

Keys

Keys are cryptographic elements that secure communication and signing operations within Mosaic Orchestration. These asymmetric key-pairs, often paired with certificates, are vital for tasks such as signing JWT tokens or authenticating external web services.

Keys can be stored internally within Mosaic or managed through external HSM (Hardware Security Module) providers (see HSM Providers below).

Mosaic supports generating new keys, uploading external keys in formats like JKS, PKCS12, or PEM, or using keys from HSM providers. HSM-managed keys offer an additional security layer, keeping sensitive materials like private keys in specialized hardware, making them non-exportable.

Keys in Mosaic are automatically versioned. When a key is replaced, the system defaults to the newest version unless otherwise specified.

Example key operations

  • RSA and EC algorithms for signing JWT tokens : You can generate and sign JWT (JSON Web Tokens) using RSA or EC cryptographic algorithms to ensure the authenticity and integrity of the data JWTs carry. To generate a locally encrypted JWT token using an RSA key stored in the Mosaic database, you can use an authscript like @crypto.generateLocalEncryptedJwt({"aal": 3}, "myKey", "db") , where myKey is the alias of the stored key you wish to use for signing, and db indicates that the key is stored internally within the Mosaic database, not on an external service.
  • Client SSL Certificates for Web Service Authentication : Mosaic supports the use of client SSL certificates to authenticate clients to servers securely. This is commonly used in server-to-server communications, where a client proves its identity to a server using a certificate. Keys managed within Mosaic can be utilized to handle these client certificates, ensuring secure and trusted connections between services.

Certificates

Certificates are PKI (Public Key Infrastructure) elements used to establish trust in communications between clients and servers. They contain public keys, which encrypt data, while the corresponding private keys decrypt it and are used for signing data. This ensures secure communication and helps prevent man-in-the-middle attacks.

Certificates can be uploaded in formats such as PEM or JKS and managed within Mosaic’s internal certificate store. They can also be loaded from URLs or JWKS URLs for seamless integration with external services.

Mosaic supports certificate versioning and rotation, allowing updates without disrupting security or communication integrity.

Example: Using certificates in external connections

When creating external connections, certificates play a vital role in securing communications via SSL/TLS. You can specify SSL identities to manage client and server certificates, ensuring encrypted and authenticated interactions.

When establishing an external connection, define the SSL Identities by setting the following:

  • Client Certificate Local Identity , that is the alias of your client certificate's private key stored in Mosaic. This key represents your application's identity when connecting to the external service. The private key remains secure and is used for signing data or decrypting data encrypted by a public key. This ensures data encryption for secure communication with external services.
  • Trusted Identities , that are the certificates of external services you trust. These certificates contain the public keys of external services and are used to establish trust. By verifying these certificates, Mosaic ensures that your application is communicating with authenticated servers, protecting against man-in-the-middle attacks. This process establishes trust in the SSL/TLS communication with external services.

SSL identities.

Credentials

Credentials are secret values, such as passwords or API keys, that authenticate access to external systems or services. They consist of a public credential ID (e.g., a username) and a secret value for authentication.

Credentials can be stored internally or managed through external providers:

  • CyberArk Secure Vault : A third-party service for secure credential management.
  • Custom External Services : Custom-defined external credential management solutions.

Credentials can be centrally managed and referenced across the platform, supporting versioning for seamless updates and replacements.

Example 1: Using credentials in external connections via the portal

When setting up external connections that require authentication, you can specify credentials stored in Mosaic to securely authenticate with external services.

When establishing an external connection, define Authentication by setting the following:

  • Authentication Type , Select the authentication method required by the external service (e.g., Basic Auth, OAuth 2.0).
  • Credential Alias , that is the alias of the credential you have stored in Mosaic. This alias references the credentials' id and secret values needed for authentication. By specifying the credential alias, Mosaic automatically includes the necessary authentication information when communicating with the external service.

authentication

Example 2: Accessing credentials via authscript

You can also access credentials programmatically using an authscript, like the example below. This method securely retrieves the credential without exposing sensitive information in your code.

Copy
Copied
@identities.extractCredentials("credential-alias", "db")
  • Parameters :
    • "credential-alias" : The alias of the credential you want to retrieve.
    • "db" : Specifies that the credential is stored in the Mosaic database.

The authscript returns an object containing the id (e.g., a user identifier) and secret (e.g., a password or API key), which can then be used to authenticate API requests or interact securely with external services:

Copy
Copied
{
    "id": "your-credential-id",
    "secret": "your-credential-secret"
}

HSM providers

HSM Providers (Hardware Security Modules) securely manage cryptographic keys in specialized hardware environments, adding an extra layer of protection for sensitive key materials.

Mosaic integrates with several HSM providers:

  • Azure Key Vault : Manages keys for signing/encrypting JWT tokens. Supports RSA for all operations and EC algorithms (EC-P256, EC-P384) for signatures.
  • AWS CloudHSM : Secures private keys, ensuring they are non-exportable.
  • Luna HSM : Supports encryption and signing operations, including for SAML and JWT keys.
  • File Systems : Securely stores keys in local file systems (e.g., nCipher ).

Each provider supports different encryption algorithms and use cases, such as RSA or EC keys for JWT signing or SSL certificates.