@crossmint/client-sdk-auth v1.2.12
@crossmint/client-sdk-auth
This SDK provides a set of tools for authenticating users in a Crossmint-powered application on the client-side. It simplifies the process of handling authentication tokens, managing user sessions, and integrating various authentication methods into your web applications.
Installation
To install the SDK, you can use npm or yarn:
npm install @crossmint/client-sdk-auth
Usage
To use the SDK in your application, follow these steps:
- Import the SDK into your project:
import { createCrossmint, CrossmintAuth } from "@crossmint/client-sdk-auth";
const crossmint = createCrossmint({
apiKey: process.env.CLIENT_CROSSMINT_API_KEY || "",
});
const crossmintAuth = CrossmintAuth.from(crossmint);
- Use the SDK to authenticate users and manage sessions:
// Get the current user
const user = await crossmintAuth.getUser();
// Log out the user and clear cookies
crossmintAuth.logout();
Custom Storage Providers
By default, the SDK uses browser cookies for storing authentication materials. For environments where cookies are not available, such as React Native, you can provide a custom storage provider.
React Native Storage Options
The SDK provides several secure storage implementations for React Native:
1. Expo SecureStore (Recommended for Expo apps)
First install dependencies:
npx expo install expo-secure-store
For Expo applications, use SecureStore which provides a secure encrypted storage solution:
import * as SecureStore from 'expo-secure-store';
import { ExpoSecureStorage, CrossmintAuth } from "@crossmint/client-sdk-auth";
// Create a custom storage provider using Expo's SecureStore
const storageProvider = new ExpoSecureStorage(SecureStore);
// Initialize auth client with secure storage
const crossmintAuth = CrossmintAuth.from(crossmint, {
storageProvider
});
2. React Native Encrypted Storage (Recommended for non-Expo apps)
First install dependencies:
npm install react-native-encrypted-storage
For vanilla React Native apps, use EncryptedStorage:
import EncryptedStorage from 'react-native-encrypted-storage';
import { RNEncryptedStorage, CrossmintAuth } from "@crossmint/client-sdk-auth";
// Create a custom storage provider using react-native-encrypted-storage
const storageProvider = new RNEncryptedStorage(EncryptedStorage);
// Initialize auth client with secure storage
const crossmintAuth = CrossmintAuth.from(crossmint, {
storageProvider
});
Implementing Custom Storage
You can implement any storage solution by implementing the StorageProvider
interface:
export interface StorageProvider {
get(key: string): string | undefined | Promise<string | undefined>;
set(key: string, value: string, expiresAt?: string): void | Promise<void>;
remove(key: string): void | Promise<void>;
}
Secure setup using HttpOnly cookies
To secure the authentication material, you can set up a custom endpoint in your backend that will handle refreshing the authentication material and storing it in HttpOnly cookies. This way, the authentication material is not accessible to JavaScript running in the browser.
Configure custom refresh route
In the client, provide the custom refresh route when creating the CrossmintAuth instance:
const crossmintAuth = CrossmintAuth.from(crossmint, {
refreshRoute: "/api/refresh",
});
This way, the SDK will use the provided route to refresh the token instead of the default one and the authentication material can be stored in HttpOnly cookies that are tied to the domain of the provided route.
Configure custom logout route
As you're now using HttpOnly cookies, logout can't happen client-side as it doesn't have access to the cookies. You can set up a custom logout route to handle the logout process.
In the client, provide the custom logout route when creating the CrossmintAuth instance:
const crossmintAuth = CrossmintAuth.from(crossmint, {
logoutRoute: "/api/logout",
});
NOTE: Depending on the framework you're using, you might need to set the whole URL in the refreshRoute
and logoutRoute
options.
Advanced Usage
You can provide callbacks for token refresh and logout events when creating the CrossmintAuthClient:
const crossmintAuth = CrossmintAuth.from(crossmint, {
callbacks: {
onTokenRefresh: (authMaterial) => {
// Handle new authentication material
},
onLogout: () => {
// Handle logout
},
},
});
Authentication Material
{
"jwt": "...",
"refreshToken": "...",
"user": {
"id": "...",
"email": "..."
}
}
These callbacks allow you to perform custom actions when tokens are refreshed or when the user logs out.
6 months ago
11 months ago
11 months ago
12 months ago
5 months ago
10 months ago
5 months ago
10 months ago
5 months ago
11 months ago
6 months ago
11 months ago
6 months ago
11 months ago
6 months ago
11 months ago
6 months ago
11 months ago
6 months ago
11 months ago
9 months ago
9 months ago
10 months ago
8 months ago
8 months ago
8 months ago
9 months ago
8 months ago
8 months ago
8 months ago
5 months ago
5 months ago
7 months ago
7 months ago
5 months ago
7 months ago
5 months ago
8 months ago
7 months ago
7 months ago
7 months ago
12 months ago
12 months ago
12 months ago
1 year ago