Quickstart

This guide takes you from Setup to a first OIDC sign-in. Deployment time depends on resource creation, builds, DNS, and the selected features.

1. Prepare the source

Use Node.js 22.18+ (22.x) or 24.11+, pnpm 9, Git, and a Cloudflare account with the necessary permissions. Use the release source you intend to evaluate.

git clone https://github.com/sgrastar/authrim.git
cd authrim
pnpm install
pnpm exec wrangler login

2. Run Setup

pnpm run setup init --env dev --lang en

For terminal-only setup, add --cli. Follow the prompts for domains, resources, email, and administrative access, and complete deployment. Preserve the generated environment state and keys.

This creates a deployed evaluation environment. Starting pnpm run dev afterwards is not required to access it. Local development is a separate workflow described in Installation.

3. Verify Discovery

Use the actual issuer URL reported for your tenant. Replace the example below; do not substitute the Admin UI URL.

AUTHRIM_ISSUER='https://auth.example.com'
curl --fail --silent --show-error \
  "$AUTHRIM_ISSUER/.well-known/openid-configuration"

Verify issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, and jwks_uri. Fetch the returned jwks_uri to confirm that signing keys are published. Use the discovered endpoints in your client instead of constructing URLs from assumptions about domains or paths.

4. Register an application

Open the Admin UI URL reported by Setup and finish the initial administrator flow. In the intended tenant, create an OIDC client with:

Setting	Example
Application	SPA, mobile, or server application matching your implementation
Grant	Authorization Code
Redirect URI	The exact callback of your application, such as http://localhost:3000/callback for local evaluation
Scopes	openid; add profile and email only when needed
PKCE	S256
Client authentication	Public clients do not embed a secret; server clients use their configured authentication method

Use the issued client ID. test-client is not an automatically provisioned client. Ensure a usable authentication method and, for email codes, actual delivery are configured.

5. Test sign-in from the application

Configure an OIDC library or an Authrim SDK with the issuer, client ID, and callback. Start Authorization Code with PKCE using a fresh verifier/challenge and fresh state and nonce values. On return, validate the response and exchange the code using the same redirect URI and verifier.

A fixed URL with a made-up client ID and constant state is not a complete sign-in test. Confirm both successful sign-in and rejection of a mismatched state or redirect URI in your application.

If a step fails

pnpm run setup status --env dev
pnpm run setup info --env dev

Check the tenant issuer, deployment status, redirect URI, client type, and email/provider configuration. For detailed installation and update guidance, see Installation.