Used Certificates Overview

Context

In The Identity Hub certificates are used and stored at different levels. To be able to keep track of these certificates and to enable administrators to get an overview of certificates that are about to expire an overview is available.

The overview shows for the current tenant:

  • the Tenant Token Signing Certificate: this is the (default) certificate used by The Identity Hub to sign tokens issued in case of the WS-Federation, SAML-P or OpenID protocol
  • all certificates used by (non-blocked) Apps when connecting via WS-Federation, SAML-P or OpenID
  • all certificates used by (logon enabled) Account Providers using WS-Federation or SAML-P

For each certificate the purpose is shown and a link is provided to the administration page where the certificate can be configured.

Certificates that need your attention, as they are about to expire use the following coloring scheme:

  • yellow: expires within the next 30 (* see note) days
  • orange: expires within the next 15 (* see note) days
  • red: expired

It is possible to sort the certificates on their expiration in order to see the ones that have expired or will expire first at the top of the overview.

Note

For on premises installations it is possible to configure the initial amount of days to look ahead, the default is 30. This value is divided by 2 to determine the amount of days to look ahead for the orange level.

Note

Root and Chain Certificates which are stored in the Certificate Store and which are used for Account Providers using Client Certificates are not shown in this overview. They can be seen at the detail page of the respective account providers like Belgium eID, Netherlands Uzi-pas etc

What to do when a certificate is about to expire?

You are the owner of the certificate

  1. If this is a certificate that is issued to you, order a new certificate at the issuer of your choice.
    Important: Make sure the new certificate start date is before your current certificate expiration date and order this soon enough to enable you and the involved parties to migrate to the new certificate.
  2. Based on the overview draw up the list of the persons you need to contact and provide with the new certificate.
  3. Contact the different involved parties to configure the new certificate.

An external party is owner of the certificate

  1. If this is a certificate owned by an external party, contact the external party and ask for a new certificate.
  2. In some cases the new certificate can be retrieved using metadata (see use cases).

Below you can find different use cases

Replacing your Tenant Token Signing Certificate

Impacted users

  • The users of all Apps that use the Tenant Token Signing Certificate

Involved parties

  • All Apps using the Tenant Token Signing Certificate either for WS-Federation (Token Signing certificate), SAML-P (Identity Provider Signing Certificate) or OpenID (JWT Token Signing Certificate)
Note

If an App has a Token Signing Certificate configured specific to the App and thus not uses the Tenant Token Signing Certificate, the App is not impacted by the expiration of the Tenant Token Signing Certificate.

Note

If a connected application uses automatic metadata monitoring (this is configured at the side of the involved party), no action is needed.

Steps

  1. Order (or renew) a new certificate. Make sure the validity period overlaps with the existing certificate.
  2. Provide the involved parties (parties managing the connected applications) with the public key of the new certificate.
Warning

The applications should accept both the new, as well as the existing certificate, as valid until the Tenant Token Signing Certificate has been replaced.

  1. When all applications have configured the new certificate at their side, replace the Tenant Token Signing Certificate by uploading the pfx file and providing the certificate password in the Tenant edit page.
Warning

For Apps using the Tenant Token Signing Certificate all the applications need to migrate in a coordinated manner. All applications need to configure the new certificate before the Tenant Token Signing Certificate can be replaced. Otherwise applications that did not configure the new certificate will not be accessible anymore.

Replacing an App Service Provider Signing and Encryption Certificate (SAML-P)

See Replacing an App Relying Party Certificate (WS-Federation)

Replacing an App Relying Party Certificate (WS-Federation)

Impacted users

  • The users of the App that use the certificate

Involved parties

  • The App using the certificate either for WS-Federation (Relying Party Certificate) or SAML-P (Service Provider Signing and Encryption Certificate)

Steps

  1. Ask the involved party managing the application to deliver the public key of the renewed certificate.
  2. To prevent downtime, the renewed certificate should have an overlap in validity with the existing certificate
  3. Replace the Relying Party Certificate in the App.

Replacing an App JWT Signing Certificate (OpenID Connect)

See Replacing an App Token Signing Certificate (WS-Federation)

Replacing an App Identity Provider Signing Certificate (SAML-P)

See Replacing an App Token Signing Certificate (WS-Federation)

Replacing an App Token Signing Certificate (WS-Federation)

Impacted users

  • The users of the App that use the App Token Signing Certificate

Involved parties

  • The App using the App Token Signing Certificate either for WS-Federation (Token Signing certificate), SAML-P (Identity Provider Signing Certificate) or OpenID (JWT Token Signing Certificate)
Note

If a connected application uses automatic metadata monitoring (this is configured at the side of the involved party), no action is needed.

Steps

  1. Order (or renew) a new certificate. Make sure the validity period overlaps with the existing certificate.
  2. Provide the involved parties (parties managing the connected application) with the public key of the new certificate.
Warning

The application should accept both the new, as well as the existing certificate, as valid until the App Token Signing Certificate has been replaced.

  1. When the application has configured the new certificate at their side, replace the App Token Signing certificate on the app by uploading the pfx file and providing the certificate password on the App edit page

Replacing an Account Provider Identity Provider Certificate (SAML-P)

For SAML-P account providers The Identity Hub allows to specify a Secondary Identity Provider certificate to enable a smooth transition. To know if action is required you should check both.

See Replacing an Account Provider Token Signing Certificate (WS-Federation)

Replacing an Account Provider Token Signing Certificate (WS-Federation)

Impacted users

  • The users that use the Account Provider to authenticate with

Involved parties

  • The Account Provider using the certificate either for WS-Federation (Token Signing Certificate) or SAML-P (Identity Provider Certificate)

Steps

  1. Ask the involved party managing the connected authentication provider to deliver the public key of the renewed certificate.
  2. To prevent downtime, the renewed certificate should have an overlap in validity with the existing certificate
  3. Add the Token Signing Certificate in the Account Provider.
    Saml-P: There are two slots (Primary and Secondary) available for the Identity Provider Certificate. This allows you to configure both the existing and new certificate as valid before the connected authentication provider switches to use the new certificate. When the connected authentication provider switches to use the new certificate there is no downtime.
Note

If the connected authentication provider publishes metadata enter this URL in the Federation Metadata URL field. If you have done this before, you can retrieve the new certificate by editing and saving the Account Provider which will poll the metadata url.

Replacing an Account Provider Service Provider Certificate (SAML-P)

See Replacing an Account Provider Token Encryption Certificate (WS-Federation)

Replacing an Account Provider Token Encryption Certificate (WS-Federation)

Impacted users

  • The users that use the Account Provider to authenticate with

Involved parties

  • The Account Provider using the certificate either for WS-Federation (Token Encryption Certificate) or SAML-P (Service Provider Certificate)
Note

If a connected authentication provider uses automatic metadata monitoring (this is configured at the side of the involved party), no action is needed.

Steps

  1. Order (or renew) a new certificate. Make sure the validity period overlaps with the existing certificate.
  2. Provide the involved parties (parties managing the connected authentication provider) with the public key of the new certificate.
Warning

The authentication provider should accept both the new, as well as the existing certificate, as valid until the certificate has been replaced.

  1. When the authentication provider has configured the new certificate at their side, replace the certificate on the account provider by uploading the pfx file and providing the certificate password on the Account Provider edit page.

Considerations on apps using the Tenant Token Signing Certificate

When creating an app it is possible to use, not copy, the token signing certificate of the tenant.
This can smoothen the setup of an app, however consider that when the signing certificate of the tenant expires all apps using the certificate are impacted as well.
Assigning a certificate specific to the app will allow for a timing suited to the app to replace it.

Certificates with a private root / intermediate

It is possible to use certificates with private root and intermediates.
To be able to upload these as tenant / account provider or app certificate the private certificates should first be uploaded as Certificate Authority. If not the certificate chain validation will fail.

Warning

When using certificates with private root / intermediates, make sure these can also be handled by the other party.

Certificate Authorities