External sign in

People can sign in to your service with an account they already have. Connections live under Sign in, Connections in the dashboard.

Connection	What you need
Google	A client ID and secret from Google Cloud
GitHub	A client ID and secret from a GitHub OAuth app
OpenID Connect	The provider's discovery URL, plus a client ID and secret
OAuth 2.0	The authorization, token and userinfo endpoints, a client ID and secret, and which userinfo fields hold the subject, email and name

You bring your own client credentials, so the consent screen at the provider shows your app's name. MicroAuth stores the secret encrypted.

A service can have up to 20 connections, with at most one Google and one GitHub. For OpenID Connect, MicroAuth reads the discovery document when you save the connection and answers 422 when it can't use it. For OpenID Connect and OAuth 2.0 you can also choose how MicroAuth sends the client secret to the provider's token endpoint: with HTTP Basic or in the form. OAuth 2.0 uses HTTP Basic unless you change it, and OpenID Connect picks one the discovery document lists.

Which connections a plan includes is on the pricing page.

Set up a connection

1. At the provider, create an OAuth app. When it asks for a callback or redirect URL, paste the one the dashboard shows for the connection. It looks like https://acme.microauth.dev/oauth/callback/<connection>.
2. In the dashboard, add the connection and paste the client ID and secret.
3. Turn it on. A button for it appears on your sign in and sign up pages.

If your service also runs on a custom domain, register the callback URL on that domain at the provider too. The dashboard lists the callback URL for every address your service has.

Turning a connection off hides its button, and people who connected it keep the link for when you turn it back on. Deleting a connection unlinks everyone who connected it. Anyone left with no other way to sign in can still reset their password by email.

How accounts are linked

• Someone whose provider account is already linked simply signs in.
• When the provider says the email address is verified, and the MicroAuth account with that email has a verified email too, the provider account links to it and the person gets an email about it. An account whose own email was never verified isn't linked, so nobody can create an account with someone else's address ahead of time and take over their provider sign in later.
• Which emails count as verified:
  • Google: when Google's ID token says email_verified is true.
  • GitHub: the primary email, when GitHub marks it verified.
  • OpenID Connect: only with Trust emails on, and never when the ID token says email_verified is false.
  • OAuth 2.0: only with Trust emails on.
• When an account with that address already exists but either email isn't verified, nothing is linked. The person signs in the usual way first, then connects the provider from Account, Security.
• Otherwise a new account is created, with your default roles. The sign up mode and your plan's user limit still apply. When the provider didn't verify the email, the new account's email starts out unverified.

Only turn on Trust emails for a provider that checks email addresses itself. Otherwise anyone who can create an account there with someone else's address could sign in as them.

When someone proves they own an account's unverified email, by resetting its password or by recovering the account with an emailed code, the email becomes verified and any provider links that came with an unverified email are removed.

Each account can have one linked account per connection, and a provider account can be linked to only one account in your service.

Two step verification

A provider doesn't replace two step verification. When someone with an authenticator app turned on signs in with a provider, they enter an authenticator code or a recovery code next. A passkey isn't offered for this step.

Connected providers

People see their linked providers under Account, Security. Connecting one or removing one asks them to confirm it's them first, and they get an email about each change. After connecting one, they come back to Security with a note that it worked.

When a sign in with a provider fails, the error page offers the step that fits: back to Security when they were connecting a provider, to their account when they're already signed in, or back to sign in otherwise.

Removing a provider needs another way to sign in, so nobody locks themselves out:

• A password counts while password sign in is on for your service.
• A passkey counts while passkey sign in is on.
• Another provider counts while its connection is on and your plan includes it.

A provider whose connection you turned off, or that your plan no longer includes, can always be removed.

What the flow protects

• The state, nonce and PKCE verifier of each external sign in stay on MicroAuth's side, bound to a short lived cookie in the person's browser.
• ID tokens from OpenID Connect providers are verified before anything is trusted. Plain OAuth 2.0 providers are read through their userinfo endpoint.
• Calls to providers only reach public addresses.