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

注記:

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

はじめに

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

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

備考:

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

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

Logto Management API へのアクセス：この場合、組み込みの Logto Management API の all 権限を含む M2M ロールを M2M アプリに割り当てる必要があります。
独自の API リソースへのアクセス：この場合、API リソースの権限を含む 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 を見つけることができます：

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

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 Management API 用
独自の API リソース用

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

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

備考:

Logto では、新しく作成されたテナント向けに事前設定済みの「Logto Management API access」M2M ロールも提供しています。このロールには Logto Management API リソースの all 権限がすでに割り当てられています。権限を手動で設定することなく、そのまま利用できます。この事前設定済みロールは必要に応じて編集・削除も可能です。

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

備考:

v1.30.1 以降、Logto 公式の @logto/api Node.js SDK が提供されており、Logto Management API とのやり取りが簡単に行えます。

Node.js with `@logto/api` SDK
Node.js
cURL

Logto Cloud

import { createManagementApi } from '@logto/api/management';

const { apiClient, clientCredentials } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const { value } = await clientCredentials.getAccessToken();
console.log('Access token:', value);

// または、アクセス トークン (Access token) の取得を省略して直接 API コールも可能です
const response = await apiClient.GET('/api/users');
console.log(response.data);

セルフホスト / OSS

OSS ユーザーはテナント ID に default を使用し、baseUrl および apiIndicator の設定も必要です。

const { apiClient, clientCredentials } = createManagementApi('default', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  baseUrl: 'https://your.logto.endpoint',
  apiIndicator: 'https://default.logto.app/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) を取得してください。

アクセストークン (Access token) レスポンス

成功したアクセスレスポンスのボディは次のようになります：

{
  "access_token": "eyJhbG...2g", // このトークンを使用して Logto Management API にアクセスします
  "expires_in": 3600, // トークンの有効期限（秒単位）
  "token_type": "Bearer", // アクセス トークン (Access token) 使用時のリクエスト認証タイプ
  "scope": "all" // Logto Management API 用のスコープ (Scope) `all`
}

注記:

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

curl --location \
  --request POST 'https://your.logto.endpoint' \
  --header 'Authorization: Basic ${your_auth_string}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=https://${tenantId}.logto.app/api' \
  --data-urlencode 'scope=all'

実際の値はご自身のものに置き換えてください。

注意:

アクセストークン (Access token) レスポンス

成功したアクセスレスポンスのボディは次のようになります：

{
  "access_token": "eyJhbG...2g", // このトークンを使用して Logto Management API にアクセスします
  "expires_in": 3600, // トークンの有効期限（秒単位）
  "token_type": "Bearer", // アクセス トークン (Access token) 使用時のリクエスト認証タイプ
  "scope": "all" // Logto Management API 用のスコープ (Scope) `all`
}

注記:

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

API リソース一覧から、アプリがアクセスする必要のある API 識別子を探します。Logto で API リソースを追加していない場合や、API リソースが何か分からない場合は認可 (Authorization) をご覧ください。

この「Online Shopping」API リソースの下に read:products と write:products の権限があると仮定します。

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

ここまでの情報をまとめてリクエストを送信します：

Node.js
cURL

const logtoEndpoint = 'https://your.logto.endpoint';
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';

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://shopping.api',
      scope: 'read:products write:products',
    }).toString(),
  });
};

curl --location \
  --request POST 'https://your.logto.endpoint/oidc/token' \
  --header 'Authorization: Basic ${your_auth_string}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=https://shopping.api' \
  --data-urlencode 'scope=read:products write:products'

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

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

{
  "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 Management API との連携
独自の API リソースとの連携

Node.js with `@logto/api` SDK
Node.js
cURL

@logto/api SDK を使用すると、以下のコードスニペットで任意の Management API と直接やり取りできます。アクセストークン (Access token) は内部でキャッシュされ、必要に応じて自動的にリフレッシュされます。

import { createManagementApi } from '@logto/api/management';

const { apiClient } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const response = await apiClient.GET('/api/applications');
console.log(response.data);

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

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

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

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

curl --location \
  --request GET 'https://your.logto.endpoint/api/applications' \
  --header 'Authorization: Bearer eyJhbG...2g'

実際の値は自身のものに置き換えてください。Bearer の後の値は、受け取ったアクセストークン (Access token)（JWT）である必要があります。

取得したアクセストークンと API リソース https://shopping.api を使って、ショッピング API の全商品を取得します：

Node.js
cURL

const apiEndpoint = 'https://your.api.endpoint';
const accessToken = 'eyJhb...2g'; // アクセストークン

const fetchProducts = async () => {
  return await fetch(`${apiEndpoint}/products`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

curl --location \
  --request GET 'https://your.api.endpoint/products' \
  --header 'Authorization: Bearer eyJhbG...2 # アクセストークン

認可 (Authorization)

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

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

はじめに​

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

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

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

Logto Cloud​

セルフホスト / OSS​

アクセス トークン (Access token) レスポンス​

アクセス トークン (Access token) レスポンス​

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

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

認可 (Authorization)​

はじめに

アクセストークンの取得

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

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

Logto Cloud

セルフホスト / OSS

アクセストークン (Access token) レスポンス

アクセストークン (Access token) レスポンス

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

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

認可 (Authorization)