@betha-plataforma/oauthdeprecated

Biblioteca JavaScript para lidar com o fluxo do OAuth 2.0 em aplicações Web, com suporte a TypeScript.

Usage no npm install needed!

<script type="module">
  import bethaPlataformaOauth from 'https://cdn.skypack.dev/@betha-plataforma/oauth';
</script>

README

@betha-plataforma/oauth

Biblioteca JavaScript para lidar com o fluxo do OAuth 2.0 em aplicações Web, com suporte a TypeScript.

Instalando

NPM

npm install @betha-plataforma/oauth

Yarn

yarn add @betha-plataforma/oauth

CDN (unpkg)

<script src="https://unpkg.com/@betha-plataforma/oauth"></script>

Ao utilizar o CDN, as referências podem ser obtidas através do window.OAuth

Utilizando

Atualmente o fluxo suportado é o Implicit, abaixo temos um exemplo de como configurá-lo.

Este fluxo é usado para aplicativos móveis e aplicações web, onde a capacidade de armazenar segredos no cliente não é garantida. Entenda melhor sobre este fluxo neste guia Introdução ao OAuth 2 da Digital Ocean e caso queira entender na prática acesse o OAuth 2.0 Playground.

OAuth

Criando uma instância de aplicação OAuth.

ℹ️ Para entender como integrar com o protocolo OAuth 2 disponibilizado pela Plataforma Betha, acesse esta seção.

import { OpenIDProvider, OAuthApplication, resolveProvider } from '@betha-plataforma/oauth';

// Client config
const config = {
  clientId: 'my_client_id',
  redirectUri: 'http://localhost:3000/callback',
  silentRedirectUri: 'http://localhost:3000/silent-callback',
  scope: 'read write'
}

// Obter um OpenID Connect através do método abaixo.
const provider: OpenIDProvider = await resolveProvider('https://my.oidc.provider.com');

// Ou configurar, conforme exemplo
const provider = {
  authorization_endpoint: `https://oauth.provider.com/v1/authorize`,
  check_session_iframe: `https://login.provider.com/v1/openidsso.jsp`,
  end_session_endpoint: `https://login.provider.com/v1/logout?continue=https://oauth.provider.com/v1/authorize?client_id=${config.clientId}%26response_type=token%26redirect_uri=${config.redirectUri}%26scope=${config.scope}`,
  introspect_endpoint: `https://oauth.provider.com/v1/tokeninfo`,
  token_endpoint: `https://oauth.provider.com/v1/token`,
  userinfo_endpoint: `https://users.provider.com/v1/api/usuarios/@me`
};

export const oAuthApp: OAuthApplication = new OAuthApplication({ ...config, provider });

Aplicação

Ao inicializar a aplicação, caso não possua sessão ativa, direcionar ao servidor de login.

import { oAuthApp } from './oauth-application.ts';

if (!oAuthApp.hasActiveSession()) {
  oAuthApp.login();
} else {
  console.log({
    user: oAuthApp.getUser()
  });
}

Redirecionamento

Após o usuário se autenticar com suas credenciais ele é redirecionado para o redirectUri (configurado ao instanciar a aplicação OAuth) com algumas informações na URL.

Neste endereço, o método handleCallback deve ser chamado para lidar com essas informações.

import { oAuthApp } from './oauth-application.ts';

oAuthApp.handleCallback();

Renovação de token

Após autenticado, é possível renovar o token em segundo plano. Para isso é necessário ter uma página que emita algumas informações para a aplicação de origem, a mesma é configurada no silentRedirectUri ao instanciar a aplicação OAuth.

<html>
  <head>
    <script>
      parent.postMessage(location.hash, location.origin);
    </script>
  </head>
</html>

Monitoração de eventos

Durante o ciclo de vida de uma sessão alguns eventos provenientes de autenticação podem ser capturados para apresentar um feedback ao usuário.

Uma instância de um monitor de eventos pode ser criada conforme o snippet abaixo:

import { OAuthMonitor } from '@betha-plataforma/oauth';
import { oauthApp } from './oauth-application.ts';

const monitorOptions = { 
  app: oauthApp, 
  interval: 500
};

const monitor = new OAuthMonitor(monitorOptions, {
  onSessionChanged: () => {
    // OAuth session changed
  },
  onSessionEnded: () => {
    // OAuth session ended
  },
  onSessionRestablished: () => {
    // OAuth session restabilished
  }
});

monitor.start();

Provedor Plataforma Betha

A Plataforma é um provedor do OAuth 2.

Para fazer a autenticação, será necessário um usuário, que pode ser criado na Central de Usuário.

O registro da aplicação para obter o clientId é gerenciado pela equipe responsável, e se necessário, deve ser solicitado.

Configurando

Os hosts para os serviços do OAuth, Login e Usuários podem ser obtidos conforme constam em https://suite.cloud.betha.com.br/env.js.

Entretanto sugerimos a importação do env.js para que sua aplicação possa obter os valores de forma dinâmica, caso em algum momento seja necessário alteração nesses serviços, serão refletidos automaticamente.

Ex: index.html

<script src="https://suite.cloud.betha.com.br/env.js"></script>

Ex: oauth-app.js

import { OAuthApplication } from '@betha-plataforma/oauth';

const ClientConfig = {
  scope: 'SCOPES',
  clientId: 'CLIENT_ID',
  redirectUri: `${window.location.origin}/auth/callback.html`,
  silentRedirectUri: `${window.location.origin}/auth/silent-callback.html`
};

const OAUTH_URL = window['___bth'].envs.suite.oauth.v1.host;
const SERVICE_LOGIN_URL = window['___bth'].envs.suite['service-login'].v1.host;
const USERS_URL = window['___bth'].envs.suite.usuarios.v1.host;

function createBethaProvider(config) {
  const provider = {
    authorization_endpoint: `${OAUTH_URL}/authorize`,
    check_session_iframe: `${SERVICE_LOGIN_URL}/openidsso.jsp`,
    end_session_endpoint: `${SERVICE_LOGIN_URL}/logout?continue=${OAUTH_URL}/authorize?client_id=${config.clientId}%26response_type=token%26redirect_uri=${config.redirectUri}%26scope=${config.scope}`,
    introspect_endpoint: `${OAUTH_URL}/tokeninfo`,
    token_endpoint: `${OAUTH_URL}/token`,
    userinfo_endpoint: `${USERS_URL}/api/usuarios/@me`
  };

  return { ...config, provider };
}

export const oAuthApp = new OAuthApplication(createBethaProvider(ClientConfig));

Playground

Exemplos podem ser encontrados no playground