Skip to content

Certificates

By default, when setting Authorization.AutocreateCertificates to false or leaving it empty, the Authorization Server uses default certificates of the user that runs the Authorization Server. The keys that are used for .NET DataProtection are stored in %localappdata%\ASP.NET\DataProtection-Keys where they are encrypted at rest by the Windows DPAPI. This is the easiest approach and requires the least amount of manual configuration.

Which is user runs the Authorization Server process (this becomes important at the end of this section)? When the Authorization Server runs on an application pool with the ApplicationPoolIdentity, its user is IIS APPPOOL\<appPoolName>, e.g. IIS APPPOOL\DefaultAppPool. When the application pool runs as a technical user, e.g. "techie", then the user identity is <machine_name>\techie. During startup, the Authorization Server logs the user identity it is using, in case it is unclear.

We recommend to store the .NET DataProtection keys in the database. For security reasons, these keys must be protected at rest. This is ensured by configuring certificates that are used by the data protection system.

The DataProtection keys are stored in the database, when the app setting Service.DataProtection.PersistKeysInDatabase is set to true.

Installing Certificates

In general, we recommend to use the Primus installer to set up certificates.

When certificates are changed later, users that already logged in have to log in again. Also, all client secrets cannot be decrypted anymore. Any created client secret will continue to work though.

The Authorization Server contains a cmd line call that automatically creates certificates and adjusts the appsettings.production.json file for the Authorization Server. Changing the certificates requires a restart of the Authorization Server, usually done by restarting the application pool when hosting on IIS.

AuthorizationService.exe setup certificates -s LocalMachine -j .\appsettings.Production.json

creates 5 certificates in the LocalMachine certificate store. To run multiple Authorization Server service instances, they must use the same certificates. The following certificates are created:

  • Auth DataProtection Key Protector Certificate - protects the .NET DataProtection keys that are stored in the database
  • 2x Auth DataProtection Key Unlock Certificate - allows for certificate rotation, used by the .NET DataProtection subsystem
  • Auth OpenIddict Server Encryption Certificate - for encrypting data that the OIDC framework OpenIddict creates
  • Auth OpenIddict Server Signing Certificate - for signing purposes of the OIDC framework OpenIddict

By default, the Authorization Server assumes to run as a single service. It can, however, be installed on multiple machines. If those machines are reachable by different URLs, they do not serve the purpose of SSO, as the usual SSO pattern works by using a browser cookie to keep the user signed in. However, for machine to machine communication that does not rely on SSO, this can reduce load on the primary Authorization Server.

IMPORTANT: Please remember the part at the beginning of this section where the actual service user identity was mentioned. This is important because certificates are usually not accessible to anyone on a system due to being sensitive data. When using certificates from the certificate stores, you must ensure that the app pool's user identity has access to the certificate, including the private key. Otherwise, the certificate cannot be used to decrypt encrypted data.

You can manually edit and assign permission for certificates stored in the local machine certificate store. Open the local computer certificate store mmc (select Run from the Start menu, and then enter certlm.msc), then use the steps select certificate -> right mouse click -> All Tasks -> Manage Private Keys.... For the IIS APPPOOL\DefaultAppPool, assign the IIS_IUSRS group, for technical app pool users assign that technical user or a user group of that user to the private key permissions.

Transferring certificates between machines or reusing existing certificates

The Primus installer does not offer an option to configure the certificate thumbprints directly. It also does not have options to transfer certificates automatically between machines.

Please create your own powershell scripts to automate this task, or use the manual steps described earlier.