サービス資格情報

AEM as a AEMとの統合では、Cloud Serviceに対して安全に認証できる必要があります。 AEM Developer Consoleは、外部のアプリケーション、システムおよびサービスがHTTP経由でAEMオーサーまたはパブリッシュサービスとプログラム的にやり取りするのを容易にするために使用されるサービス資格情報へのアクセスを許可します。

サービス資格情報は、ローカル開発アクセストークンと似ている場合がありますが、いくつかの主な方法で異なります。

  • サービス資格情報は、アクセストークンではなく、__​アクセストークンの取得に使用される資格情報です。
  • サービス資格情報はより永続的で(365日ごとに期限切れになります)、ローカル開発アクセストークンは毎日期限切れになるのに対して、失効しない限り変更されません。
  • AEM as a AEMCloud Service環境のサービス資格情報は、単一のテクニカルアカウントユーザーにマッピングされます。一方、ローカル開発アクセストークンは、アクセストークンを生成したAEMユーザーとして認証されます。

3つすべてをCloud Service環境として各AEMへのアクセス権を取得するために使用できるので、サービス資格情報と、生成するアクセストークンの両方を秘密にする必要があります

サービス資格情報の生成

サービス資格情報の生成は、次の2つの手順に分かれます。

  1. Adobe IMS組織管理者による1回限りのサービス資格情報の初期化
  2. サービス資格情報JSONのダウンロードと使用

サービス資格情報の初期化

ローカル開発アクセストークンとは異なり、サービス資格情報をダウンロードするには、AdobeOrg IMS管理者が​1回限りの初期化​をおこなう必要があります。

サービス資格情報の初期化

これは、AEM as a Cloud Service環境ごとに1回のみ初期化されます。

  1. 次の方法でログインしていることを確認します。
    • Adobe IMS組織の管理者
    • Cloud Manager - Developer IMS製品プロファイルのメンバー
    • AEM User​または​AEM Administrators IMS製品プロファイル(AEM Author)のメンバー
  2. AdobeCloud Managerにログインします。
  3. AEM as a Cloud Service環境を含むプログラムを開き、のサービス資格情報を設定できるようにします。
  4. 環境」セクションで環境の横にある省略記号をタップし、「開発者コンソール」を選択します。
  5. 統合」タブをタップします。
  6. サービス資格情報を取得」ボタンをタップします。
  7. サービス資格情報が初期化され、JSONとして表示されます

AEM開発者コンソール — 統合 — サービス資格情報の取得

AEM as a AEMCloud Service環境のサービス資格情報が初期化されると、Adobe IMS組織の他の開発者がそれらをダウンロードできます。

サービス資格情報のダウンロード

サービス資格情報のダウンロード

サービス資格情報のダウンロードは、初期化と同じ手順に従います。 初期化がまだおこなわれていない場合は、「サービス資格情報を取得」ボタンをタップすると、エラーが表示されます。

  1. 次の形式でログインしていることを確認します。
    • Cloud Manager — 開発者 IMS製品プロファイルのメンバー(AEM Developer Consoleへのアクセスを許可)
      • Cloud Service環境としてのSandbox AEMには、この​Cloud Manager - Developer​メンバーシップは必要ありません
    • AEM User​または​AEM Administrators IMS製品プロファイル(AEM Author)のメンバー
  2. AdobeCloud Managerにログインします。
  3. と統合するAEM環境としてのCloud Serviceを含むプログラムを開きます。
  4. 環境」セクションで環境の横にある省略記号をタップし、「開発者コンソール」を選択します。
  5. 統合」タブをタップします。
  6. サービス資格情報を取得」ボタンをタップします。
  7. 左上隅のダウンロードボタンをタップして、サービス資格情報の値が含まれているJSONファイルをダウンロードし、安全な場所に保存します。
    • サービス資格情報に問題が発生した場合は、すぐにAdobeサポートに連絡して、失効させてもらってください

サービス資格情報のインストール

サービス資格情報は、JWTの生成に必要な詳細を提供します。JWTは、AEM as a Cloud Serviceでの認証に使用されるアクセストークンと交換されます。 サービス資格情報は、AEMにアクセスするために使用する外部アプリケーション、システム、またはサービスがアクセスできる安全な場所に保存する必要があります。 サービス資格情報の管理方法と管理場所は、お客様ごとに一意です。

簡単にするために、このチュートリアルでは、にサービス資格情報をコマンドラインで渡しますが、ITセキュリティチームと協力して、組織のセキュリティガイドラインに従ってこれらの資格情報を保存し、アクセスする方法を理解します。

  1. ダウンロードしたサービス資格情報JSONを、プロジェクトのルートにあるservice_token.jsonという名前のファイルにコピーします。
    • しかし、Gitに資格情報をコミットしないでください。

サービス資格情報を使用

完全形式のJSONオブジェクトであるサービス資格情報は、JWTやアクセストークンとは異なります。 代わりに、(秘密鍵を含む)サービス資格情報を使用してJWTを生成し、このJWTをアクセストークンのAdobe IMSAPIと交換します。

サービス資格情報 — 外部アプリケーション

  1. サービス資格情報をAEM Developer Consoleから安全な場所にダウンロードします。
  2. 外部アプリケーションは、プログラム環境としてAEMとやり取りする必要があります。Cloud Service
  3. 外部アプリケーションは、安全な場所からサービス資格情報を読み込みます
  4. 外部アプリケーションは、サービス資格情報の情報を使用してJWTトークンを構築します
  5. JWTトークンがAdobe IMSに送信され、アクセストークンと交換されます。
  6. Adobe IMSは、AEMへのアクセスに使用できるアクセストークンをCloud Serviceとして返します
    • アクセストークンには、有効期限をリクエストできます。 アクセストークンの有効期間を短くし、必要に応じて更新することをお勧めします。
  7. 外部アプリケーションは、HTTPリクエストをCloud ServiceとしてAEMに対しておこない、アクセストークンをBearerトークンとしてHTTPリクエストのAuthorizationヘッダーに追加します
  8. AEM as aCloud ServiceはHTTPリクエストを受信し、リクエストを認証し、HTTPリクエストによってリクエストされた作業を実行し、HTTPレスポンスを外部アプリケーションに返します

外部アプリケーションの更新

サービス資格情報を使用してAEM as aCloud Serviceにアクセスするには、外部アプリケーションを次の3つの方法で更新する必要があります。

  1. サービス資格情報を読み取る
    • 簡単にするために、ダウンロードしたJSONファイルからこれらを読み取りますが、実際に使用するシナリオでは、サービス資格情報は組織のセキュリティガイドラインに従って安全に保存する必要があります
  2. サービス資格情報からJWTを生成
  3. JWTをアクセストークンと交換する
    • サービス資格情報が存在する場合、外部アプリケーションは、AEMにCloud Serviceとしてアクセスする際に、ローカル開発アクセストークンの代わりにこのアクセストークンを使用します

このチュートリアルでは、Adobeの@adobe/jwt-auth npmモジュールを使用して、(1)サービス資格情報からJWTを生成し、(2)1回の関数呼び出しでアクセストークンと交換します。 アプリケーションがJavaScriptベースでない場合は、他の言語のサンプルコードで、サービス資格情報からJWTを作成し、Adobe IMSを使用してアクセストークンと交換する方法を確認してください。

サービス資格情報の読み取り

getCommandLineParams()を確認し、ローカル開発アクセストークンJSONで読み取るのと同じコードを使用して、サービス資格情報JSONファイルを読み取れることを確認します。

function getCommandLineParams() {
    ...

    // Read in the credentials from the provided JSON file
    // Since both the Local Development Access Token and Service Credentials files are JSON, this same approach can be re-used
    if (parameters.file) {
        parameters.developerConsoleCredentials = JSON.parse(fs.readFileSync(parameters.file));
    }

    ...
    return parameters;
}

JWTの作成とアクセストークンの交換

サービス資格情報が読み取られると、JWTが生成され、そのJWTがアクセストークン用のAdobe IMSAPIと交換されます。JWTはCloud ServiceとしてAEMにアクセスするために使用できます。

このサンプルのAdobe IMSはNode.jsベースなので、 @adobe/jwt-auth npmモジュールを使用して、(1)JWTの生成と(20のアプリケーションとのやり取りを容易にすることをお勧めします。 アプリケーションが別の言語を使用して開発されている場合は、他のプログラミング言語を使用してAdobe IMSにHTTPリクエストを作成する方法に関する適切なコードサンプルを確認してください。

  1. getAccessToken(..)を更新して、JSONファイルの内容を調べ、それがローカル開発のアクセストークンかサービス資格情報かを判断します。 これは、ローカル開発アクセストークンJSON用にのみ存在する.accessTokenプロパティが存在するかどうかを確認することで、簡単に実現できます。

    サービス資格情報が指定されている場合、アプリケーションはJWTを生成し、アクセストークンのAdobe IMSと交換します。 @adobe/jwt-authauth(...)関数を使用します。この関数は、両方ともJWTを生成し、1回の関数呼び出しでアクセストークンと交換します。 auth(..)のパラメーターは、コードで説明するように、サービス資格情報JSONから取得できる特定の情報で構成されるJSONオブジェクトです。

     async function getAccessToken(developerConsoleCredentials) {
    
         if (developerConsoleCredentials.accessToken) {
             // This is a Local Development access token
             return developerConsoleCredentials.accessToken;
         } else {
             // This is the Service Credentials JSON object that must be exchanged with Adobe IMS for an access token
             let serviceCredentials = developerConsoleCredentials.integration;
    
             // Use the @adobe/jwt-auth library to pass the service credentials generated a JWT and exchange that with Adobe IMS for an access token.
             // If other programming languages are used, please see these code samples: https://www.adobe.io/authentication/auth-methods.html#!AdobeDocs/adobeio-auth/master/JWT/samples/samples.md
             let { access_token } = await auth({
                 clientId: serviceCredentials.technicalAccount.clientId, // Client Id
                 technicalAccountId: serviceCredentials.id,              // Technical Account Id
                 orgId: serviceCredentials.org,                          // Adobe IMS Org Id
                 clientSecret: serviceCredentials.technicalAccount.clientSecret, // Client Secret
                 privateKey: serviceCredentials.privateKey,              // Private Key to sign the JWT
                 metaScopes: serviceCredentials.metascopes.split(','),   // Meta Scopes defining level of access the access token should provide
                 ims: `https://${serviceCredentials.imsEndpoint}`,       // IMS endpoint used to obtain the access token from
             });
    
             return access_token;
         }
     }
    

    現在は、ローカル開発のアクセストークンJSONまたはサービス資格情報JSONのいずれかのJSONファイルがfileコマンドラインパラメーターを介して渡されるかどうかに応じて、アプリケーションはアクセストークンを取得します。

    サービス資格情報は365日ごとに期限切れになりますが、JWTと対応するアクセストークンは頻繁に期限切れになり、期限が切れる前に更新する必要があります。 これは、Adobe IMS🔗が提供するrefresh_token を使用して実行できます。

  2. これらの変更を適用し、AEM Developer Consoleからダウンロードしたサービス資格情報JSONを(簡単に、service_token.jsonと同じindex.jsとして保存するために)、コマンドラインパラメーター<a2/をservice_token.jsonに置き換えてアプリケーションを実行し、propertyValueを新しい値に更新して、効果をAEMで確認します。file

    $ node index.js \
        aem=https://author-p1234-e5678.adobeaemcloud.com \
        folder=/wknd/en/adventures/napa-wine-tasting \
        propertyName=metadata/dc:rights \
        propertyValue="WKND Restricted Use" \
        file=service_token.json
    

    端末への出力は次のようになります。

    200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting.json
    403 - Forbidden @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_277654931.jpg.json
    403 - Forbidden @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_239751461.jpg.json
    403 - Forbidden @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_280313729.jpg.json
    403 - Forbidden @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_286664352.jpg.json
    

    403 - Forbidden​行は、AEMをCloud Serviceとして呼び出すHTTP API呼び出しでエラーを示します。 これらの403 Forbiddenエラーは、アセットのメタデータを更新しようとしたときに発生します。

    この理由は、サービス資格情報に基づくアクセストークンが、自動作成されたテクニカルアカウントAEMユーザーを使用してAEMに対する要求を認証するためです。デフォルトでは、読み取りアクセス権のみを持ちます。 AEMへのアプリケーション書き込みアクセス権を付与するには、アクセストークンに関連付けられたテクニカルアカウントAEMユーザーにAEMでの権限を付与する必要があります。

AEMでのアクセスの設定

サービス資格情報から派生したアクセストークンは、 Contributors AEMユーザーグループのメンバーシップを持つテクニカルアカウントAEM Userを使用します。

サービス資格情報 — テクニカルアカウントAEM

テクニカルアカウントAEMユーザーがAEMに存在したら(最初のアクセストークンによるHTTPリクエストの後)、このAEMユーザーの権限は他のAEMユーザーと同じように管理できます。

  1. まず、AEM開発者コンソールからダウンロードしたサービス資格情報JSONを開いて、テクニカルアカウントのAEMログイン名を探し、次のようなintegration.email値を探します。12345678-abcd-9000-efgh-0987654321c@techacct.adobe.com.
  2. 対応するAEM環境のオーサーサービスにAEM管理者としてログインします。
  3. ツール > セキュリティ > ユーザー​に移動します。
  4. 手順1で識別した​Login Name​を持つAEMユーザーを探し、Properties​を開きます。
  5. グループ」タブに移動し、DAMユーザー​グループ(アセットへの書き込みアクセス権)を追加します。
  6. 「保存して閉じる」​をタップします。

AEMでアセットに対する書き込み権限を持つ権限を持つテクニカルアカウントで、アプリケーションを再実行します。

$ node index.js \
    aem=https://author-p1234-e5678.adobeaemcloud.com \
    folder=/wknd/en/adventures/napa-wine-tasting \
    propertyName=metadata/dc:rights \
    propertyValue="WKND Restricted Use" \
    file=service_token.json

端末への出力は次のようになります。

200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting.json
200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_277654931.jpg.json
200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_286664352.jpg.json
200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_239751461.jpg.json
200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_280313729.jpg.json

変更の確認

  1. aemコマンドラインパラメーターで指定したのと同じホスト名を使用して)更新されたAEM as aCloud Service環境にログインします。
  2. アセット / ファイル​に移動します。
  3. folderコマンドラインパラメーターで指定されたアセットフォルダーに移動します(例:WKND > English > Adventures > Napa Wine Tasting)。
  4. フォルダー内の任意のアセットの​プロパティ​を開きます
  5. 詳細」タブに移動します。
  6. 更新されたプロパティの値を確認します。例えば、Copyright​は、更新されたmetadata/dc:rights JCRプロパティにマッピングされ、propertyValueパラメーターで指定された値を反映します(例:WKND Restricted Use)。

WKNDでのメタデータの使用の制限の更新

おめでとうございます。

これで、ローカル開発のアクセストークンと、実稼動に対応したサービス間アクセストークンを使用して、プログラムによってAEMにCloud Serviceとしてアクセスできるようになりました。

このページ