Social sign-in

Introduction

Featuresocial Many people would rather click "Continue with Google" than invent another password. navree-social adds that button to your app without changing how the rest of it works: a social sign-in ends with the same Navree user and the same access and refresh tokens as a password login, so every route, permission and audit entry behaves as before.

It covers the whole flow:

• Providers: Google, GitHub, Apple, Microsoft, GitLab (including self-hosted), Slack, LinkedIn, Discord and X built in, any OpenID Connect provider by its issuer URL, and your own through a trait.
• A safe redirect: the state parameter is sealed with your application key and carries a PKCE verifier and, for OpenID Connect, a nonce. It expires after 10 minutes and works once.
• Verified identities: ID tokens are checked against the provider's published keys (signature, issuer, audience, expiry and nonce) before Navree trusts them.
• Linked accounts: one user can sign in with a password, GitHub and Google. Accounts are linked automatically only when the provider has verified the email address.
• Navree tokens: the callback answers exactly like POST /api/auth/login, two-factor challenge included.
• Provider tokens (optional), encrypted at rest and refreshed for you, for apps that call the provider's API later, such as syncing meetings from Google Calendar into CRM activities.

Installation

Turn on the social feature of the navree facade. It is opt-in: the default full feature leaves it out.

[dependencies]
navree = { git = "https://github.com/NavreeHQ/navree", features = ["social"] }

Add SocialModule after AuthModule. It calls the providers through the HTTP client, so include HttpClientModule:

Navree::app()
    .module(ConfigModule::for_root(sources))
    .module(CryptoModule::from_config())      // seals states, encrypts tokens
    .module(HttpModule::from_config())
    .module(HttpClientModule::from_config())
    .module(DatabaseModule::from_config())
    .module(CacheModule::from_config())       // remembers used states
    .module(AuthModule::from_config())
    .module(SocialModule::from_config())      // section `social`
    // ...

CacheModule is optional: without it, used states are remembered in the process, which is enough for a single instance. With several instances, give the cache a shared store so a state used on one instance is refused on the others.

The module contributes the migration set social (after auth), which creates social_accounts: one row per linked provider account, with the user, the provider, the provider's user id, the email, name, avatar and handle it reported, and the encrypted provider tokens when you store them. Deleting a user deletes their rows.

Configuration

Register an OAuth app with each provider, then list the providers in the social section. Each provider's callback URL is {redirect_base}/{provider}; register that exact URL with the provider:

[social]
redirect_base = "https://app.acme.test/auth/callback"  # the front end's page
link_by_email = "verified"                             # verified | never

[social.providers.github]
client_id = "Iv1.8a61f9b3a7aba766"

[social.providers.google]
client_id = "481203-k2l9.apps.googleusercontent.com"
hosted_domain = "acme.test"   # optional: only this Google Workspace

[social.providers.microsoft]
client_id = "0f6c1d2e-8a3b-4c5d-9e7f-1a2b3c4d5e6f"
tenant = "organizations"      # common | organizations | consumers | <tenant id>

Client secrets go in .env:

APP_SOCIAL__PROVIDERS__GITHUB__CLIENT_SECRET=4f1c0e7b9a...
APP_SOCIAL__PROVIDERS__GOOGLE__CLIENT_SECRET=GOCSPX-7Hk2...
APP_SOCIAL__PROVIDERS__MICROSOFT__CLIENT_SECRET=Q8a8Q~mX2...

A provider without a client_id, an unknown provider type, a redirect_base that isn't an absolute URL, an Apple key that can't be read or a custom provider that isn't registered fails the boot, naming the key. Provider keys are lower-case letters, digits, - and _. SocialModule::for_root(SocialOptions { .. }) takes the same options in code.

Providers

Any other OpenID Connect provider (Okta, Auth0, Keycloak, Zitadel, your company's SSO) works by its issuer. Navree reads its discovery document when the app starts, and again on first use if the provider couldn't be reached then. A document that names another issuer is refused:

[social.providers.okta]
type = "oidc"
name = "Okta"                        # shown in errors and in the accounts list
issuer = "https://acme.okta.com"
client_id = "0oa8f2kq1xYz3AbC4d5e"
scopes = ["openid", "profile", "email", "groups"]

Each provider asks for the scopes it needs to read a name and an email. Add more with scopes; they are requested in addition to the defaults. Every provider gets a PKCE challenge (S256) unless you set pkce = false for it.

How Navree reads the user:

• Google, Apple, Microsoft and oidc providers: from the ID token, verified against the provider's JSON Web Key Set (RS256, PS256, ES256 or EdDSA; key sets are cached for an hour and fetched again when a new key id appears). When the ID token has no email, Google and oidc providers fill it in from their userinfo endpoint.
• GitLab, Slack and LinkedIn: from their userinfo endpoints, with the access token.
• GitHub, Discord and X: from their APIs.

How the flow works

Navree's auth is token-based and a browser app keeps the tokens in its backend-for-frontend (BFF), so a social sign-in runs through the BFF too:

1. The sign-in page links to a BFF route, say /auth/social/github. The BFF calls GET /api/auth/social/github/redirect, stores the returned state in a short-lived httpOnly cookie and redirects the browser to url.
2. The user approves at GitHub, and GitHub sends the browser to https://app.acme.test/auth/callback/github?code=...&state=....
3. The BFF's callback page checks that the state in the URL equals the one in its cookie. That check binds the flow to this browser, so nobody can sign a victim into the attacker's account.
4. The BFF posts {code, state} to POST /api/auth/social/github/callback and gets the same answer as a login: it stores the tokens in its cookies, as it does for a password login, and sends the browser on to the app.

Apple posts code, state and user to the callback page instead of adding them to the URL, so that page accepts a POST, and the state cookie must be sent on that cross-site post (SameSite=None; Secure).

The first call:

GET /api/auth/social/github/redirect?return_to=/deals HTTP/1.1

{
  "url": "https://github.com/login/oauth/authorize?response_type=code&client_id=Iv1.8a61f9b3a7aba766&redirect_uri=https%3A%2F%2Fapp.acme.test%2Fauth%2Fcallback%2Fgithub&scope=read%3Auser+user%3Aemail&state=nvs1.Bq2...&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256",
  "state": "nvs1.Bq2..."
}

The callback:

POST /api/auth/social/github/callback HTTP/1.1
Content-Type: application/json

{ "code": "6f0a3d1e9b2c8f7a4e5d", "state": "nvs1.Bq2..." }

{
  "user": { "__type": "User", "id": "01a17748-e211-72fc-abb3-836e604457d0", "name": "Ada Lovelace", "email": "[email protected]", "email_verified_at": "2026-10-26T08:17:07Z", "created_at": "2026-10-26T08:17:07Z" },
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh_token": "01a17748-e21b-71c6-97cf-968b61f8e6b3.1ug0BGRxe4Fa...",
  "token_type": "Bearer",
  "expires_in": 900,
  "return_to": "/deals"
}

return_to comes back from the sealed state, and only relative paths are accepted (/deals, never https://... or //...), so it can't send the browser to another site. A native or mobile app that holds its own tokens follows the same two calls, with its own redirect URI and its own state check.

What can go wrong:

Every answer carries its code in the error body, so your sign-in page can tell "registration is closed" from "use your work address" in the user's language.

Linking accounts

When someone signs in with a provider, Navree looks for their user in this order:

1. A linked account. A social_accounts row for this provider and provider user id signs in its user, and is updated with what the provider reported this time.
2. The same verified email. With link_by_email = "verified" (the default), a user whose email matches an email the provider has verified gets the account linked, and is signed in. An unverified email never links: anyone can type any address into some providers.
3. A new user. With social.registration on (it defaults to auth.registration), Navree creates the user with the provider's name and email, marks the email as verified when the provider did, links the account and signs them in. The user has no password until they set one through password reset. A provider that shares no email address can't create a user (400).
4. Otherwise the callback answers 409, so the person signs in with their password and connects the provider from their settings:

{ "statusCode": 409, "message": "An account with this email already exists. Sign in, then connect GitHub in your settings.", "error": "Conflict", "code": "email_taken" }

With registration off and no matching user, the answer is 403 Registration is closed. Restrict who may sign up through a provider with allowed_email_domains = ["acme.test"], per provider or for the whole section: only a verified address in one of those domains may sign in or sign up.

Two-factor authentication

A user with two-factor authentication gets the same challenge from the callback as from a password login (two_factor_required, challenge_token, expires_in), and finishes with POST /api/auth/2fa/verify. Set social.two_factor = "skip" to trust the provider's own second factor instead.

Connecting and disconnecting providers

Signed-in users manage their providers with three routes:

GET .../redirect?intent=link needs the user's access token too (401 without it): the state is sealed for that user, so only they can finish the link, and a link state can't sign anyone in. Linking an account that already belongs to another user is a 409 (account_already_linked), and so is connecting a second account of a provider the user has already connected (provider_already_connected). Disconnecting the last way a user can sign in (no password and no other provider) is a 409 too (last_sign_in_method), so nobody locks themselves out; disconnecting a provider that isn't connected is a 404 (provider_not_connected).

Using the Social service

The routes are built on the Social service. Use it directly when you want your own routes, a different response or extra checks:

use navree::auth::{ClientMeta, LoginOutcome};
use navree::prelude::*;
use navree::social::{Social, SocialCallback, SocialRedirect};

#[injectable]
pub struct SsoController {
    social: Arc<Social>,
}

#[controller("/sso", version = "1")]
impl SsoController {
    /// `GET /api/v1/sso/okta`: where to send the browser.
    #[get("/okta")]
    #[public]
    async fn redirect(&self) -> Result<Json<SocialRedirect>> {
        Ok(Json(self.social.redirect("okta").await?))
    }

    /// `POST /api/v1/sso/okta`: `{code, state}` from the callback page.
    #[post("/okta")]
    #[public]
    async fn callback(
        &self,
        meta: ClientMeta,
        Json(callback): Json<SocialCallback>,
    ) -> Result<Json<serde_json::Value>> {
        let profile = self.social.user("okta", &callback).await?;
        let groups = profile.raw["groups"].as_array().cloned().unwrap_or_default();
        if !groups.iter().any(|g| g == "crm-users") {
            return Err(AppError::forbidden().with_detail("Ask IT for access to the CRM"));
        }
        match self.social.sign_in(&profile, &meta).await? {
            LoginOutcome::Authenticated { user, tokens } => Ok(Json(serde_json::json!({
                "user_id": user.id,
                "access_token": tokens.access_token,
                "refresh_token": tokens.refresh_token,
            }))),
            LoginOutcome::TwoFactorRequired { challenge_token, .. } => Ok(Json(serde_json::json!({
                "two_factor_required": true,
                "challenge_token": challenge_token,
            }))),
        }
    }
}

A SocialError returned with ? keeps its answer (400 for a bad state, 409 for the linking rules, and so on).

SocialUser has provider, id (the provider's user id), name, email, email_verified, avatar_url, nickname, token and raw, the provider's whole profile as JSON (the ID token's claims, or the API's user object). Build one with SocialUser::new(provider, id) and .name(..), .email(Some(..), verified), .avatar_url(..), .nickname(..), .token(..) and .raw(..).

sign_in and the token refresh join the request's unit of work in a handler; link and unlink take yours. Linking and disconnecting emit their events and audit entries after the commit.

Calling the provider's API later

To call the provider on the user's behalf after sign-in (read their Google Calendar, post to their Slack), ask for the scopes and store the tokens:

[social]
store_tokens = true

[social.providers.google]
client_id = "481203-k2l9.apps.googleusercontent.com"
scopes = ["https://www.googleapis.com/auth/calendar.readonly"]
# Ask Google for a refresh token:
params = { access_type = "offline", prompt = "consent" }

Tokens are encrypted with the application key before they're written to social_accounts, at every sign-in and link. token returns a current access token, refreshing it first when it has expired or expires within a minute:

let google = social.token(user.id, "google").await?; // Secret<String>
let events = http
    .get("https://www.googleapis.com/calendar/v3/calendars/primary/events")
    .bearer(google.expose())
    .send()
    .await?;

When the provider refuses the refresh (the user revoked access) or no refresh token was stored, token returns SocialError::Reauthorize, and the account stays linked for sign-in. Without stored tokens it returns SocialError::NoToken, and for a provider the user hasn't connected, SocialError::NotLinked. Returned from a handler with ?, they answer 409 reauthorization_required, 404 no_provider_token and 404 provider_not_connected, so the front end can offer "Connect Google again".

Your own provider

A provider that speaks neither OAuth 2.0 with a standard profile endpoint nor OpenID Connect gets a SocialProvider implementation. Implement its key and the two steps:

use navree::BoxFuture;
use navree::prelude::*;
use navree::social::{
    AuthorizeUrl, ProviderConfig, ProviderToken, SocialError, SocialProvider, SocialUser,
};

#[injectable]
pub struct Zoho {
    http: Arc<navree::http_client::HttpClient>,
}

impl SocialProvider for Zoho {
    fn key(&self) -> &'static str {
        "zoho"
    }

    fn authorize_url(&self, _config: &ProviderConfig, url: AuthorizeUrl) -> AuthorizeUrl {
        url.endpoint("https://accounts.zoho.com/oauth/v2/auth")
            .scopes(["AaaServer.profile.Read"])
    }

    fn user<'a>(
        &'a self,
        _config: &'a ProviderConfig,
        token: ProviderToken,
    ) -> BoxFuture<'a, Result<SocialUser, SocialError>> {
        Box::pin(async move {
            let profile: serde_json::Value = self
                .http
                .get("https://accounts.zoho.com/oauth/user/info")
                .bearer(token.access_token.expose())
                .send()
                .await?
                .json()?;
            Ok(SocialUser::new("zoho", profile["ZUID"].to_string())
                .name(profile["Display_Name"].as_str().unwrap_or_default())
                .email(profile["Email"].as_str(), true)
                .token(token)
                .raw(profile))
        })
    }
}

Register it with .module(SocialModule::for_feature::<Zoho>()) and configure it under its key, [social.providers.zoho], with type = "custom" and token_url. Navree still does the state, PKCE, code exchange (sending the client secret in the form), linking and token issuing. authorize_url receives the URL with Navree's parameters, the configured scopes and parameters already in place; config has the provider's whole configuration, endpoint overrides included.

Events and audit entries

Both carry user_id, provider and provider_user_id, and are emitted after the change commits, when EventsModule is in the app.

With the audit log, sign-ins are recorded as auth.login with metadata.provider (auth.two_factor_challenge when a second factor is due), new users as auth.register with metadata.provider, and links as social.linked and social.unlinked. Provider tokens are never recorded.

Testing

Social::fake() returns a Social that never calls a provider, and a SocialFake that decides what each code returns. States are still sealed and checked, so your tests go through the same steps as production:

use navree::prelude::*;
use navree::social::{Social, SocialUser};
use navree::testing::TestApp;
use serde_json::json;

#[tokio::test]
async fn a_new_github_user_gets_an_account_and_tokens() {
    let (social, fake) = Social::fake();
    fake.on_code(
        "github",
        "code-ada",
        SocialUser::new("github", "583231")
            .name("Ada Lovelace")
            .email(Some("[email protected]"), true),
    );

    let app = TestApp::builder()
        .temp_database()
        .config("app.key", navree::crypto::generate_key())
        .config("social.redirect_base", "https://app.acme.test/auth/callback")
        .config("social.providers.github.client_id", "test")
        .module(CryptoModule::from_config())
        .module(DatabaseModule::from_config())
        .module(AuthModule::from_config())
        .module(SocialModule::from_config())
        .override_value(Arc::new(social))
        .build()
        .await;

    let redirect = app
        .client()
        .get("/api/auth/social/github/redirect")
        .send()
        .await
        .assert_status(200);
    let state = redirect.json_value()["state"].as_str().unwrap().to_owned();

    app.client()
        .post("/api/auth/social/github/callback")
        .json(&json!({ "code": "code-ada", "state": state }))
        .send()
        .await
        .assert_status(200)
        .assert_json_path("user.email", json!("[email protected]"));

    // The state works once.
    app.client()
        .post("/api/auth/social/github/callback")
        .json(&json!({ "code": "code-ada", "state": state }))
        .send()
        .await
        .assert_error(400, "Invalid or expired state");
}

A code the fake doesn't know is refused with invalid_grant, as a provider would. The fake skips an oidc provider's discovery document. To test a provider integration itself, keep the real Social, point the provider's endpoint keys (url, authorize_url, token_url, userinfo_url, jwks_url) at a local mock server, and let the HTTP client reach it (http_client.ssrf.allow_hosts = ["127.0.0.1"]).

Reference

The routes sit under auth.routes_prefix, next to the authentication routes.