OAuth Providers

Supported providers

How it works

1. The platform sign-in package on the device (e.g. google_sign_in or sign_in_with_apple) runs the native flow and returns an identity token.
2. You pass that token to Koolbase.auth.signInWithGoogle / signInWithApple.
3. Koolbase verifies the token server-side against the provider's public keys, creates or links the user, and returns a session.

Configuration is per-project

OAuth provider settings live at the project level — you configure each provider once, in the dashboard, and every environment in the project uses the same configuration. This matches how the rest of Koolbase scopes server-side resources (see Projects & Environments).

Sign in with Google

Add your OAuth client IDs from the Google Cloud Console to your project (typically one each for iOS, Android, and web). Koolbase accepts tokens issued for any of the configured client IDs.

Flutter

Add google_sign_in to your pubspec.yaml, then:

import 'package:google_sign_in/google_sign_in.dart';
import 'package:koolbase_flutter/koolbase_flutter.dart';

final googleUser = await GoogleSignIn().signIn();
final googleAuth = await googleUser?.authentication;

final user = await Koolbase.auth.signInWithGoogle(
  idToken: googleAuth!.idToken!,
);

React Native & Web

Install @react-native-google-signin/google-signin, then:

import { GoogleSignin } from '@react-native-google-signin/google-signin';
// @koolbase/js in the browser — same call, same result
import { Koolbase } from '@koolbase/react-native';

GoogleSignin.configure({
  webClientId: '<your-web-client-id>.apps.googleusercontent.com',
});

const userInfo = await GoogleSignin.signIn();

const session = await Koolbase.auth.signInWithGoogle({
  idToken: userInfo.idToken!,
});

Requires koolbase_flutter ≥ 2.11.0 / @koolbase/react-native ≥ 1.11.0.

Sign in with Apple

Add your iOS app's Bundle ID to your project. Koolbase verifies the Apple identity token server-side against Apple's JWKS endpoint.

Flutter

Add sign_in_with_apple to your pubspec.yaml, then:

import 'package:sign_in_with_apple/sign_in_with_apple.dart';
import 'package:koolbase_flutter/koolbase_flutter.dart';

final credential = await SignInWithApple.getAppleIDCredential(
  scopes: [
    AppleIDAuthorizationScopes.email,
    AppleIDAuthorizationScopes.fullName,
  ],
);

final user = await Koolbase.auth.signInWithApple(
  identityToken: credential.identityToken!,
  nonce: credential.nonce,
  fullName: credential.givenName != null
      ? AppleFullName(
          givenName: credential.givenName,
          familyName: credential.familyName,
        )
      : null,
);

React Native & Web

Install @invertase/react-native-apple-authentication, then:

import appleAuth from '@invertase/react-native-apple-authentication';
            // @koolbase/js in the browser — same call, same result
import { Koolbase } from '@koolbase/react-native';

            const response = await appleAuth.performRequest({
              requestedOperation: appleAuth.Operation.LOGIN,
              requestedScopes: [appleAuth.Scope.EMAIL, appleAuth.Scope.FULL_NAME],
            });

            const session = await Koolbase.auth.signInWithApple({
              identityToken: response.identityToken!,
              nonce: response.nonce,
              fullName: response.fullName
                ? {
                    givenName: response.fullName.givenName ?? undefined,
                    familyName: response.fullName.familyName ?? undefined,
                  }
                : undefined,
            });

The nonce parameter

One rule for both providers: pass the exact string that appears in the identity token's nonce claim — Koolbase compares it verbatim, with no server-side hashing. What that string is differs by provider: Apple puts the SHA-256 hash of your raw nonce in the claim, so pass the same hashed value you set on the native authorization request (the raw nonce will fail with a mismatch). Google echoes the nonce as you supplied it to the sign-in flow, so pass that value verbatim.

The parameter is optional — omitted, the token is still fully verified (signature, issuer, audience, expiry, and for Apple a 15-minute issued-at cap). But the nonce is what binds the token to your app's specific sign-in attempt, so we recommend always sending it: you're already generating one for the native flow, and forwarding it costs one field.

Sign in with GitHub

GitHub sign-in is planned and not yet available. Google and Apple are the supported providers today.

Account linking

Linking is based on email. If a user with the same email already exists, signing in with an OAuth provider links to that existing account rather than creating a duplicate.

For Apple specifically, Koolbase auto-links to an existing account only when both the existing email and the Apple-provided email are verified and match. Otherwise a new account is created, which keeps relay-address sign-ins from silently merging into the wrong account.

Migrating from older SDKs

Earlier SDKs exposed a generic oauthLogin() method, a redirect-based getGoogleAuthUrl() flow, and a KoolbaseAppleAuth.signIn() helper. These have been replaced by the native-token methods above.

API reference

Flutter uses named parameters and returns the signed-in user; React Native takes an options object and returns a session. Both create the account on first sign-in and link to an existing one by email.