Certificate Authentication
Certificate authentication lets the runtime service principal authenticate to Microsoft Graph and the Office 365 Management APIs with an X.509 certificate held in Key Vault, instead of a client secret. It is the recommended option for the runtime account — there is no secret to leak or to rotate in app settings, and the private key never leaves Key Vault. See the Security & permissions model for how the runtime account authenticates overall.
- The certificate lives in Key Vault. Its private key is exposed to the App Service as a managed secret, so the runtime identity needs Get on both certificates and secrets.
- The certificate subject and name must be
O365AdvancedAnalytics(CN=O365AdvancedAnalytics) — this is what the solution looks for and is not currently configurable. - You switch it on with the
UseClientCertificate=trueapp setting (see the Configuration reference); theClientSecretvalue is then ignored.
- A deployed solution with a Key Vault (the installer creates one).
- Permission to manage certificates in that Key Vault (granted in the steps below).
- Access to the runtime app registration in Entra ID, to upload the certificate's public key.
You can run the system with certificates instead of client secrets. Here’s how to set that up.
By default, no permissions are given for certificates in the key vault for any users – just service-accounts:
We need to add permissions for the current user in Azure portal & the application identity for certificates (note: the installer now grants the runtime account get rights for certificates).
Go to vault access policies.
Create a new policy for the current user to manage certificates:
It’s up to you what permissions you give yourself; your user permissions aren’t used by the import web-jobs. Your permissions should include though the ability to upload/generate certificates.
These are for your user only.
In case you haven’t got the permissions configured already, allow the runtime account read access to certificates.
We assume vault access policies are used.
Make sure get is selected:
Click Next and save to apply the permission changes.
Create a new certificate to use for authentication. You can have Key Vault generate it for you, or use your own CA if you prefer that way.
Recommended: give it a long validity as access to APIs will break when it expires until the configuration in the app service is manually updated with the new certificate.
Important: the subject-name and certificate name must be "O365AdvancedAnalytics" (CN=O365AdvancedAnalytics) as that’s what the solution expects. For now, this isn’t configurable.
Also note: the private key for the generated certificate is stored as a managed secret, so the app service identity will need secret get permission too.
Now open and download the public key:
Take note of thumbprint:
The corresponding public-key can now be used for the application registration. In "certificates" for the application registration:
Verify thumbprint is the same as certificate stored in Key Vault.
By default the system will use client-secret authentication. To force certificate authentication, add a setting "UseClientCertificate" with value "true" to the app service configuration and save. You can optionally remove the "ClientSecret" value too; with the 1st setting as "true", the secret is ignored.
Another mandatory setting to have is "WEBSITE_LOAD_USER_PROFILE" with value "1" so the app service can parse X509 certificates. More information online.
Make sure the certificate is read successfully by checking the logs of the "Office365ActivityImport" job:
Here we see that the operation has failed because there’s no certificate in the key vault.
There is no automatic certificate rotation support. When the certificate is renewed in Key Vault, you must overwrite the certificate in Entra ID with the new one too and restart the web-jobs.