AI Prompts

claude mcp add nauthera-docs --transport http https://www.nauthera.io/mcp

I'm evaluating Nauthera (https://www.nauthera.io) as the identity provider for my team. It is a self-hosted OAuth 2.0 and OpenID Connect provider for Kubernetes, whose operator manages each application's OAuth client as an OIDCClient resource.
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links. Do not invent features, fields or endpoints. If the docs don't cover something, say so.
 
Our context (if this repository holds our applications or infrastructure, read it to fill in what I leave out):
- Identity setup today: [e.g. Keycloak, Auth0, Dex, Okta, Entra ID, none]
- Applications that need sign-in or tokens: [e.g. 3 web apps, 2 internal APIs, a CLI]
- Where they run: [e.g. EKS, GKE, on-prem Kubernetes]
- Requirements: [e.g. Google Workspace sign-in, mandatory MFA, passkeys, SAML, SCIM, a tenant per customer]
 
Read the introduction (slug "index", especially "What it does today" and "What it does not do"), https://www.nauthera.io/standards, "operator", "operator-or-dynamic-registration" and "architecture". Then give me:
1. A requirement-by-requirement table: supported, partly supported or not supported, each with the doc page that says so.
2. What we would gain, and what we would have to build, run or give up.
3. The project status exactly as the docs state it, and what it means for our timeline.
4. An outline of moving one representative application of ours to Nauthera.
Be candid. If Nauthera is the wrong fit for us, say so and why.

Help me run Nauthera locally on a kind cluster and complete a first OpenID Connect sign-in.
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links. Do not invent commands, flags or config keys.
 
Follow the Quick Start (slug "quick-start") step by step:
1. Check the prerequisites it lists (Docker, kind, kubectl, Helm, curl, jq) and tell me what's missing on my machine, with the install command for my OS.
2. Pick the newest release from https://www.nauthera.io/downloads, create the cluster, install cert-manager, PostgreSQL and the chart as the guide shows, and save the local CA.
3. Check the discovery document, then guide me through creating an account.
4. Register a client for my own app with an OIDCClient manifest, with redirect URI [http://localhost:5173/callback], and show me where the operator writes its secret.
5. Grant my account the admin role and open the admin dashboard.
Explain each command before you run it. If a step fails, read "troubleshooting" and explain the cause before trying a fix.

Help me install Nauthera on our Kubernetes cluster with its Helm chart, including the operator.
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links. Do not invent chart values, config keys or flags. If the docs don't cover something, say so.
 
Our environment (read this repository for what I leave out):
- Cluster: [e.g. EKS 1.31, kind for a first try]
- Public issuer hostname: [e.g. auth.example.com]
- Ingress or Gateway API: [e.g. ingress-nginx, Gateway API with Envoy Gateway]
- cert-manager: [yes/no]
- PostgreSQL: [managed service or in-cluster]
- Redis: [managed service or in-cluster]
- SMTP relay for email: [provider]
 
Read "installation", "operator", "configuration", "keys-and-secrets" and "security". Then:
1. Summarize the requirements and pick the newest release from https://www.nauthera.io/downloads. The images and chart are public, so no registry credentials are needed.
2. Write a values file for the production profile. Trace every value to the docs. Never put secret values in it: use Kubernetes Secrets the way the docs describe, with placeholders.
3. Check our environment against "What the chart checks for you" before installing.
4. Install, then verify the discovery document, readiness, and that the operator reaches the gRPC AdminService over mutual TLS.
5. Apply a test OIDCClient, and show me its status and the Secret the operator writes.
6. Tell me what to back up and how to upgrade, from "operations".
Explain each command before running it, and ask before anything that changes the cluster.

Add "Sign in with Nauthera" to this application. Nauthera is our OpenID Connect provider.
- Issuer: [https://auth.example.com, or https://auth.example.com/orgs/<slug> for another organization]
- App URL: [https://app.example.com]
- Do we need refresh tokens (the app acts for the user while they're away)? [yes/no]
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links. Do not invent OIDCClient fields or endpoints. If the docs don't cover something, say so.
 
1. Read this repository: language, framework, any existing authentication, and how it is deployed (Kubernetes manifests, Helm, Kustomize).
2. Read "integration", "guides", "oidc-client" and the framework guide that matches ours ("guides/better-auth", "guides/spring-boot", "guides/go", "guides/dotnet"). If none matches, use the framework's established, maintained OpenID Connect library and follow "integration" for the protocol.
3. Write an OIDCClient manifest next to the app's Deployment: authorization_code (plus refresh_token and offline_access only if we need them), exact redirect and post-logout redirect URIs, pkcePolicy required_s256, deletionPolicy Retain. Use private_key_jwt where the matching guide does; otherwise a generated secret, mounted from the Secret the operator writes (keys client-id, client-secret, issuer).
4. Implement sign-in, the callback, sign-out through the end-session endpoint (with id_token_hint and client_id), and the app's session. Configure the library with the issuer and discovery; don't hard-code endpoints.
5. On the callback check state and iss (RFC 9207); validate the ID token's signature, iss, aud, exp and nonce. If we use refresh tokens, store the rotated one every time and never refresh concurrently for the same user.
6. Show me how to run it locally against the Quick Start issuer https://localhost:8443, trusting its local CA, with a client registered by an OIDCClient with a generated secret.
Finish with the checklist at the end of "integration", ticked off against your change, and list anything you could not verify.

Add sign-in with Nauthera to this [single-page / mobile / desktop] app. Nauthera is our OpenID Connect provider at issuer [https://auth.example.com].
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links. Do not invent OIDCClient fields or endpoints. If the docs don't cover something, say so.
 
1. Read this repository: platform, framework, routing, existing authentication.
2. Read "integration" (especially "Pick a client type" and the notes on redirect URIs and consent), "oidc-client", "tokens" and "sessions".
3. Check our redirect URI against what the docs say is supported before writing code. If the usual redirect for our platform (a custom URI scheme, a loopback port) is not supported yet, tell me, and propose the supported alternative, such as an https redirect the app claims.
4. For a browser app, tell me whether a small backend-for-frontend that keeps the tokens out of the browser would be safer for us, and why.
5. Write a public OIDCClient manifest (tokenEndpointAuthMethod none, PKCE S256, exact redirect URIs) and implement the authorization code flow with PKCE using a maintained, certified OpenID Connect library for our platform.
6. Check state and iss on the callback, validate the ID token, handle refresh-token rotation if we use offline_access, and sign out through the end-session endpoint.
Finish with the checklist at the end of "integration" and list anything you could not verify.

Make this API accept access tokens issued by Nauthera.
- Issuer: [https://auth.example.com]
- The API's resource URI, which becomes the token's aud: [https://orders.example.com/]
- Scopes per route: [e.g. GET /orders needs orders:read, POST /orders needs orders:write]
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links. Do not invent claims or endpoints. If the docs don't cover something, say so.
 
1. Read this repository: language, framework and how requests are routed.
2. Read "guides" (especially "Two kinds of application"), step 9 of "integration", "tokens", and the matching guide ("guides/go", "guides/dotnet", "guides/spring-boot") if there is one.
3. Validate tokens locally against the issuer's JWKS with a maintained JWT library: signature with pinned algorithms, typ at+jwt (so an ID token is refused), iss, aud equal to our resource URI in the normalized form the docs describe, exp, and the scope each route needs. Don't call /introspect: the docs explain why it doesn't work for an API.
4. Ask me whether to accept plain bearer tokens or require DPoP-bound tokens (cnf.jkt) as the Go and .NET guides do, and explain the trade-off for our callers.
5. Answer 401 and 403 with the right WWW-Authenticate challenge.
6. Write tests for a valid token, an expired one, the wrong aud, the wrong iss, an ID token instead of an access token, and a missing scope.
7. Recommend an access token lifetime for our callers, given that revocation doesn't reach access tokens yet.

Let this service call [the orders API at https://orders.example.com/] with its own access token from Nauthera, using the client_credentials grant.
- Issuer: [https://auth.example.com]
- Scopes it needs: [e.g. orders:read]
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links. Do not invent OIDCClient fields or endpoints. If the docs don't cover something, say so.
 
1. Read this repository: language, HTTP client, and how the service is deployed.
2. Read "guides" (especially "Keys instead of secrets"), "Machine-to-machine: client credentials" in "integration", "tokens", "oidc-client", and "guides/go" or "guides/dotnet" if they match.
3. Prefer private_key_jwt over a shared secret: an ES256 key whose private half lives in a Kubernetes Secret mounted read-only, and whose public half is published as a JWK set on a public https URL set as spec.jwksUri. The server fetches that URL and refuses loopback and private addresses, so tell me if we can't publish one, and fall back to a generated secret with the trade-off explained.
4. Write the OIDCClient manifest.
5. Request tokens with resource set to the API's URI and the scopes it needs. Cache each token until shortly before it expires; there is no refresh token.
6. If the API requires DPoP, send a proof with every token request and API call, and handle the use_dpop_nonce retry the docs describe.
7. For local development, show the switch the guides describe to a client with a generated secret, registered by an OIDCClient.

Add "log in with Nauthera" to this [CLI / device app] using the OAuth device authorization grant. Issuer: [https://auth.example.com].
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links. Do not invent fields or endpoints. If the docs don't cover something, say so.
 
1. Read this repository: language, how the tool is distributed, where it could store credentials.
2. Read "Devices and CLIs: the device authorization grant" in "integration", "sign-in-flows/consent-and-devices", "tokens" and "oidc-client".
3. Write a public OIDCClient manifest with the urn:ietf:params:oauth:grant-type:device_code grant (plus refresh_token if the tool should stay logged in).
4. Implement the flow: request the codes, show the user_code and verification_uri (and a QR code of verification_uri_complete if the device has a screen), then poll the token endpoint no faster than interval. Keep polling on authorization_pending, add five seconds after slow_down, stop on access_denied or expired_token.
5. Store tokens in the OS keychain or credential store, not in a plain file. Store the rotated refresh token every time and never refresh concurrently.
6. Add a logout command that revokes the refresh token at the revocation endpoint and clears the stored credentials.

Plan and prepare moving our applications' OAuth clients from [Keycloak / Auth0 / Dex / Okta / Entra ID / ...] to Nauthera, declared as OIDCClient manifests.
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links. Do not invent OIDCClient fields or features. If the docs don't cover something, say so.
 
1. Find every OAuth/OIDC client this repository configures: realm exports, Terraform, Helm values, environment variables, application config. Make a table: client, type, grant types, redirect and logout URIs, scopes, authentication method, token lifetimes, custom claims, and which app uses it.
2. Read "index" ("What it does not do"), "oidc-client", "clients", "tokens", "organizations" and "user-management".
3. Map each client to an OIDCClient. Flag everything with no equivalent in Nauthera, citing the page that says so: for example SAML, SCIM, the implicit or password grant, mutual-TLS client authentication, client_secret_jwt, token exchange, custom-scheme redirects, loopback redirects whose port is chosen at run time (a fixed-port loopback redirect works), and custom claim mappers.
4. Write the manifests next to each app's Deployment, and the app config changes: the new issuer, and the client credentials read from the Secret the operator writes.
5. Explain how user accounts would get into Nauthera, from what "user-management" and "sign-in-flows/social-sign-in" describe, and what users would notice (new password, re-enrolling MFA, linking a social account).
6. Write a cut-over plan per application, with the order, how to test it, and how to roll back.
List the open questions I need to answer before we start.

Design how our [customers / business units / environments] map to Nauthera organizations, and prepare the manifests.
 
Our situation: [e.g. B2B SaaS with ~40 customers, some bring their own Entra ID or Google Workspace; each customer has its own subdomain]
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links. Do not invent fields or features. If the docs don't cover something, say so.
 
1. Read "organizations", "organization-resource", "identity-provider-resource", "oidc-client", "mfa", "branding-resource" and "email".
2. Explain the model as the docs describe it: each organization other than the main one is its own issuer under /orgs/<slug>, and the main organization's issuer is the root URL; each has its own keys, a client belongs to exactly one organization, and sessions never cross organizations.
3. Compare one organization per tenant with one shared organization for our case, and recommend one.
4. Write the Organization manifests, and for tenants that bring their own provider, the IdentityProvider manifests, with secrets referenced from Kubernetes Secrets.
5. Show the change in our application (read this repository) that picks the right issuer and client per tenant, and how it validates tokens from several issuers safely.
6. List what each new tenant needs at onboarding, as a checklist we can automate.

Set up how users sign in to [our app / our organization] in Nauthera.
What I want: [e.g. "Sign in with Google" for employees, mandatory second factor outside the office network, passkeys allowed, no SMS]
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links. Do not invent fields or features. If the docs don't cover something, say so plainly.
 
1. Read "mfa", "sign-in-flows/social-sign-in", "sign-in-flows/passkeys", "sign-in-flows/second-factor", "identity-provider-resource", "organization-resource" and "oidc-client".
2. Explain how the deployment, organization and client policies combine (each can only tighten the one above), and where each of my wishes belongs.
3. Write the manifests: IdentityProvider (with its client secret from a Kubernetes Secret and the redirect URI to register at the provider), the organization's policy and network zones, and the client's identityProviders and secondFactor.
4. List the server configuration each piece needs, such as the passkey relying-party ID or enabling registration.
5. Describe what a user sees in each case: first sign-in, sign-in from the office, from a new network, and losing their authenticator.
Tell me which of my wishes Nauthera can't meet today.

Review how this repository integrates with Nauthera, as a security reviewer.
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links. Judge against what the docs say, and cite the page for each finding.
 
1. Find every place the code or manifests touch Nauthera: OIDCClient manifests, OIDC library config, token validation, session handling, logout, secret handling.
2. Read "integration" (especially its checklist), "guides" (the threat table in "The setup these guides use"), "tokens", "oidc-client", "sessions" and "security".
3. Check at least: the issuer and organization; exact redirect URIs; PKCE S256; state, iss and nonce checks; full ID token validation; in APIs, local validation with typ at+jwt, aud, iss, exp and scope; refresh-token rotation and no concurrent refreshes; access-token lifetimes; secrets never in Git, images or logs; private_key_jwt or DPoP where the guides recommend them; logout through the end-session endpoint; deletionPolicy on each OIDCClient.
4. Report findings ranked by severity, each with the file and line, why it matters, and the fix. Mark anything you could not confirm from the code.
Don't change code until I've seen the report.

Help me find out why this Nauthera [sign-in / token request / refresh / OIDCClient] fails.
 
What I see (redact secrets, tokens and codes first):
[the error page or response body, the request URL without secrets, `kubectl describe oidcclient <name>` output, and server or app logs]
 
Source of truth: the Nauthera docs. If the nauthera-docs MCP server is connected, use its search-docs and get-doc tools; otherwise fetch https://www.nauthera.io/llms.txt and the .md pages it links.
 
1. Read "troubleshooting" (error formats, problem codes, common problems), "sign-in-flows/errors", and the pages for the step that fails ("integration", "oidc-client", "operator", "tokens").
2. Read the relevant code and manifests in this repository.
3. Give me ranked hypotheses. Consider at least: a redirect URI that doesn't match exactly, the wrong issuer or organization path, a missing or wrong PKCE verifier, a code reused or redeemed too late, a refresh token used twice, a client the operator reports as Refused, a Secret the operator couldn't deliver, a clock skew, and a captcha or rate limit.
4. For each hypothesis, tell me how to confirm it (a command, a log field such as the trace ID, a status field) before changing anything.
5. Then give the fix for the confirmed cause, and how to keep it from coming back.

## Nauthera
 
This project uses Nauthera (https://www.nauthera.io), a self-hosted OAuth 2.0 / OpenID
Connect provider for Kubernetes, as its identity provider.
 
- Issuer: https://auth.example.com
- OAuth clients are declared as OIDCClient resources (nauthera.io/v1alpha1) next to each
  app's Deployment. The operator registers them and writes client secrets into a
  Kubernetes Secret (keys client-id, client-secret, issuer). Never commit a secret.
- Before writing auth code or manifests, read the docs: use the nauthera-docs MCP server
  (search-docs, get-doc), or https://www.nauthera.io/llms.txt and the .md pages it links.
  For a whole task, such as adding sign-in or protecting an API, start from its prompt
  (list-prompts, get-prompt).
  Key pages: https://www.nauthera.io/docs/v1/integration.md,
  https://www.nauthera.io/docs/v1/oidc-client.md, https://www.nauthera.io/docs/v1/tokens.md.
- Don't invent OIDCClient fields, endpoints or config keys. If the docs don't cover it,
  say so.
- Always: PKCE S256, exact redirect URIs, check state and iss on the callback, validate
  access tokens locally (typ at+jwt, iss, aud, exp, scope), store each rotated refresh
  token and never refresh concurrently for one user.