Sign your app's users in with GitHub or Google
Put a “Sign in with GitHub” button on your app’s own login page. The visitor authenticates with the provider, comes back, and gets the same application session a password login gives. No password is stored and none is needed.
The platform does the protocol work (state, browser binding, code exchange, the session). Your rules make the one decision that belongs to you: which identity record, if any, this provider account signs in as. The platform never creates or links an account on its own.
Supported providers are github and google. The steps below use GitHub; for Google, register a Google OAuth client and use google wherever github appears.
You need an identity model and a session model on the application first (see authentication-basics). A login-submission model is only needed if you also keep a password form.
1. Create the two browser endpoints
Section titled “1. Create the two browser endpoints”The provider leg starts and ends on two public inbound services. Create both; they differ only by name:
POST /api/v1/applications/{application_id}/services{ "name": "Sign-in start", "service_type": "webhook_in", "base_url": "https://example.invalid", "auth_type": "none", "settings": {"public": true}}settings.public must be true: a browser following a redirect sends no API key, and without it an anonymous request answers 404. base_url is required by the service shape and is not used for inbound traffic. Keep both service ids. The second one is the callback service.
2. Register the application with the provider
Section titled “2. Register the application with the provider”The redirect address the provider must allow is on your application’s public origin (its custom domain, or its platform subdomain):
<application origin>/api/v1/services/<callback service id>/inboundFor GitHub: Settings, Developer settings, OAuth Apps, New OAuth App. Set the homepage to the application origin and the authorization callback URL to the address above, then generate a client secret. The sign-in requests the read:user and user:email scopes.
3. Store the provider credentials
Section titled “3. Store the provider credentials”One more service holds the client id and secret. auth_config is encrypted at rest and never returned:
{ "name": "GitHub sign-in credentials", "service_type": "rest", "base_url": "https://github.com", "auth_type": "oauth2", "auth_config": {"client_id": "<client-id>", "client_secret": "<client-secret>"}, "settings": {"oauth_provider": "github", "callback_service_id": "<callback-service-uuid>"}}settings.oauth_provider names the provider and settings.callback_service_id ties the credentials to the callback endpoint from step 1. Use one credentials service per provider.
4. Provision the identity that may sign in
Section titled “4. Provision the identity that may sign in”Self-registration can stay off. Create the identity record yourself with an authorized call; an identity created without a password can only sign in through a provider:
POST /api/v1/public/applications/{application_id}/models/{identity_model_id}/records{"data": {"email": "owner@example.com", "display_name": "Owner"}}Keep the record id. Step 6 signs this record in.
5. Start rule: send the visitor to the provider
Section titled “5. Start rule: send the visitor to the provider”Rules on an inbound service use the webhook_received trigger and are tied to the service with scope. This rule answers the start endpoint with a redirect to the provider:
POST /api/v1/applications/{application_id}/rules{ "name": "Sign-in: send the visitor to GitHub", "trigger": "webhook_received", "phase": "response", "scope": {"service_config_id": "<start-service-uuid>"}, "condition": {"==": [1, 1]}, "actions": [{"type": "begin_oauth_authorization", "provider": "github", "return_to": "/"}]}return_to is where the visitor lands after signing in. It must be a root-relative path or a URL on the application’s own origin. The action also sets a short-lived, HttpOnly browser-binding cookie, so the flow can only be finished by the browser that began it.
6. Callback rules: redeem the code, then decide
Section titled “6. Callback rules: redeem the code, then decide”Three rules on the callback service. The first redeems the provider’s answer in the post_save phase:
{ "name": "Sign-in callback: redeem the code", "trigger": "webhook_received", "phase": "post_save", "scope": {"service_config_id": "<callback-service-uuid>"}, "condition": {"==": [1, 1]}, "actions": [{"type": "exchange_oauth_code", "provider": "github"}]}A successful exchange leaves one row for the response phase to read:
| Key | Meaning |
|---|---|
query_rows.0.provider |
The provider name. |
query_rows.0.provider_subject |
The provider’s stable account id. Decide on this, not on the email. |
query_rows.0.email, query_rows.0.email_verified |
The provider-asserted email. GitHub reports only a verified primary address. |
query_rows.0.display_name |
The provider’s display name, or null. |
A refused exchange (expired or replayed state, another browser, a provider error) leaves query_rows empty.
The second rule signs the visitor in when the account is the one you allow. identity_record_id is the record from step 4:
{ "name": "Sign-in callback: sign the owner in", "trigger": "webhook_received", "phase": "response", "scope": {"service_config_id": "<callback-service-uuid>"}, "condition": {"==": [{"var": "query_rows.0.provider_subject"}, "<allowed-provider-account-id>"]}, "actions": [{"type": "mint_oauth_login_code", "identity_record_id": "<identity-record-uuid>"}]}The third turns everyone else away, including a refused exchange:
{ "name": "Sign-in callback: refuse everyone else", "trigger": "webhook_received", "phase": "response", "priority": 1, "scope": {"service_config_id": "<callback-service-uuid>"}, "condition": {"!=": [{"var": "query_rows.0.provider_subject"}, "<allowed-provider-account-id>"]}, "actions": [{"type": "redirect", "to": "/denied"}]}mint_oauth_login_code takes only identity_record_id, and the record must belong to the application’s identity model. It redirects the browser to the application’s exchange route, which issues the session (the same cookies, session record and login_succeeded event as a password login) and then lands on return_to. The code is single-use, expires after two minutes, and is bound to the browser that began the flow.
GitHub’s numeric account id is public: https://api.github.com/users/<login> returns it as id.
7. Add the button and protect the pages
Section titled “7. Add the button and protect the pages”The login page needs only a link to the start endpoint. Publish it at the login slug, because an unauthenticated request for a protected page is sent there:
{ "id": "github-sign-in", "type": "button", "content": {"label": "Sign in with GitHub", "href": "/api/v1/services/<start-service-uuid>/inbound"}}Give each private page the setting {"requires_auth": true}, and publish a plain denied page for the refusal in step 6.
For the signed-in visitor to read or change records through page blocks, set the model’s consumer_reads and consumer_writes policies (see row-level-security). A model without them grants a signed-in visitor nothing.
More than one user
Section titled “More than one user”The rules above admit one fixed account, which suits a private tool. To admit many, store each person’s provider account on their identity record (for example a unique provider_key field holding github:<provider_subject>), have the callback look the identity up by that key, and pass the matching record’s id to mint_oauth_login_code. Send a visitor with no matching identity to a refusal or sign-up page. Match on provider_subject; an email can be reassigned by the provider’s user.
Checking it
Section titled “Checking it”Open a protected page signed out: you should land on the login page, and the button should take you to the provider. After approving, you should land on return_to signed in. The rule logs of the three callback rules show which one matched, and the session model holds one new active record. Tokens, codes and the client secret do not appear in rule data, rule logs or service logs.
