為你的 Angular 應用程式新增驗證 (Authentication)

本指南將帶你整合 Logto Angular SDK v2 到你的應用程式中。

提示:

本指南使用第一方 @logto/angular v2 SDK，支援 Angular 20，並提供相依性注入與 Signals。
範例專案可在我們的 SDK 儲存庫找到。

先決條件

一個 Logto Cloud 帳號或自行架設 Logto。
已在 Logto Console 建立的單頁應用程式（SPA）。
一個 Angular 20 專案。

安裝

透過你喜愛的套件管理器安裝 Logto SDK：

npm
pnpm
yarn

npm i @logto/angular

pnpm add @logto/angular

yarn add @logto/angular

整合

初始化 Logto provider

在你的 Angular 專案中，於 app.config.ts 註冊 provideLogto 以及你的應用程式路由：

app/app.config.ts
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),
    // ...other providers
  ],
};

provideLogto 會在瀏覽器首次渲染後自動還原驗證 (Authentication) 狀態。你不需要在元件中呼叫初始化方法。

備註:

當使用伺服器端渲染（SSR, Server-side Rendering）時，驗證 (Authentication) 狀態與權杖僅在瀏覽器中可用。請使用 isLoading() 顯示載入狀態直到初始化完成。如果你需要在伺服器渲染期間取得已驗證資料，請使用伺服器或 BFF SDK。

設定 redirect URI

在進入細節之前，這裡先快速說明一下終端使用者的體驗。登入流程可簡化如下：

你的應用程式呼叫登入方法。
使用者被重新導向至 Logto 登入頁面。對於原生應用程式，會開啟系統瀏覽器。
使用者登入後，會被重新導向回你的應用程式（設定為 redirect URI）。

此驗證流程遵循 OpenID Connect (OIDC) 協議，Logto 強制執行嚴格的安全措施以保護使用者登入。
如果你有多個應用程式，可以使用相同的身分提供者 (IdP, Identity provider)（Logto）。一旦使用者登入其中一個應用程式，Logto 將在使用者訪問另一個應用程式時自動完成登入流程。

欲了解更多關於基於重導登入的原理和優勢，請參閱 Logto 登入體驗解析。

備註:

在以下的程式碼片段中，我們假設你的應用程式運行在 http://localhost:3000/。

配置重定向 URI

切換到 Logto Console 的應用程式詳細資訊頁面。新增一個重定向 URI http://localhost:3000/callback。

就像登入一樣，使用者應被重定向到 Logto 以登出共享會話。完成後，將使用者重定向回你的網站會很不錯。例如，將 http://localhost:3000/ 新增為登出後重定向 URI 區段。

然後點擊「儲存」以保存更改。

處理 redirect

建立 callback 元件，讓 Logto 將使用者導回你的應用程式後完成登入。使用 afterNextRender 確保 callback 處理僅在瀏覽器端執行：

app/callback.component.ts
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>正在完成登入...</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(() => {
        // SDK 會透過 logto.error() 將 callback 錯誤暴露給模板。
      });
    });
  }
}

isSignInRedirected() 用來檢查 URL 是否符合有效的登入階段。如果有人在沒有登入階段的情況下訪問 callback 路由，此範例會將他們導回應用程式首頁，而不是嘗試完成登入。

在 app.routes.ts 註冊 callback 路由。它必須與你的 redirect URI 路徑一致，且不能要求驗證。例如，若 redirect URI 以 /callback 結尾，則使用 callback：

app/app.routes.ts
import { type Routes } from '@angular/router';

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

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

根元件需要 <router-outlet /> 來渲染此路由，詳見下一步。

注入 LogtoService 以啟動登入與登出。將註冊過的 redirect URI 傳給這些方法。postRedirectUri 告訴 SDK 在成功處理登入 callback 後要導向哪裡：

備註:

在呼叫 signIn() 之前，請確保已在管理控制台中正確配置了 Redirect URI。

app/app.component.ts
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/');
  }
}

直接在模板中讀取 isLoading()、isAuthenticated() 與 error() Signals：

app/app.component.html
@if (logto.error(); as error) {
<p role="alert">{{ error.message }}</p>
} @if (logto.isLoading()) {
<p>載入中...</p>
} @else if (logto.isAuthenticated()) {
<button type="button" (click)="signOut()">登出</button>
} @else {
<button type="button" (click)="signIn()">登入</button>
}

<router-outlet />

請將 <router-outlet /> 放在驗證 (Authentication) 條件判斷之外，這樣 callback 可以在使用者登入前正確渲染。

呼叫 .signOut() 將清除記憶體和 localStorage 中所有的 Logto 資料（如果存在）。

檢查點：測試你的應用程式

現在，你可以測試你的應用程式：

執行你的應用程式，你會看到登入按鈕。
點擊登入按鈕，SDK 會初始化登入流程並將你重定向到 Logto 登入頁面。
登入後，你將被重定向回應用程式並看到登出按鈕。
點擊登出按鈕以清除權杖存儲並登出。

取得使用者資訊

顯示使用者資訊

若要顯示使用者資訊，請使用 getIdTokenClaims() 從 ID 權杖 (ID token) 讀取宣告 (claims)，無需額外網路請求。於你的 AppComponent 中新增 effect，當 isAuthenticated() 變為 true（包含恢復現有會話時）時載入宣告。匯入 JsonPipe 以顯示結果：

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(() => {
          // SDK 會透過 logto.error() 將錯誤暴露給模板。
        });
    });
  }

  // ...保留前一步驟的 signIn() 與 signOut() 方法
}

在模板的 logto.isAuthenticated() 分支內新增以下內容：

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

請求額外宣告 (claims)

你可能會發現從 getIdTokenClaims() 返回的物件中缺少一些使用者資訊。這是因為 OAuth 2.0 和 OpenID Connect (OIDC) 的設計遵循最小權限原則 (PoLP, Principle of Least Privilege)，而 Logto 是基於這些標準構建的。

預設情況下，僅返回有限的宣告 (Claims)。如果你需要更多資訊，可以請求額外的權限範圍 (Scopes) 以存取更多宣告。

資訊:

「宣告 (Claim)」是對主體所做的斷言；「權限範圍 (Scope)」是一組宣告。在目前的情況下，宣告是關於使用者的一部分資訊。

以下是權限範圍與宣告關係的非規範性範例：

提示:

「sub」宣告表示「主體 (Subject)」，即使用者的唯一識別符（例如使用者 ID）。

Logto SDK 將始終請求三個權限範圍：openid、profile 和 offline_access。

於你的 provideLogto 設定中新增權限範圍 (scopes)：

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,
      ],
    }),
    // ...其他 providers
  ],
};

變更權限範圍 (scopes) 後請重新登入。額外的 ID 權杖 (ID token) 宣告 (claims)，如 email 與 phone_number，將可透過 getIdTokenClaims() 取得，並由上述範例顯示。

需要網路請求的宣告 (Claims)

為了防止 ID 權杖 (ID token) 膨脹，某些宣告 (Claims) 需要透過網路請求來獲取。例如，即使在權限範圍 (Scopes) 中請求了 custom_data 宣告，它也不會包含在使用者物件中。要存取這些宣告，你可以使用 fetchUserInfo() 方法：

app/app.component.ts
// 將此方法加入 AppComponent，並於登入後呼叫。
async loadUserInfo() {
const userInfo = await this.logto.fetchUserInfo();
// 現在你可以存取 userInfo.custom_data、userInfo.identities 等。
return userInfo;
}

此方法將透過請求 userinfo 端點來獲取使用者資訊。要了解更多可用的權限範圍 (Scopes) 和宣告 (Claims)，請參閱權限範圍 (Scopes) 和宣告 (Claims) 部分。

fetchUserInfo() 可與 API 資源 (API resource) 存取權杖 (access token) 一同使用。設定 resources 不會阻止 SDK 請求使用者資訊。

權限範圍 (Scopes) 與宣告 (Claims)

Logto 採用 OIDC 權限範圍 (Scopes) 與宣告 (Claims) 慣例來定義從 ID 權杖 (ID token) 及 OIDC userinfo 端點取得使用者資訊時的權限範圍與宣告。無論「權限範圍 (Scope)」還是「宣告 (Claim)」，皆為 OAuth 2.0 與 OpenID Connect (OIDC) 規範中的術語。

對於標準 OIDC 宣告 (Claims)，其是否包含於 ID 權杖 (ID token) 內，完全取決於所請求的權限範圍 (Scopes)。擴充宣告（如 custom_data 與 organizations）則可透過自訂 ID 權杖 (Custom ID token) 設定，額外配置於 ID 權杖中。

以下是支援的權限範圍 (Scopes) 及對應的宣告 (Claims) 清單：

標準 OIDC 權限範圍 (Scopes)

openid（預設）

Claim name	Type	Description
sub	`string`	使用者的唯一識別符 (The unique identifier of the user)

profile（預設）

Claim name	Type	Description
name	`string`	使用者全名 (The full name of the user)
username	`string`	使用者名稱 (The username of the user)
picture	`string`	終端使用者大頭貼的 URL。此 URL 必須指向圖片檔案（如 PNG、JPEG 或 GIF），而非包含圖片的網頁。請注意，此 URL 應明確指向適合描述終端使用者的個人照片，而非任意由終端使用者拍攝的照片。(URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User.)
created_at	`number`	終端使用者建立時間。以自 Unix epoch（1970-01-01T00:00:00Z）以來的毫秒數表示。(Time the End-User was created. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).)
updated_at	`number`	終端使用者資訊最後更新時間。以自 Unix epoch（1970-01-01T00:00:00Z）以來的毫秒數表示。(Time the End-User's information was last updated. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).)

其他標準宣告 (Standard claims) 包含 family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo 及 locale 也會包含在 profile 權限範圍內，無需額外請求 userinfo endpoint。與上表宣告不同的是，這些宣告僅在其值不為空時才會回傳，而上表宣告若值為空則會回傳 null。

備註:

與標準宣告不同，created_at 與 updated_at 宣告使用毫秒而非秒為單位。

email

Claim name	Type	Description
email	`string`	使用者的電子郵件地址 (The email address of the user)
email_verified	`boolean`	電子郵件地址是否已驗證 (Whether the email address has been verified)

phone

Claim name	Type	Description
phone_number	`string`	使用者的電話號碼 (The phone number of the user)
phone_number_verified	`boolean`	電話號碼是否已驗證 (Whether the phone number has been verified)

address

請參閱 OpenID Connect Core 1.0 以瞭解 address 宣告的詳細資訊。

資訊:

標註為 （預設） 的權限範圍 (Scopes) 會由 Logto SDK 自動請求。當請求對應權限範圍時，標準 OIDC 權限範圍下的宣告 (Claims) 會始終包含於 ID 權杖 (ID token) 中，且無法關閉。

擴充權限範圍 (Extended scopes)

以下權限範圍由 Logto 擴充，會透過 userinfo endpoint 回傳宣告 (Claims)。這些宣告也可透過 Console > Custom JWT 設定直接包含於 ID 權杖 (ID token) 中。詳情請參閱自訂 ID 權杖 (Custom ID token)。

custom_data

Claim name	Type	Description	Included in ID token by default
custom_data	`object`	使用者的自訂資料 (The custom data of the user)

identities

Claim name	Type	Description	Included in ID token by default
identities	`object`	使用者的連結身分 (The linked identities of the user)
sso_identities	`array`	使用者的連結 SSO 身分 (The linked SSO identities of the user)

roles

Claim name	Type	Description	Included in ID token by default
roles	`string[]`	使用者的角色 (The roles of the user)	✅

urn:logto:scope:organizations

Claim name	Type	Description	Included in ID token by default
organizations	`string[]`	使用者所屬的組織 ID (The organization IDs the user belongs to)	✅
organization_data	`object[]`	使用者所屬的組織資料 (The organization data the user belongs to)

備註:

這些組織宣告 (Organization claims) 也可在使用不透明權杖 (Opaque token) 時，透過 userinfo endpoint 取得。然而，不透明權杖無法作為組織權杖 (Organization tokens) 來存取組織專屬資源。詳見不透明權杖與組織 (Opaque token and organizations)。

urn:logto:scope:organization_roles

Claim name	Type	Description	Included in ID token by default
organization_roles	`string[]`	使用者所屬組織角色，格式為 `<organization_id>:<role_name>` (The organization roles the user belongs to with the format of `<organization_id>:<role_name>`)	✅

API 資源 (API resources)

我們建議先閱讀 🔐 角色型存取控制 (RBAC, Role-Based Access Control)，以瞭解 Logto RBAC 的基本概念以及如何正確設定 API 資源。

設定 Logto 用戶端

一旦你設定了 API 資源，就可以在應用程式中配置 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>',
      resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
    }),
    // ...other providers
  ],
};

每個 API 資源都有其自身的權限（權限範圍）。

例如，https://shopping.your-app.com/api 資源具有 shopping:read 和 shopping:write 權限，而 https://store.your-app.com/api 資源具有 store:read 和 store:write 權限。

要請求這些權限，你可以在應用程式中配置 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: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
      resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
    }),
    // ...other providers
  ],
};

你可能會注意到權限範圍是獨立於 API 資源定義的。這是因為 OAuth 2.0 的資源標示符 (Resource Indicators) 指定請求的最終權限範圍將是所有目標服務中所有權限範圍的笛卡兒積。

因此，在上述情況中，權限範圍可以從 Logto 的定義中簡化，兩個 API 資源都可以擁有 read 和 write 權限範圍而不需要前綴。然後，在 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'], // 權限範圍 (Scopes)
      resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // API 資源 (API resources)
    }),
    // ...other providers
  ],
};

對於每個 API 資源，它將請求 read 和 write 權限範圍。

備註:

請求未在 API 資源中定義的權限範圍是可以的。例如，即使 API 資源中沒有可用的 email 權限範圍，你也可以請求 email 權限範圍。不可用的權限範圍將被安全地忽略。

成功登入後，Logto 將根據使用者的角色向 API 資源發出適當的權限範圍。

變更資源或權限範圍（Scopes）後，請重新登入，讓使用者能授權更新後的設定。

取得 API 資源的存取權杖 (Access token)

要獲取特定 API 資源的存取權杖 (Access token)，你可以使用 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()">
        取得 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'));
  }
}

此方法將返回一個 JWT 存取權杖 (Access token)，當使用者擁有相關權限時，可以用來存取 API 資源。如果當前快取的存取權杖 (Access token) 已過期，此方法將自動嘗試使用重新整理權杖 (Refresh token) 獲取新的存取權杖 (Access token)。

請使用你設定中的精確資源標示符（resource identifier）。每次發送 API 請求時呼叫 getAccessToken(resource)，讓 SDK 回傳有效的權杖，而不是在元件中無限期保存權杖。

取得組織權杖 (Organization tokens)

如果你對組織 (Organization) 不熟悉，請閱讀 🏢 組織（多租戶，Multi-tenancy）以開始了解。

在配置 Logto client 時，你需要新增 UserScope.Organizations 權限範圍 (scope)：

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.Organizations], // 權限範圍 (Scopes)：[UserScope.Organizations]
    }),
    // ...other providers
  ],
};

使用者登入後，你可以為使用者獲取組織權杖 (organization token)：

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)"
            >
              取得組織權杖 (Organization token)
            </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(() => {
          // SDK 會透過 logto.error() 將錯誤暴露給模板使用。
        });
    });
  }

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

將 UserScope.Organizations 與現有權限範圍合併，並在更新設定後重新登入。getOrganizationToken(organizationId) 會回傳指定 Logto 組織的權杖；如需 API 資源權杖，請使用 getAccessToken(resource)。

將存取權杖 (Access token) 加入請求標頭

將權杖放入 Authorization HTTP 標頭，格式為 Bearer（Bearer YOUR_TOKEN）。例如，將下列方法加入注入 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();
}

備註:

範例使用 fetch。如果你使用 Angular 的 HttpClient，請在其請求選項中設定相同的 Authorization 標頭。

延伸閱讀

終端使用者流程：驗證流程、帳號流程與組織流程 (End-user flows: authentication flows, account flows, and organization flows) 設定連接器 (Configure connectors) 授權 (Authorization)

先決條件​

安裝​

整合​

初始化 Logto provider​

設定 redirect URI​

關於基於重導的登入​

配置重定向 URI​

處理 redirect​

實作登入與登出​

檢查點：測試你的應用程式​

取得使用者資訊​

顯示使用者資訊​

請求額外宣告 (claims)​

需要網路請求的宣告 (Claims)​

權限範圍 (Scopes) 與宣告 (Claims)​

標準 OIDC 權限範圍 (Scopes)​

擴充權限範圍 (Extended scopes)​

API 資源 (API resources)​

設定 Logto 用戶端​

取得 API 資源的存取權杖 (Access token)​

取得組織權杖 (Organization tokens)​

將存取權杖 (Access token) 加入請求標頭​

延伸閱讀​