# Adopting Nauthera

> A guide for companies bringing Nauthera in: what to decide first, fitting next to an existing identity provider, migration, ownership, rollout and operations.

The rest of these docs describe what Nauthera does. This section is about bringing it
into a company: the decisions to make before the first install, the teams that need to
be involved, and the order to do things in so that no application loses its sign-in
along the way.

> Nauthera is pre-1.0, in a design-partner program: its signed server and operator images and its Helm chart are public on the GitHub Container Registry, and teams can apply for one of five design-partner seats to pilot it with direct support. The source is private. Use these guides to plan an adoption and run a pilot, and check
> each page's limits against your requirements before you commit a production date.

## The guides

| Guide | Answers |
|---|---|
| [Existing Identity Providers](https://www.nauthera.io/docs/v1/adoption/existing-identity-providers) | We already have Entra ID, Okta or Google Workspace. Do we replace it, or put Nauthera in front of it? |
| [Migration](https://www.nauthera.io/docs/v1/adoption/migration) | How do we move applications, clients and users off another OpenID provider without a big-bang cutover? |
| [Ownership](https://www.nauthera.io/docs/v1/adoption/ownership) | Which team runs the server, who declares clients, who administers users, and how are those boundaries enforced? |
| [Rollout](https://www.nauthera.io/docs/v1/adoption/rollout) | In which order do we move environments and applications, how do we know a stage is done, and how do we roll back? |
| [GitOps & Argo CD](https://www.nauthera.io/docs/v1/adoption/gitops) | How do we run all of this from Git with Argo CD, and how should the repositories and Argo CD projects be laid out? |
| [Operational Requirements](https://www.nauthera.io/docs/v1/adoption/operational-requirements) | What infrastructure, secrets, monitoring, backups and on-call does a production deployment need? |

## Decisions to make first

Most of these are hard or impossible to change later, so settle them before the first
production install.

| Decision | Why it matters | Where it is set |
|---|---|---|
| **The issuer URL** | It is in every token, every application's configuration and every provider's redirect URI. Changing it means reconfiguring every client. Pick a hostname you will keep, such as `https://auth.example.com`. | `issuer.url` |
| **Organizations** | Each organization is its own issuer, user base and set of signing keys, and users and sessions never cross them. One organization for the workforce, one per customer tenant, or a single one for everything. | [Organizations](https://www.nauthera.io/docs/v1/organizations) |
| **FIPS mode** | Fixed when an organization is created. It changes how passwords are hashed and needs a FIPS build. | [FAPI and FIPS mode](https://www.nauthera.io/docs/v1/organizations#fapi-mode-and-fips-mode) |
| **Where users come from** | Federated from an identity provider you already run, created and invited by administrators, signing themselves up, or a mix. | [Existing Identity Providers](https://www.nauthera.io/docs/v1/adoption/existing-identity-providers) |
| **How clients are registered** | The [operator](https://www.nauthera.io/docs/v1/operator) for applications on Kubernetes, `nauthera-cli` for the rest, and dynamic registration only for software you don't deploy. | [Operator or Dynamic Registration?](https://www.nauthera.io/docs/v1/operator-or-dynamic-registration) |
| **Who holds the platform role** | `platform-owner` in the main organization can act in every organization. Decide who holds it, and how few. | [Ownership](https://www.nauthera.io/docs/v1/adoption/ownership) |
| **Second-factor policy** | The deployment's policy is the ceiling every organization and client can only tighten. | [Multi-Factor Authentication](https://www.nauthera.io/docs/v1/mfa) |

## What Nauthera does not cover

Check these against your requirements early, because each one can rule an application or
an integration out:

- **No SAML**, in either direction. Applications that speak only SAML, and upstream
  providers that offer only SAML, cannot be connected.
- **No SCIM provisioning.** Users are not pushed from or to a directory; they are
  created by an administrator, by signing up, or on their first sign-in through a
  federated provider. Deprovisioning is covered in
  [Existing Identity Providers](https://www.nauthera.io/docs/v1/adoption/existing-identity-providers#leavers-and-deprovisioning).
- **No password write-back to LDAP or Active Directory.** An
  [LDAPDirectory](https://www.nauthera.io/docs/v1/ldap-directory-resource) signs users in with their directory
  password, but the server only reads the directory: passwords are set, reset and
  expired there.
- **No import of password hashes.** Users moved from another system set a new password,
  or sign in through a federated provider. See [Migration](https://www.nauthera.io/docs/v1/adoption/migration#users).
- **No mutual-TLS client authentication, token exchange or JWT bearer grant.** See
  [What it does not do](https://www.nauthera.io/docs/v1#what-it-does-not-do) and the [standards page](https://www.nauthera.io/standards).

## A typical path

```mermaid
flowchart LR
  D[Decide] --> P[Pilot] --> O[Get ready] --> W[Waves] --> R[Retire]
```

1. **Decide** the items above, and write down who owns each part
   ([Ownership](https://www.nauthera.io/docs/v1/adoption/ownership)).
2. **Pilot** one low-risk application in a non-production environment, federated to your
   existing identity provider if you have one.
3. **Get operationally ready**: backups that have been restored once, alerts that page
   someone, an upgrade rehearsed ([Operational Requirements](https://www.nauthera.io/docs/v1/adoption/operational-requirements)).
4. **Move applications in waves**, each with a rollback ([Rollout](https://www.nauthera.io/docs/v1/adoption/rollout)).
5. **Retire** the old provider's clients once nothing signs in through them
   ([Migration](https://www.nauthera.io/docs/v1/adoption/migration#retiring-the-old-provider)).