Skip to main content

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

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>',
  })
}
info

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

Login​

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();
});

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.

Login através de popup​

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();
});

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;
});

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();
  ...
}

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 ,
  })
}

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 ,
  })
}

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();
});

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();
});

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();
});

Logout​

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

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

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