OAuth 2 認証

概要

Destination SDKを使用し、 OAuth 2 認証フレームワーク.

このページでは、Destination SDKがサポートする様々な OAuth 2 認証フローについて説明し、宛先の OAuth 2 認証を設定する手順を説明します。

OAuth 2 認証の詳細を宛先設定に追加する方法

システムの前提条件

最初の手順として、Adobe Experience Platform用のアプリをシステム内で作成するか、システムにExperience Platformを登録する必要があります。 目的は、宛先へのExperience Platformを認証するために必要な、クライアント ID とクライアント秘密鍵を生成することです。 システムでのこの設定の一環として、Adobe Experience Platform OAuth 2 リダイレクト/コールバック URL が必要です。これは、以下のリストから取得できます。

• https://platform-va7.adobe.io/data/core/activation/oauth/api/v1/callback
• https://platform-nld2.adobe.io/data/core/activation/oauth/api/v1/callback
• https://platform-aus5.adobe.io/data/core/activation/oauth/api/v1/callback

この手順の最後には、次の内容が必要になります。

• クライアント ID。
• クライアントの秘密鍵
• Adobeのコールバック URL （認証コード付与用）。

Destination SDK

Experience Platformで宛先の OAuth 2 認証を設定するには、OAuth 2 の詳細を 宛先設定、 customerAuthenticationConfigurations パラメーターを使用する場合は、 platform.adobe.io/data/core/activation/authoring/destinations API エンドポイント. 詳しくは、 設定例. OAuth 2 認証付与タイプに応じて、設定テンプレートに追加する必要があるフィールドに関する具体的な指示については、このページで詳しく説明します。

サポートされている OAuth 2 付与タイプ

Experience Platformでは、次の表に示す 3 つの OAuth 2 付与タイプをサポートしています。 カスタム OAuth 2 設定がある場合、Adobeは、統合のカスタムフィールドを使用して、それをサポートできます。 詳細は、各付与タイプの節を参照してください。

上記の表は、標準の OAuth 2 フローで使用されるフィールドの一覧です。 これらの標準フィールドに加えて、様々なパートナー統合に対して、追加の入力および出力が必要になる場合があります。 Adobeは、上記の標準フィールドパターンのバリエーションに対応しながら、期限切れのアクセストークンなどの無効な出力を自動的に再生成するメカニズムをサポートできる、Destination SDK用の柔軟な OAuth 2 認証/承認フレームワークを設計しました。

どのような場合でも、出力にはアクセストークンが含まれます。アクセストークンは、宛先への認証と保守をExperience Platformがおこなうために使用されます。

Adobeが OAuth 2 認証用に設計したシステム：

• 追加のデータフィールド、非標準の API 呼び出しなど、3 つの OAuth 2 付与をすべてサポートし、それらのバリエーションを考慮します。
• 90 日間、30 分間など、指定したライフタイム値を持つアクセストークンをサポートします。
• 更新トークンの有無に関わらず、OAuth 2 認証フローがサポートされます。

認証コードを持つ OAuth 2

宛先が標準の OAuth 2.0 認証コードフローをサポートしている場合 ( RFC 標準仕様など ) またはそのバリエーションについては、以下の必須フィールドとオプションフィールドを参照してください。

この認証方法を宛先に設定するには、次の行を設定に追加します ( /destinations endpoint:

{
//...
  "customerAuthenticationConfigurations": [
    {
      "authType": "OAUTH2",
      "grant": "OAUTH2_AUTHORIZATION_CODE",
      "accessTokenUrl": "https://api.moviestar.com/OAuth/access_token",
      "authorizationUrl": "https://www.moviestar.com/dialog/OAuth",
      "refreshTokenUrl": "https://api.moviestar.com/OAuth/refresh_token",
      "clientId": "Experience-Platform-client-id",
      "clientSecret": "Experience-Platform-client-secret",
      "scope": ["read", "write"]
    }
  ]
//...
}

パスワード付き OAuth 2

OAuth 2 のパスワード付与については、 RFC 標準仕様)、Experience Platformには、ユーザー名とパスワードが必要です。 認証フローでは、Experience Platformはこれらの資格情報をアクセストークンと、オプションで更新トークンと交換します。
Adobeは、以下の標準入力を利用して、値を上書きできるので、宛先の設定を簡略化します。

この認証方法を宛先に設定するには、次の行を設定に追加します ( /destinations endpoint:

{
//...
  "customerAuthenticationConfigurations": [
    {
      "authType": "OAUTH2",
      "grant": "OAUTH2_PASSWORD",
      "accessTokenUrl": "https://api.moviestar.com/OAuth/access_token",
      "clientId": "Experience-Platform-client-id",
      "clientSecret": "Experience-Platform-client-secret",
      "scope": ["read", "write"]
    }
  ]

クライアント資格情報付き OAuth 2 許可

OAuth 2 クライアント資格情報を設定できます ( RFC 標準仕様) 宛先で使用できます。以下に示す標準の入力および出力をサポートします。 値をカスタマイズできます。 詳しくは、 OAuth 2 設定のカスタマイズ 」を参照してください。

この認証方法を宛先に設定するには、次の行を設定に追加します ( /destinations endpoint:

{
//...
  "customerAuthenticationConfigurations": [
    {
      "authType": "OAUTH2",
      "grant": "OAUTH2_CLIENT_CREDENTIALS",
      "accessTokenUrl": "https://api.moviestar.com/OAuth/access_token",
      "refreshTokenUrl": "https://api.moviestar.com/OAuth/refresh_token",
      "clientId": "Experience-Platform-client-id",
      "clientSecret": "Experience-Platform-client-secret",
      "scope": ["read", "write"]
    }
  ]
//...
}

OAuth 2 設定のカスタマイズ

上記の節で説明した設定は、標準の OAuth 2 付与について説明します。 ただし、Adobeが設計したシステムは柔軟性を提供し、OAuth 2 付与のバリエーションに対してカスタムパラメーターを使用できます。 標準の OAuth 2 設定をカスタマイズするには、 authenticationDataFields パラメーターを設定します。

例 1:使用 authenticationDataFields 認証応答から得られる情報を取り込む

この例では、宛先プラットフォームに、一定時間が経過すると期限切れになる更新トークンがあります。 この場合、パートナーは refreshTokenExpiration 更新トークンの有効期限を refresh_token_expires_in フィールドに値を入力します。

{
   "customerAuthenticationConfigurations":[
      {
         "authType":"OAUTH2",
         "options":{

         },
         "grant":"OAUTH2_AUTHORIZATION_CODE",
         "accessTokenUrl":"https://api.moviestar.com/OAuth/access_token",
         "authorizationUrl":"https://api.moviestar.com/OAuth/authorization",
         "scope":[
            "read",
            "write",
            "delete"
         ],
         "refreshTokenUrl":"https://api.moviestar.com/OAuth/accessToken",
         "clientSecret":"client-secret-here",
         "authenticationDataFields":[
            {
               "name":"refreshTokenExpiration",
               "title":"Refresh Token Expires In",
               "description":"Time in seconds when the refresh token will expire",
               "type":"string",
               "isRequired":false,
               "source":"CUSTOMER",
               "authenticationResponsePath":"refresh_token_expires_in"
            }
         ]
      }
   ]
}

例 2:使用 authenticationDataFields 特別な更新トークンを提供する

この例では、パートナーは、特別な更新トークンを提供するために宛先を設定します。 さらに、アクセストークンの有効期限は API 応答で返されないので、デフォルト値（この場合は 3600 秒）をハードコードできます。

      "authenticationDataFields": [
        {
            "name": "refreshToken",
            "value": "special_refresh_token"
        },
        {
            "name": "expiresIn",
            "value": 3600
        }
      ]

例 3:ユーザーは、宛先を設定する際に、クライアント ID とクライアント秘密鍵を入力します

この例では、の節で示すように、グローバルクライアント ID とクライアント秘密鍵を作成する代わりに、を使用します。 システムの前提条件の場合、顧客はクライアント ID、クライアントの秘密鍵、アカウント ID（顧客が宛先へのログインに使用する ID）を入力する必要があります

{
    //...
    "customerAuthenticationConfigurations": [
        {
            "authType": "OAUTH2",
            "grant": "OAUTH2_CLIENT_CREDENTIALS",
            "authenticationDataFields": [
                {
                    "name": "clientId",
                    "title": "Client ID",
                    "description": "Client ID",
                    "type": "string",
                    "isRequired": true,
                    "source": "CUSTOMER"
                },
                {
                    "name": "clientSecret",
                    "title": "Client Secret",
                    "description": "Client Secret",
                    "type": "string",
                    "isRequired": true,
                    "format": "password",
                    "source": "CUSTOMER"
                },
                {
                    "name": "moviestarId",
                    "title": "Moviestar ID",
                    "description": "Moviestar ID",
                    "type": "string",
                    "isRequired": true,
                    "source": "CUSTOMER"
                }
            ],
            "accessTokenRequest": {
                "destinationServerType": "URL_BASED",
                "urlBasedDestination": {
                    "url": {
                        "templatingStrategy": "PEBBLE_V1",
                        "value": "https://{{ authData.moviestarId }}.yourdestination.com/identity/oauth/token"
                    }
                },
                "httpTemplate": {
                    "requestBody": {
                        "templatingStrategy": "PEBBLE_V1",
                        "value": "{{ formUrlEncode('grant_type', 'client_credentials', 'client_id', authData.clientId, 'client_secret', authData.clientSecret) | raw }}"
                    },
                    "httpMethod": "POST",
                    "contentType": "application/x-www-form-urlencoded"
                },
                "responseFields": [
                    {
                        "templatingStrategy": "PEBBLE_V1",
                        "value": "{{ response.body.access_token }}",
                        "name": "accessToken"
                    },
                    {
                        "templatingStrategy": "PEBBLE_V1",
                        "value": "{{ response.body.scope }}",
                        "name": "scope"
                    },
                    {
                        "templatingStrategy": "PEBBLE_V1",
                        "value": "{{ response.body.token_type }}",
                        "name": "tokenType"
                    },
                    {
                        "templatingStrategy": "PEBBLE_V1",
                        "value": "{{ response.body.expires_in }}",
                        "name": "expiresIn"
                    }
                ]
            }
        }
    ]
//...
}

次のパラメーターを authenticationDataFields OAuth 2 設定をカスタマイズするには：

アクセストークンの更新

Adobeは、ユーザーがプラットフォームにログインし直す必要なく、期限切れのアクセストークンを更新するシステムを設計しました。 システムで新しいトークンを生成できるので、宛先へのアクティベーションがシームレスに顧客に対して続行されます。

アクセストークンの更新を設定するには、Adobeが更新トークンを使用して新しいアクセストークンを取得できるように、テンプレート化された HTTP リクエストを設定する必要が生じる場合があります。 アクセストークンの有効期限が切れると、Adobeは指定したパラメーターを追加し、指定されたテンプレートリクエストを受け取ります。 以下を使用： accessTokenRequest パラメーターを使用して、アクセストークンの更新メカニズムを設定します。

{
   "customerAuthenticationConfigurations":[
      {
         "authType":"OAUTH2",
         "grant":"OAUTH2_CLIENT_CREDENTIALS",
         "accessTokenRequest":{
            "destinationServerType":"URL_BASED",
            "urlBasedDestination":{
               "url":{
                  "templatingStrategy":"PEBBLE_V1",
                  "value":"https://{{authData.customerId}}.yourdestination.com/identity/oauth/token"
               }
            },
            "httpTemplate":{
               "requestBody":{
                  "templatingStrategy":"PEBBLE_V1",
                  "value":"{{ formUrlEncode('grant_type', 'client_credentials', 'client_id', authData.clientId, 'client_secret', authData.clientSecret) | raw }}"
               },
               "httpMethod":"POST",
               "contentType":"application/x-www-form-urlencoded",
               "headers":[

               ]
            },
            "responseFields":[
               {
                  "templatingStrategy":"PEBBLE_V1",
                  "value":"{{ response.body.expires_in }}",
                  "name":"expiresIn"
               },
               {
                  "templatingStrategy":"PEBBLE_V1",
                  "value":"{{ response.body.access_token }}",
                  "name":"accessToken"
               }
            ],
            "validations":[
               {
                  "name":"access_token validation",
                  "actualValue":{
                     "templatingStrategy":"PEBBLE_V1",
                     "value":"{{response.body.access_token is empty }}"
                  },
                  "expectedValue":{
                     "templatingStrategy":"PEBBLE_V1",
                     "value":"false"
                  }
               },
               {
                  "name":"response status",
                  "actualValue":{
                     "templatingStrategy":"PEBBLE_V1",
                     "value":"{{ response.status }}"
                  },
                  "expectedValue":{
                     "templatingStrategy":"PEBBLE_V1",
                     "value":"200"
                  }
               }
            ]
         }
      }
   ]
}

次のパラメーターを accessTokenRequest トークンの更新プロセスをカスタマイズするには：

テンプレート規則

認証のカスタマイズに応じて、前の節で示したように、認証応答のデータフィールドにアクセスする必要が生じる場合があります。 そのためには、 Pebble テンプレート言語 Adobeで使用され、以下のテンプレート規則を参照して OAuth 2 実装をカスタマイズします。

次の手順

この記事を読むと、Adobe Experience Platformでサポートされる OAuth 2 認証パターンと、OAuth 2 認証サポートを使用して宛先を設定する方法を理解できます。 次に、「Destination SDK」を使用して、OAuth 2 がサポートされる宛先を設定できます。 読み取り Destination SDKを使用した宛先の設定 を参照してください。

Business.Adobe.com リソース