ID Magalu SDKs

O ID Magalu SDK oferece uma maneira eficiente e rápida de adicionar autenticação a uma ampla variedade de aplicativos. Este guia explica como integrar, implementar e exibir detalhes do perfil do usuário em um aplicativo React Single-Page Application usando o SDK.

Você pode visualizar ou baixar um aplicativo de amostra disponibilizado no Github.

Como baixar

Para começar, instale o ID Magalu SDK como uma dependência em seu projeto.

npm i @magalucloud/sdk-idmagalu-js

npm i @magalucloud/sdk-idmagalu-react

Configurando o SDK

Crie uma única instância do ID Magalu SDK antes de renderizar ou inicializar sua aplicação. Isso pode ser feito utilizando o método async/await ou com promisses. Essa instância precisa ser declarada apenas uma vez em seu projeto.

Em aplicativos React, apenas importe o componente AuthProvider e envolva seu aplicativo nele.

Para que funcione corretamente, você deve definir as seguintes propriedades:

clientId: Código retornado pelo CLI ao cadastrar sua aplicação.
redirectUri: A URL em seu aplicativo para o qual você gostaria que o ID Magalu redirecionasse os usuários após eles serem autenticados.
scope: Os escopos a serem solicitados ao ID Magalu.

import createClient from '@idmagalu/sdk-auth-pkce-js'
(async () => {
  const clientIDMagalu = await createClient({
    client_id: '<CLIENT_ID>',
    redirect_uri: '<REDIRECT_URI>',
  })
}

import { AuthProvider } from "@magalucloud/sdk-idmagalu-react";

const App = () => (
  <AuthProvider clientId="YOUR_CLIENT_ID" redirectUri="YOUR_REDIRECT_URI">
    <App />
  </AuthProvider>
);

info

A propriedade scope é opcional e caso não seja informado, seu valor padrão é openid profile.

Depois de configurar, é hora de implementar o login em seu projeto. Para isso, você irá utilizar o método login() para inciar o fluxo de autenticação que redireciona os usuários para página do ID Magalu.

document.getElementById("login").addEventListener("click", async () => {
  await clientIDMagalu.login();
});

import { useAuth } from "@magalucloud/sdk-idmagalu-react";

function LoginButton() {
  const { login } = useAuth();

  return <Button onClick={login}>Entrar com ID Magalu</Button>;
}

export default LoginButton;

Após o usuário autenticar com sucesso, ele será redirecionado de volta para a URL de retorno que você configurou anteriormente no redirect_uri.

Se você preferir que o fluxo de autenticação ocorra em um popup, em vez de redirecionar o usuário para uma nova página, utilize o método loginWithPopup. Dessa forma, uma janela será aberta e o usuário poderá fazer a autenticação e, ao concluí-la, o controle será devolvido à aplicação.

document.getElementById("login").addEventListener("click", async () => {
  await clientIDMagalu.loginWithPopup();
});

import { useAuth } from "@magalucloud/sdk-idmagalu-react";

function LoginButton() {
  const { loginWithPopup } = useAuth();

  return <Button onClick={() => loginWithPopup()}>Entrar com ID Magalu</Button>;
}

export default LoginButton;

O método tem como responsabilidade realizar a troca do código de autorização pelos dados de acesso. Sendo assim, a propriedade getTokenSilently não precisa estar definida na instância.

Caso sua aplicação pretenda obter os dados de acesso, o mesmo método retornará as seguintes informações.

document.getElementById("login").addEventListener("click", async () => {
  const response = await clientIDMagalu.loginWithPopup();
  // access_token: string;
  // created_at: number;
  // expires_in: number;
  // id_token: string;
  // refresh_token: string;
  // scope: string;
  // token_type: string;
});

import { useAuth } from "@magalucloud/sdk-idmagalu-react";

function LoginButton() {
  const { loginWithPopup } = useAuth();

  async function handleAuth(){
    const response = await loginWithPopup()
    // access_token: string;
    // created_at: number;
    // expires_in: number;
    // id_token: string;
    // refresh_token: string;
    // scope: string;
    // token_type: string;
  }

  return <Button onClick={() => handleAuth()}>Entrar com ID Magalu</Button>;
}

export default LoginButton;

Troca do código pelo token de acesso

Ao ser redirecionado de volta para sua aplicação o ID Magalu SDK fornece um método chamado handleRedirectCallback, responsável por concluir a autenticação trocando o código de autorização pelo token de acesso.

Para que esse evento possa ser utilizado, a aplicação deve ser capaz de validar a presença do code como parâmetro da URL.

if (location.search.includes("code=")) {
  const session = await clientIDMagalu.handleRedirectCallback();
  ...
}

import { useAuth } from "@magalucloud/sdk-idmagalu-react";

function AuthContext() {
  const { handleRedirectCallback } = useAuth();

  useEffect(() => {
    async function handleCodeExchange() {
      if (location.search.includes("code=")) {
        const session = await handleRedirectCallback()
        ...
      }
    }

    handleCodeExchange()
  },[])

  ...
}

O método handleRedirectCallback retorna as seguintes informações:

{
    access_token: string;
    created_at: number;
    expires_in: number;
    id_token: string;
    refresh_token: string;
    scope: string;
    token_type: string;
}

Disponibilizamos também uma outra alternativa a esta ação, utilize a propriedade getTokenSilently como true ao criar a instância. Dessa forma, o SDK será responsável por realizar o code exchange de forma silenciosa.

import createClient from '@idmagalu/sdk-auth-pkce-js'
(async () => {
  const clientIDMagalu = await createClient({
    client_id: '<CLIENT_ID>',
    redirect_uri: '<REDIRECT_URI>',
    getTokenSilently: true ,
  })
}

import { AuthProvider } from "@magalucloud/sdk-idmagalu-react";

const App = () => (
  <AuthProvider
    clientId="YOUR_CLIENT_ID"
    redirectUri="YOUR_REDIRECT_URI"
    getTokenSilently={true}
  >
    <Routes />
  </AuthProvider>
);

Armazenamento do token no estado de autenticação

Por padrão, os JWT's fornecidos pelo ID Magalu são armazenados na memória. Isso protege contra ataques CSRF (possíveis se armazenados como cookie do lado do cliente) e ataques XSS (possíveis se persistidos no armazenamento local).

A desvantagem dessa abordagem, no entanto, é que se uma página for atualizada ou uma nova guia for aberta, o token será apagado da memória e o botão de login precisará ser clicado novamente para autenticar.

Rotação de tokens de atualização

O ID Magalu SDK pode ser configurado para usar a rotação de tokens de atualização a fim de obter novos tokens de acesso silenciosamente.

A rotação de tokens de atualização é uma prática fundamental para melhorar a segurança em sistemas de autenticação e autorização. Essa técnica consiste em substituir regularmente os tokens de acesso por novos tokens, geralmente usando tokens de atualização. Ao utilizar a rotação de tokens de atualização, os sistemas podem reduzir significativamente o impacto de possíveis violações de segurança.

Para ativar o uso dessa prática, utilize a propriedade useRefreshTokens como true.

import createClient from '@idmagalu/sdk-auth-pkce-js'
(async () => {
  const clientIDMagalu = await createClient({
    client_id: '<CLIENT_ID>',
    redirect_uri: '<REDIRECT_URI>',
    getTokenSilently: true ,
    useRefreshTokens: true ,
  })
}

import { AuthProvider } from "@magalucloud/sdk-idmagalu-react";

const App = () => (
  <AuthProvider
    clientId="YOUR_CLIENT_ID"
    redirectUri="YOUR_REDIRECT_URI"
    getTokenSilently={true}
    useRefreshTokens={true}
  >
    <Routes />
  </AuthProvider>
);

Uma vez configurado, o ID Magalu SDK chamará diretamente o endpoint /oauth/token para atualizar os tokens sempre que houver uma nova renderização.

Abaixo temos um exemplo desse payload:

{
  "client_id": "<CLIENT_ID>",
  "grant_type": "refresh_token",
  "refresh_token": "<REFRESH_TOKEN>"
}

Atualizar token de acesso

Para uma aplicação que precisa gerenciar dados de sessão de forma eficaz, fornecemos o método handleRefreshToken.

import { useAuth } from "@magalucloud/sdk-idmagalu-react";

function Component() {
  const { handleRefreshToken } = useAuth();

  useEffect(() => {
    async function handleUpdateToken(){
      const refreshToken = localStorage.getItem('id_magalu_refresh_token')
      const sessionData = await handleRefreshToken(refreshToken)

      ...
    }

    handleUpdateToken()
  },[])

  ...
}

No exemplo acima, estamos acessando o token de atualização do localStorage apenas como demonstração. No entanto, a aplicação deve ser responsável por armazenar essa informação de maneira adequada.

O método recebe como argumento o token de atualização. Como retorno, teremos os dados da sessão.

Carregamento da página

Utilize o método isLoading para controlar sua aplicação até que os novos tokens sejam recebidos após a renderização da página.

import { useAuth } from "@magalucloud/sdk-idmagalu-react";

function Component() {
  const { isLoading } = useAuth();

  ...
}

Obtendo informações do usuário

Use o método getUser para obter informações do usuário ativo na sessão. No SDK React, este método chama-se user.

document.getElementById("getUser").addEventListener("click", () => {
  const user = clientIDMagalu.getUser();
});

import { useAuth } from "@magalucloud/sdk-idmagalu-react";

function Component() {
  const { user } = useAuth();

  return (
    <div className="text-black uppercase text-xs font-bold">
      {`Olá, ${user.name}`}
    </div>
  );
}

Exemplo de retorno:

{
  email: string;
  profile_image_url: string;
  name: string;
}

Obtendo informações da sessão

Use o método isAuthenticated para validar o status da sessão. Seu retorno é um boolean.

document.getElementById("isAuthenticated").addEventListener("click", () => {
  const isAuthenticated = clientIDMagalu.isAuthenticated();
});

import { useAuth } from '@magalucloud/sdk-idmagalu-react';

function Component() {
  const { isAuthenticated } = useAuth();

  ...
}

Obtendo o token de acesso

Use o método getToken para obter o token de acesso armazenado na memória. Seu retorno é uma string.

document.getElementById("getToken").addEventListener("click", () => {
  const accessToken = clientIDMagalu.getToken();
});

import { useAuth } from '@magalucloud/sdk-idmagalu-react';

function component() {
  const { getToken } = useAuth();

  ...
}

Logout

Use o método logout para desconectar o usuário de sua aplicação.

document.getElementById("logout").addEventListener("click", async () => {
  await clientIDMagalu.logout();
});

import { useAuth } from "@magalucloud/sdk-idmagalu-react";

function LogoutButton() {
  const { logout } = useAuth();

  return <Button onClick={logout}>Logout</Button>;
}

export default LogoutButton;

Essa operação efetuará a revogação do token do usuário apenas de sua aplicação, se o usuário estiver autenticado em outra aplicação com o ID Magalu, essa sessão manterá ativa e consequentemente por conta do processo de SSO (Single Sign On) se ele voltar em sua aplicação, o ID Magalu gerará um novo token de sua aplicação sem a necessidade do usuário digitar novamente seu usuário e senha

Como baixar​

Configurando o SDK​

Login​

Login através de popup​

Troca do código pelo token de acesso​

Armazenamento do token no estado de autenticação​

Rotação de tokens de atualização​

Atualizar token de acesso​

Carregamento da página​

Obtendo informações do usuário​

Obtendo informações da sessão​

Obtendo o token de acesso​

Logout​