React Native Support

[nandorojo]

Hey, are there plans for React Native support? Would you be open to a PR?

[cmatheson]

@nandorojo very sorry about the slow response. We don't have plans for React Native yet, but are open to PRs.

[sbkl]

@cmatheson Started to work on an implementation plan for this. The idea would be for authkit-js create-client to accept an optional storage props (and an optional storageNamespace to avoid conflict) with the following interface:

export interface TokenStorage {
  getItem(
    key: string
  ): string | undefined | null | Promise<string | undefined | null>;
  setItem(key: string, value: string): void | Promise<void>;
  removeItem(key: string): void | Promise<void>;
  reset(): void | Promise<void>;
}

Initialise the storage if provided in the Client class and use the external storage if provided instead of the browser api based implementation.

Then, another PR would be necessary to the autkit-react package to allow for the AutkitProvider to accept the two optional props: storage and storageNamespace and link them to authkit-js implementation.

Am I missing something and are you fine if I provide a PR for it?

[sbkl]

I reviewed how Clerk is doing it and how workos recommend to integrate with expo for SSO here, basically, it requires to use expo-auth-session and expo-web-browser along with expo-secure-store. Would it make more sense to create a separate package then? authkit-expo

[sbkl]

Some progress. Made it work using convex in this case which is what I am using. Now, need to work on packaging it and a nice API.

storage

import * as SecureStore from "expo-secure-store";

export const storage = {
  getItem: (key: string) => SecureStore.getItemAsync(key),
  removeItem: (key: string) => SecureStore.deleteItemAsync(key),
  setItem: (key: string, value: string) => SecureStore.setItemAsync(key, value),
};

providers

import * as React from "react";

import { storage } from "@/lib/storage";
import { ConvexQueryClient } from "@convex-dev/react-query";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ConvexProviderWithAuth, ConvexReactClient } from "convex/react";

interface ProvidersProps {
  children: React.ReactNode;
}

const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL!, {
  unsavedChangesWarning: false,
});
const convexQueryClient = new ConvexQueryClient(convex);
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      queryKeyHashFn: convexQueryClient.hashFn(),
      queryFn: convexQueryClient.queryFn(),
    },
  },
});
convexQueryClient.connect(queryClient);

export function Providers({ children }: ProvidersProps) {
  return (
    <ConvexProviderWithAuth client={convex} useAuth={useWorkosConvexAuth}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </ConvexProviderWithAuth>
  );
}

function useWorkosConvexAuth() {
  const [isLoading, setIsLoading] = React.useState(true);
  const [isAuthenticated, setIsAuthenticated] = React.useState(false);

  React.useEffect(() => {
    async function init() {
      const accessToken = await storage.getItem("accessToken");
      if (accessToken) {
        setIsAuthenticated(true);
      }
      setIsLoading(false);
    }
    init();
  }, []);

  const fetchAccessToken = React.useCallback(
    async ({
      forceRefreshToken: _forceRefreshToken,
    }: {
      forceRefreshToken: boolean;
    }) => {
      // TODO: handle refresh token
      return storage.getItem("accessToken");
    },
    []
  );

  return React.useMemo(
    () => ({
      isLoading,
      isAuthenticated,
      fetchAccessToken,
    }),
    [isLoading, isAuthenticated, fetchAccessToken]
  );
}

auth-form

import { Button } from "@/components/ui/button";
import { api } from "@/convex/_generated/api";
import { storage } from "@/lib/storage";
import { useAction } from "convex/react";
import * as AuthSession from "expo-auth-session";
import * as WebBrowser from "expo-web-browser";
import { View } from "react-native";

export function AuthForm() {
  const getAuthorisationUrl = useAction(api.workos.action.getAuthorisationUrl);
  const authenticateWithCode = useAction(
    api.workos.action.authenticateWithCode
  );

  async function handleGoogleLogin() {
    // The redirectUri must be added to the sign-in callback in the workos dashboard
    const redirectUri = AuthSession.makeRedirectUri().toString();

    const authorisationUrl = await getAuthorisationUrl({
      provider: "GoogleOAuth",
      redirectUri,
    });

    const result = await WebBrowser.openAuthSessionAsync(
      authorisationUrl,
      redirectUri
    );

    if (result.type !== "success" || !result.url)
      throw new Error("Authentication cancelled or failed");

    const params = new URL(result.url).searchParams;

    const code = params.get("code");

    if (!code) throw new Error("No code returned");

    const { accessToken, refreshToken, user } = await authenticateWithCode({
      code,
    });

    await storage.setItem("refreshToken", refreshToken);
    await storage.setItem("accessToken", accessToken);
    await storage.setItem("user", JSON.stringify(user));
  }

  return (
    <View className="flex-1 items-center justify-center">
      <Button icon="logo-google" onPress={handleGoogleLogin}>
        Sign In with Google
      </Button>
    </View>
  );
}

convex actions (server side calls)

export const getAuthorisationUrl = publicAction({
  args: {
    provider: v.string(),
    redirectUri: v.string(),
  },
  async handler(_ctx, args) {
    const workos = new WorkOS(env.WORKOS_API_KEY);
    const url = workos.userManagement.getAuthorizationUrl({
      clientId: env.WORKOS_CLIENT_ID,
      provider: args.provider,
      redirectUri: args.redirectUri,
    });

    return url;
  },
});

export const authenticateWithCode = publicAction({
  args: {
    code: v.string(),
  },
  async handler(_ctx, { code }) {
    const workos = new WorkOS(env.WORKOS_API_KEY);
    const response = await workos.userManagement.authenticateWithCode({
      clientId: env.WORKOS_CLIENT_ID,
      code,
    });

    return response;
  },
});

[joshuabaker]

@cmatheson Coming to this fresh and quite surprised this is so much harder than I believe it should be.

The main concern here is that the provided Expo guide is actually using insecure approaches (e.g. shipped keys, no PCKE, etc.). Even the repo has a warning about this, but the guide hasn’t been updated.

There is also nothing on token exchange or user validation here, which wouldn’t be a stretch to include.

Please can we get an updated guide for native apps.

[ShaneZhengNZ]

@joshuabaker I mean, the provided Expo Guide is ok, although no PCKE, we can do something similar to what @sbkl is doing, implement the BFF pattern (so that you have your backend to talk to WorkOS API).

My approach:

• app fetches the authentication URL by calling my backend http://localhost:8000/login
• my backend replies with authorization_url (by calling workos.user_management.get_authorization_url)
• app does await openAuthSessionAsync(authUri, app_scheme), and get the code (response looks like ${app_scheme}?code=actual_code)
• app parses the code, and calls my backend to get access token, refresh token and user object (http://localhost:8000/verify_user_by_code)
• app saves the access token and refresh token
• app uses the access token to make further API calls
• When the access token expires, the app calls my backend with the refresh token to get a new access token (http://localhost:8000/refresh_token). The backend calls workos.user_management.authenticate_with_refresh_token to get a new access token and return to the app

This should work.

However, I agree with @sbkl that WorkOS should have a library called authkit-react-native (I prefer this over authkit-expo, because authkit-react-native means it can be used by any React Native apps, not limited to Expo).

However, I face the issue of how to log out. The server-side function looks like def get_logout_url(self, session_id: str, return_to: Optional[str] = None) -> str:. I need to know the session ID before I can get the logout URL.

I think you can decode the access token, and get session id from there, but I want to show all the user sessions, therefore, in the verify_user_by_code function, I return the sessions with the user, access token and refresh token.
`
@app.get("/verify_user_by_code")
def verify_user_by_code(code: str) -> dict[str, Any]:
authentication_result = workos.user_management.authenticate_with_code(code=code, session={"seal_session": True, "cookie_password": f'{password}'})
sessions = workos.user_management.list_sessions(user_id=authentication_result.user.id)

return {
    "user": authentication_result.user,
    "access_token": authentication_result.access_token,
    "refresh_token": authentication_result.refresh_token,
    "sessions": sessions.data
}

`

Now, when you log out, you can call the backend http://localhost:8000/log-out endpoint to get the logout URL

finally, use this to log out

<ThemedButton
  title="Sign Out"
  onPress={async () => {
    const signOutUrlResult = await fetch(
      `http://localhost:8000/log_out?session_id=${sessionId}&return_to=${APP_SCHEME}`
    );
    const signOutUri = await signOutUrlResult.json();
  
    await openAuthSessionAsync(signOutUri, APP_SCHEME, {
      preferEphemeralSession: true,
    });
  }}
/>

[ShaneZhengNZ]

@sbkl are you still working on this? Maybe we can work on this together for an RN package to seamlessly integrate WorkOS with Expo (React Native)

[clearfram3]

when?

[joshuabaker]

Expo + WorkOS

Here’s a setup that I made that leverage’s Expo’s AuthSession approach. It uses the WorkOS hosted flow.

View context and hook code

import AsyncStorage from "@react-native-async-storage/async-storage";
import type { AuthenticationResponse } from "@workos-inc/node";
import {
  AccessTokenRequest,
  AuthRequest,
  makeRedirectUri,
  RefreshTokenRequest,
  RevokeTokenRequest,
  TokenResponse,
} from "expo-auth-session";
import * as SecureStore from "expo-secure-store";
import * as WebBrowser from "expo-web-browser";
import {
  type ReactNode,
  createContext,
  useCallback,
  useContext,
  useEffect,
  useState,
} from "react";

type MetaStorageValue = {
  user?: AuthenticationResponse["user"];
  organizationId?: AuthenticationResponse["organizationId"];
  impersonator?: AuthenticationResponse["impersonator"];
  authenticationMethod?: AuthenticationResponse["authenticationMethod"];
};

type ClientIdOrAuthorizationEndpoint =
  | { clientId?: string; authorizationEndpoint: string }
  | { clientId: string; authorizationEndpoint?: string };

type AuthProviderOptions = ClientIdOrAuthorizationEndpoint & {
  children: ReactNode;
  redirectUri?: string;
  tokenEndpoint: string;
  revocationEndpoint: string;
  storageKeyPrefix?: string;
  devMode?: boolean;
};

type AuthValue = MetaStorageValue & {
  isLoading: boolean;
  signIn: (options?: {
    screenHint?: "sign-up" | "sign-in";
  }) => Promise<boolean>;
  signOut: (options?: { skipConfirmation?: boolean }) => Promise<boolean>;
  getAccessToken: (options?: {
    forceRefresh?: boolean;
  }) => Promise<string | null>;
};

const AuthContext = createContext<AuthValue>({
  isLoading: false,
  signIn: async () => false,
  signOut: async () => false,
  getAccessToken: async () => null,
});

// We can have a default authorization endpoint as no private key is required
const defaultAuthorizationEndpoint =
  "https://api.workos.com/user_management/authorize";

WebBrowser.maybeCompleteAuthSession();

export function AuthProvider({
  children,
  clientId = "",
  redirectUri = makeRedirectUri(),
  authorizationEndpoint = defaultAuthorizationEndpoint,
  tokenEndpoint,
  revocationEndpoint,
  storageKeyPrefix = "workos",
  devMode = false,
}: AuthProviderOptions) {
  if (authorizationEndpoint === defaultAuthorizationEndpoint && !clientId) {
    throw new Error(
      "clientId is required when using default authorizationEndpoint"
    );
  }

  const requestConfigKey = `${storageKeyPrefix}.tokens`;
  const metaKey = `${storageKeyPrefix}.meta`;

  const [meta, setMeta] = useState<MetaStorageValue | null>(null);
  const [isLoading, setIsLoading] = useState(true);

  const storeTokenResponse = useCallback(
    async (tokenResponse: TokenResponse) => {
      assertAuthenticationResponse(tokenResponse.rawResponse);

      const requestConfig = tokenResponse.getRequestConfig();
      await SecureStore.setItemAsync(
        requestConfigKey,
        JSON.stringify(requestConfig)
      );

      const { user, organizationId, impersonator, authenticationMethod } =
        tokenResponse.rawResponse;
      const meta = { user, organizationId, impersonator, authenticationMethod };
      await AsyncStorage.setItem(metaKey, JSON.stringify(meta));
      setMeta(meta);
    },
    [requestConfigKey, metaKey]
  );

  const readTokenResponse =
    useCallback(async (): Promise<TokenResponse | null> => {
      const storedRequestConfig =
        await SecureStore.getItemAsync(requestConfigKey);
      if (!storedRequestConfig) return null;
      const requestConfig = JSON.parse(storedRequestConfig);
      return new TokenResponse(requestConfig);
    }, [requestConfigKey]);

  const clearStorage = useCallback(async () => {
    try {
      await SecureStore.deleteItemAsync(requestConfigKey);
      await AsyncStorage.removeItem(metaKey);
    } finally {
      setMeta(null);
    }
  }, [requestConfigKey, metaKey]);

  const revokeToken = useCallback(async () => {
    const tokenResponse = await readTokenResponse();
    if (!tokenResponse?.accessToken) return;
    const revokeTokenRequest = new RevokeTokenRequest({
      clientId,
      token: tokenResponse.accessToken,
    });
    await revokeTokenRequest.performAsync({ revocationEndpoint });
    await clearStorage();
  }, [revocationEndpoint, clientId, clearStorage, readTokenResponse]);

  const getAccessToken = useCallback(
    async (options?: { forceRefresh?: boolean }): Promise<string | null> => {
      const forceRefresh = options?.forceRefresh ?? false;
      try {
        let tokenResponse = await readTokenResponse();

        if (!tokenResponse) {
          await clearStorage();
          return null;
        }

        if (forceRefresh || tokenResponse.shouldRefresh()) {
          const refreshTokenRequest = new RefreshTokenRequest({
            refreshToken: tokenResponse.refreshToken,
            clientId,
          });

          tokenResponse = await refreshTokenRequest.performAsync({
            tokenEndpoint,
          });

          await storeTokenResponse(tokenResponse);
        }

        return tokenResponse.accessToken;
      } catch (error) {
        if (devMode) console.error(error);
        await clearStorage();
        return null;
      }
    },
    [
      readTokenResponse,
      clearStorage,
      devMode,
      tokenEndpoint,
      clientId,
      storeTokenResponse,
    ]
  );

  const signIn = useCallback(
    async ({
      screenHint = "sign-in",
    }: { screenHint?: "sign-up" | "sign-in" } = {}) => {
      const authSessionRequest = new AuthRequest({
        clientId,
        redirectUri,
        extraParams: { provider: "authkit", screen_hint: screenHint },
      });

      const authSessionResult = await authSessionRequest.promptAsync({
        authorizationEndpoint,
      });

      if (authSessionResult.type === "error") {
        throw new Error(
          authSessionResult.error?.description ?? "Unknown error"
        );
      }

      if (authSessionResult.type !== "success") {
        // User cancelled
        return false;
      }

      if (authSessionRequest.state !== authSessionResult.params.state) {
        throw new Error("State mismatch");
      }

      if (!authSessionRequest.codeVerifier) {
        throw new Error("Code verifier missing");
      }

      const tokenRequest = new AccessTokenRequest({
        code: authSessionResult.params.code,
        clientId,
        redirectUri,
        extraParams: {
          code_verifier: authSessionRequest.codeVerifier,
        },
      });

      const tokenResponse = await tokenRequest.performAsync({ tokenEndpoint });

      await storeTokenResponse(tokenResponse);

      return true;
    },
    [
      clientId,
      redirectUri,
      authorizationEndpoint,
      tokenEndpoint,
      storeTokenResponse,
    ]
  );

  const signOut = useCallback(
    async ({
      skipConfirmation = false,
    }: { skipConfirmation?: boolean } = {}) => {
      if (!meta) return false;

      if (skipConfirmation) {
        await revokeToken();
        return true;
      }

      return new Promise<boolean>((resolve) => {
        import("react-native").then(({ Alert }) => {
          Alert.alert(
            meta.user?.email
              ? `Are you sure you want to sign out as ${meta.user.email}?`
              : "Are you sure you want to sign out?",
            undefined,
            [
              {
                text: "Cancel",
                style: "cancel",
                onPress: () => resolve(false),
              },
              {
                text: "Sign out",
                style: "destructive",
                onPress: async () => {
                  await revokeToken();
                  resolve(true);
                },
              },
            ]
          );
        });
      });
    },
    [meta, revokeToken]
  );

  useEffect(() => {
    WebBrowser.warmUpAsync();

    setIsLoading(true);

    (async () => {
      try {
        // Restore authentication metadata from storage
        const storedMeta = await AsyncStorage.getItem(metaKey);
        setMeta(storedMeta !== null ? JSON.parse(storedMeta) : null);
        // Refresh access token, which will also clear if the session was revoked
        await getAccessToken({ forceRefresh: true });
      } finally {
        setIsLoading(false);
      }
    })();

    return () => {
      WebBrowser.coolDownAsync();
    };
  }, [metaKey, getAccessToken]);

  return (
    <AuthContext.Provider
      value={{ ...meta, isLoading, signIn, signOut, getAccessToken }}
    >
      {children}
    </AuthContext.Provider>
  );
}

export function useAuth(): AuthValue {
  const context = useContext(AuthContext);
  if (!context) {
    throw new Error("useAuth must be used within an AuthProvider");
  }
  return context;
}

function assertAuthenticationResponse(
  response: unknown
): asserts response is AuthenticationResponse {
  if (!response || typeof response !== "object" || !("user" in response)) {
    throw new Error("Invalid authentication response");
  }
}

Usage

Pop the AuthProvider into your layout.

<AuthProvider
  authorizationEndpoint={`${process.env.EXPO_PUBLIC_API_URL!}/v1/auth/authorize`}
  tokenEndpoint={`${process.env.EXPO_PUBLIC_API_URL!}/v1/auth/token`}
  revocationEndpoint={`${process.env.EXPO_PUBLIC_API_URL!}/v1/auth/revoke`}
> // …

The above-configured endpoints are the minimum viable approach.

• authorizationEndpoint handles the redirect to the hosted flow (alternatively set the clientId prop)
• tokenEndpoint handles the exchanging (i.e. code or refresh token)
• revocationEndpoint is to sign out by preventing reuse of the token

You can then use the useAuth hook to trigger sign in and check the authentication state.

const { isLoading, user, signIn, signOut } = useAuth();

View Hono example

import { getWorkOS } from "@/lib/auth/workos";
import { zValidator } from "@/utils/validator-wrapper";
import { AuthenticationResponse } from "@workos-inc/node";
import { Hono } from "hono";
import { getConnInfo } from "hono/cloudflare-workers";
import { decodeJwt } from "jose";
import { z } from "zod";
import {
  ServerTokenResponseConfig,
  ResponseErrorConfig,
} from "expo-auth-session";

type TokenResponse = (ServerTokenResponseConfig | ResponseErrorConfig) &
  AuthenticationResponse;

const auth = new Hono<{ Bindings: CloudflareBindings }>();

// Redirect to WorkOS authentication URL
auth.get(
  "/authorize",
  zValidator(
    "query",
    z.object({
      redirect_uri: z.string(),
      code_challenge: z.string(),
      code_challenge_method: z.enum(["S256"]),
      state: z.string().optional(),
      screen_hint: z.enum(["sign-up", "sign-in"]).optional(),
    })
  ),
  async (c) => {
    const params = c.req.valid("query");
    const workos = getWorkOS(c);

    const authUrl = workos.userManagement.getAuthorizationUrl({
      clientId: c.env.WORKOS_CLIENT_ID,
      provider: "authkit",
      codeChallenge: params.code_challenge,
      codeChallengeMethod: params.code_challenge_method,
      redirectUri: params.redirect_uri,
      state: params.state,
      screenHint: params.screen_hint,
    });

    console.log(authUrl);

    return c.redirect(authUrl);
  }
);

// Gets or refreshes a token from WorkOS
auth.post(
  "/token",
  zValidator(
    "form",
    z.discriminatedUnion("grant_type", [
      z.object({
        grant_type: z.literal("authorization_code"),
        code: z.string(),
        code_verifier: z.string(),
      }),
      z.object({
        grant_type: z.literal("refresh_token"),
        refresh_token: z.string(),
      }),
    ])
  ),
  async (c) => {
    const params = c.req.valid("form");
    const workos = getWorkOS(c);
    const clientId = c.env.WORKOS_CLIENT_ID;

    try {
      let authenticationResponse: AuthenticationResponse;

      if (params.grant_type === "authorization_code") {
        authenticationResponse =
          await workos.userManagement.authenticateWithCode({
            clientId,
            code: params.code,
            codeVerifier: params.code_verifier,
          });
      } else if (params.grant_type === "refresh_token") {
        authenticationResponse =
          await workos.userManagement.authenticateWithRefreshToken({
            clientId,
            refreshToken: params.refresh_token,
            ipAddress: getConnInfo(c).remote.address,
            userAgent: c.req.header("User-Agent"),
          });
      } else {
        return c.json({ error: "Invalid grant type" }, 400);
      }

      return c.json(formatTokenResponse(authenticationResponse));
    } catch (error) {
      return c.json({ error: "Internal server error" }, 500);
    }
  }
);

// Revokes a token from WorkOS
auth.post(
  "/revoke",
  zValidator(
    "form",
    z.object({
      token: z.string(),
    })
  ),
  async (c) => {
    const params = c.req.valid("form");
    const workos = getWorkOS(c);

    const decodedToken = decodeJwt<{ sid: string }>(params.token);

    await workos.userManagement.revokeSession({
      sessionId: decodedToken.sid,
    });

    return c.json({ success: true });
  }
);

function formatTokenResponse(
  authenticationResponse: AuthenticationResponse
): TokenResponse {
  const { accessToken, refreshToken } = authenticationResponse;
  const decodedToken = decodeJwt<{ exp: number }>(accessToken);
  return {
    ...authenticationResponse,
    access_token: accessToken,
    refresh_token: refreshToken,
    expires_in: decodedToken.exp - Math.floor(Date.now() / 1000),
    issued_at: decodedToken.iat,
  };
}

export default auth;

[joshuabaker]

@cmatheson This should really be supported by the WorkOS team. The currently fragmented JS SDK is frustrating and makes things far harder than they should be.

In my opinion, the JS SDK should be a monorepo that includes common platforms like Next.js and Expo as convenient packages alongside AuthKit. As it stands, there’s no consistent core JS package that works across different clients (i.e. Next.js seems to do a ton of custom stuff).

[LagBug]

Are there plans by the WorkOS team to support RN/Expo? It really should be something that gets worked on.

[joshuabaker]

I’ve created a new package that’s essentially what I published above: authkit-react-native

[joshuabaker]

@cmatheson @mthadley @nicknisi Was keen to PR, but I think it would be worth thinking about how this actually fits here. My sense is that the WorkOS TS SDKs should really be under one roof in a monorepo.

Is there a reason that the team didn’t take that approach?

Core features (session, base TS client, etc., mostly abstracted away)
@workos-inc/authkit-core

Server packages
@workos-inc/authkit-hono
@workos-inc/authkit-express

Framework packages
@workos-inc/authkit-nextjs
@workos-inc/authkit-tanstack-start
@workos-inc/authkit-react-native
@workos-inc/authkit-expo

Based on everything being disjointed currently, I can imagine this is wishful thinking now, but it does mean that contributions like this aren’t exactly easy (or possible).