Social login

Let users sign in with Google, GitHub, Microsoft, or any OpenID Connect provider — alongside, or instead of, email and password. You register an app with the provider, hand agentry the client ID and secret, and a sign-in button appears.

Make sure authentication is enabled first (agentry auth enable with a database bound).

The one URL you'll register everywhere

Every provider asks for a callback URL (sometimes called "redirect URI" or "authorization callback URL"). For agentry it's always:

https://<your-app-host>/auth/oauth/<provider>/callback

<your-app-host> is wherever people sign in — your deployment URL or your custom domain — and <provider> is google, github, microsoft, or generic-oidc. For example:

https://my-app-3f7e2a1c.agentry.live/auth/oauth/google/callback
https://app.yourcompany.com/auth/oauth/github/callback

Register every host you sign in from

The callback uses whatever host the visitor arrived on. If users will sign in at both your *.agentry.live URL and a custom domain, register the callback for each one in the provider's console.

Add a provider

agentry auth providers add <provider> \
  --client-id <CLIENT_ID> \
  --client-secret <CLIENT_SECRET>

agentry checks that the provider is reachable and the credentials are well-formed (so a typo fails now, not at a user's first login), stores the config for the current server + profile, and prints the exact callback URL to register. Then redeploy your app so it picks up the new provider.

List or remove providers any time:

agentry auth providers list
agentry auth providers remove google

Google

1. In the Google Cloud Console, create an OAuth 2.0 Client ID of type Web application.
2. Under Authorized redirect URIs, add: https://<your-app-host>/auth/oauth/google/callback
3. Copy the Client ID and Client secret.
4. Register it:

agentry auth providers add google \
  --client-id 12345.apps.googleusercontent.com \
  --client-secret GOCSPX-...

Default scopes: openid email profile. Users are asked which Google account to use on each sign-in.

GitHub

1. On GitHub: Settings → Developer settings → OAuth Apps → New OAuth App.
2. Set Authorization callback URL to: https://<your-app-host>/auth/oauth/github/callback
3. Copy the Client ID, generate a Client secret, and register:

agentry auth providers add github \
  --client-id Iv1.abc123 \
  --client-secret <secret>

GitHub private emails

If a user keeps their primary email private on GitHub, GitHub may not return it, and an account can't be created without an email. Ask such users to make their email public, or to sign in with email/password or another provider instead.

Microsoft (Entra ID / Azure AD)

1. In the Azure Portal: App registrations → New registration.
2. Add a Web redirect URI: https://<your-app-host>/auth/oauth/microsoft/callback
3. Copy the Application (client) ID and create a client secret.
4. Register. By default agentry uses Microsoft's multi-tenant sign-in (any work/school or personal account):

agentry auth providers add microsoft \
  --client-id <app-id> \
  --client-secret <secret>

To restrict to a single tenant, pass that tenant's issuer:

agentry auth providers add microsoft \
  --client-id <app-id> --client-secret <secret> \
  --issuer https://login.microsoftonline.com/<TENANT-ID>/v2.0

Any OpenID Connect provider (Okta, Keycloak, Authentik, …)

Use generic-oidc and point it at your provider's issuer URL. agentry reads the provider's /.well-known/openid-configuration to discover the rest.

1. Create an OIDC client in your provider, redirect URI: https://<your-app-host>/auth/oauth/generic-oidc/callback
2. Register:

agentry auth providers add generic-oidc \
  --client-id my-client \
  --client-secret <secret> \
  --issuer https://keycloak.example.com/realms/myrealm

Default scopes: openid email profile. Override with --scopes "openid email profile groups" if your provider needs more.

Apple

Sign in with Apple isn't available yet — it needs a verification flow that's still in progress. Use Google, GitHub, Microsoft, OIDC, or email/password in the meantime.

Custom scopes

Any provider accepts --scopes to request more than the defaults:

agentry auth providers add google \
  --client-id ... --client-secret ... \
  --scopes "openid email profile https://www.googleapis.com/auth/calendar.readonly"

How it fits together

However a user signs in — email/password or any provider — your app sees the same identity headers (X-Forwarded-Email, X-Forwarded-User, and X-Forwarded-Provider telling you which method they used). You don't write provider-specific code. See reading the signed-in user.

Next

• Email & password — the built-in account system social login sits alongside.
• Custom domains — remember to register its callback URL too.