Clients

An OAuth client belongs to exactly one organization. Today there are two ways to register one, with a third on the way.

#Through the AdminService

UpsertOIDCClient is a declarative, idempotent full replace with an etag for optimistic concurrency. When the spec asks for a secret (secret.generate), the server generates one, stores only its argon2id hash, and returns the plaintext once, in the response to the upsert that created it.

On a local stack, nauthera-cli drives the same RPC:

go run ./cmd/nauthera-cli create client my-app \
  --redirect-uri https://app.example.com/callback \
  --post-logout-redirect-uri https://app.example.com/ \
  --scopes openid,profile,email,offline_access \
  --grant-types authorization_code,refresh_token \
  --pkce required_s256

nauthera-cli talks to the AdminService over plaintext gRPC, so the server must have server.grpc.allow_insecure: true. It is a development tool, not a way to manage production.

#Dynamic client registration

POST /register implements RFC 7591. Each registration must present an initial access token: a bearer token for the target organization that carries the nauthera.clients:register scope. The response includes a registration_access_token and a registration_client_uri for RFC 7592 management. Store the token from the registration response: read and update responses do not return it again (#78).

curl -s https://auth.example.com/register \
  -H "Authorization: Bearer $INITIAL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "client_name": "My App",
        "redirect_uris": ["https://app.example.com/callback"],
        "grant_types": ["authorization_code"],
        "response_types": ["code"],
        "token_endpoint_auth_method": "client_secret_basic",
        "scope": "openid profile email"
      }'

The registration policy is fixed in code and cannot be loosened by configuration:

• Initial access token: always required. It is what binds the new client to an organization.
• Scopes: only openid, profile and email. offline_access is deliberately excluded, so a self-registered client gets no refresh tokens and has to come back through /authorize with a live session. Any nauthera.* scope is refused outright.
• Grant types: authorization_code and refresh_token.
• PKCE: required_s256 by default.
• Redirect URIs: at most 8.

Back-channel logout URIs (backchannel_logout_uri) can be registered only this way. A client's display name is checked for characters built to be misread, and suspicious names are recorded in the audit log.

#Client settings

#Redirect URIs

Redirect URIs are matched exactly, with no wildcards and no prefix matching. Two relaxations that native apps need are not supported yet: any port on a loopback redirect (#84) and private-use URI schemes (#87).

#Secrets

Rotating a secret currently means deleting the client and creating it again. Rotation in place is tracked in #351.

#Scopes

Besides openid, profile, email and offline_access, the server reserves the nauthera. prefix for its own resource scopes. These can be granted only to clients registered through the gRPC AdminService. Dynamic registration refuses them.

Admin scopes also need a matching RBAC role. See Admin API & Users.