sitemap.xml llms.txt
Skip to main content

Authentication Functions

The Authentication adapter provides functionality to authenticate and manage a user's Epicenter session.

Importing the adapter​

To use the functions of the Authentication adapter, import it as shown:
import { authAdapter } from 'epicenter-libs';

The authAdapter namespace exports functions that make calls to the Authentication API.

learn more

For descriptions of the objects used by the authentication adapter functions, read Authentication Entities.

Login​

Removes any previous sessions and returns a new authenticated session.

Function signature
export async function login(
    credentials: UserCredentials | AppCredentials,
    optionals: { objectType?: string, forcePathInclusion?: boolean } & RoutingOptions = {}
): Promise<Session>

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

  • credentials: A union of two possible types of login credentials:
    • UserCredentials: Contains a user’s handle, password, and group key.
    • AppCredentials: Contains an application’s secret key.
  • optionals: An object containing additional options:
    • objectType (optional, type: string): Specifies the type of object ("user" or "account").
    • forcePathInclusion (optional, type: boolean): Forces an admin login to include the path in the generated cookie. When an admin login should be limited in scope to a single project, this prevents login issues when trying to access other simulations.
    • RoutingOptions: An (object with routing-specific options)[/docs/developer-reference/utils/routers.md#routingoptions-interface]

Return value​

A Promise resolving to the new Session object.

Usage example​

Here is a JavaScript example where the login() function is called to log in a user:

JavaScript example
import { authAdapter } from 'epicenter-libs';

const usernameEl = document.getElementById('username');
const passwordEl = document.getElementById('password');
const groupEl = document.getElementById('group');
const groupLabelEl = document.getElementById('group-label');
const adminCheckboxEl = document.getElementById('admin');

const session = await authAdapter.login({
    handle: usernameEl.value,
    password: passwordEl.value,
    groupKey: groupEl.value,
}, {objectType: adminCheckboxEl.checked ? 'admin' : 'user' });

Update session​

Update a user's session to the correct group or an admin's session to the correct account.

Function signature
export async function regenerate(
                        groupOrAccount: string,
                        optionals: { objectType?: string, forcePathInclusion?: boolean, } & 
                        RoutingOptions = {}
                        ): Promise<Session>
warning

The function fails if the user/admin does not already belong to the group/account.

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

  • groupOrAccount: Group key or account name
  • optionals: An object containing additional options:
    • objectType (optional, type: string) Possible values:
      • "user" (Default): Update the session to the specified group context (groupOrAccount is treated as a group key).
      • "admin": Update the session to the specified account/project context (groupOrAccount is treated as an account name), which uses the platform's focus API.
    • forcePathInclusion (optional, type: boolean): Forces an admin login to include the path in the generated cookie. When an admin login should be limited in scope to a single project, this prevents login issues when trying to access other simulations.
    • RoutingOptions: An object with routing-specific options

Return value​

A Promise resolving to the updated Session object.

Usage example​

JavaScript example
import { authAdapter } from 'epicenter-libs';

// Changes the current user session to have a group context associated with the provided key
await authAdapter.regenerate('00000165ad4e6a3cd22b993340b963820239');

// Changes the current admin session to use the account context for the 'acme' account
await authAdapter.regenerate('acme', { objectType: 'admin' });

View current session​

Function signature
export async function getSession(optionals: RoutingOptions = {}): Promise<Session>

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

RoutingOptions is an optional parameter containing an object with routing-specific options.

Return value​

A Promise resolving to the currently authenticated Session object.

Local session​

The following three functions facilitate storing the session locally for faster access. No API calls are made.

Get local session​

getLocalSession() returns the local session as a Session object.

JavaScript example
import authAdapter from 'epicenter-libs';
const session = authAdapter.getLocalSession();

Set local session​

setLocalSession(session: Session) updates the local session with the Session object passes in the parameter and returns the Session object.

Remove local session​

removeLocalSession() sets the local session to undefined and disconnects all live connections. Returns Promise<void>.

Logout​

Log out of current Epicenter session:

  • Terminate the user session.
  • Disconnect live WebSockets connections.
  • Removes the user from the presence cache.
learn more

The logout function ensures that the user's presence is dropped immediately when the user logs off.

Function signature
export async function logout(
    verificationOptionals: RoutingOptions = {},
    presenceOptionals: RoutingOptions = verificationOptionals
): Promise<void>

Permissions​

Requires a role of PARTICIPANT or higher.

Parameters​

  • verificationOptionals (optional): An object of type RoutingOptions. Defaults to an empty object if not provided. Used for additional verification options.
  • presenceOptionals (optional): An object of type RoutingOptions. Defaults to the value of verificationOptionals if not provided. Used for additional routing options during the presence group deletion process.

Return value​

A Promise that resolves to void.

Usage example​

Here is a JavaScript example where the logout() function is called to log a user out:

JavaScript example
import { authAdapter } from 'epicenter-libs';

// Define DOM elements
const displayNameEl = document.getElementById('display-name');
const groupRoleEl = document.getElementById('group-role');
const logoutEl = document.getElementById('logout');

logoutEl.onclick = (e) => {
    e.target.disabled = true;
    authAdapter.logout().then(() => {
        displayNameEl.textContent = 'stranger';
        groupRoleEl.textContent = 'not currently signed in on Epicenter';
        e.target.disabled = false;
    });
};

Reset a user's password​

Send a link to reset a user's password to their email.

Function signature
export async function resetPassword(
                                handle: string,
                                optionals: {  redirectURL?: string, subject?: string,} & 
                                RoutingOptions = {}
                                ): Promise<void>

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

  • handle (type: string): User's handle used to log in
  • optionals: Optional parameters
    • redirectURL (type: string): The URL to redirect to after the password is reset
    • subject (type: string): The subject line for the password-reset email
    • RoutingOptions: An (object with routing-specific options)[/docs/developer-reference/utils/routers.md#routingoptions-interface]
warning

The redirect URL must be in the Forio domain. Otherwise, an error is thrown.

Return value​

A Promise that resolves to void.

Usage example​

JavaScript example
import authAdapter from 'epicenter-libs';

document.getElementById('reset-password').addEventListener('submit', async(event) => {
    event.preventDefault();
    const { handle } = event.target.elements;
    await authAdapter.resetPassword(handle.value, 'https://forio.com/app/account/project',
                                    'Please reset your password!');
    }
);

Single Sign-On​

The following three functions support authenticating through an external Identity Provider via SAML-based Single Sign-On.

Authenticate via SSO​

Authenticates single sign-on and returns a promise that resolves to a session object.

Function signature
export async function sso(
                        optionals: RoutingOptions = {},
                        ): Promise<Session>

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

  • optionals (optional): An object of type RoutingOptions. Defaults to an empty object if not provided. Pass network call option overrides here.

Return value​

A Promise resolving to the Session object.

Usage example​

JavaScript example
import { authAdapter } from 'epicenter-libs';

const session = await authAdapter.sso();

Retrieves the SAML link from the project's SSO configuration.

Function signature
export async function getSAMLLink(
                        optionals: RoutingOptions = {},
                        ): Promise<string>

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

  • optionals (optional): An object of type RoutingOptions. Defaults to an empty object if not provided. Pass network call option overrides here.

Return value​

A Promise resolving to the SAML link as a string.

Usage example​

JavaScript example
import { authAdapter } from 'epicenter-libs';

const samlLink = await authAdapter.getSAMLLink();

Generate a SAML redirect URL​

Generates an Epicenter URL that will redirect the browser to the SAML URL.

Function signature
export function generateSAMLLINK(
                        optionals: RoutingOptions = {},
                        ): string

Parameters​

  • optionals (optional): An object of type RoutingOptions. Defaults to an empty object if not provided. Pass network call option overrides here.

Return value​

The generated SAML URL as a string. Unlike the other functions on this page, this one is synchronous and does not return a Promise.

Usage example​

JavaScript example
import { authAdapter } from 'epicenter-libs';

const samlURL = authAdapter.generateSAMLLINK();

Verify a security token​

The verify() function checks the validity of a token and returns a Promise resolving to the currently authenticated Session object.

Function signature
export async function verify(
                        token: string,
                        optionals: RoutingOptions = {},
                        ): Promise<Session>

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

  • token (type: string): a Bearer token
  • RoutingOptions: an optional parameter containing an (object with routing-specific options)[/docs/developer-reference/utils/routers.md#routingoptions-interface]

Report user's outcome​

To send the outcome of the user's participation in a simulation to an external link, use the ssoOutcome() function.

Function signature
export async function ssoOutcome(
                        ltiVersion : string,
                        outcomeInformation: {value: number, sourcedId: string, outcomeServiceUrl: string,},
                        optionals: RoutingOptions = {}
                    ): Promise<Record<string, unknown>>

Parameters​

  • ltiVersion: string (Required) - The version of LTI to use. Valid values: "1.1", "1.2", and "1.3".
  • outcomeInformation (Required) - An object containing the outcome details to be sent to the outcome service:
    • value: number - The value to pass back to the outcomeServiceUrl. For example, the grade a student received upon simulation completion.
    • sourcedId: string - The ID of the current assignment or student as provided by the client using the SSO service.
    • outcomeServiceUrl: string - The URL where the outcome information should be sent.
  • optionals: RoutingOptions (Optional) - An object containing additional routing options. Pass network call option overrides here. Defaults to an empty object {}.

Return value​

A promise that resolves to undefined (indicating success).