npm install --save @withkoji/auth|
Warning
|
This package is deprecated and is included only for backwards compatibility. For new templates, use withkoji-koji-core.html. |
The @withkoji/auth package enables you to authenticate users in Koji templates.
This package provides methods for determining the current user’s role (whether or not the user created the Koji). This information can be used to tailor the experience based on who is viewing the Koji. For example, you can design a protected "admin" experience that is accessible only to the creator of the Koji. It also enables the template to send notifications to the creator’s Koji account.
Install the package in the frontend and backend services of your Koji project.
npm install --save @withkoji/auth|
Important
|
To support instant remixes of your template, you must also install the withkoji-vcc-package.html package and implement the VccMiddleware on your backend server.
This middleware maintains the environment variables for instant remixes, ensuring that user authentication applies to the correct remix version.
|
Instantiates Auth.
projectID – (Backend only) String, unique identifier for the Koji.
projectToken – (Backend only) String, secret key for the Koji.
|
Tip
|
When instantiating Auth on the backend, you must provide these parameters, which are available as environment variables at runtime.
For instant remixes, you must implement VccMiddleware to manage these variables.
See withkoji-vcc-package.html.
|
import Auth from '@withkoji/auth';
// Frontend
const auth = new Auth();
// Backend
const auth = new Auth(
res.locals.KOJI_PROJECT_ID,
res.locals.KOJI_PROJECT_TOKEN,
);Checks whether the current user has granted authorizations to the current Koji. Use this method on the frontend to determine whether to request authorization for certain capabilities.
grants – Array, list of authorization grants to check for the user.
See AuthGrantCapability.
(Async) Boolean, indicates whether the user has already granted authorization for the capabilities.
const hasGrant = await auth.checkGrant(['username', 'push_notifications']);Gets the user’s authorization grants for the current Koji. Use this method on the backend to validate the user’s grants and use the information for authorized capabilities. See AuthGrantCapability.
userToken – String, temporary token for the current user’s session.
See getToken and getTokenWithCallback.
(Async) AuthGrant object for the current user.
const grant = await auth.getGrant(token);Gets the user’s role for the current Koji, which can be used to enable a different experience for the creator.
userToken – String, temporary token for the current user’s session.
See getToken and getTokenWithCallback.
|
Note
|
To resolve the role for a given user, both the user token, obtained on the frontend, and the project token, obtained from environment variables on the backend, are necessary. |
(Async) String, one of the following values:
admin – User is the "owner" (creator) of this Koji.
user – User is not the owner of this Koji.
unknown – User is not logged in.
const token = await auth.getToken();Gets a token identifying the current user, and requests the specified authorization grants for the current Koji.
|
Note
|
A user token is created when a logged-in user loads a Koji app, and destroyed when the user closes the app. If the user revisits the Koji app, a different token is generated. Tokens are specific to a user and a Koji app, so the same user will have different tokens for different apps. You can use a token to validate the user’s role and authorization grants for the current Koji app. |
grants – Array, list of authorization grants to request from the user.
See AuthGrantCapability.
allowAnonymous – Boolean, (Optional) determines how to proceed for a user who is not logged in to Koji.
If set to true, the returned token will be null.
If set to false or undefined, the user is prompted to log in before a token is generated.
usageDescription – String, (Optional) custom message to display when requesting the grant.
(Async) String, temporary token for the current user’s session, or null if the user is not logged in.
const token = await auth.getToken(
['username', 'push_notifications']
);Gets a token identifying the current user, and requests the specified authorization grants for the current Koji. Then, invokes a callback function to handle backend requests for the user’s role and grant information.
|
Note
|
A user token is created when a logged-in user loads a Koji app, and destroyed when the user closes the app. If the user revisits the Koji app, a different token is generated. Tokens are specific to a user and a Koji app, so the same user will have different tokens for different apps. You can use a token to validate the user’s role and authorization grants for the current Koji app. |
handler – Function, handles backend requests for the user’s role and authorization grants.
Receives the following property as input:
userToken – String, temporary token for the current user’s session.
grants – Array, list of authorization grants to request from the user.
See AuthGrantCapability.
allowAnonymous – Boolean, (Optional) determines how to proceed for a user who is not logged in to Koji.
If set to true, the returned token will be null.
If set to false or undefined, the user is prompted to log in before a token is generated.
auth.getTokenWithCallback((token) => {
// Handle on the backend, for example:
// Request user's role and update template based on it
// Request user's unique ID for this Koji
}, ['username', 'push_notifications']);(Async) Sends a notification to the Koji account of a user who interacted with a Koji.
|
Note
|
You must obtain the user’s authorization before you can send push notifications from a Koji. On the frontend, use checkGrant determine whether the user has already granted authorization, and use getToken or getTokenWithCallback to request authorization, if needed. |
userId – String, user’s unique ID for this Koji.
See getGrant.
notification – PushNotification object, details of the desired notification.
await auth.pushNotification({
icon: '❓',
appName: 'Ask me anything',
message: 'Your custom video is ready! View now',
ref: '?dynamic-receipt=buyer',
});(Async) Sends a notification to the Koji account of the user who created the Koji.
notification – PushNotification object, details of the desired notification.
await auth.pushNotificationToOwner({
icon: '❓',
appName: 'Ask me anything',
message: 'Someone asked you a question! Respond now',
ref: '?context=admin',
});Array of capabilities that a user can grant the current Koji authorization to use. To request authorization grants from a user, use getToken or getTokenWithCallback in your frontend service. To validate the current user’s authorization grants, use checkGrant in your frontend service. To use the information for authorized capabilities, use getGrant in your backend service.
The following authorization grants are available:
push_notifications – Allows the current Koji to send push notifications to the user.
username – Creates a unique ID for the user on the current Koji, and allows the Koji to map the user’s token to a persistent user ID in storage, such as a backend database.
An AuthGrant object contains information about capabilities that the current user has authorized the current Koji to use.
You can use getGrant to retrieve the AuthGrant object associated with the user’s token.
The AuthGrant object includes the following properties.
{
userId: string; (1)
dateCreated: string; (2)
pushNotificationsEnabled: boolean; (3)
attributes: {[index: string]: any}; (4)
}userId – User’s unique ID for this Koji.
dateCreated – Date the authorization grants were requested or updated.
pushNotificationsEnabled – Indicator of whether the user has authorized the Koji to send push notifications.
attributes – Object that contains authorization information for the user.
A PushNotification object defines a notification to send to a user’s Koji account.
To send a push notification to the user who created a Koji, use pushNotificationToOwner.
To send a push notification to a user who interacts with a Koji, obtain or verify the user’s authorization, and then use pushNotification.
{
icon: string; (1)
appName: string; (2)
message: string; (3)
ref?: string; (4)
}icon – Icon to display next to the message, either the URL of an image or an emoji character.
appName – Headline for the message.
For example, the name of the Koji that generated the notification.
message – Content of the message.
ref – (Optional) Query parameters to append to the Koji URL when the notification is tapped.
For example, load the admin experience or a dynamic receipt from the notification.
Core package replacement modules: Identity (backend), Identity (frontend)