SAML Signing Certificates

When the IdP sends a SAML response, the SP must verify the authenticity of the response, and that it has not been tampered with by an unauthorized third party. The SAML response signing certificate allows the SP to perform this verification.

Consider the fictional SaaS company HireOS, which offers recruiting software to other businesses. HireOS is an online application that allows its customers to track leads, candidates, and interviews. HireOS is referred to as the SP by SAML.

Now let’s consider HireOS’ newest enterprise customer: Enterprise Corp. Enterprise Corp is a large enterprise company that wants to use HireOS to manage their recruiting. Enterprise Corp IT Admins need recruiters and other employees who will use HireOS to log in using Enterprise Corp’s identity provider, Okta. Okta is one of many companies known as an IdP to SAML.

After identifying the user – whether from the SAML request or from IdP initiated SSO – Okta SAML will generate the SAML response, which includes SAML assertions, the X.509 certificate, and the signature value. Upon receiving the response from Okta SAML, HireOS will verify that the response came from Okta SAML by decrypting the signature, using the public key on the X.509 certificate, and checking if the hash values match.

When planning your SAML integration, there are a few things to consider related to SAML response signing certificates.

Your SAML response signing certificate will eventually expire and must be kept up to date in order to maintain service. Your certificate’s expiration time will vary, but typically, response certificates are valid anywhere from 1-5 years. If your certificate is uploaded in the WorkOS Dashboard, you can see when it expires by going to Organizations, selecting the Organization, and then clicking on the Connection containing the response certificate. If your company has a shared Slack channel with WorkOS, we will help ensure that your SAML response signing certificates stay up to date by automatically sending a notification before a certificate expires.

There are two options to upload your response certificate to a Connection, both of which can be done either in the WorkOS Dashboard, or by your customer using the Admin Portal.

To facilitate certificate renewal, WorKOS offers the ability to renew SAML certificates through the Admin Portal. When a certificate is nearing expiration (within 90 days), or has already expired, a notification will appear on the Dashboard Overview page with details about the certificate.

Alternatively, you are also able to filter connections that have either expired or expiring connections directly from the Organization page’s filters.

From the Connection page you can generate an Admin Portal link that WorkOS can email directly to the IT admin. By entering the IT admins’ email address, WorkOS will email them with a certificate renewal Admin Portal link, and they will be notified about future expiring certificates. Alternatively, you can copy the link and share it with them directly.

The IT Admin will be guided to a step by step flow to renew their certificate; the exact steps will vary based on the IdP.

To streamline this process, you can instead choose to upload a metadata URL to WorkOS that we will automatically keep updated as metadata changes. If your customer’s IdP refreshes a certificate, WorkOS will automatically pull in the updated metadata. Your customer can upload a metadata URL to the Admin Portal during setup. Alternatively, they can provide it to your to manually upload via the Dashboard.

SP metadata such as the Entity ID, IdP SSO URL, and SAML response signing certificate can be uploaded manually through the Dashboard or the Admin Portal. This may be done either by uploading an XML metadata file, or by individually inputting metadata values. When metadata becomes out of date, such as an X.509 certificate expiring, new information must manually be uploaded. If you would like to upload the data for your customer, they must first send the relevant metadata to you. You can then upload it via the WorkOS Dashboard by navigating to the Organization and selecting the specific Connection.

When the SP sends a SAML request, the IdP must verify that the request is actually coming from the SP and has not been tampered with by an unauthorized third party. IdP’s choose to handle this verification in different ways, and some use a SAML request signing certificate. Microsoft AD FS SAML uses a relying party trust, which is similar to a SAML request signing certificate, and the concepts covered in this article are applicable. In WorkOS, Connections that take advantage of a request certificate will expose an SP metadata URL that can be sent to the IdP in order to give it access to the signing certificate.

Once again, let’s consider the fictional SaaS company HireOS, which offers recruiting software to other businesses. HireOS is referred to as the SP by SAML.

HireOS’ newest enterprise customer is called Enterprise Corp. Enterprise Corp IT Admins need recruiters and other employees who will use HireOS to log in using Enterprise Corp’s identity provider, Okta. Okta is one of many companies known as an IdP to SAML.

In SP initiated SSO, HireOS will first send a SAML request to Okta SAML. If a request certificate is being used, then the X.509 certificate along with a signing signature will be attached to the request. Upon receiving the request, Okta SAML will verify that the request came from HireOS by decrypting the signature using the public key on the X.509 certificate and confirming the hash values match.

When planning your SAML integration, there are a few things to consider related to SAML request signing certificates.

Your SAML request signing certificate will eventually expire and must be kept up to date in order to maintain service. WorkOS will automatically update the request signing certificate on the SP metadata URL before it expires. It is up to your customer and their IdP to either monitor the SP metadata URL, or manually keep it up to date. If your company has a shared Slack channel with WorkOS, you will automatically be notified when the X.509 certificate on the SP metadata URL is updated, so that you can check with your customer that they have the latest metadata.

There are potentially two options for your customer to upload SP metadata, and will vary based on their IdP. In both cases, you will need to provide your customer with the SP metadata URL, which can be found in the WorkOS Dashboard by going to Organizations, selecting the Organization, and then selecting the Connection.

To streamline this process, your customer instead may choose to monitor our SP metadata URL. Their IdP will regularly check our URL for updates to the metadata. When WorkOS makes an update, such as refreshing an X.509 certificate that is expiring soon, their IdP will automatically make the change.

Your customer can manually download the SP metadata document from the URL, extract the certificate, and upload it to their IdP. When the certificate is getting ready to expire, they can repeat this process to give their IdP the most up to date certificate.

This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at User Management, a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.