Managing SAML X.509 Certificates

Setting up a SAML connection for SSO is a somewhat complicated back-and-forth setup with your enterprise customers. When managing these SAML connections, one of the steps involved is to manage X.509 certificates.

Your customer will be required to provide you with an X.509 certificate that will be valid for some time (typically 1-10 years depending on the provider). This article will cover what exactly these certificates do, why they are needed, and why you as the developer need to carefully manage these.

This article assumes some working knowledge of SAML. If you’re not too familiar, check out this blog post which dives deeper into how SAML works.

What are X.509 Certificates used for?

‍SAML X.509 certificates are a crucial step in validating the signature of a SAML request and response. At a high level, X.509 certificates are used to allow your application also known as the Service Provider (SP) to verify the authenticity of a SAML response. Some Identity Providers (IdP) may require or provide the option to use a SAML signing certificate for the SAML request as well. In these cases, the IdP verifies the authenticity of the SAML request coming from your application.

When your customer sets up SAML SSO with your application, they will provide you with an X.509 certificate that they obtained from the IdP. This X.509 certificate will include a public key for a corresponding private key that the IdP will use for SAML response signing. On the other hand, for SAML request signing you will typically provide your customer with an SP metadata URL that they will upload to the IdP such that the IdP can verify the SAML requests.

When a customer attempts a sign in to your application (also known as an SP Initiated flow), they will be redirected to the IdP to authenticate. The IdP must authenticate that the request is coming from your application, and they will use the public key from the SAML request signing certificate to verify this. As mentioned above, this is obtained by the IdP from the SP metadata URL provided during initial setup. An exception to this is Microsoft Entra ID SAML, which uses a relying party trust — which is similar in its responsibility to the SAML response signing certificate.

Once the request has been verified, your application will receive a SAML response from the IdP. Your application will decrypt this assertion using the public key found in the X.509 certificate that was uploaded earlier to verify that the assertion did indeed come from the IdP.

To give a more intuitive sense of how the entire flow works, lets zoom out and follow two examples, a SAML sign in being initiated from your application, as well as one from the IdP. In this first example, the user will initiate the sign in process from your application:

This example follows an IdP initiated flow, in which the user starts the authentication from the IdP to access your application:

What happens if these expire?

‍If these links expire, then there is a potential SSO outage for your customer. Without a valid X.509 certificate for response validation, you will not be able to validate the response from the IdP and unable to sign customers in.

Using Dynamic Metadata URLs

‍You can also encourage your customer to give you a metadata URL to be able to dynamically fetch new certificates as they become available. This will ensure that if a customer sets up a new certificate in their IdP, your application can fetch it using the metadata URL, and be ready to switch over when it becomes activated.

Metadata URLs are preferable to manual certificate upload as it minimizes the back and forth between your team, and your customer.

Note that not all IdPs support metadata URLs.  As of publishing this article, IdPs that do support metadata URLs for fetching of updated certificate data include:

• Okta, ADFS, Azure, PingOne, CAS, ClassLink, Duo, Keycloak, MiniOrange, NetlQ, Oracle, PingOne, Salesforce, and Simple SAML

The following IdPs do not support metadata URLs for fetching of updated certificate data.  These IdPs provide a metadata file, which contains information about the connection’s certificates but cannot be polled like a URL for certificate renewals. Instead, your customer must still provide you with the latest metadata file, similar to manual certificate exchanges.

• Google Workspace, JumpCloud, LastPass, OneLogin, PingFederate, Cloudflare, Rippling, Shibboleth

Best Practices

‍In order to keep your application’s SSO running smoothly with no downtime, you should make sure that do the following:

1. Set up alerting beforehand based on certificate expiry dates ‍

Typically a 90-day window should be sufficient to reach out to customers and give them some time to coordinate the renewal. You want to make sure that you have ample time to coordinate the back and forth required for certificate renewal

2. Encourage your customers to provide you with dynamic metadata URLs

You want to minimize having to manually request and upload a certificate for each expiry, especially as the number of enterprise customers you has grows. Ensure that you are handling the switch off from the old to new active certificates smoothly, potentially rotating through all available certificates for the customer

3. Carefully orchestrate swapping out certificates

Some IdPs such as Okta, will only allow a single certificate to be active at any given time, this means that you must first obtain the new certificate from your customer, add it to your system, make sure that you are still processing existing requests using the old SAML certificate, and then start using the new one as soon as your customer activates it. This typically requires a bit of coordination with your customer to ensure no downtime

WorkOS Certificate Management Flow

‍WorkOS has built flows in order to minimize this process to make it as smooth as possible to keep certificate active at all times. During set up, WorkOS’ Admin Portal flow will encourage your customers to upload metadata URLs and allow WorkOS to automatically handle the transition to new certificates with no downtime.

However, if your customers do choose to manually upload their certificates, the Dashboard has built in alerts to keep you on top of upcoming expiries. As you scale up it becomes important to stay on top of these expirations, and the Dashboard supports advanced filtering to find SAML connections that are expired, or with upcoming expiries. You will also receive notifications through email, or Slack about upcoming customer expiries to make sure that you're always on top of any situation.

IT Admin Management

WorkOS allows you to send your customers a link to allow them to upload their certificates directly to WorkOS in a straightforward step-by-step flow to keep your connections working smoothly. WorkOS also supports adding the email address of the IT admin for a particular customer to send them expiring notifications and directly allow them to use the self-serve renewal flow.

Next Steps

‍SAML Certificate management is a pain point amongst all SAML SSO connections that you will inevitably experience when expanding to enterprise customers. If you are interested in using WorkOS to manage your SSO connections and minimize all the complications of managing SSO certificates, check out the SSO documentation.