サーバーサイド API 用のアクセストークンの生成 generating-access-tokens-for-server-side-apis
一部のアーキテクチャでは、AEM インフラストラクチャ外のサーバーでホストされているアプリケーションからAdobe Experience Manager(AEM)as a Cloud Serviceを呼び出します。 たとえば、モバイルアプリケーションがサーバーを呼び出し、そのサーバーがAEM as a Cloud ServiceにAPI リクエストを行うとします。
AEM as a Cloud Service Developer Consoleを使用して、OAuth サーバー間のテクニカルアカウントを作成します。 お使いのアプリケーションは、Adobe Identity Management サービス (IMS) client_credentials付与を使用して、アクセストークンのクライアント IDとクライアント秘密鍵を交換します。 署名されたJWT、秘密鍵、または証明書は必要ありません。
developer.adobe.com/consoleのAdobe Developer Consoleとは異なります。 AEM Developer Consoleで説明されているテクニカルアカウントを作成および管理します。サーバー間フロー the-server-to-server-flow
IMS組織管理者の役割を持つユーザーで、AEM オーサーの AEM Users または AEM Administrators 製品プロファイルのメンバーでもあるユーザーは、テクニカルアカウントを作成できます。 クライアントシークレットは、作成時に作成したユーザーにのみ表示されます。 AEM as a Cloud Service Environment管理者の役割を持つユーザーは、クライアントの秘密鍵を含まないアカウントの詳細を表示できます。
サーバー間のフローには、次の手順があります。
- OAuth サーバー間のテクニカルアカウントを作成し、作成時に表示されるクライアントシークレットを含む資格情報を保存します。
- AEMにリクエストを行うサーバーに、資格情報を安全に保存します。
- クライアント ID、クライアント秘密鍵、およびスコープを使用して、IMSからアクセストークンをリクエストします。
- テクニカルアカウントの製品プロファイルとAEM権限を設定します。
- アクセストークンをベアラートークンとして使用してAEM APIを呼び出します。
テクニカルアカウントの作成と認証情報の取得 fetch-the-aem-as-a-cloud-service-credentials
-
統合を開きます。 アプリケーションがアクセスする環境のAEM Developer Consoleを開き、「統合」を選択します。 新しいテクニカルアカウントを作成を選択します。
新しいテクニカルアカウントの作成がハイライト表示された
-
テクニカルアカウントを作成します。 ダイアログで、資格情報タイプとして OAuth サーバー間(S2S) を選択し、作成を選択します。
-
クライアントの秘密鍵を保存します。 クライアントシークレットを保存 ダイアログに、
technicalAccount.clientSecretを含む資格情報が表示されます。 資格情報をダウンロードを選択してaem-s2s-credentials.jsonとして保存するか、クリップボードにコピーを選択します。 秘密鍵マネージャーまたはアプリケーションの別のアクセス制御された場所に資格情報を保存します。
「閉じる」を選択します。 秘密鍵 の確認ダイアログにアクセスせずに 閉じる場合は、秘密鍵を安全に保存した後にのみ 閉じる を選択します。 ダイアログを閉じた後、秘密鍵を再度表示することはできません。
-
テクニカルアカウントを確認します。 新しいOAuth サーバー間アカウントが、Active クライアント秘密鍵とともに一覧表示されます。 リストに表示される秘密鍵IDは、秘密鍵を識別します。 これは秘密値ではないため、トークン要求で
client_secretとして使用することはできません。
シークレットの詳細を後で確認するには、クライアントシークレットの行メニューを開き、表示を選択します。 資格情報ダイアログには、IMS エンドポイント、スコープ、クライアント ID、テクニカルアカウント電子メール、秘密鍵ID、失効状況が表示されます。 クライアントの秘密値は表示されません。
クライアントの秘密値を含まない
AEM サーバー以外での AEM サービス資格情報のインストール install-the-aem-service-credentials-on-a-non-aem-server
AEMを呼び出すサーバーサイドアプリケーションでのみ資格情報を使用できるようにします。 シークレットマネージャーまたはその他のアクセス制御ストレージメカニズムを使用します。
ブラウザー側のコード、モバイルアプリケーション、ソースコントロール、またはログにクライアントの秘密鍵を置かないでください。 アクセストークンもシークレットとして扱います。
OAuth アクセストークンのリクエスト request-an-oauth-access-token
HTTPS POST リクエストをhttps://<imsEndpoint>/ims/token/v3に送信します。 資格情報JSONのimsEndpointはIMS ホスト名です。 例えば、ims-na1.adobelogin.comはhttps://ims-na1.adobelogin.com/ims/token/v3を使用しています。 ステージ資格情報を使用する際は、ステージのホスト名を含め、資格情報で指定されたホスト名を使用します。
Content-Type: application/x-www-form-urlencodedを使用し、次のフォームフィールドをリクエスト本文に含めます。
grant_typeclient_credentialsclient_idtechnicalAccount.clientIdです。client_secrettechnicalAccount.clientSecretです。scopescopesの値をコンマで結合しました。各フォーム値をURL エンコードします。 URLまたはクエリ文字列内ではなく、リクエスト本文にシークレットを送信します。
応答には、access_token、token_typeおよびexpires_inが含まれます。 access_tokenを使用してAEMを呼び出します。 expires_inの値は、トークンの有効期間(秒単位)です。 有効期限が固定されているのではなく、その値を使用します。
有効期限が近づくまでアクセストークンをキャッシュして再利用し、同じクライアント資格情報で新しいトークンをリクエストします。 この付与には、JWT交換や更新トークンは必要ありません。
Node.js認証例 nodejs-authentication-example
最小限のOAuth サーバー間の実装については、AEM-CS API クライアントライブラリの例を参照してください。 組み込みのNode.js APIを使用し、追加の依存関係なしでNode.js 18以降が必要です。
この例では、integration オブジェクト内の資格情報を想定しています。 AEM Developer Consoleからダウンロードされたaem-s2s-credentials.json ファイルには、このラッパーのない資格情報が含まれています。 例えばjqを使用する前に、コンテンツをラップします。
jq '{integration: .}' aem-s2s-credentials.json > downloaded_integration.json
または、完全な内容が最上位のintegration フィールドの値になるようにファイルを編集します。 サンプルリポジトリのチェックアウトから、次を実行します。
node oauth-s2s-cli.js downloaded_integration.json
プログラムで使用する場合、OAuth ヘルパーは、ラップされたオブジェクトをrequestAccessToken(credentials)として受け入れます。 integration内のIMS ホスト名、クライアント ID、クライアント秘密鍵、およびスコープを使用します。
資格情報ファイルは非公開にします。 CLIはアクセストークンを出力します。 出力を共有ログに送信したり、公開したりしないでください。 この例のREADMEでは、AEM API リクエストでトークンを使用する方法も示しています。
AEM API の呼び出し calling-the-aem-api
値Bearer <access_token>を使用して、AEM as a Cloud Service環境へのリクエストのAuthorization ヘッダーにアクセストークンを含めます。
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://author-p<program-id>-e<environment-id>.adobeaemcloud.com/content/dam.json"
アプリケーションがアクセスする環境と階層のホスト名を使用します。 テクニカルアカウントがアクセスを許可されたリソースのみを呼び出します。
AEM のテクニカルアカウントユーザーに対する適切な権限の設定 set-the-appropriate-permissions-for-the-technical-account-user-in-aem
- Adobe Admin Consoleを開きます。
- 製品とサービスの下の AEM as a Cloud Service を選択します。
- 統合用の製品プロファイルを作成するか、適切な既存のプロファイルを選択します。
- 「ユーザーを追加」を選択し、資格情報から
emailを使用してテクニカルアカウントを追加します。 - 製品プロファイルの変更を反映する時間を確保します。 テクニカルアカウント用に生成されたアクセストークンを使用して、AEMにAPI呼び出しを行います。 製品プロファイルはAEM グループとして同期され、テクニカルアカウントはメンバーとして同期されます。
- 適切なAEM オーサーインスタンスで、ツール > セキュリティ > グループを開きます。 製品プロファイルグループを見つけ、テクニカルアカウントが メンバー の下に表示されていることを確認します。 ツール/セキュリティ/ユーザーのグループ メンバーシップを確認することもできます。
- 設定 > セキュリティ > 権限を開きます。 製品プロファイルに対応するグループを選択し、API呼び出しに必要な権限を設定します。
- アプリケーションがアクセスする各層に対して、必要なAPI呼び出しを確認します。 統合に必要な権限のみを付与します。
IMSおよびAEM ユーザーとグループの詳細については、IMS サポート を参照してください。
開発者フロー developer-flow
ローカルテストの場合、開発者は、OAuth サーバー間のテクニカルアカウントを作成することなく、AEM Developer Consoleで直接開発アクセストークンを生成できます。 トークンは、開発者がアクセスできるAEM環境の呼び出しに使用できます。 無人サーバーサイドアプリケーションには、ローカル開発トークンではなく、OAuth サーバー間の資格情報を使用します。
AEM Developer Consoleの使用に必要な権限については、開発者向けガイドライン を参照してください。
アクセストークンの生成 generating-the-access-token
- AEM Developer Consoleで、統合 > ローカルトークンに移動します。
- 「ローカル開発トークンを取得」を選択します。
アクセストークンを使用した AEM アプリケーションの呼び出し call-the-aem-application-with-an-access-token
AEM APIの呼び出しで説明されているように、ローカル開発アクセストークンをAuthorization ヘッダーのベアラートークンとして使用します。
ローカルマシンで実行中のAEM プロジェクトの場合、IMS アクセストークンは必要ありません。
クライアント秘密鍵の回転 refresh-credentials
OAuth サーバー間の資格情報は、年間証明書の更新を必要としません。 シークレットが公開されるたびに、クライアント シークレットを定期的にローテーションします。 新しい秘密鍵を作成し、アプリケーションをその秘密鍵に切り替え、その後に古い秘密鍵を取り消すだけです。
シークレットを作成および取り消すには、保存したシークレット値が必要です。 AEM Developer Consoleは、入力された秘密鍵を使用して、IMSでリクエストを認証するだけであり、それを保存しません。
-
新しい秘密鍵を作成します。 統合で、OAuth サーバー間アカウントの名前の横にあるアクションメニューを開き、新しいシークレットを作成を選択します。 これは、クライアントシークレットの行メニューではなく、アカウントレベルのメニューです。
新しいシークレットの作成がハイライト表示された
-
アクティブな秘密鍵で認証します。 新しいシークレットを作成 ダイアログで、アカウントのアクティブなクライアントシークレットの値を入力し、新しいシークレットを作成を選択します。
-
新しいシークレットを保存します。 ダイアログには、新しい秘密鍵が一度だけ表示され、
clientId、secretId、clientSecret、scopesが表示されます。 ダウンロードまたはコピーして安全に保存し、ダイアログを閉じます。 シークレットを安全に保存した後にのみ閉じることを確認します。 ダイアログを閉じた後、新しい秘密鍵を再度表示することはできません。
-
アプリケーションを新しい秘密鍵に切り替えます。 すべてのアプリケーションインスタンスおよびデプロイメントが使用する資格情報の
technicalAccount.clientSecret値を、新しいclientSecretに置き換えます。 その他の資格情報の値は変更されません。新しいシークレットで新しいアクセストークンをリクエストし、続行する前に必要なAEM API呼び出しを確認します。 アプリケーションのカットオーバー中も、両方のシークレットはアクティブのままです。 以前に発行されたアクセストークンを再利用しても、新しい秘密鍵は検証されません。
-
失効用の古い秘密鍵を選択します。 すべてのアプリケーションが新しいシークレットを使用したら、古いシークレットの行メニューを開き、無効化を選択します。 秘密鍵IDを確認して、古い秘密鍵が選択されていることを確認します。
-
失効を確認します。 クライアントシークレットを取り消すダイアログで、取り消すクライアントシークレット IDを確認し、そのシークレットの値を入力して、取り消しを選択します。 秘密値がなくなった場合は、Adobe サポートにお問い合わせください。 失効がIMSを通じて伝播すると、アプリケーションはその秘密鍵を使用して新しいトークンをリクエストすることはできません。 既存のアクセストークンは引き続き有効です。
-
結果を確認します。 古い秘密鍵は 失効 と表示されますが、新しい秘密鍵は アクティブ のままです。
失効が有効になった後、古い秘密鍵が新しいアクセストークンを発行できないこと、および新しい秘密鍵が可能であることを確認します。 表示されたステータスだけを確認しても、IMSの伝播は検証されません。
-
不要になった場合は、失効した秘密鍵を削除します。 リストから失効した秘密鍵を削除するには、その行メニューを開き、削除を選択して確認します。
資格情報の失効 credentials-revocation
失効は、新しいトークン要求に対して選択した秘密鍵を無効にします。 秘密鍵の値が失効する必要があります。 失効の反映には時間がかかる場合があります。 秘密鍵を取り消すと、既に発行されたアクセストークンがすぐに無効になると仮定しないでください。
失効した秘密鍵の Delete は、秘密鍵IDや失効状況などのメタデータをAEM Developer Consoleから削除します。 別のIMS失効を実行することはなく、アクティブな秘密鍵には使用できません。
テクニカルアカウントの削除 delete-a-technical-account
テクニカルアカウントを削除すると、IMS内のアカウントとそのすべてのクライアントシークレットが直ちに取り消されます。 アカウントの資格情報に対して新しいアクセストークンは発行されず、現在のトークンの有効期限が切れると、それを使用する統合は機能しなくなります。 アクセス権を復元するには、新しいテクニカルアカウントを作成し、その資格情報でアプリケーションを更新し、AEMで必要な権限を再度割り当てる必要があります。
アカウントの削除は元に戻せません。 どのアプリケーションがアカウントに依存しているかを確認した後にのみ確認し、個人秘密のローテーションステップとして使用しないでください。
-
統合で、テクニカルアカウント名の横にあるアクションメニューを開き、削除を選択します。
削除が強調表示された
-
テクニカルアカウントの削除 ダイアログを確認し、削除を選択します。
JWT ベースの統合の移行 migrate-a-jwt-based-integration
- AEM Developer Consoleで新しいOAuth サーバー間テクニカルアカウントを作成します。
- 新しいテクニカルアカウントを必要な製品プロファイルに割り当て、AEM権限を設定します。
- JWTに署名して交換する代わりに
client_credentialsを使用してトークンをリクエストするようにサーバーサイドアプリケーションを更新します。 - 新しいアカウントを使用して、新しいトークンの生成と必要なAPI呼び出しを確認します。
- すべてのアプリケーションインスタンスでOAuth サーバー間を使用した後、古いJWT資格情報を廃止し、古いテクニカルアカウントを削除します。
古いアカウントでの証明書および秘密鍵操作については、JWT レガシーガイド を参照してください。 交換統合が検証される前に、古いアカウントを削除しないでください。