Adicionar autenticação ao seu aplicativo Angular

dica

• A demonstração a seguir é construída em Angular 18.0.0 e angular-auth-oidc-client.
• O projeto de exemplo está disponível no repositório GitHub.

Pré-requisitos

• Uma conta Logto Cloud ou um Logto auto-hospedado.
• Um aplicativo de página única Logto criado.

Instalação

Instale o Logto JS core SDK e a biblioteca cliente Angular OIDC:

npm

npm i @logto/js angular-auth-oidc-client

pnpm

pnpm add @logto/js angular-auth-oidc-client

yarn

yarn add @logto/js angular-auth-oidc-client

Integração

Configurar aplicativo

No seu projeto Angular, adicione o provedor de autenticação no seu app.config.ts:

app/app.config.ts

import { buildAngularAuthConfig } from '@logto/js';
import { provideAuth } from 'angular-auth-oidc-client';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withFetch()),
    provideAuth({
      config: buildAngularAuthConfig({
        endpoint: '<your-logto-endpoint>',
        appId: '<your-app-id>',
        redirectUri: 'http://localhost:3000/callback',
        postLogoutRedirectUri: 'http://localhost:3000/',
      }),
    }),
    // ...outros provedores
  ],
};

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.

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 lidar com isso adequadamente. A biblioteca angular-auth-oidc-client fornece suporte embutido para lidar com o redirecionamento. Você pode simplesmente configurar os configs do provedor de autenticação corretamente e a biblioteca cuidará do resto.

app/app.config.ts

export const appConfig: ApplicationConfig = {
  providers: [
    provideAuth({
      config: buildAngularAuthConfig({
        // ...outras configurações
        redirectUri: 'http://localhost:3000/callback',
        postLogoutRedirectUri: 'http://localhost:3000/',
      }),
    }),
    // ...outros provedores
  ],
};

Implementar login e logout

No componente onde você deseja implementar login e logout (por exemplo, app.component.ts), injete o OidcSecurityService e use-o para fazer login e logout.

app/app.component.ts

import { OidcSecurityService } from 'angular-auth-oidc-client';

export class AppComponent implements OnInit {
  constructor(public oidcSecurityService: OidcSecurityService) {}

  signIn() {
    this.oidcSecurityService.authorize();
  }

  signOut() {
    this.oidcSecurityService.logoff().subscribe((result) => {
      console.log('app sign-out', result);
    });
  }
}

Em seguida, no template, adicione botões para login e logout:

app/app.component.html

<button (click)="signIn()">Sign in</button>
<br />
<button (click)="signOut()">Sign out</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

Uma vez que o usuário tenha feito login com sucesso, o Logto emitirá um Token de ID (ID token) que contém as reivindicações de informações do usuário. O Token de ID é um JSON Web Token (JWT).

É importante notar que as reivindicações de informações do usuário que podem ser recuperadas dependem dos escopos usados pelo usuário durante o login, e considerando o desempenho e o tamanho dos dados, o Token de ID pode não conter todas as reivindicações do usuário; algumas reivindicações do usuário estão disponíveis apenas no endpoint userinfo (veja a lista relacionada abaixo).

A utilidade buildAngularAuthConfig() habilitará autoUserInfo e renewUserInfoAfterTokenRenew se não houver resource fornecido na configuração. Isso significa que o Logto buscará automaticamente as informações do usuário após o login e renovará as informações do usuário após a renovação do token.

info

Para saber mais sobre como configurar a biblioteca angular-auth-oidc-client, veja a documentação oficial.

Exibir informações do usuário

O OidcSecurityService fornece uma maneira conveniente de se inscrever no estado de autenticação, bem como nas informações do usuário:

app/app.component.ts

import { OidcSecurityService } from 'angular-auth-oidc-client';
import { decodeIdToken, type IdTokenClaims } from '@logto/js';

export class AppComponent implements OnInit {
  isAuthenticated = false;
  idTokenClaims?: IdTokenClaims;
  accessToken?: string;

  constructor(public oidcSecurityService: OidcSecurityService) {}

  ngOnInit() {
    this.oidcSecurityService.checkAuth().subscribe(({ isAuthenticated, idToken, accessToken }) => {
      console.log('app authenticated', isAuthenticated, idToken);
      this.isAuthenticated = isAuthenticated;
      this.idTokenClaims = decodeIdToken(idToken);
      this.accessToken = accessToken;
    });
  }

  // ...outros métodos
}

E use-o no template:

app/app.component.html

<button *ngIf="!isAuthenticated" (click)="signIn()">Sign in</button>
<ng-container *ngIf="isAuthenticated">
  <pre>{{ idTokenClaims | json }}</pre>
  <p>Access token: {{ accessToken }}</p>
  <!-- ... -->
  <button (click)="signOut()">Sign out</button>
</ng-container>

Solicitar reivindicações adicionais

Você pode perceber que algumas informações do usuário estão faltando no objeto retornado de idToken. 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 de autenticação:

app/app.config.ts

import { UserScope, buildAngularAuthConfig } from '@logto/js';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withFetch()),
    provideAuth({
      config: buildAngularAuthConfig({
        // ...outras configurações
        scopes: [
          UserScope.Email,
          UserScope.Phone,
          UserScope.CustomData,
          UserScope.Identities,
          UserScope.Organizations,
        ],
      }),
    }),
    // ...outros provedores
  ],
};

Então você pode acessar as reivindicações adicionais no valor de retorno de idToken.

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 configurar a opção userData:

app/app.component.ts

import { OidcSecurityService } from 'angular-auth-oidc-client';
import { type UserInfoResponse } from '@logto/js';

export class AppComponent implements OnInit {
isAuthenticated = false;
userData?: UserInfoResponse;
accessToken?: string;

constructor(public oidcSecurityService: OidcSecurityService) {}

ngOnInit() {
  this.oidcSecurityService
    .checkAuth()
    .subscribe(({ isAuthenticated, userData, accessToken }) => {
      console.log('app authenticated', isAuthenticated, idToken);
      this.isAuthenticated = isAuthenticated;
      this.userData = userData;
      this.accessToken = accessToken;
    });
}

// ...outros métodos
}

// Agora você pode acessar a reivindicação `userData.custom_data`

Ao configurar userData, o SDK buscará as informações do usuário solicitando ao endpoint userinfo após o usuário fazer login, e userData estará disponível assim que a solicitação for concluída.

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ção	Tipo	Descrição	Precisa de userinfo?
sub	string	O identificador único do usuário	Não

profile

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
name	string	O nome completo do usuário	Não
username	string	O nome de usuário do usuário	Não
picture	string	URL 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_at	number	Hora 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_at	number	Hora 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ção	Tipo	Descrição	Precisa de userinfo?
email	string	O endereço de email do usuário	Não
email_verified	boolean	Se o endereço de email foi verificado	Não

phone

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
phone_number	string	O número de telefone do usuário	Não
phone_number_verified	boolean	Se o número de telefone foi verificado	Nã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ção	Tipo	Descrição	Precisa de userinfo?
custom_data	object	Os dados personalizados do usuário	Sim

identities

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
identities	object	As identidades vinculadas do usuário	Sim
sso_identities	array	As identidades SSO vinculadas do usuário	Sim

urn:logto:scope:organizations

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
organizations	string[]	Os IDs das organizações às quais o usuário pertence	Não
organization_data	object[]	Os dados das organizações às quais o usuário pertence	Sim

urn:logto:scope:organization_roles

Nome da Reivindicação	Tipo	Descrição	Precisa de userinfo?
organization_roles	string[]	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

Configurar angular-auth-oidc-client para recurso 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.

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

/app/app.config.ts

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withFetch()),
    provideAuth({
      config: buildAngularAuthConfig({
        // ...other config
        resource: 'https://your-api-resource.com',
      }),
    }),
    // ...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

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withFetch()),
    provideAuth({
      config: buildAngularAuthConfig({
        // ...other config
        resource: 'https://your-api-resource.com',
        scopes: ['openid', 'profile', 'offline_access', 'read', 'write'],
      }),
    }),
    // ...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.

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.

Agora, o token de acesso estará no formato JSON Web Token (JWT) em vez de uma string aleatória (token opaco).

atenção

Tanto autoUserInfo quanto renewUserInfoAfterTokenRenew serão desativados quando resource estiver configurado. Isso ocorre porque o token de acesso será solicitado para o recurso de API específico e não para o endpoint de informações do usuário.

Atualmente, apenas os SDKs oficiais do Logto suportam a capacidade de solicitar tanto informações do usuário quanto tokens de acesso a recursos de API. Se você precisar solicitar ambos, por favor, não hesite em nos contatar.

Leituras adicionais

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