@uaveiro/systems-bar v1.0.10

Table of Contents

• Get started
• Installation
• Styles
• Usage
• Authentication
  • Authentication Callback - /login route
  • Authentication Utilities
    • External packages
  • getAuthUserInformation
• API
  • Component Props
  • AuthConfig Props
  • Public Links Props
  • User Links Props
• Troubleshooting
  • Styling reset

Get started

@uaveiro/systems-bar is a reusable component library that helps the University of Aveiro contributors, developers and colleges. Add a universal navigation bar with all the university services.

Installation

@uaveiro/systems-bar components are written in Web Component using LitElement. Add @uaveiro/systems-bar components to your project.

npm install --save @uaveiro/systems-bar

Or with yarn

yarn add @uaveiro/systems-bar

Styles

Some styles have to be loaded on the page for the service bar to function properly. These styles contain the icons part, the font-family and the grid itself.

<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:100,300,400,500,700,900"/>

<link rel="stylesheet" href="https://static.ua.pt/css/font-awesome-pro/5.8.1/css/all.min.css"/>

<link rel="stylesheet" href="https://static.ua.pt/css/ua/static-lib/grid.css"/>

<link rel="stylesheet" href="https://static.ua.pt/css/portal-ua/1.0/systembar.min.css"/>

Usage

Use the component anywhere you use HTML: in your main document, a CMS, Markdown, or a framework like React or Vue.

import "@uaveiro/systems-bar";

or

<!--For older browser like IE 11 load the scripts below-->
<script src="https://unpkg.com/@webcomponents/webcomponentsjs@2.4.3/webcomponents-bundle.js"></script>

<!--Gets the most recent version-->
<script src="https://unpkg.com/@uaveiro/systems-bar"></script>

<!--Or With fixed version-->
<script src="https://unpkg.com/@uaveiro/systems-bar@1.0.5"></script>

and use them like so

<ua-systems-bar></ua-systems-bar>

Example with props

<ua-systems-bar
  publicLinks={JSON.stringify([
    { text: "My Custom Link", href: "#" },
    { text: "Another Custom Link", href: "#" },
  ])}
  userLinks={JSON.stringify([
    { text: "Open link", href: "#" },
    { text: "Custom Link", href: "#" },
  ])}
  lang="pt"
  containerFluid
/>

Authentication

Authentication is done with a JWT token. This token is located on LocalStorage. The system bar interprets the localStorage token location with the following name sb-ua-auth-token.

It is up to the developer to configure the authentication flow in his application so that the system bar can take advantage of its authenticated functionalities.

Below is the entire authentication configuration flow. The sample code below is done through React but it is possible to do it with simple javascript, since the system bar is agonistic to frameworks.

The settings below are based on the environment. This example are the default values when no authentication settings are entered.

<ua-systems-bar
  authConfig={JSON.stringify({
    login: "https://wso2-is.dev.ua.pt/oauth2/authorize",
    logout: "https://wso2-is.dev.ua.pt/oidc/logout",
    clientId: "D2wPaAQ3_dfgJgeStXAfwJRCKu0a",
    idToken: localStorage.getItem("sb-ua-auth-id-token"),
    callbackUri: "http://localhost:8081/pt/login",
  })}
/>

Authentication Callback - /login route

When the user clicks the "Login" link on the service bar, he is redirected to the University's IDP authentication page, after a successful authentication he is redirected (a callback is made) to the route /login, it is on this route where the token is interpreted and stored in LocalStorage.

For this, the developer has to add a route with the login name to his route system in the application.

import React, { useEffect } from "react";
//Router
import { useHistory } from "react-router-dom";
//Components
import { Loading } from "@uaveiro/ui";
//utils
import queryString from "query-string";

const AuthenticationCallback = () => {
  const history = useHistory();

  const getUserAuthToken = async (access_token, id_token) => {
    try {
      const res = await fetch(
        `https://api-portal.dev.ua.pt/api/v1/authentication/wso2/portal/login/${access_token}?local=true`
      );

      const { token } = await res.json();

      localStorage.setItem("sb-ua-auth-token", token);
      localStorage.setItem("sb-ua-auth-id-token", id_token);

      window.location.href = "/";
    } catch (error) {
      window.location.href = "/404";
    }
  };

  useEffect(() => {
    if (typeof window !== "undefined") {
      const { access_token, id_token } = queryString.parse(
        history.location.hash
      );

      getUserAuthToken(access_token, id_token, lastPath);
    }
  }, []);
  return <Loading />;
};

export default AuthenticationCallback;

Authentication Utilities

Below is a set of utilities to facilitate the manipulation of authentication in the application.

External packages

yarn add jwt-decode query-string

getAuthUserInformation

This function makes use of the token that is stored in LocalStorage. Use this function to determine if the user is logged in or even to collect personal information such as the User ID. This function makes use of the jwt-decode package to decode the token

const parseJwt = (token) => {
  var base64Url = token.split(".")[1];
  var base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
  var jsonPayload = decodeURIComponent(
    atob(base64)
      .split("")
      .map(function (c) {
        return "%" + ("00" + c.charCodeAt(0).toString(16)).slice(-2);
      })
      .join("")
  );

  return JSON.parse(jsonPayload);
};

const getAuthUserInformation = () => {
  const token = localStorage.getItem("sb-ua-auth-token");
  const defaultResponse = {
    token: "",
    authenticated: false,
  };

  if (token !== null) {
    const tokenData = parseJwt(token);

    if (Date.now().valueOf() / 1000 < tokenData.exp) {
      return {
        authenticated: true,
        token,
        photo: "https://via.placeholder.com/150",
        ...tokenData,
      };
    } else {
      return defaultResponse;
    }
  } else {
    return defaultResponse;
  }
};

API

Component Props

Component ua-systems-bar is based on a set of modifiable props, below the table represents the type of property and its description

AuthConfig Props

context The context collects the most appropriate information for each application where the bar is implemented

Public Links Props

publicLinks represents an array of objects with a data set to build central navigation

User Links Props

userLinks represents an array of objects with a data set to build the user's Avatar dropdown

Troubleshooting

Styling reset

If the service bar has style problems, you may not have reset the basic browser styles yet. Reset stylesheet helps to reduce browser inconsistencies in things like default line heights, margins and font sizes of headings, and so on.

  <style>
    *,
    *:before,
    *:after {
      margin: 0;
      padding: 0;
      box-sizing: border-box;
    }
  </style>