Adicionar autenticação ao seu aplicativo Angular

Este guia mostrará como integrar o Logto Angular SDK v2 ao seu aplicativo.

dica:

• Este guia utiliza o SDK oficial @logto/angular v2, que oferece suporte ao Angular 20 e fornece injeção de dependência e Signals.
• O projeto de exemplo está disponível em nosso repositório do SDK.

Pré-requisitos

• Uma conta no Logto Cloud ou um Logto auto-hospedado.
• Um aplicativo de página única (SPA) criado no Logto Console.
• Um projeto Angular 20.

Instalação

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

npm

npm i @logto/angular

pnpm

pnpm add @logto/angular

yarn

yarn add @logto/angular

Integração

Inicializar o provedor Logto

No seu projeto Angular, registre provideLogto e as rotas do seu aplicativo em app.config.ts:

app/app.config.ts

// Exemplo de configuração do Logto no Angular
import { type ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideLogto } from '@logto/angular';

import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideLogto({
      endpoint: '<your-logto-endpoint>',
      appId: '<your-app-id>',
    }),
    provideRouter(routes),
    // ...outros providers
  ],
};

O provideLogto restaura automaticamente o estado de autenticação após o primeiro render do navegador. Você não precisa chamar um método de inicialização em seus componentes.

nota:

Ao usar renderização do lado do servidor (SSR), o estado de autenticação e os tokens estão disponíveis apenas no navegador. Use isLoading() para exibir um estado de carregamento até que a inicialização termine. Se você precisar de dados autenticados durante a renderização no servidor, utilize um SDK de servidor ou BFF.

Configurar URIs de redirecionamento

Antes de entrarmos 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 app 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 seu app (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.

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 o redirecionamento

Crie um componente de callback para completar o login após o Logto redirecionar o usuário de volta para seu aplicativo. Use afterNextRender para que o tratamento do callback ocorra apenas no navegador:

app/callback.component.ts

// Exemplo de componente de callback para autenticação Logto
import { afterNextRender, Component, inject } from '@angular/core';
import { LogtoService } from '@logto/angular';

@Component({
  selector: 'app-callback',
  standalone: true,
  template: `
    @if (logto.error(); as error) {
      <p role="alert">{{ error.message }}</p>
    } @else {
      <p>Completando o login...</p>
    }
  `,
})
export class CallbackComponent {
  readonly logto = inject(LogtoService);

  constructor() {
    afterNextRender(() => {
      void (async () => {
        const callbackUri = window.location.href;

        if (!(await this.logto.isSignInRedirected(callbackUri))) {
          window.location.replace(window.location.origin);
          return;
        }

        await this.logto.handleSignInCallback(callbackUri);
      })().catch(() => {
        // O SDK expõe erros de callback através de logto.error() para o template.
      });
    });
  }
}

isSignInRedirected() verifica se a URL corresponde a uma sessão de login ativa. Se alguém acessar a rota de callback sem uma sessão, este exemplo o retorna para a página inicial do aplicativo em vez de tentar completar o login.

Registre a rota de callback em app.routes.ts. Ela deve corresponder ao caminho do seu URI de redirecionamento e não deve exigir autenticação. Por exemplo, use callback para um URI de redirecionamento terminando em /callback:

app/app.routes.ts

// Exemplo de rota de callback para autenticação Logto
import { type Routes } from '@angular/router';

import { CallbackComponent } from './callback.component';

export const routes: Routes = [
  { path: 'callback', component: CallbackComponent },
  // ...outras rotas
];

O componente raiz precisa de um <router-outlet /> para renderizar essa rota, como mostrado no próximo passo.

Implementar login e logout

Injete o LogtoService para iniciar o login e o logout. Passe os URIs de redirecionamento registrados para esses métodos. O postRedirectUri informa ao SDK para onde navegar após o processamento bem-sucedido do callback de login:

nota:

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

app/app.component.ts

// Exemplo de uso do LogtoService para login e logout
import { Component, inject } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { LogtoService } from '@logto/angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RouterOutlet],
  templateUrl: './app.component.html',
})
export class AppComponent {
  readonly logto = inject(LogtoService);

  async signIn() {
    await this.logto.signIn({
      redirectUri: 'http://localhost:3000/callback',
      postRedirectUri: window.location.origin,
    });
  }

  async signOut() {
    await this.logto.signOut('http://localhost:3000/');
  }
}

Leia os sinais isLoading(), isAuthenticated() e error() diretamente no template:

app/app.component.html

@if (logto.error(); as error) {
<p role="alert">{{ error.message }}</p>
} @if (logto.isLoading()) {
<p>Carregando...</p>
} @else if (logto.isAuthenticated()) {
<button type="button" (click)="signOut()">Sair</button>
} @else {
<button type="button" (click)="signIn()">Entrar</button>
}

<router-outlet />

Mantenha o <router-outlet /> fora das condições de autenticação para que o callback possa ser renderizado antes do usuário estar autenticado.

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 seu aplicativo e verá o botão de logout.
4. Clique no botão de logout para limpar o armazenamento de tokens e sair.

Obter informações do usuário

Exibir informações do usuário

Para exibir as informações do usuário, use getIdTokenClaims() para ler as reivindicações (Claims) do token de ID sem uma solicitação de rede adicional. Adicione um effect ao seu AppComponent para carregar as reivindicações quando isAuthenticated() se tornar verdadeiro, inclusive quando uma sessão existente for restaurada. Importe JsonPipe para exibir o resultado:

app/app.component.ts

import { JsonPipe } from '@angular/common';
import { Component, effect, inject, signal } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { LogtoService, type IdTokenClaims } from '@logto/angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [JsonPipe, RouterOutlet],
  templateUrl: './app.component.html',
})
export class AppComponent {
  readonly logto = inject(LogtoService);
  readonly user = signal<IdTokenClaims | undefined>(undefined);

  constructor() {
    effect(() => {
      if (!this.logto.isAuthenticated()) {
        this.user.set(undefined);
        return;
      }

      void this.logto
        .getIdTokenClaims()
        .then((claims) => {
          this.user.set(claims);
        })
        .catch(() => {
          // O SDK expõe o erro através de logto.error() para o template.
        });
    });
  }

  // ...mantenha os métodos signIn() e signOut() do passo anterior
}

Adicione o seguinte dentro do ramo logto.isAuthenticated() do seu template:

app/app.component.html

@if (user(); as claims) {
<pre>{{ claims | json }}</pre>
}

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.

Adicione os escopos (scopes) à sua configuração provideLogto:

app/app.config.ts

import { type ApplicationConfig } from '@angular/core';
import { provideLogto, UserScope } from '@logto/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideLogto({
      endpoint: '<your-logto-endpoint>',
      appId: '<your-app-id>',
      scopes: [
        UserScope.Email,
        UserScope.Phone,
        UserScope.CustomData,
        UserScope.Identities,
        UserScope.Organizations,
      ],
    }),
    // ...outros providers
  ],
};

Faça login novamente após alterar os escopos. As reivindicações adicionais do token de ID, como email e phone_number, estarão disponíveis a partir de getIdTokenClaims() e serão exibidas pelo exemplo acima.

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():

app/app.component.ts

// Adicione este método ao AppComponent e chame-o após o login.
async loadUserInfo() {
const userInfo = await this.logto.fetchUserInfo();
// Agora você pode acessar userInfo.custom_data, userInfo.identities, etc.
return userInfo;
}

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.

fetchUserInfo() pode ser usado juntamente com tokens de acesso de recursos de API. Configurar resources não impede que o SDK solicite informações do usuário.

Escopos e reivindicações

Logto utiliza as convenções de escopos e reivindicações (scopes and claims) do OIDC para definir os escopos e reivindicações para obtenção de informações do usuário a partir do token de ID (ID token) e do endpoint userinfo do OIDC. Tanto "escopo (Scope)" quanto "reivindicação (Claim)" são termos das especificações do OAuth 2.0 e OpenID Connect (OIDC).

Para reivindicações padrão do OIDC, a inclusão no token de ID é estritamente determinada pelos escopos solicitados. Reivindicações estendidas (como custom_data e organizations) podem ser configuradas adicionalmente para aparecer no token de ID através das configurações de Token de ID personalizado.

Aqui está a lista de escopos suportados e as reivindicações correspondentes:

Escopos OIDC padrão

openid (padrão)

Nome da reivindicação	Tipo	Descrição
sub	string	O identificador único do usuário

profile (padrão)

Nome da reivindicação	Tipo	Descrição
name	string	O nome completo do usuário
username	string	O nome de usuário do usuário
picture	string	URL da foto de perfil do usuário final. Esta URL DEVE se referir 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. Observe que esta URL DEVE referenciar especificamente uma foto de perfil do usuário final adequada para exibição, em vez de uma foto arbitrária tirada pelo usuário final.
created_at	number	Momento 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).
updated_at	number	Momento 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).

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 forem vazios, enquanto as reivindicações acima retornarão null se os valores estiverem vazios.

nota:

Diferente das reivindicações padrão, as reivindicações created_at e updated_at usam milissegundos em vez de segundos.

email

Nome da reivindicação	Tipo	Descrição
email	string	O endereço de email do usuário
email_verified	boolean	Se o endereço de email foi verificado

phone

Nome da reivindicação	Tipo	Descrição
phone_number	string	O número de telefone do usuário
phone_number_verified	boolean	Se o número de telefone foi verificado

address

Consulte o OpenID Connect Core 1.0 para detalhes sobre a reivindicação de endereço.

info:

Escopos marcados como (padrão) são sempre solicitados pelo SDK do Logto. As reivindicações sob escopos OIDC padrão são sempre incluídas no token de ID quando o escopo correspondente é solicitado — elas não podem ser desativadas.

Escopos estendidos

Os seguintes escopos são estendidos pelo Logto e retornarão reivindicações através do endpoint userinfo. Essas reivindicações também podem ser configuradas para serem incluídas diretamente no token de ID através de Console > Custom JWT. Veja Token de ID personalizado para mais detalhes.

custom_data

Nome da reivindicação	Tipo	Descrição	Incluído no token de ID por padrão
custom_data	object	Os dados personalizados do usuário

identities

Nome da reivindicação	Tipo	Descrição	Incluído no token de ID por padrão
identities	object	As identidades vinculadas do usuário
sso_identities	array	As identidades SSO vinculadas do usuário

roles

Nome da reivindicação	Tipo	Descrição	Incluído no token de ID por padrão
roles	string[]	Os papéis do usuário	✅

urn:logto:scope:organizations

Nome da reivindicação	Tipo	Descrição	Incluído no token de ID por padrão
organizations	string[]	Os IDs das organizações às quais o usuário pertence	✅
organization_data	object[]	Os dados das organizações às quais o usuário pertence

nota:

Essas reivindicações de organização também podem ser recuperadas via endpoint userinfo ao usar um token opaco. No entanto, tokens opacos não podem ser usados como tokens de organização para acessar recursos específicos da organização. Veja Token opaco e organizações para mais detalhes.

urn:logto:scope:organization_roles

Nome da reivindicação	Tipo	Descrição	Incluído no token de ID por padrão
organization_roles	string[]	Os papéis da organização aos quais o usuário pertence no formato <organization_id>:<role_name>	✅

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 o cliente Logto

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

app/app.config.ts

import { type ApplicationConfig } from '@angular/core';
import { provideLogto } from '@logto/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideLogto({
      endpoint: '<your-logto-endpoint>',
      appId: '<your-app-id>',
      resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
    }),
    // ...other providers
  ],
};

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/app.config.ts

import { type ApplicationConfig } from '@angular/core';
import { provideLogto } from '@logto/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideLogto({
      endpoint: '<your-logto-endpoint>',
      appId: '<your-app-id>',
      scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
      resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
    }),
    // ...other providers
  ],
};

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/app.config.ts

import { type ApplicationConfig } from '@angular/core';
import { provideLogto } from '@logto/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideLogto({
      endpoint: '<your-logto-endpoint>',
      appId: '<your-app-id>',
      scopes: ['read', 'write'], // escopos de permissão
      resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // recursos de API
    }),
    // ...outros providers
  ],
};

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.

Faça login novamente após alterar os recursos ou escopos para que o usuário possa autorizar a configuração atualizada.

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():

app/api-resource.component.ts

import { Component, inject, signal } from '@angular/core';
import { LogtoService } from '@logto/angular';

@Component({
  selector: 'app-api-resource',
  standalone: true,
  template: `
    @if (logto.error(); as error) {
      <p role="alert">{{ error.message }}</p>
    }
    @if (logto.isAuthenticated()) {
      <button type="button" [disabled]="logto.isLoading()" (click)="loadAccessToken()">
        Obter token de acesso à API (Get API access token)
      </button>
      <pre>{{ accessToken() }}</pre>
    }
  `,
})
export class ApiResourceComponent {
  readonly logto = inject(LogtoService);
  readonly accessToken = signal('');

  async loadAccessToken() {
    this.accessToken.set(await this.logto.getAccessToken('https://shopping.your-app.com/api'));
  }
}

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.

Use o identificador exato do recurso da sua configuração. Chame getAccessToken(resource) sempre que fizer uma requisição à API para que o SDK possa retornar um token válido, em vez de manter um token indefinidamente em seu componente.

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/app.config.ts

import { type ApplicationConfig } from '@angular/core';
import { provideLogto, UserScope } from '@logto/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideLogto({
      endpoint: '<your-logto-endpoint>',
      appId: '<your-app-id>',
      // destaque-início
      scopes: [UserScope.Organizations],
      // destaque-fim
    }),
    // ...outros providers
  ],
};

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

app/organizations.component.ts

import { Component, effect, inject, signal } from '@angular/core';
import { LogtoService } from '@logto/angular';

@Component({
  selector: 'app-organizations',
  standalone: true,
  template: `
    @if (logto.error(); as error) {
      <p role="alert">{{ error.message }}</p>
    }
    @if (logto.isAuthenticated()) {
      <ul>
        @for (organizationId of organizationIds(); track organizationId) {
          <li>
            <span>{{ organizationId }}</span>
            <button
              type="button"
              [disabled]="logto.isLoading()"
              (click)="loadOrganizationToken(organizationId)"
            >
              Obter token de organização
            </button>
          </li>
        }
      </ul>
      <pre>{{ organizationToken() }}</pre>
    }
  `,
})
export class OrganizationsComponent {
  readonly logto = inject(LogtoService);
  readonly organizationIds = signal<string[]>([]);
  readonly organizationToken = signal('');

  constructor() {
    effect(() => {
      if (!this.logto.isAuthenticated()) {
        this.organizationIds.set([]);
        this.organizationToken.set('');
        return;
      }

      void this.logto
        .getIdTokenClaims()
        .then((claims) => {
          this.organizationIds.set(claims.organizations ?? []);
        })
        .catch(() => {
          // O SDK expõe o erro através de logto.error() para o template.
        });
    });
  }

  async loadOrganizationToken(organizationId: string) {
    this.organizationToken.set(await this.logto.getOrganizationToken(organizationId));
  }
}

Una UserScope.Organizations a quaisquer escopos existentes e faça login novamente após atualizar a configuração. getOrganizationToken(organizationId) retorna um token para a organização Logto selecionada; use getAccessToken(resource) para um token de recurso de API.

Anexar token de acesso aos cabeçalhos da requisição

Coloque o token no cabeçalho HTTP Authorization usando o formato Bearer (Bearer SEU_TOKEN). Por exemplo, adicione este método a um componente autenticado que injeta LogtoService:

async fetchProducts() {
  const accessToken = await this.logto.getAccessToken('https://shopping.your-app.com/api');
  const response = await fetch('https://shopping.your-app.com/api/products', {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }

  return response.json();
}

nota:

O exemplo usa fetch. Se você usar o HttpClient do Angular, defina o mesmo cabeçalho Authorization nas opções da requisição.

Leituras adicionais

Fluxos do usuário final: fluxos de autenticação, fluxos de conta e fluxos de organização Configurar conectores Autorização (Authorization)