@betha-plataforma/oauth v1.0.4
@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