Skip to main content

Rotate the certificate for SAML Authentication

Only available for Workspaces with single sign-on enabled using SAML authentication

This document outlines the process to rotate the public key certificate used for SAML authentication. This operation requires Administrator privileges.

There can be only one active certificate.

You may experience some authentication downtime while DeployGate and your Identity Provider (IdP) complete the certificate rotation. Please consider this downtime when planning your certificate rotation work.

Rotate the certificate from the Workspace Admin Console

This feature is currently under development. Until it becomes available, please use the Web API as an alternative.

Rotate the certificate via the Web API

Please refer to the API Reference - Update the certificate for SAML authentication document for more details.

Preparation: Obtain the API Key

Please refer to the Admin Guide - Using the Workspace API Key document for information on how to obtain the Workspace's API Key. You can also visit the API Reference guide for details about obtaining a Workspace Administrator’s User API Key. We recommend using the Workspace API Key for the smoothest operations and to avoid permission issues.

1. Download a new public key certificate (X.509 format) from your IdP

Please download a new public key certificate in the X.509 format. Please contact your IdP service for download instructions or assistance.

2. Call the Web API via the command line

The following code sample uses “curl” to call the Web API. If you would like to use “wget” or other commands, please ensure that the “idp_cert” field is a file part instead of the certificate’s content.

curl \
-X PUT \
--url "${Workspace Name}/saml_settings/update_certificate" \
-H "Authorization: Bearer ${API Key}" \
-F "idp_cert=@${Path to the new certificate}"

3. Authenticate

Please check if your account or test accounts can be authenticated through SP-initiated SAML and/or IdP-initiated SAML. DeployGate’s public key certificate rotation process completes if the authentication succeeds without any errors.