Auth

Import members from @edx/frontend-platform/auth

Simplifies the process of making authenticated API requests to backend edX services by providing common authN/authZ client code that enables the login/logout flow and handles ensuring the presence of a valid JWT cookie.

The initialize function performs much of the auth configuration for you. If, however, you're not using the initialize function, an authenticated API client can be created via:

import {
  configure,
  fetchAuthenticatedUser,
  getAuthenticatedHttpClient
} from '@edx/frontend-platform/auth';
import { getConfig } from '@edx/frontend-platform';
import { getLoggingService } from '@edx/frontend-platform/logging';

configure({
  loggingService: getLoggingService(),
  config: getConfig(),
});

const authenticatedUser = await fetchAuthenticatedUser(); // validates and decodes JWT token
const authenticatedHttpClient = getAuthenticatedHttpClient();
const response = await getAuthenticatedHttpClient().get(`https://example.com/api/user/data/${authenticatedUser.username}`); // fetching from an authenticated API using user data

As shown in this example, auth depends on the configuration document and logging.

NOTE: The documentation for AxiosJwtAuthService is nearly the same as that for the top-level auth interface, except that it contains some Axios-specific details.

Source:

Classes

AxiosJwtAuthService
MockAuthService

Interfaces

AuthService
HttpClient
UserData

Members

(private, inner, constant) AUTHENTICATED_USER_TOPIC

Source:

Methods

(inner) configure(AuthService, options) → {AuthService}

Parameters:
Name Type Description
AuthService class
options *
Source:
Returns:
Type
AuthService

(async, inner) ensureAuthenticatedUser(redirectUrlopt) → {Promise.<UserData>}

Ensures a user is authenticated. It will redirect to login when not authenticated.

Parameters:
Name Type Attributes Default Description
redirectUrl string <optional>
 config.BASE_URL

to return user after login when not authenticated.
Source:
Returns:
Type
Promise.<UserData>

(async, inner) fetchAuthenticatedUser() → {Promise.<UserData>|Promise.<null>}

Reads the authenticated user's access token. Resolves to null if the user is unauthenticated.

Source:
Returns:

Resolves to the user's access token if they are logged in.

Type
Promise.<UserData> | Promise.<null>

(inner) getAuthService() → {AuthService}

Source:
Returns:
Type
AuthService

(inner) getAuthenticatedHttpClient(optionsopt) → {HttpClient}

Gets the authenticated HTTP client for the service.

Parameters:
Name Type Attributes Description
options Object <optional>

Optional options for how to configure the authenticated HTTP client

Properties
Name Type Attributes Description
useCache boolean <optional>

Whether to use front end caching for all requests made with the returned client
Source:
Returns:
Type
HttpClient

(inner) getAuthenticatedUser() → {UserData|null}

If it exists, returns the user data representing the currently authenticated user. If the user is anonymous, returns null.

Source:
Returns:
Type
UserData | null

(inner) getHttpClient(optionsopt) → {HttpClient}

Gets the unauthenticated HTTP client for the service.

Parameters:
Name Type Attributes Description
options Object <optional>

Optional options for how to configure the authenticated HTTP client

Properties
Name Type Attributes Description
useCache boolean <optional>

Whether to use front end caching for all requests made with the returned client
Source:
Returns:
Type
HttpClient

(inner) getLoginRedirectUrl(redirectUrl)

Builds a URL to the login page with a post-login redirect URL attached as a query parameter.

const url = getLoginRedirectUrl('http://localhost/mypage');
console.log(url); // http://localhost/login?next=http%3A%2F%2Flocalhost%2Fmypage
Parameters:
Name Type Description
redirectUrl string

The URL the user should be redirected to after logging in.
Source:

(inner) getLogoutRedirectUrl(redirectUrl)

Builds a URL to the logout page with a post-logout redirect URL attached as a query parameter.

const url = getLogoutRedirectUrl('http://localhost/mypage');
console.log(url); // http://localhost/logout?redirect_url=http%3A%2F%2Flocalhost%2Fmypage
Parameters:
Name Type Description
redirectUrl string

The URL the user should be redirected to after logging out.
Source:

(async, inner) hydrateAuthenticatedUser()

Fetches additional user account information for the authenticated user and merges it into the existing authenticatedUser object, available via getAuthenticatedUser().

 console.log(authenticatedUser); // Will be sparse and only contain basic information.
 await hydrateAuthenticatedUser()
 const authenticatedUser = getAuthenticatedUser();
 console.log(authenticatedUser); // Will contain additional user information
Source:
Fires:
  • event:AUTHENTICATED_USER_CHANGED

(inner) redirectToLogin(redirectUrl)

Redirects the user to the login page.

Parameters:
Name Type Description
redirectUrl string

The URL the user should be redirected to after logging in.
Source:

(inner) redirectToLogout(redirectUrl)

Redirects the user to the logout page.

Parameters:
Name Type Description
redirectUrl string

The URL the user should be redirected to after logging out.
Source:

(inner) resetAuthService()

Source:

(inner) setAuthenticatedUser(authUser)

Sets the authenticated user to the provided value.

Parameters:
Name Type Description
authUser UserData
Source:
Fires:
  • event:AUTHENTICATED_USER_CHANGED

Events

AUTHENTICATED_USER_CHANGED

Published when the authenticated user data changes. This can happen when the authentication service determines that the user is authenticated or anonymous, as well as when we fetch additional user account data if the hydrateAuthenticatedUser flag has been set in the initialize function.

Source:
See:
  • {@link module:Initialization~initialize}