Pular para o conteúdo principal

Adicionar autenticação ao seu aplicativo React

Este guia mostrará como integrar o Logto ao seu aplicativo React.

dica

Pré-requisitos​

Instalação​

Importe o Logto SDK através do seu gerenciador de pacotes favorito:

npm i @logto/react

Integração​

Inicializar o provedor Logto​

Importe e use LogtoProvider para fornecer um contexto Logto ao seu aplicativo:

App.tsx
import { LogtoProvider, LogtoConfig } from '@logto/react';

const config: LogtoConfig = {
  endpoint: '<your-logto-endpoint>', // Ex.: http://localhost:3001
  appId: '<your-application-id>',
};

const App = () => (
  <LogtoProvider config={config}>
    <YourAppContent />
  </LogtoProvider>
);

Configurar URIs de redirecionamento​

Antes de mergulharmos nos detalhes, aqui está uma visão geral rápida da experiência do usuário final. O processo de login pode ser simplificado da seguinte forma:

  1. Seu aplicativo invoca o método de login.
  2. O usuário é redirecionado para a página de login do Logto. Para aplicativos nativos, o navegador do sistema é aberto.
  3. O usuário faz login e é redirecionado de volta para o seu aplicativo (configurado como o URI de redirecionamento).
Sobre o login baseado em redirecionamento
  1. Este processo de autenticação segue o protocolo OpenID Connect (OIDC), e o Logto aplica medidas de segurança rigorosas para proteger o login do usuário.
  2. Se você tiver vários aplicativos, pode usar o mesmo provedor de identidade (Logto). Uma vez que o usuário faz login em um aplicativo, o Logto completará automaticamente o processo de login quando o usuário acessar outro aplicativo.

Para saber mais sobre a lógica e os benefícios do login baseado em redirecionamento, veja Experiência de login do Logto explicada.

nota

Nos trechos de código a seguir, assumimos que seu aplicativo está sendo executado em http://localhost:3000/.

Configurar URIs de redirecionamento​

Vá para a página de detalhes do aplicativo no Logto Console. Adicione um URI de redirecionamento http://localhost:3000/callback.

URI de redirecionamento no Logto Console

Assim como no login, os usuários devem ser redirecionados para o Logto para sair da sessão compartilhada. Uma vez concluído, seria ótimo redirecionar o usuário de volta para o seu site. Por exemplo, adicione http://localhost:3000/ como a seção de URI de redirecionamento pós logout.

Em seguida, clique em "Salvar" para salvar as alterações.

Lidar com redirecionamento​

Como usamos http://localhost:3000/callback como o URI de redirecionamento, agora precisamos tratá-lo adequadamente.

Primeiro, vamos criar uma página de callback:

pages/Callback/index.tsx
import { useHandleSignInCallback } from '@logto/react';

const Callback = () => {
  const { isLoading } = useHandleSignInCallback(() => {
    // Faça algo quando terminar, por exemplo, redirecione para a página inicial
  });

  // Quando está em andamento
  if (isLoading) {
    return <div>Redirecionando...</div>;
  }

  return null;
};

Por fim, insira o código abaixo para criar uma rota /callback que NÃO requer autenticação:

App.tsx
// Assumindo react-router
<Route path="/callback" element={<Callback />} />

Implementar login e logout​

Fornecemos dois hooks useHandleSignInCallback() e useLogto() que podem ajudá-lo a gerenciar facilmente o fluxo de autenticação.

nota

Antes de chamar .signIn(), certifique-se de que você configurou corretamente o URI de redirecionamento no Admin Console.

pages/Home/index.tsx
import { useLogto } from '@logto/react';

const Home = () => {
  const { signIn, signOut, isAuthenticated } = useLogto();

  return isAuthenticated ? (
    <button onClick={signOut}>Sign Out</button>
  ) : (
    <button onClick={() => signIn('http://localhost:3000/callback')}>Sign In</button>
  );
};

Chamar .signOut() limpará todos os dados do Logto na memória e no localStorage, se existirem.

Ponto de verificação: Teste seu aplicativo​

Agora, você pode testar seu aplicativo:

  1. Execute seu aplicativo, você verá o botão de login.
  2. Clique no botão de login, o SDK iniciará o processo de login e redirecionará você para a página de login do Logto.
  3. Após fazer login, você será redirecionado de volta para o seu aplicativo e verá o botão de logout.
  4. Clique no botão de logout para limpar o armazenamento local e sair.

Obter informações do usuário​

Exibir informações do usuário​

Para exibir as informações do usuário, você pode usar o método getIdTokenClaims(). Por exemplo, na sua página Home:

pages/Home/index.tsx
import { useLogto, type IdTokenClaims } from '@logto/react';
import { useEffect, useState } from 'react';

const Home = () => {
  const { isAuthenticated, getIdTokenClaims } = useLogto();
  const [user, setUser] = useState<IdTokenClaims>();

  useEffect(() => {
    (async () => {
      if (isAuthenticated) {
        const claims = await getIdTokenClaims();
        setUser(claims);
      }
    })();
  }, [getIdTokenClaims, isAuthenticated]);

  return (
    // ...
    {isAuthenticated && user && (
      <table>
        <thead>
          <tr>
            <th>Nome</th>
            <th>Valor</th>
          </tr>
        </thead>
        <tbody>
          {Object.entries(user).map(([key, value]) => (
            <tr key={key}>
              <td>{key}</td>
              <td>{typeof value === 'string' ? value : JSON.stringify(value)}</td>
            </tr>
          ))}
        </tbody>
      </table>
    )}
  );
}

Solicitar reivindicações adicionais​

Você pode perceber que algumas informações do usuário estão faltando no objeto retornado de getIdTokenClaims(). Isso ocorre porque OAuth 2.0 e OpenID Connect (OIDC) são projetados para seguir o princípio do menor privilégio (PoLP), e o Logto é construído com base nesses padrões.

Por padrão, reivindicações limitadas são retornadas. Se você precisar de mais informações, pode solicitar escopos adicionais para acessar mais reivindicações.

info

Uma "reivindicação (Claim)" é uma afirmação feita sobre um sujeito; um "escopo (Scope)" é um grupo de reivindicações. No caso atual, uma reivindicação é uma informação sobre o usuário.

Aqui está um exemplo não normativo da relação escopo - reivindicação:

dica

A reivindicação "sub" significa "sujeito (Subject)", que é o identificador único do usuário (ou seja, ID do usuário).

O Logto SDK sempre solicitará três escopos: openid, profile e offline_access.

Para solicitar escopos adicionais, você pode configurar as configurações do provedor Logto:

App.tsx
import { LogtoConfig, UserScope } from '@logto/react';

const config: LogtoConfig = {
  // ...outras configurações
  scopes: [
    UserScope.Email,
    UserScope.Phone,
    UserScope.CustomData,
    UserScope.Identities,
    UserScope.Organizations,
  ],
};

Então você pode acessar as reivindicações adicionais no valor de retorno de getIdTokenClaims():

const claims = await getIdTokenClaims();
// Agora você pode acessar reivindicações adicionais `claims.email`, `claims.phone`, etc.

Reivindicações que precisam de solicitações de rede​

Para evitar o inchaço do Token de ID (ID token), algumas reivindicações requerem solicitações de rede para serem buscadas. Por exemplo, a reivindicação custom_data não está incluída no objeto do usuário, mesmo que seja solicitada nos escopos. Para acessar essas reivindicações, você pode usar o método fetchUserInfo():

const { fetchUserInfo } = useLogto();

const userInfo = await fetchUserInfo();

// Agora você pode acessar a reivindicação `userInfo.custom_data`
Este método buscará as informações do usuário solicitando ao endpoint userinfo. Para saber mais sobre os escopos e reivindicações disponíveis, veja a seção Escopos e reivindicações.

Escopos e reivindicações​

Logto usa as convenções de escopos e reivindicações do OIDC para definir os escopos e reivindicações para recuperar informações do usuário do Token de ID e do endpoint userinfo do OIDC. Tanto "escopo" quanto "reivindicação" são termos das especificações OAuth 2.0 e OpenID Connect (OIDC).

Aqui está a lista de Escopos (Scopes) suportados e as Reivindicações (Claims) correspondentes:

openid

Nome da ReivindicaçãoTipoDescriçãoPrecisa de userinfo?
substringO identificador único do usuárioNão

profile

Nome da ReivindicaçãoTipoDescriçãoPrecisa de userinfo?
namestringO nome completo do usuárioNão
usernamestringO nome de usuário do usuárioNão
picturestringURL da foto de perfil do Usuário Final. Este URL DEVE referir-se a um arquivo de imagem (por exemplo, um arquivo de imagem PNG, JPEG ou GIF), em vez de uma página da Web contendo uma imagem. Note que este URL DEVE referenciar especificamente uma foto de perfil do Usuário Final adequada para exibição ao descrever o Usuário Final, em vez de uma foto arbitrária tirada pelo Usuário Final.Não
created_atnumberHora em que o Usuário Final foi criado. O tempo é representado como o número de milissegundos desde a época Unix (1970-01-01T00:00:00Z).Não
updated_atnumberHora em que as informações do Usuário Final foram atualizadas pela última vez. O tempo é representado como o número de milissegundos desde a época Unix (1970-01-01T00:00:00Z).Não

Outras reivindicações padrão incluem family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo e locale também serão incluídas no escopo profile sem a necessidade de solicitar o endpoint userinfo. Uma diferença em relação às reivindicações acima é que essas reivindicações só serão retornadas quando seus valores não estiverem vazios, enquanto as reivindicações acima retornarão null se os valores estiverem vazios.

nota

Ao contrário das reivindicações padrão, as reivindicações created_at e updated_at estão usando milissegundos em vez de segundos.

email

Nome da ReivindicaçãoTipoDescriçãoPrecisa de userinfo?
emailstringO endereço de email do usuárioNão
email_verifiedbooleanSe o endereço de email foi verificadoNão

phone

Nome da ReivindicaçãoTipoDescriçãoPrecisa de userinfo?
phone_numberstringO número de telefone do usuárioNão
phone_number_verifiedbooleanSe o número de telefone foi verificadoNão

address

Por favor, consulte o OpenID Connect Core 1.0 para os detalhes da reivindicação de endereço.

custom_data

Nome da ReivindicaçãoTipoDescriçãoPrecisa de userinfo?
custom_dataobjectOs dados personalizados do usuárioSim

identities

Nome da ReivindicaçãoTipoDescriçãoPrecisa de userinfo?
identitiesobjectAs identidades vinculadas do usuárioSim
sso_identitiesarrayAs identidades SSO vinculadas do usuárioSim

urn:logto:scope:organizations

Nome da ReivindicaçãoTipoDescriçãoPrecisa de userinfo?
organizationsstring[]Os IDs das organizações às quais o usuário pertenceNão
organization_dataobject[]Os dados das organizações às quais o usuário pertenceSim

urn:logto:scope:organization_roles

Nome da ReivindicaçãoTipoDescriçãoPrecisa de userinfo?
organization_rolesstring[]Os papéis da organização aos quais o usuário pertence com o formato <organization_id>:<role_name>Não

Considerando o desempenho e o tamanho dos dados, se "Precisa de userinfo?" for "Sim", isso significa que a reivindicação não aparecerá no Token de ID, mas será retornada na resposta do endpoint userinfo.

Recursos de API​

Recomendamos ler 🔐 Controle de Acesso Baseado em Papel (RBAC) primeiro para entender os conceitos básicos do RBAC do Logto e como configurar corretamente os recursos de API.

Configurar cliente Logto​

Depois de configurar os recursos de API, você pode adicioná-los ao configurar o Logto em seu aplicativo:

App.tsx
import { LogtoConfig } from '@logto/react';

const config: LogtoConfig = {
  // ...other configs
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // Adicionar recursos de API
};

Cada recurso de API tem suas próprias permissões (escopos).

Por exemplo, o recurso https://shopping.your-app.com/api tem as permissões shopping:read e shopping:write, e o recurso https://store.your-app.com/api tem as permissões store:read e store:write.

Para solicitar essas permissões, você pode adicioná-las ao configurar o Logto em seu aplicativo:

App.tsx
import { LogtoConfig } from '@logto/react';

const config: LogtoConfig = {
  // ...other configs
  scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};

Você pode notar que os escopos são definidos separadamente dos recursos de API. Isso ocorre porque Resource Indicators for OAuth 2.0 especifica que os escopos finais para a solicitação serão o produto cartesiano de todos os escopos em todos os serviços de destino.

Assim, no caso acima, os escopos podem ser simplificados a partir da definição no Logto, ambos os recursos de API podem ter escopos read e write sem o prefixo. Então, na configuração do Logto:

App.tsx
import { LogtoConfig } from '@logto/react';

const config: LogtoConfig = {
  // ...other configs
  scopes: ['read', 'write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};

Para cada recurso de API, ele solicitará os escopos read e write.

nota

Não há problema em solicitar escopos que não estão definidos nos recursos de API. Por exemplo, você pode solicitar o escopo email mesmo que os recursos de API não tenham o escopo email disponível. Escopos indisponíveis serão ignorados com segurança.

Após o login bem-sucedido, o Logto emitirá os escopos apropriados para os recursos de API de acordo com os papéis do usuário.

Buscar token de acesso para o recurso de API​

Para buscar o token de acesso para um recurso de API específico, você pode usar o método getAccessToken:

pages/Home/index.tsx
import { useLogto } from '@logto/react';

const Home = () => {
  const { isAuthenticated, getAccessToken } = useLogto();
  const [accessToken, setAccessToken] = useState('');

  useEffect(() => {
    (async () => {
      if (isAuthenticated) {
        const token = await getAccessToken('https://shopping.your-app.com/api');
        setAccessToken(token);
      }
    })();
  }, [isAuthenticated, getAccessToken]);

  return <p>{{ accessToken }}</p>;
};

Este método retornará um token de acesso JWT que pode ser usado para acessar o recurso de API quando o usuário tiver as permissões relacionadas. Se o token de acesso em cache atual tiver expirado, este método tentará automaticamente usar um token de atualização para obter um novo token de acesso.

Buscar tokens de organização​

Se organização é um conceito novo para você, por favor, leia 🏢 Organizações (Multi-tenancy) para começar.

Você precisa adicionar o escopo UserScope.Organizations ao configurar o cliente Logto:

App.tsx
import { LogtoConfig, UserScope } from '@logto/react';

const config: LogtoConfig = {
  // ...other configs
  scopes: [UserScope.Organizations],
};

Uma vez que o usuário esteja autenticado, você pode buscar o token de organização para o usuário:

pages/Organizations/index.tsx
import { useLogto } from '@logto/react';
import { useEffect, useState } from 'react';

const Organizations = () => {
  const { isAuthenticated, getOrganizationToken, getIdTokenClaims } = useLogto();
  const [organizationIds, setOrganizationIds] = useState<string[]>();

  useEffect(() => {
    (async () => {
      if (!isAuthenticated) {
        return;
      }
      const claims = await getIdTokenClaims();

      console.log('ID token claims', claims);
      setOrganizationIds(claims?.organizations);
    })();
  }, [isAuthenticated, getIdTokenClaims]);

  return (
    <section>
      <ul>
        {organizationIds?.map((organizationId) => {
          return (
            <li key={organizationId}>
              <span>{organizationId}</span>
              <button
                type="button"
                onClick={async () => {
                  console.log('raw token', await getOrganizationToken(organizationId));
                }}
              >
                buscar token (ver console)
              </button>
            </li>
          );
        })}
      </ul>
    </section>
  );
};

export default Organizations;

Anexar token de acesso aos cabeçalhos da solicitação​

Coloque o token no campo Authorization dos cabeçalhos HTTP com o formato Bearer (Bearer YOUR_TOKEN), e você está pronto para prosseguir.

nota

O fluxo de integração do Bearer Token pode variar com base no framework ou solicitante que você está usando. Escolha sua própria maneira de aplicar o cabeçalho de solicitação Authorization.

Leituras adicionais​

Fluxos do usuário final: fluxos de autenticação, fluxos de conta e fluxos de organização Configurar conectores Proteger sua API