Building login
DraftThe 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:
- The url of the service connecting to the OIDC server must be registered with a scope and a client ID.
- The callback from the OIDC server should be handled with the LoginCallbackHandler component.
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.