Building login

Draft

The Login pattern describes how HDS Login components and HDS Header login functionalities are meant to work together.

Principles

Login components

HDS Login components include React context, components and hooks for handling user authorisation, API tokens, session polling and GraphQL queries.

Requirements

The following steps are required for user authentication:

Log in process

Logging in or out of an OIDC server requires browser redirections to the server and back. User interfaces only show login and logout buttons. No other form elements are needed.

The login call is asyncronous and may fail if the OIDC server is offline or the service URL is not registered. The user interface must indicate loading has started, and possible errors must be handled by the user interface.

The HDS Header Login button handles all of these scenarios.

Log out process

Log out is almost identical to the log in process. It is also asyncronous and may fail.

The HDS Header Logout button handles all of these scenarios.

User data from the OIDC server

User information is stored in tokens which are decrypted by the Login system and an user object is provided to user interfaces. It holds, for example, user's name and email address.

User object can be accessed with the useAuthenticatedUser hook.

The HDS Header User menu automatically shows the user's name and initials.

User data from the Profile Service

Profile information is not used by the HDS. It can be fetched with the GraphQL module, but it is not used in HDS components. The user object returned by the OIDC server has a profile property, but that is just an unfortunate naming convention. It is not the Helsinki Profile.

Header.Login components

HDS Header has built-in functionalities for login button as well as a dropdown user menu. The Header Login button is a variant of Header.ActionBarItem that uses the fixedRightPosition prop to have special functionalities in mobile breakpoints. From breakpoint M (≥ 768px) and down, the Login button is hidden, and the contents are moved inside the Header.ActionBar component's menu alongside NavigationMenu. See more documentation on Header.Login on the Header component page.

All Header login components require the LoginProvider React Context. Other Header components can be used to build identical functionalities, but user interactions and data must be handled manually.

Header Login button

The Login button is an action item in the header. It indicates loading progress and handles connection errors.

Header User Menu Button

The User Menu button offers placement for user information.

  • The user's name and initials.
  • Can host links and icons.
  • Should host a logout button.

Header Logout Submenu Button

The Logout Submenu button is a submenu item in the header dropdown. It indicates loading progress and handles connection errors.

To learn more about the Header component and its subcomponents, please refer to the component page.