Authentication
Juno allows you to securely identify users anonymously and save their data on the blockchain.
Our easy-to-use SDKs support authentication via Internet Identity and more providers will be added soon.
Juno Authentication integrates tightly with other Juno services like datastore and storage.
You can manage your users in the authentication view in Juno's console. A new entry is created when a user succesfully signs in (see below).
The Juno SDK must be installed and initialized in your app to use the authentication features.
Sign-in
You can authorize an existing or new user with the identity provider using signIn
.
import { signIn } from "@junobuild/core";
await signIn();
The sign-in feature has options to customize the authentication:
maxTimeToLive
: a maximum time to live (4 hours per default,BigInt(4 * 60 * 60 * 1000 * 1000 * 1000)
)
The duration is given. It remains unchanged, regardless of whether the users are active or inactive.
derivationOrigin
: a specific parameter of Internet Identitywindowed
: by default, the authentication flow is presented to the user in a popup that is automatically centered on desktop. This behavior can be disabled by setting the option tofalse
. In that case, the authentication flow will occur in a separate tab.
Sign-out
You can end a user's session by logging them out.
import { signOut } from "@junobuild/core";
await signOut();
This will clear the sign-in information stored in IndexedDB.
Subscription
You can subscribe to the user state (signed-in or out) by using the subscriber function. This function provides a technical user and will trigger whenever the user's state changes.
import { authSubscribe } from "@junobuild/core";
authSubscribe((user: User | null) => {
console.log("User:", user);
});
If you register the subscriber at the top of your application, it will propagate the user's state accordingly (e.g. null
when a new user opens the app, the new user's entry when they sign in, the existing user when they refresh the browser within the valid duration, and null
again when they sign out).
Subscribing returns a callback that can be executed to unsubscribe:
import { authSubscribe } from "@junobuild/core";
const unsubscribe = authSubscribe((user: User | null) => {
console.log("User:", user);
});
// Above subscriber ends now
unsubscribe();
Advanced
To proactively detect when a session duration expires, you can use the pre-bundled Web Worker provided by Juno's SDK.
To do so, you can follow these steps:
- Copy the worker file provided by Juno's SDK to your app's static folder. For example, to your
public
folder with a NPMpostinstall
script:
{
"postinstall": "rsync -aqz node_modules/@junobuild/core/dist/workers/*.js public/workers/"
}
- Enable the option when you initialize Juno:
import { initJuno } from "@junobuild/core";
await initJuno({
satelliteId: "aaaaa-bbbbb-ccccc-ddddd-cai",
workers: {
auth: true,
},
});
The auth
option can accept either true
, which will default to using a worker located at https://yourapp/workers/auth.worker.js, or a custom
string` to provide your own URL.
When the session expires, it will be terminated with a standard sign-out. Additionally, an informational event called junoSignOutAuthTimer
will be thrown at the document
level. This event is optional and can be used, for example, to display a warning to your users.
document.addEventListener("junoSignOutAuthTimer", () => {
// Display an information to your users
}), {passive: true});