Login

API

Table of contents

• Components
  • LoginButton
  • LoginCallbackHandler
  • LoginProvider
  • SessionEndedHandler
  • WithAuthentication
  • WithAuthenticatedUser
  • WithoutAuthenticatedUser
• Modules
  • Oidc Client
  • Api tokens client
  • Session poller
  • GraphQL module
  • ApolloClient module
  • TokenizedFetch module
• Oidc client hooks
• Api tokens client hooks
• Session poller hooks
• GraphQL module hooks
• ApolloClient module hooks
• TokenizedFetch module hooks
• Generic signal hooks
• Beacon
• Signals

Components

LoginButton

| [Table 1: Properties of the LoginButton component] |

Button text is passed and rendered as a child.

LoginCallbackHandler

In some scenarios, when the component is rendered multiple times, usually in development mode with strict mode enabled, the onError callback is called with an error that can usually be ignored. The error indicates a login callback is already being handled. The error can be checked with the exported function isHandlingLoginCallbackError(error).

LoginProvider

SessionEndedHandler

WithAuthentication

WithAuthenticatedUser

WithoutAuthenticatedUser

Modules

Usually, just logging in is not enough. The user must be able to fetch data from backend servers. That cannot be done unless the user's access token is exchanged for API tokens. Api tokens are sent in the headers of backend requests to authenticate the user. HDS Login modules include also API token handling. It is an independent module, but it communicates with the Oidc client and updates automatically when the user logs in or is updated. The modules emit signals that can be listened to and reacted to.

There are four modules to handle the user's needs:

• Oidc client for user data.
• Api tokens client for acquiring backend tokens.
• ApolloClient module to provide the client and auto-append api tokens to queries.
• GraphQL module for fetching data from a graphQL server. Fetching can be automatically linked to
• TokenizedFetch module for fetching data from a server. Requests are automatically linked to the Api Tokens client.

All modules can be used without React and without each other. But a >user object is required to get API tokens and poll the session.

Oidc client

The Oidc client uses the oidc-client-ts and has the same settings but different defaults.

Settings

Default userManager settings

These override the default settings of the oidc-client-ts.

Methods

Other exported utility functions

The following functions can be imported and used without the Oidc client module:

import { isUserExpired } from 'hds-react';

if (isUserExpired(user)) {
  // Show an error
}

State change signals

When the user does something, the Oidc client's state changes and the UI can indicate it by reacting to the state change signals. The simplest way to react to signals is useOidcClientTracking hook. The current state can also be read with oidcClient.getState().

There are utility functions for each state change. Use these to check if the emitted signal contains that state.

Error signal types

Errors are rarely thrown; they are emitted as error signals where the error object is in the signal payload. Errors are instances of the OidcClientError. It is an extended Error object with a type property and multiple .is... getters for checking error types. The error object also contains the thrown error in error.originalError property.

Event signals

The Oidc client also emits event signals when an action is complete or starting. The difference between state changes and events is the UI does not usually need to react to events.

Dedicated signal triggers

Generic triggers for Oidc client signals. These trigger only if the signal originated from the Oidc client.

State change triggers require the signal to have the Oidc client namespace and type stateChange. Signal.payload.type must contain one of the states.

Event triggers require the signal to have the Oidc client namespace and type event. Signal.payload.type contains one of the events.

Error triggers require the signal to have the Oidc client namespace and type error. Signal.payload.type contains one of the errors.

Getting signal payloads

Sometimes the most significant part of a signal is the payload. There are predefined payload getters for the Oidc client. If the given signal is not from Oidc client or is not of the given type, the function returns null. So there is no need to pre-check the signal namespace or type.

Hooks

Oidc client hooks are listed in the hooks section.

Api tokens client

The Api tokens client listens to the Oidc client signals and waits until the user is authenticated and then fetches the API tokens. It retries if fetch fails and terminates when the maximum number of retries is reached. When the user is about to expire and renews, API tokens are also renewed automatically.

When user renewal starts, API tokens are also removed to prevent usage of API tokens that are not possibly valid anymore. Use isRenewing() to check if API tokens are being renewed, and if it returns 'false', then use the API tokens returned by getTokens().

Requirements

URL where to get the tokens from. A user's access token is also required, so the user must be authenticated to fetch API tokens.

Settings

Methods

Api Token Client Tracker utility

Multiple modules need to track api tokens and their renewal process. This util listens to changes and also times out when the renewal is taking too long.

The function returns an object with following properties

Other exported utility functions

The following functions can be imported and used without the Api tokens client module:

import { getApiTokensFromStorage } from 'hds-react';

const apiTokens = getApiTokensFromStorage();
if (apiTokens) {
  // Use tokens
}

State change signals

The Api tokens client has no state changes.

Error signal types

Returned errors are instances of the ApiTokensClientError. It is an extended Error object with type property and multiple .is... getters for checking error types. The error object also contains the thrown error in error.originalError property.

Event signals

The Api tokens client also emits events when an action is complete or starting.

Dedicated signal triggers

Triggers for Api tokens client signals. These trigger signals only originated from the Api tokens client.

Event triggers require the signal to have Api tokens client namespace and type event. Signal.payload.type contains one of the events.

Error triggers require the signal to have Api tokens client namespace and type error. Signal.payload.type contains one of the errors.

Getting signal payloads

Sometimes the most significant part of a signal is the payload. There are predefined payload getters for the Api tokens client. If the given signal is not from Api tokens client or is not given type, the function returns null. So there is no need to pre-check the signal namespace or type.

Hooks

Api tokens client hooks are listed in the hooks section.

Session poller

The user's session could end outside of the current browser window. The Session poller calls the userinfo endpoint and notifies when it receives an unauthorized or forbidden response. Successes and other errors are ignored.

Requirements

Polling requires a user and the userManager from the Oidc client. The polling endpoint is fetched from userManager's metadata.

Settings

Methods

Other exported utility functions

The following function can be imported and used without the Session poller module:

import { createSessionPoller } from 'hds-react';

const sessionPoller = createSessionPoller();

State change signals

The Session poller has no state changes.

Error signal types

Returned errors are instances of the SessionPollerError. It is an extended Error object with type property and multiple .is... getters for checking error types. The error object also contains the thrown error in error.originalError property.

Event signals

The Session poller also emits events when an action is complete or starting.

Dedicated signal triggers

Triggers for Session pollersignals. These trigger signals only originated from the Session poller.

Event triggers require the signal to have a Session poller namespace and type event. Signal.payload.type contains one of the events.

Error triggers require the signal to have a Session pollernamespace and type error. Signal.payload.type contains one of the errors.

Getting signal payloads

Sometimes the most significant part of a signal is the payload. There are predefined payload getters for the Session poller. If the given signal is not from the Session poller or is not given type, the function returns null. So there is no need to pre-check the signal namespace or type.

GraphQL Module

Loading data from a graphQL server may require user authentication and api tokens. The GraphQL module can be set to listen to the Api token client and start querying when api tokens are ready. It can pick the correct api token and set it to the query headers.

The module can also be used without api tokens and can be controlled manually.

Unlike the Api token client and Session Poller, the GraphQL Module must be manually added to the <LoginProvider>.

import { ApolloClient } from '@apollo/client';
import { createGraphQLModule } from 'hds-react';
import { queryDocument } from './<path to queries>';

const graphQLClient = new ApolloClient({
  uri: 'https://graphql.endpoint.com/graphql/',
  cache: new InMemoryCache(),
});

const options = {
  graphQLClient,
  query: queryDocument,
  queryOptions: {
    errorPolicy: 'all',
  },
};
const graphQLModule = createGraphQLModule(options);

<LoginProvider {...loginProps} modules={[graphQLModule]}></LoginProvider>;

Requirements

To execute a query, the following requirements must be met:

• A graphQLClient (ApolloClient) must be configured and passed to the GraphQL module.
• A query document must be provided.

If the graphQL end-point requires an authentication, then the authentication headers must be set by

• Providing them in queryOptions.header.
• Setting them in queryHelper().
• Requiring api tokens with options.requireApiTokens and setting options.apiTokenKey.

Important

The module props do not require a query document or a graphQLClient, but a query cannot be executed without them. Both can also be passed as arguments to the query(options). The client can also be set by calling setClient(client).

Once set, the client is stored, and there is no need to pass it again. The query document is not stored, so different queries can be used every time.

When used with Helsinki City Profile, the queryOptions.errorPolicy should be set to "all". Otherwise, queries will fail when a weakly authenticated user tries to get the profile. The resulting data will include (dismissable) errors, and an ApolloClient query will fail when the data has an error property.

The createGraphQLModule function is a Generic Typescript function with two types: createGraphQLModule<Q = GraphQLQueryResult, T = NormalizedCacheObject>. The first type, Q, defines what kind of results the query returns. The latter, T, only describes the cache type of the ApolloClient and is not usually changed.

Settings

Methods

Other exported utility functions

The following functions can be imported and used without the GraphQL module module:

State change signals

The GraphQL module has no state changes.

Error signal types

Returned errors are instances of the GraphQLModuleError. It is an extended Error object with type property and multiple .is... getters for checking error types. The error object also contains the thrown error in error.originalError property.

Event signals

The GraphQL module also emits events when an action is complete or starting.

Dedicated signal triggers

Triggers for GraphQL modulesignals. These trigger signals only originated from the GraphQL module.

Event triggers require the signal to have a GraphQL module namespace and type event. Signal.payload.type contains one of the events.

Error triggers require the signal to have a GraphQL modulenamespace and type error. Signal.payload.type contains one of the errors.

Getting signal payloads

Sometimes the most significant part of a signal is the payload. There are predefined payload getters for the GraphQL module. If the given signal is not from the GraphQL module or is not given type, the function returns null. So there is no need to pre-check the signal namespace or type.

ApolloClient Module

Appending api tokens to every query and manually waiting for api token renewal is a complicated task. The ApolloClient module links itself to the Api token client and automatically appends tokens and also awaits for token renewals.

The module can also be used without api tokens. This module does not emit signals.

The ApolloClient Module must be manually added to the <LoginProvider>. Preferably use the LoginProviderWithApolloContext which also creates the ApolloContext.

import { createApolloClientModule } from 'hds-react';

const options = {
  clientOptions:{
    // apollo client option.
  },
  tokenSetter: (headers, apiTokens) => {
    return {
      Authentication: apiTokens['tokenToAppend'],
    };
  },
};
const apolloClientModule = createApolloClientModule(options);

<LoginProviderWithApolloContext {...loginProps} modules={[apolloClientModule]}></LoginProviderWithApolloContextx  >;

The createApolloClientModule function is a Generic Typescript function: createApolloClientModule<T = InMemoryCache>. The generic describes the cache type of the ApolloClient and is not usually changed.

Settings

Methods

The ApolloClient does not emit any signals. Therefore there are no hooks or triggers related to signals.

TokenizedFetch Module

Loading data from a server may require user authentication and api tokens. The TokenizedFetch module listens to the Api token client and appends api tokens to the request headers.

The TokenizedFetch Module must be manually added to the <LoginProvider>.

import { createTokenizedFetchModule } from 'hds-react';

const options = {
  tokenSetter: (headers, apiTokens) => {
    return {
      Authentication: apiTokens['tokenToAppend'],
    };
  },
};
const tokenizedFetchModule = createTokenizedFetchModule(options);

<LoginProvider {...loginProps} modules={[tokenizedFetchModule]}></LoginProvider>;

Settings

Methods

Other exported utility functions

The following functions can be imported and used without the TokenizedFetch module module:

State change signals

The TokenizedFetch module has no state changes.

Error signal

The module emits only one kind of error. They are instances of the TokenizedFetchModuleError. It is an extended Error object with type property and a hasResponseIdentifierMatch helper function to identify fetch calls. The error object also contains the thrown error in error.originalError property.

The hasResponseIdentifierMatch(type:string)=>boolean returns true if the error originated from a fetch with given id. Ids are used only when using tokenizedFetchWithSignals or emitResponse.

Event signals

The TokenizedFetch module also emits events only when the tokenizedFetchWithSignals is used. Events can also be manually emitted with emitFetchStart or emitResponse

The simplest way to track signals is with hooks.

Dedicated signal triggers

Triggers for TokenizedFetch module signals. These trigger signals only originated from the TokenizedFetch module.

The createTriggerPropsForTokenizedFetchResponseSignals(identifier: string): SignalTrigger creates a SignalTrigger that returns true if the signal is an event signal from the TokenizedFetch Module and its payload has given identifier.

Getting signal payloads

Sometimes the most significant part of a signal is the payload. There are predefined payload getters for the TokenizedFetch module. If the given signal is not from the TokenizedFetch module or is not given type, the function returns null. So there is no need to pre-check the signal namespace or type.

Oidc client hooks

The usage of the Oidc client hooks is described in the usage section.

Api tokens client hooks

The usage of the Api tokens client hooks is described in the usage section.

Session poller hooks

The usage of the Session poller hooks is described in the usage section.

GraphQL module hooks

The usage of the GraphQL module hooks is described in the usage section.

ApolloClient module hooks

The usage of the ApolloClient module hooks is described in the usage section.

TokenizedFetch module hooks

Generic signal hooks

Important! The listener passed to useSignalListener must be memoized or the hook will attach a new listener on each render because the props changed. The old one is disposed of but to avoid unnecessary listeners, use memoization with useMemo or useCallback. Note that all triggerFor... functions are constants and do not need memoization.

useSignalTrackingWithReturnValue and useSignalListener store their arguments in React refs, so memoization is not needed.

The usage of the signal hooks is described in the usage section.

Beacon

The beacon is the controller of all signals and listeners. It emits all signals and connects all modules. It also stores all modules. Modules are added and connected by calling beacon.addContext(module). The beacon then calls module.connect() with the beacon as the only argument. After that, the module can listen to and emit signals.

Beacon methods

Important

Like in React, once a signal (an event in React) is emitted, it is destroyed after all listeners have been called. Copy the object if it is needed for later use.

Signals

Signals have a type property to separate, for example errors, from other signals. Signals are easier to create with utility functions than by manually setting all properties.

The signal object

A signal is an object with the following properties:

Signal types and payloads

Custom modules may emit any other kind of signal with different payloads.

Emitting signals

Only custom modules can emit signals. See the custom module documentation.

See also custom namespaced beacons.

Important

If a listener is added while signaling and it is triggered by the currently emitted signal, a loop could be created. This could occur when using hooks and not memoizing listeners. Avoid emitting signals inside listeners.

Listening to signals

A signal listener is a function that receives one argument: the signal. A listener can listen to all signals or just one type of signal with a certain namespace. Listeners can be even more specific and listen to signals with certain payloads. In short, a listener can listen to any properties of the signal and is triggered when all properties match.

The listener is called only if the emitted signal matches the given props.

For example, if the trigger props (the first argument) passed to beacon.addListener(trigger, listener) is { type:'error' }, the listener (second argument) is called when the emitted signal has a matching type. It does not matter what other props the signal has.

If the trigger props are { namespace:'myModule', payload:{ type: 'click' } }, the emitted signal must have those properties with the same, exact values. Other properties are not checked.

The trigger can also be a function. Internally all triggers are converted to functions.

Instead of writing signal types as strings, it is better to use predefined triggers:

• Oidc client triggers.
• Api tokens client triggers.
• Session poller triggers.
• GraphQL module triggers.
• TokenizedFetch module triggers.
• Generic triggers.

Generic triggers

Generic create... functions create trigger functions from given props. Creator functions are not objects, so they can be used to create triggers for multiple namespaces, payloads and so on.

See also hooks.

Generic signal utility functions

Create

Signals are easier to create with functions than by manually setting all properties.

Check

Check the signal type or namespace with these utilities.

Get payloads

Returns signal payload if the signal type is a match.

Convert and filter

waitForSignals

The function returns a promise, which is resolved when the given signal(s) have been detected. Or it rejects the promise when a signal from an optional rejection list is given.

The function can be used for racing conditions, for example waiting for a user renewal success or error, whichever comes first.

Or wait for a longer set of emitted signals from the start of user renewal to the end of API token renewal.

The promise is created with waitForSignals(beaconInstance, arrayOfTriggers, options).

When the promise is resolved, it returns an array of received signals. If it is rejected, an error is returned.

There is no timeout. The promise can be rejected by setting a custom signal type to options.rejectOn and emit a matching signal.

import { waitForSignals, userRenewalStartedTrigger } from 'hds-react';
const createMyCustomModule = (): ConnectedModule => {
  let beacon: Beacon | undefined;
  const myCustomRejectSignal = { type: 'reject', namespace: 'myNamespace' };
  const listener = (signal) => {
    setTimeout(() => {
      beacon.emit(myCustomRejectSignal);
    }, 20000);
    waitForSignals(beacon, [isUserUpdatedSignal], {
      rejectOn: [isUserRemovedSignal, isRenewalErrorSignal, myCustomRejectSignal],
    })
      .then((signals) => {
        //
      })
      .catch((error) => {
        //
      });
  };
  return {
    namespace: helperNamespace,
    connect: (targetBeacon) => {
      beacon = targetBeacon;
      beacon.addListener(userRenewalStartedTrigger, listener);
    },
  };
};

Object types from oidc-client-ts

The Oidc client module uses the oidc-client-ts. Some of its objects are returned from the module. Their documentation can be found in its repository:

• User
• UserManager
• UserManagerSettings