# Rotating SAML Signing Certificates SAML signing certificates are used by the identity provider to sign SAML assertions, and Teleport verifies the signature to authenticate users. Certificates have a fixed validity period, after which they expire, and SSO will no longer work. The default lifetime for these certificates is set by the identity provider, for example Entra ID (3 years) or Okta (10 years). When a signing certificate is expiring or expired, Teleport raises a cluster alert with details about the certificate that needs to be rotated. ![Cluster alert showing expiring SAML signing certificate](/docs/assets/images/cluster-alert-05f37135f79fbad327e8561ad9bd64e0.png) ## How to update the certificate in Teleport The `entity_descriptor` field on a SAML connector stores the metadata from the identity provider, including any signing certificates. For detailed steps on generating and activating certificates in your identity provider, including how to obtain the metadata XML or URL, see [How to rotate a SAML certificate](#how-to-rotate-a-saml-certificate) below. There are two methods for updating the rotated certificate in Teleport: ### Using the `entity_descriptor_url` (recommended) The `entity_descriptor_url` field on a SAML connector stores the metadata URL from the identity provider. When the SAML connector is saved with this field, the `entity_descriptor` field will be automatically populated with data from the identity provider at save time. 1. Navigate to your identity provider and find the metadata URL; save it for later 2. In the Teleport web UI, navigate to **Zero Trust Access** > **Auth Connectors**, find your SAML connector, and click **Edit** ![Navigate to SAML connector edit](/docs/assets/images/navigate-saml-edit-5362a7f2bd1c028064ced312dc6eed41.png) 3. Observe that the connector has an `entity_descriptor_url` field and an `entity_descriptor` field populated with the identity provider metadata ![SAML connector editor initial state](/docs/assets/images/saml-editor-initial-state-f6112a36fa189b593f5069a02e8f79c8.png) 4. Populate the `entity_descriptor_url` field with the metadata URL from your identity provider and delete the `entity_descriptor` field and its contents, then save the connector ![SAML connector editor with updated fields](/docs/assets/images/saml-editor-updated-fields-e1f454bfebb2a13c8215ef0acafe803d.png) 5. Observe that the `entity_descriptor` field is repopulated with fresh metadata from the identity provider, including the rotated certificate ![SAML connector editor repopulated metadata](/docs/assets/images/saml-editor-repopulated-metadata-1a3fffbe9b01bece8baa1d67c24f891b.png) 6. Return to your identity provider, activate the new certificate and remove the old one ### Manually updating the `entity_descriptor` In the absence of a populated `entity_descriptor_url` field, the `entity_descriptor` field can be manually populated. 1. Navigate to your identity provider and find the metadata XML file; save it for later 2. In the Teleport web UI, navigate to **Zero Trust Access** > **Auth Connectors**, find your SAML connector, and click **Edit** ![Navigate to SAML connector edit](/docs/assets/images/navigate-saml-edit-5362a7f2bd1c028064ced312dc6eed41.png) 3. Replace the contents of the `entity_descriptor` field with the contents of the metadata XML file saved in the first step, then save the connector ![Replacing contents of entity descriptor field](/docs/assets/images/saml-editor-only-entity-descriptor-6974c1a18461fe7a5d64469c9a4b5e53.png) 4. Return to your identity provider, activate the new certificate and remove the old one ## How to rotate a SAML certificate Rotating a certificate involves creating a new certificate in your identity provider, updating Teleport to trust it, then activating it in the identity provider and removing the old one. --- UPDATE TELEPORT BEFORE ACTIVATING You must update Teleport to trust the new certificate before activating it in the identity provider. Activating before updating Teleport will cause SSO to break. See [How to update the certificate in Teleport](#how-to-update-the-certificate-in-teleport). --- ### Entra ID In Entra ID, SAML signing certificates are managed in the Enterprise Application configuration. #### Create the certificate 1. Log in to Microsoft Entra admin center 2. Navigate to **Enterprise apps** > **All applications**, and select the SAML app ![Entra enterprise applications list](/docs/assets/images/entra-enterprise-apps-b6ca2b64898ecbc0f1fb54f298f711b0.png) 3. Go to **Single sign-on** and scroll to the **SAML Certificates** section, then click the **Edit** button under **Token signing certificate** ![Entra edit SAML certificates](/docs/assets/images/entra-edit-saml-certificates-b8153cc57510d73119fce056d5b04cff.png) 4. Click the **New Certificate** button, then click the **Save** button ![Entra new certificate button](/docs/assets/images/entra-new-certificate-ebda0a74e80adab84ffb8e6cfd621e79.png) 5. Either copy the metadata URL or download the metadata XML, which will be needed to update Teleport: - Scroll to the **SAML Certificates** section of the **Single sign-on** page and copy the metadata URL from the **App Federation Metadata Url** field ![Entra copy metadata URL](/docs/assets/images/entra-copy-metadata-url-93c249c6b9f2810c358f3c9add2c1601.png) - Select the **Download federated certificate XML** item for the new certificate entry to download the metadata XML ![Entra download metadata XML](/docs/assets/images/entra-download-cert-xml-aad2c57f2987b66caa142eb6ac8185da.png) #### Activate the certificate 1. Scroll to the **SAML Certificates** section of the **Single sign-on** page and click the **Edit** button under **Token signing certificate** 2. Find your newly created certificate and select **Make certificate active** ![Entra activate certificate](/docs/assets/images/entra-activate-cert-c83ef6a9b2808aec829025c682dc2aaa.png) 3. When you have confirmed SSO is working, remove the old certificate by selecting **Delete Certificate** ![Entra delete certificate](/docs/assets/images/entra-delete-cert-bcaa24698bab83d19e1af61468ea8d99.png) ### Okta In Okta, SAML signing certificates are managed under the **Sign On** tab for the application. #### Create the certificate 1. Log in to the Okta Admin Console 2. Navigate to **Applications** > **Applications** and select the SAML app ![Okta applications list](/docs/assets/images/okta-applications-d07f392f558035dfdc1753627dcf74fd.png) 3. Go to the **Sign On** tab, scroll to the **SAML Signing Certificates** section and click the **Generate New Certificate** button ![Okta generate new certificate](/docs/assets/images/okta-generate-certificate-33aa5afbffbf15c4967b83e3be770ee4.png) 4. Either copy the metadata URL or download the metadata XML, which will be needed to update Teleport: - Scroll to the **Sign on methods** section and copy the metadata URL from the **SAML 2.0** section ![Okta copy metadata URL](/docs/assets/images/okta-copy-metadata-url-c2987bbf8436c4a3162655b7abd1c08c.png) - Scroll to the **SAML Signing Certificates** section and download the metadata XML from **Actions** > **View IdP metadata** ![Okta view metadata XML](/docs/assets/images/okta-view-metadata-ddef8167dc197675e41f3777dd2c6379.png) #### Activate the certificate 1. Scroll to the **SAML Signing Certificates** section and find your newly created certificate 2. Select **Actions** > **Activate** on the new certificate entry to activate the certificate ![Okta activate certificate](/docs/assets/images/okta-activate-cert-19b958160c7551a5a7649fd181d3d234.png) 3. When you have confirmed SSO is working, remove the old certificate by selecting **Actions** > **Delete** on the old certificate entry ![Okta delete certificate](/docs/assets/images/okta-delete-cert-94b7a0511412e2574eb08e54fa6a5408.png)