Skip to main content

Certificate Authentication in Microsoft Azure

To use certificate-based authentication (specifically for OAuth2 Client Credentials flow, as used in the Microsoft Graph integration within this project), the certificate and its corresponding private key must meet several technical and configuration requirements:

Certificate and Key Requirements​

  • Key Type: The private key must be an RSA Private Key. This is currently the only supported algorithm in the ClientAuthenticationFactory (see ClientAuthenticationFactory.java).
  • Certificate Type: The certificate should be an X.509 certificate.
  • Storage: The certificate and private key must be stored in a KeyStore that the application can access.

Azure AD (Entra ID) Configuration​

  • Public Key Upload: The public part of the certificate (typically a .cer or .pem file) must be uploaded to the App Registration in the Azure Portal under Certificates & secrets > Certificates.
  • Permissions: The App Registration must have the necessary Application Permissions (e.g., Mail.Read, Mail.Send) granted and "Admin consent" must be provided.

Application Configuration Requirements​

When configuring the connection (e.g., for a Microsoft Graph Mail Repository or Server), the following information is required:

  • Authentication Method: Must be set to CERTIFICATE
  • Tenant ID: The directory (tenant) ID of your Azure instance.
  • Client ID: The application (client) ID of your App Registration.
  • Certificate Name (Alias): The alias name under which the certificate and private key are stored in the KeyStore.
  • KeyStore Password: The password required to access the private key in the KeyStore.

Technical Implementation Details​

  • The application uses the certificate to sign a JWT (JSON Web Token) as a client_assertion when requesting an access token from the Microsoft identity platform (v2.0 endpoint).
  • The audience of the JWT is automatically set to the Microsoft token endpoint (e.g., https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token).
  • The integration is built upon the ScribeJava library using a custom JwtAuthenticationScheme.

Configuration via System Properties​

The application uses the property adito.auth.keyStorePassword to define the password for both the KeyStore and the private key used for OAuth2 certificate authentication.

You can set it when starting the ADITO server by adding the following JVM argument:

-Dadito.auth.keyStorePassword=your_password_here

To fully configure the certificate storage, the following properties are typically used together:

  • adito.auth.keyStore: Path to the KeyStore file (e.g., /path/to/keystore.jks).
  • adito.auth.keyStorePassword: The password for the KeyStore and the keys within.
  • adito.auth.keyStoreType: (Optional) The type of the KeyStore (e.g., JKS, PKCS12).
  • adito.auth.keyStoreProvider: (Optional) The security provider.
info

In a managed ADITO system, these properties are automatically managed by the ADITO operator.

Howto: Create a new certificate​

This section describes how to create a new certificate to use with the Graph Mailserver. You can use the Java keytool utility to generate a new KeyStore containing a self-signed certificate and a private key.

  1. Generate a new KeyStore and Certificate: Execute the following command in your terminal. Replace [ALIAS_NAME], [PASSWORD], and [FILENAME].p12 with your desired values:

    keytool -genkeypair -alias [ALIAS_NAME] -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore [FILENAME].p12 -validity 3650
    • -alias: The unique name for your certificate within the KeyStore (referenced as Certificate Name (Alias) in ADITO).
    • -keyalg RSA: Specifies the RSA algorithm (required by ADITO).
    • -keysize 2048: Recommended key size.
    • -storetype PKCS12: The industry-standard KeyStore format.
    • -validity 3650: Certificate validity in days (e.g., 3650 days is approximately 10 years).

  2. Export the Public Certificate (for Azure): Azure requires the public part of the certificate. Export it using the following command:

    keytool -exportcert -alias [ALIAS_NAME] -keystore [FILENAME].p12 -storetype PKCS12 -file [CERTIFICATE_NAME].cer -rfc
    • -file [CERTIFICATE_NAME].cer: The output file containing the public certificate.
    • -rfc: Exports the certificate in PEM format (Base64 encoded), which is easily readable and accepted by Azure.

  3. Upload to Azure: Upload the generated .cer file to your App Registration in the Azure Portal under Certificates & secrets > Certificates.

  4. Configure ADITO: Use the .p12 file path and the password you defined to configure the adito.auth.keyStore and adito.auth.keyStorePassword properties.

Sources​

important

Don't use a self-signed certificate for production environments.