Eduzz Accounts React Wrapper

Sobre

SDK para fazer integração de aplicações react com o accounts, sistema de autenticação único da Eduzz. O SDK também disponibiliza uma funcionalidade de autorização através de interceptors para o axios.

Pré-requisitos

• [ ] CDN do script fornecido pela Eduzz, adicionado no index.html
• [ ] Frontend utilizando ReactJS
• [ ] Backend deve disponibilizar duas rotas, uma para login e outra para refresh token.

Sumário

1. Sobre

2. Instalação

   • Configurar script Eduzz
   • Instalar O SDK

3. Como usar

   • Importar o AuthProvider do SDK
   • Usar AuthProvider

Instalação

1. Colocar o script fornecido pela Eduzz, em public/index.html do projeto ReactJS

<script
  rel="preconnect"
  src="https://cdn.eduzzcdn.com/accounts/accounts.js"
></script>

2. Instalar O SDK

• Adicionar o SDK ao projeto

    yarn add @eduzz/accounts-react-wrapper

• ⚠️ Se o seu npm for >=3.x adicionar peerDependencies ao projeto, utilizar o comando exemplo abaixo com as libs exibidas no warning do seu terminal:

      yarn add lib1@^1.20.1 lib2@^0.23.0 lib3@^2.0.2

Como usar

1. Criar arquivo de configuração para o AuthProvider

// Nome de arquivo sugerido: config/accounts.ts
// Exemplo:
import {
  AuthProviderConfig,
  authentication,
} from '@eduzz/accounts-react-wrapper';

const config: AuthProviderConfig = {
  accounts: {
    partnerId: 'itj90bnlrg0394fnvrg8903lsdgn',
    env: 'homolog',
  },
  api: {
    url: 'http://localhost:5000',
    login: {
      request: {
        path: '/auth/login',
        tokenKey: 'accountToken',
        params: {
          key: 'value',
        },
      },
      response: {
        tokenKey: 'bearerToken',
        refreshTokenKey: 'refreshToken',
        mapData: 'data',
      },
    },
    refresh: {
      request: {
        path: '/auth/refreshtoken',
        refreshTokenKey: 'refreshToken',
        params: {
          key: 'value',
        },
      },
      response: {
        tokenKey: 'bearerToken',
        refreshTokenKey: 'refreshToken',
        mapData: 'data',
      },
    },
  },
  backOffice: {
    urlParam: 'accounts_login_token',
  },
  authentication,
};

/*
  Configuração dos endpoints de login e refresh token.
  
  1. Login

  1.1 Request

  - path: Path do endpoint de login;
  - tokenKey: Nome da propriedade de token retornada pelo script accounts esperada pelo backend;
  - params(opcional): Quaisquer outros parâmetros necessários.

  1.2 Response

  Definição do nome das propriedades de token e refresh token retornadas no endpoint de login.

  - mapData(opcional): string do path que contém as respostas da api. ex: data.dados
  
  2. Refresh

  2.1 Request

  - path: Path do endpoint de refresh token;
  - refreshTokenKey: Nome da propriedade de refresh token esperada pelo o backend;
  - params(opcional): Quaisquer outros parâmetros necessários.

  2.2 Response

  Definição do nome das propriedades de token e refresh token retornadas no endpoint de refresh token.
  
  - mapData(opcional): string do path que contém as respostas da api. ex: data.dados

  Configuração do Back Office

  Configurar o query param de login via Back Office para que o SDK identifique o login como suporte, não faça o refresh do token e siga o fluxo de autenticação a partir de login no accounts.

  A definição dessa parâmetro está no projeto backoffice.

  No exemplo de configuração abaixo o SDK espera o parâmetro accounts_login_token na URL e identifica como login de suporte.

  backOffice(opcional): {
    urlParam: "accounts_login_token",
  }  
  
  */

export default config;

2. Importar o AuthProvider e o arquivo de configuração, e envolver a árvore de elementos da aplicação

import { AuthProvider } from '@eduzz/accounts-react-wrapper';
import config from './config/accounts.ts';

ReactDOM.render(
  <React.StrictMode>
    <AuthProvider config={config}>
      <App />
    </AuthProvider>
  </React.StrictMode>,
  document.getElementById('root')
);

3. Importar hook useAuth e utlizar no componente

import { useAuth } from '@eduzz/accounts-react-wrapper';

type ExapledBearerTokenDecoded = {
  name: string;
  email: string;
}

function App() {
  const { bearerTokenDecoded, loading, bearerToken, logout } = useAuth<ExapledBearerTokenDecoded>();

  return (
    <div className='App'>
      <header className='App-header'>
        <div className="App">
          <p>user name: {bearerTokenDecoded?.name}</p>
          <p>user email: {bearerTokenDecoded?.email}</p>
          <p>bearerToken: {bearerToken}</p>
          <p>loading: {loading}</p>
          <button onClick={logout}>Logout</button>
        </div>
      </header>
    </div>
  )
}

4. Inicializar interceptors

import { Apis } from 'web/services/api'
import { useAuth } from '@eduzz/accounts-react-wrapper';
import axios from 'axios'

type ExapledBearerTokenDecoded = {
  name: string;
  email: string;
}

function App() {
  const { bearerTokenDecoded, loading, bearerToken, logout, interceptors } = useAuth<ExapledBearerTokenDecoded>();

  useEffect(()=>{
    interceptors?.axios.initialize({
				interceptors: axios.interceptors,
				active: { // não obrigatório, se não passar ativa todos os interceptors.
					addBearerOnAllRequests: true, // default
					logoutWhenResponseIsUnauthorized: true, // default
					refreshWhenBearerTokenIsExpired: true, // default
				}
			});
  },[bearerToken])

  return (
    <div className='App'>
      <header className='App-header'>
        <div className="App">
          <p>user name: {bearerTokenDecoded?.name}</p>
          <p>user email: {bearerTokenDecoded?.email}</p>
          <p>bearerToken: {bearerToken}</p>
          <p>loading: {loading}</p>
          <button onClick={logout}>Logout</button>
        </div>
      </header>
    </div>
  )
}