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

外部APIクライアントの作成

組織管理者が鍵ペアを用意し、管理画面で外部APIクライアントの作成操作を行います。この操作を受けて、metatellの認証基盤にOAuthクライアントが作成されます。管理画面に登録するのは公開鍵だけです。秘密鍵は外部システムで安全に保管してください。

1. 鍵ペアを作成する​

外部APIクライアントの認証には、ES256用の鍵ペア（公開鍵・秘密鍵）が必要です。

以下はNode.js環境でjoseを使ってJWKを生成する例です。

mkdir metatell-external-api-client-test
cd metatell-external-api-client-test
npm init -y
npm install jose

generate-keys.mjsを作成します。

import { generateKeyPair, exportJWK } from 'jose'
import { randomUUID } from 'node:crypto'
import { writeFile } from 'node:fs/promises'

const kid = randomUUID()
const { privateKey, publicKey } = await generateKeyPair('ES256', { extractable: true })

const publicJwk = {
  ...(await exportJWK(publicKey)),
  alg: 'ES256',
  kid,
  use: 'sig'
}
const privateJwk = {
  ...(await exportJWK(privateKey)),
  alg: 'ES256',
  kid,
  use: 'sig'
}

await writeFile('public-jwk.json', `${JSON.stringify(publicJwk, null, 2)}\n`, { mode: 0o644 })
await writeFile('private-jwk.json', `${JSON.stringify(privateJwk, null, 2)}\n`, { mode: 0o600 })
console.log(`公開鍵をpublic-jwk.jsonに出力しました（kid: ${kid}）`)

以下のコマンドでスクリプトを実行します。

node generate-keys.mjs

生成されるファイルは次の2つです。

ファイル用途取り扱い
public-jwk.jsonmetatell管理画面への登録kty、crv、x、y、kid、alg、useを含む
private-jwk.jsonclient assertionの署名秘密鍵パラメータdを含むため、外部システムだけで保管する

秘密鍵を間違って登録しないように注意して下さい。

2. 管理画面でクライアントを作成する​

管理画面にログインします。

ログイン後、サイドバーの開発者向け > 外部APIクライアントを開きます。

外部APIクライアントの一覧画面

  1. クライアントを作成を選択
  2. 用途が分かる表示名を入力（例: 予約システム連携）
  3. public-jwk.jsonの内容を初期公開鍵のJWK (JSON)に貼り付け
  4. 作成を選択

外部APIクライアントの作成画面

作成後、クライアント詳細画面に次の接続情報が表示されます。

外部APIクライアントの接続情報と公開鍵

項目用途
client_idAPIクライアントの識別子
issuerトークンの発行者
token endpointトークンの取得先
realm認証基盤上の識別子

作成直後に同期状態がpendingまたはfailedの場合は、詳細画面で再同期を実行し、syncedになることを確認します。

外部APIクライアントの再同期とクライアント操作

3. API権限を設定する​

クライアント詳細画面のAPI権限セクションで、外部システムに許可する操作を設定します。

権限許可する操作
readロールの取得
writeロールの変更

ルームロールでは、操作を許可する範囲として次の項目を設定します。

  • 操作を許可するルーム
  • 操作を許可するグループ（グループを対象にする場合）
  • ユーザー、グループ、ログインユーザー、未ログインユーザーごとのreadとwrite
  • writeで設定を許可するルームロール

ルームロールAPIの権限設定

組織ロールでは、ユーザーの組織ロールに対するreadとwriteを設定します。

組織ロールAPIの権限設定

4. 公開鍵をローテーションする​

クライアント詳細画面の公開鍵 > 鍵を追加から、次の公開鍵を追加できます。公開鍵はクライアントあたり最大3本です。

  1. 新しい鍵ペアを生成
  2. 新しい公開鍵を管理画面へ追加
  3. 外部システムを新しいkidと秘密鍵で署名するように切り替え
  4. 旧公開鍵を管理画面から削除

公開鍵を削除すると、その鍵で署名したclient assertionを検証できなくなります。外部システムの切り替えを確認してから削除してください。

に最終更新