Key Management

The built-in token issuer will manage the keys used to protect tokens issued by the /connect/token endpoint and cookies used by the PolicyServer Management UI. Key managment follows best practices for handling key material including:

• automatic rotation of keys

• secure storage of keys at rest using data protection

• announcement of new keys

• maintainence of retired keys

Keys are first announced which will cause them to be added to the list of keys in the OIDC discovery document, but will not be used for 14 days. This gives sufficient time for clients to re-discover signing keys. After this they are promoted and will be used to sign tokens. Keys are rotated 90 days after creation at which point they are retired. Retired keys are kept for 14 days after which they are deleted.

If there are no eligible signing keys available a new signing key will be generated. This will happen if the SigningKeys table or DataProtectionKeys table have been emptied or only contain ineligible keys (for example after restoring an older database backup), or if the master key used to encrypt data protection keys is changed.

Note

If clients already have tokens signed by keys that are no longer available and encounter access denied errors when calling Policy Server apis they will need to request a new token or will continue to fail until the current token expires and a new one is requested.

Restarting clients will force the token to be refreshed if necessary.

Any users that are using the Policy Server management UI will be signed out of the Management UI and have to sign back in.

When new signing keys are generated due to Policy Server being started for the first time, if Policy Server is unable to verify a token or cookie it will re-check to see if another instance has created another signing key which mitigates against multiple instances starting simultaneously generating incompatible signing keys.

Data Protection

The signing keys created by key managment are protected using ASP.NET Core Data Protection. By default this is configured to use the database to store the Data Protection Keys as well. These keys are always protected using a master key, but the key used to protect them is generated and machine specific. In order to support multiple instances of Policy Server for load balanced scenarios it is necessary to set the UseDatabase option to true and provide an x509 certificate. (format???)

Policy Server supports either a certificate file or a certificate thumbprint which is used to locate the certificate in the certificate store on windows. On linux it is necessary to provide a certificate file.

The master key configuration in PolicyServer can be set in the configuration file policyserver.json as follows:

Using certificate file with password:

"PolicyServer" : {

  //other config values
  ...

  "management": {
    "DataProtection": {
      "UseDatabase": true,
      "CertificateFileName": "/certificate/file/location",
      "CertificateFilePassword": "certificate-password"
    }
  }
}

Using certificate thumbprint:

"PolicyServer" : {

  //other config values
  ...

  "management": {
    "DataProtection": {
      "UseDatabase": true,
      "CertificateThumbprint": "certiciate-thumbprint"
    }
  }
}

Using certificate file without password:

"PolicyServer" : {

  //other config values
  ...

  "management": {
    "DataProtection": {
      "UseDatabase": true,
      "CertificateFileName": "/certificate/file/location"
    }
  }
}