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

Machine-to-machine: Logto での認証 (Auth)

注記:

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

はじめに​

Machine-to-machine (M2M) は、リソースと直接通信する必要があるアプリ（ユーザーではなく）を持っている場合に認証 (Authentication) する一般的な方法です。通常、M2M アプリはユーザーの操作を必要としないため、UI はありません。例えば、Logto でユーザーのカスタムデータを更新する API サービスや、日々の注文を取得する統計サービスなどです。

Logto は RBAC をアクセス制御ポリシーとして使用しているため、API を保護するために M2M アプリに M2M ロールを割り当てることが必要です。

備考:

現在の RBAC とユーザーロールと M2M ロールの違いについて学ぶには、ロールの設定 を参照してください。

Logto で machine-to-machine アプリを使用する一般的なユースケースは次の 2 つです：

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

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

Assign M2M roles modal

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

Assign M2M roles page

では、エンドツーエンドのプロセスを見ていきましょう。明確にするために、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}`,
    },
  });
};

認証 (Authentication)​

Logto Management API 以外の独自の API リソースを保護している場合は、リソースの認証 (Authentication) を実装することを忘れないでください。詳細については、API を保護する を参照してください。