Skip to content

The v1 docs follow nauthera-server's main branch and its 0.x releases on the way to 1.0, so fields and APIs can still change.

v1

Rolling Out Nauthera Across a Company

Docs version v1 (main)Nauthera is pre-1.0, in a design-partner programUpdated

Identity is on the path of every sign-in, so roll Nauthera out the way you would a database: in small steps, each reversible, each with someone watching. This page orders the steps; Migration covers the mechanics of moving one application.

An example timeline for a mid-sized company. The pilot and operational readiness run in parallel, and the waves start only when both are done:

Environments

EnvironmentShapeUsed for
LocalThe Quick Start stack, or kind-up from the installation guideApplication teams writing their OIDCClient and trying sign-in
StagingThe production Helm profile at a smaller size: same PostgreSQL and Redis topology, same certificates setup, same alertsThe pilot, every wave's rehearsal, every upgrade's rehearsal
ProductionThe production profile (Operational Requirements)Real users

Give each environment its own issuer URL, keys and database. Nothing should be shared between staging and production, so a staging client can never sign in to production. Keep the manifests the same across environments and change only the values, so what was tested is what ships.

1. Pilot

Pick one application that is internal, has a forgiving user base and a team willing to report problems, and move it in staging, then in production. The pilot is done when it has shown:

  • sign-in, sign-out and, if the app uses them, refresh and logout work end to end (front-channel logout for an OIDCClient, back-channel for a dynamically registered client), through your upstream provider if you federate;
  • the second-factor policy behaves as security expects, including trustMfa;
  • the operator delivers the client's Secret, and a rotation (deleting the Secret) reaches the running application;
  • alerts fire into the right channel, and someone has acknowledged a test page;
  • a database backup has been restored into a scratch environment and served sign-ins;
  • an upgrade to a newer chart version went through staging without downtime;
  • support has handled at least one locked-out user and one lost second factor.

Write down what went wrong. Those notes become the runbook for the waves.

2. Waves

Group the remaining applications, smallest risk first:

  1. Internal tools with few users and no external customers.
  2. Workforce applications that everyone uses daily. These test the sign-in volume and the help desk.
  3. APIs and service-to-service clients (client_credentials), which have no users but break silently. Move the API's token validation first, then its callers one at a time (Migration).
  4. Customer-facing applications, last, once the platform has run for weeks without an incident.

Keep a wave small enough that rolling all of it back would be a normal deploy. Don't change Nauthera itself (an upgrade, a signing-key rotation, a policy change) during a wave.

Go / no-go

Before each wave, check:

  • Every application in the wave has its OIDCClient Ready in production, and has signed in against it in staging.
  • Every API it calls accepts tokens from both issuers.
  • Its accounts exist in Nauthera, or the federated provider is offered for sign-up.
  • Users were told what changes for them, and when.
  • There are no firing alerts, and Nauthera's last upgrade was at least a few days ago.
  • Each application's team is on hand for the cutover, and knows how to roll back.

3. Watching a cutover

For the first hours after an application moves, watch:

SignalWhere
Sign-ins that do not complete, and whyauth.sign_in.completed audit events and their cause, filtered by the client
Federation failuresThe same events with a cause of upstream_denied, upstream_unavailable, upstream_token_invalid or upstream_email_missing, where upstream_error holds the provider's own error code, and the IdentityProvider's status
The application's daily users climbing to what the old provider showedGET /v1/admin/orgs/{slug}/clients/{id}/usage, or the client in the dashboard
Error rate and latencyThe errors and latency alert groups
Lockouts and throttling, which spike when many users reset passwords at onceThe security alert group and Rate Limits & Lockout
Help desk ticketsYour ticketing system, tagged by wave

A wave of invitations or password resets sends a burst of email. Check that the organization's relay accepts the volume, and watch the outbox drain.

Talking to users

Users notice three things, so say them before the wave:

  • the sign-in page looks different (brand it per client with a Branding resource so it looks like the application);
  • they sign in once more, and set a password or a second factor again unless they sign in through the company provider;
  • where to go for help, and what an invitation or reset email will look like, so they don't take it for phishing.

Rolling back

Rollback is per application, and it is the reverse of the cutover: deploy the application with the old provider's issuer, client and secret again. That works for as long as you keep:

  • the old provider's client registered, which Migration says to keep until its refresh tokens have expired;
  • the APIs accepting both issuers;
  • the application's user mapping able to read both sub values.

Users signed in through Nauthera sign in once more at the old provider. Accounts created in Nauthera stay, so moving forward again later needs no new import. Leave the OIDCClient in place during a rollback; its deletionPolicy decides what deleting it would do.

After the last wave

  • Remove the old issuer from every API, and retire the old provider (Migration).
  • Narrow operator.namespaces and the gRPC allowlist to what is now in use.
  • Hand on-call to the steady-state rota, and schedule the first restore drill and the first signing-key rotation.