@dfinity/auth-client v2.1.3
@dfinity/auth-client
0.10.5 Idle update - see changes here
Simple interface to get your web application authenticated with the Internet Identity Service
Visit the Dfinity Forum and SDK Documentation for more information and support building on the Internet Computer.
Additional API Documentation can be found here.
Installation
Using AuthClient:
npm i --save @dfinity/auth-client
In the browser:
import { AuthClient } from "@dfinity/auth-client";
To get started with auth client, run
const authClient = await AuthClient.create();
The authClient can log in with
authClient.login({
// 7 days in nanoseconds
maxTimeToLive: BigInt(7 * 24 * 60 * 60 * 1000 * 1000 * 1000),
onSuccess: async () => {
handleAuthenticated(authClient);
},
});
It opens an identity.ic0.app
window, saves your delegation to localStorage, and then sets you up with an identity.
Then, you can use that identity to make authenticated calls using the @dfinity/agent
Actor
.
const identity = await authClient.getIdentity();
const actor = Actor.createActor(idlFactory, {
agent: new HttpAgent({
identity,
}),
canisterId,
});
Storage and Key management
If you prefer not to use ECDSA keys or the default IndexedDb storage interface, you can provide your own. Some reasons to use a custom storage implementation might be
- You prefer to use LocalStorage
- You don't want to persist keys across page loads for heightened security
- You have an alternate strategy for identity management
There is an exported LocalStorage interface, but any structure that implements the AuthClientStorage
interface will work.
export type StoredKey = string | CryptoKeyPair;
export interface AuthClientStorage {
get(key: string): Promise<StoredKey | null>;
set(key: string, value: StoredKey): Promise<void>;
remove(key: string): Promise<void>;
}
So you could easily implement your own
const noStorageImpl = {
get(key: string) {
return Promise.resolve(null);
},
set(key: string, value: StoredKey) {
return Promise.resolve();
},
remove(key: string) {
return Promise.resolve();
},
};
const authClient = await AuthClient.create({
storage: noStorageImpl,
});
If you are using a custom storage implementation like LocalStorage
that only supports strings, you should use the keyType
option to use an Ed25519
key instead of the default ECDSA
key.
const authClient = await AuthClient.create({
storage: new LocalStorage(),
keyType: 'Ed25519',
});
The AuthClient provides two forms of security for session management. The first is built into the Internet Identity delegation - the maxTimeToLive
option in nanoseconds determines how long the DelegationIdentity
you get back will be valid for. The second is the Idle Manager, which moniters keyboard, mouse and touchscreen identity. The Idle Manager will automatically log you out if you don't interact with the browser for a period of time.
If you pass no options to the IdleManager, it will log you out after 10 minutes of inactivity by removing the DelegationIdentity
from localStorage and then calling window.location.reload()
.
If you pass an onIdle
option, it will call that function when the user is idle, replacing the default window.location.reload() behavior. You can also register callbacks after the idleManager is created with the idleManager.registerCallback()
method, which will also replace the default callback.
The full set of options for the IdleManager is:
/**
* Callback after the user has gone idle
*/
onIdle?: IdleCB;
/**
* timeout in ms
* @default 30 minutes [600_000]
*/
idleTimeout?: number;
/**
* capture scroll events
* @default false
*/
captureScroll?: boolean;
/**
* scroll debounce time in ms
* @default 100
*/
scrollDebounce?: number;
Additionally, the AuthClient accepts a couple additional flags to idleOptions
to control the IdleManager:
/**
* Disables idle functionality for {@link IdleManager}
* @default false
*/
disableIdle?: boolean;
/**
* Disables default idle behavior - call logout & reload window
* @default false
*/
disableDefaultIdleCallback?: boolean;
IdleManager Example Usage
const authClient = await AuthClient.create({
idleOptions: {
idleTimeout: 1000 * 60 * 30, // set to 30 minutes
disableDefaultIdleCallback: true // disable the default reload behavior
}
});
// ...authClient.login()
const identity = await authClient.getIdentity();
const actor = Actor.createActor(idlFactory, {
agent: new HttpAgent({
identity,
}),
canisterId,
});
refreshLogin() {
// prompt the user then refresh their authentication
authClient.login({
onSuccess: async () => {
const newIdentity = await AuthClient.getIdentity();
Actor.getAgent(actor).replaceIdentity(newIdentity);
}
});
}
authClient.idleManager?.registerCallback?.(refreshLogin);
In this code, we create an authClient
with an idle timeout of 30 minutes. When the user is idle, we invalidate their identity and prompt them to login again.
After the user logs in, we can set the new identity in the actor without reloading the page.
Note: depends on @dfinity/agent and @dfinity/identity.
2 months ago
3 months ago
6 months ago
5 months ago
5 months ago
3 months ago
6 months ago
6 months ago
3 months ago
8 months ago
8 months ago
9 months ago
9 months ago
9 months ago
10 months ago
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago