メインコンテンツまでスキップ

マシン間通信：Logto での認証 (Authentication)

注記:

このガイドは、Admin Console で「Machine-to-machine」タイプのアプリケーションを作成したことを前提としています。

はじめに​

マシン間通信 (M2M) とは、アプリ（ユーザーではなく）がリソースと直接通信する必要がある場合によく使われる認証 (Authentication) の手法です（通常、M2M アプリはユーザー操作を必要としないため、UI を持ちません）。例としては、Logto 内のユーザーのカスタムデータを更新する API サービスや、日次注文データを取得する統計サービスなどがあります。

Logto ではアクセス制御ポリシーとしてロールベースのアクセス制御 (RBAC) を採用しているため、API への直接サービス通信を保護するには、M2M アプリに M2M ロールを割り当てる必要があります。

備考:

現在の RBAC やユーザーロールと M2M ロールの違いについては、グローバルロールの設定 をご覧ください。

Logto でマシン間通信アプリを利用する主なユースケースは 2 つあります：

  1. Logto Management API へのアクセス：この場合、組み込みの Logto Management API の all 権限を含む M2M ロールを M2M アプリに割り当てる必要があります。
  2. 独自の API リソースへのアクセス：この場合、API リソースの権限を含む M2M ロールを M2M アプリに割り当てる必要があります。

M2M アプリ作成プロセス中に、アプリケーションに M2M ロール を割り当てるページに案内されます：

M2M ロール割り当てモーダル

また、すでに M2M アプリが作成されている場合は、M2M アプリの詳細ページでこれらのロールを割り当てることもできます：

M2M ロール割り当てページ

それでは、エンドツーエンドのプロセスを順に見ていきましょう。分かりやすくするために、Logto Management API へのアクセスとその他の API リソースへのアクセスの手順を分けて説明します。なお、すでに Logto で M2M アプリを作成済みであることを前提とします。

アクセストークンの取得​

アクセストークンリクエストの基本​

M2M アプリは、HTTP リクエストエンティティボディで application/x-www-form-urlencoded 形式を使用して次のパラメーターを追加し、トークンエンドポイントに POST リクエストを送信してアクセス トークンを取得します：

  • grant_type: client_credentials に設定する必要があります
  • resource: アクセスしたいリソース
  • scope: アクセスリクエストのスコープ

また、トークンエンドポイントが M2M アプリを認証 (Authentication) するために、リクエストヘッダーに M2M アプリの資格情報を含める必要があります。

これは、リクエストの Authorization ヘッダーに Basic authentication 形式でアプリの資格情報を含めることで実現されます。ここで、ユーザー名は App ID、パスワードは App Secret です。

M2M アプリの詳細ページから App ID と App Secret を見つけることができます：

App ID と App Secret

アクセストークンリクエストの例：

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&resource=https://shopping.api
&scope=read:products write:products

アクセストークンのリクエスト​

注記:

以下のデモでは、https://your.logto.endpoint を対象の Logto エンドポイントに置き換えてください。Logto Cloud の場合は https://{your-tenant-id}.logto.app となります。

Logto は組み込みの「Logto Management API」リソースを提供しています。これは Logto Management API にアクセスするための all 権限を持つ読み取り専用のリソースで、API リソースリストから確認できます。リソース API インジケーターは https://{your-tenant-id}.logto.app/api の形式であり、これはアクセス トークンリクエストボディで使用されるリソース値になります。

Logto Management API の詳細

Logto Management API にアクセスする前に、M2M アプリがこの組み込みの「Logto Management API」リソースから all 権限を含む M2M ロールを割り当てられていることを確認してください。

備考:

Logto は、新しく作成されたテナントに対して事前に設定された「Logto Management API アクセス」M2M ロールも提供しています。このロールには Logto Management API リソースのすべての権限が既に割り当てられているため、手動で権限を設定することなく直接使用できます。この事前設定されたロールは、必要に応じて編集および削除することもできます。

では、これまでの内容をまとめてリクエストを送信しましょう：

const logtoEndpoint = 'https://your.logto.endpoint'; // あなたの Logto エンドポイントに置き換えてください
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';
const tenantId = 'your-tenant-id';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: `https://${tenantId}.logto.app/api`,
      scope: 'all',
    }).toString(),
  });
};
注意:

Logto Cloud ユーザー向け：Logto Management API とやり取りする際には、カスタムドメインを使用できません。デフォルトの Logto エンドポイント https://{your_tenant_id}.logto.app/oidc/token を使用してアクセス トークンを取得してください。

アクセストークンレスポンス​

正常なアクセスレスポンスの例：

{
  "access_token": "eyJhbG...2g", // このトークンを使って Logto Management API へアクセス
  "expires_in": 3600, // トークンの有効期限（秒単位）
  "token_type": "Bearer", // アクセストークン利用時の認証タイプ
  "scope": "all" // Logto Management API 用のスコープ `all`
}
注記:

Logto は現在、M2M アプリがユーザーを表すことをサポートしていません。アクセス トークンのペイロード内の sub はアプリ ID になります。

アクセストークンを使ったリソースアクセス​

トークンレスポンスには token_type フィールドがあり、これは Bearer に固定されています。

したがって、API リソースサーバーとやり取りする際には、アクセス トークンを HTTP ヘッダーの Authorization フィールドに Bearer 形式（Bearer YOUR_TOKEN）で配置する必要があります。

要求されたアクセス トークンを使用して、Logto のすべてのアプリケーションを取得するために、組み込みの Logto Management API リソース https://[your-tenant-id].logto.app/api を使用します：

const logtoEndpoint = 'https://your.logto.endpoint'; // あなたの Logto エンドポイントに置き換えてください
const accessToken = 'eyJhb...2g'; // アクセス トークン

const fetchLogtoApplications = async () => {
  return await fetch(`${logtoEndpoint}/api/applications`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

認可 (Authorization)​

Logto Management API 以外の独自の API リソースを保護する場合は、API サービス側で認可 (Authorization) ロジックを実装し、アクセストークンを検証して M2M アプリがリソースにアクセスするための必要な権限を持っているか確認する必要があります。

詳細は 認可 (Authorization) および アクセストークンの検証 をご覧ください。