# Renew SSO Credentials

<EnterpriseFeature name="Single Sign On" />

Your SSO connection authenticates Zuplo to your identity provider with a
credential that you create and own:

- An OIDC or OAuth2 **client secret**, for connections that use OpenID Connect.
- A **SAML signing certificate**, for connections that use SAML.

Both kinds expire. When one expires, the identity provider stops accepting the
sign-in request, and everyone who signs in to Zuplo through that connection is
locked out until you replace the credential.

Renewing the credential is your responsibility. Zuplo can't create a credential
in your identity provider or extend the expiry date of an existing one.

## Nothing reminds you automatically

Most identity providers notify you about a narrower set of credentials than
administrators expect:

- **Microsoft Entra ID** sends automatic expiry email for SAML signing
  certificates on enterprise applications. It doesn't send email about client
  secrets on app registrations.
- **Auth0**, which Zuplo uses to broker enterprise SSO, sends email about an
  expiring SAML certificate on a connection. It doesn't send email about an
  expiring OIDC client secret.

If your connection uses a client secret, assume that no one notifies you. Record
the expiry date when you create the secret and set your own reminder.

## What an expired credential looks like

Sign-in fails for every user on the connection, and the failure happens at your
identity provider before the user returns to Zuplo. With Microsoft Entra ID, the
error names the app registration:

```
The provided client secret keys for app '<app-id>' are expired.
```

Other providers word it differently. Look for `invalid_client` from an OIDC
provider, or a message about an expired or untrusted certificate from a SAML
provider.

Two signals point at credential expiry rather than a configuration change:
sign-in worked until a specific date, and the failure affects every user on the
connection at once.

## Renew a credential before it expires

While you can still sign in to Zuplo, rotate the credential yourself:

<Stepper>

1. In your identity provider, create a new client secret or signing certificate
   for the application that Zuplo connects to. Keep the old credential active
   until the new one works.
1. Open
   [**Account Settings → Security**](https://portal.zuplo.com/+/account/settings/security)
   in the Zuplo Portal and click "Edit Connection" in the "Single Sign On (SSO)"
   section. See [Edit Single Sign On](./enterprise-sso.mdx#edit-single-sign-on)
   for details.
1. Enter the new client secret or upload the new certificate, then save the
   connection.
1. Sign out and sign back in to Zuplo to confirm the connection works.
1. Remove the old credential from your identity provider.

</Stepper>

## Recover from a credential that has already expired

:::caution

If your account requires enterprise SSO, an expired credential locks out every
user, including administrators. Nobody can reach **Account Settings → Security**
to fix the connection, so this case isn't self-serve.

:::

<Stepper>

1. In your identity provider, create a new client secret or signing certificate
   for the application that Zuplo connects to.
1. Email [support@zuplo.com](mailto:support@zuplo.com) and tell them that your
   SSO credential expired. Zuplo can issue a self-service SSO link that lets you
   update the connection without signing in to the Zuplo Portal.
1. Open the link, enter the new credential, and save the connection. Make sure
   the connection is still enabled.
1. Sign in to Zuplo to confirm that the connection works.
1. Remove the old credential from your identity provider.

</Stepper>

## Stay ahead of the next expiry

- **Set a calendar reminder** for 30 days before the expiry date, on a shared
  team calendar rather than one person's. Credential lifetimes outlast staff
  changes.
- **Choose a shorter lifetime**, such as six or twelve months, instead of the
  longest one your provider offers. Frequent rotation keeps the procedure
  familiar and documented, and a two-year secret usually expires long after
  everyone who set it up has forgotten it exists.
- **Prefer a certificate credential over a client secret** when your provider
  supports it. Microsoft Entra ID treats certificates as the more secure
  credential type for app registrations.
- **Rotate with an overlap.** Most providers let you hold two active credentials
  at once, so you can add the new one, switch Zuplo over, verify sign-in, and
  then delete the old one without downtime.
- **Monitor expiry dates** with the tools your provider gives you. The next
  section links to them.

## Provider documentation

Each provider manages and monitors its own credentials. Use their documentation
for the exact steps.

**Microsoft Entra ID**

- [Add and manage app credentials](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials)
  — add a client secret or certificate to an app registration.
- [Renew expiring application credentials recommendation](https://learn.microsoft.com/en-us/entra/identity/monitoring-health/recommendation-renew-expiring-application-credential)
  — flags app-registration credentials that expire within the next 30 days.
  Requires a Microsoft Entra Workload ID license.
- [Export app registrations with expiring secrets and certificates](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/scripts/powershell-export-apps-with-expiring-secrets)
  — a PowerShell sample that reports expiring credentials across your tenant.

**Okta**

- [Manage secrets and keys for OIDC app client authentication](https://help.okta.com/oie/en-us/content/topics/apps/oauth-client-cred-mgmt.htm)
- [Manage signing certificates](https://help.okta.com/en-us/content/topics/apps/manage-signing-certificates.htm)

**Google Workspace**

- [Maintain SAML certificates](https://support.google.com/a/answer/7394709)

For any other identity provider, look for the credential management page of the
application you created for Zuplo.