OAuth 2 認証
Destination SDKは、宛先に対して複数の認証方式をサポートしています。 その中に、OAuth 2 認証フレームワーク を使用して宛先を認証するオプションがあります。
ここでは、Destination SDKでサポートされている様々な OAuth 2 認証フローについて説明し、宛先用の OAuth 2 認証の設定手順を示します。
サポートされる統合タイプ supported-integration-types
このページで説明される機能をサポートする統合のタイプについて詳しくは、以下の表を参照してください。
OAuth 2 認証の詳細の宛先設定への追加方法 how-to-setup
システムの前提条件 prerequisites
最初の手順として、お使いのシステムで 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/callbackhttps://platform-nld2.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform-aus5.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform-can2.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform-gbr9.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform.adobe.io/data/core/activation/oauth/api/v1/callback
この手順の終了時に、以下を持っている必要があります。
- クライアント ID
- クライアントシークレット
- アドビのコールバック URL(認証コード付与用)。
Destination SDK で行う必要があること to-do-in-destination-sdk
Experience Platformで宛先用に OAuth 2 認証を設定するには、 パラメーターの 宛先設定 customerAuthenticationConfigurations に OAuth 2 の詳細を追加する必要があります。 詳細な例については、顧客認証を参照してください。OAuth 2 認証付与タイプに応じて、設定テンプレートに追加する必要があるフィールドに関する具体的な手順については、このページで後述します。
サポートされる OAuth 2 付与タイプ oauth2-grant-types
Experience Platform は、以下の表にある 3 つの OAuth 2 付与タイプをサポートします。カスタム OAuth 2 設定がある場合、アドビは、統合のカスタムフィールドを活用して、それをサポートできます。詳しくは、付与タイプに関する各節を参照してください。
- 以下の節で指示されているように、入力パラメーターを指定します。Adobeの内部システムは、プラットフォームの認証システムに接続して、出力パラメーターを取得します。このパラメーターは、ユーザーを認証したり、宛先への認証を維持したりするために使用されます。
- 表内で太字でハイライト表示されている入力パラメーターは、OAuth 2 認証フローで必須のパラメーターです。 その他のパラメーターはオプションです。ここに示されていないその他のカスタム入力パラメーターについては、OAuth 2 設定のカスタマイズおよびアクセストークンの更新の節で詳しく説明しています。
- clientId
- clientSecret
- 対象範囲
- authorizationUrl
- accessTokenUrl
- refreshTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
- clientId
- clientSecret
- 対象範囲
- accessTokenUrl
- username
- password
- accessToken
- expiresIn
- refreshToken
- tokenType
- clientId
- clientSecret
- 対象範囲
- accessTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
上記の表には、標準的な OAuth 2 フローで使用されるフィールドが示されています。これらの標準的なフィールドに加えて、様々なパートナー統合では、追加の入力および出力が必要になる可能性があります。Adobeでは、上記の標準フィールドパターンに対するバリエーションを処理できる一方で、無効な出力(期限切れのアクセストークンなど)を自動的に再生成するメカニズムをサポートする、Destination SDK用の柔軟な OAuth 2 認証フレームワークを設計しています。
どのような場合でも、出力には、アクセストークン(Experience Platformが宛先に対する認証や認証の管理に使用)が含まれています。
OAuth 2 認証用にAdobeが設計したシステムは、次のとおりです。
- 3 つの OAuth 2 付与をすべてサポートすると同時に、それらのバリエーション(追加のデータフィールド、非標準的な API 呼び出しなど)を考慮します。
- 90 日、30 分または指定したその他のライフタイム値など、様々なライフタイム値を持つアクセストークンをサポートします。
- 更新トークンを含む/含まない OAuth 2 認証フローをサポートします。
認証コードを使用した OAuth 2 authorization-code
宛先が標準的な OAuth 2.0 認証コードフロー(RFC 標準仕様を参照)またはそのバリエーションをサポートしている場合は、以下の必須フィールドおよびオプションフィールドを参照してください。
- clientId
- clientSecret
- 対象範囲
- authorizationUrl
- accessTokenUrl
- refreshTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
宛先に対してこの認証方法を設定するには、(宛先設定を作成 する際に、設定に以下の行を追加し す。
{
//...
"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"]
}
]
//...
}
authTypegrantaccessTokenUrlauthorizationUrlrefreshTokenUrlrefreshTokenUrl は、accessTokenUrl と同じです。clientIdclientSecretscopeパスワード付与を使用した OAuth 2
OAuth 2 パスワード付与(RFC 標準仕様を参照)の場合、Experience Platform には、ユーザーのユーザー名とパスワードが必要です。認証フローでは、Experience Platformはこれらの資格情報をアクセストークンおよび(オプションで)更新トークンと交換します。
アドビでは、宛先設定をシンプル化するために、値を上書きする機能を備えた、以下の標準入力を利用します。
- clientId
- clientSecret
- 対象範囲
- accessTokenUrl
- username
- password
- accessToken
- expiresIn
- refreshToken
- tokenType
username および password に対して、任意のパラメーターを追加する必要はありません。宛先設定で "grant": "OAUTH2_PASSWORD" を追加すると、システムは、宛先を認証する際に、ユーザーに Experience Platform UI でユーザー名およびパスワードを指定することをリクエストします。宛先に対してこの認証方法を設定するには、(宛先設定を作成 する際に、設定に以下の行を追加し す。
{
//...
"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"]
}
]
authTypegrantaccessTokenUrlclientIdclientSecretscopeクライアント資格情報付与を使用した OAuth 2
以下に示す標準入力および出力をサポートする、OAuth 2 クライアント資格情報(RFC 標準仕様を参照)宛先を設定できます。値をカスタマイズできます。詳しくは、OAuth 2 設定のカスタマイズを参照してください。
- clientId
- clientSecret
- 対象範囲
- accessTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
宛先に対してこの認証方法を設定するには、(宛先設定を作成 する際に、設定に以下の行を追加し す。
{
//...
"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"]
}
]
//...
}
authTypegrantaccessTokenUrlrefreshTokenUrlrefreshTokenUrl は、accessTokenUrl と同じです。clientIdclientSecretscopeOAuth 2 設定のカスタマイズ customize-configuration
上記の節で説明されている設定は、標準的な OAuth 2 付与を記述しています。ただし、アドビが設計したシステムには、OAuth 2 付与のバリエーションにカスタムパラメーターを使用できる柔軟性があります。標準的な OAuth 2 設定をカスタマイズするには、以下の例に示すように、authenticationDataFields パラメーターを使用します。
例 1:authenticationDataFields を使用した認証応答に由来する情報のキャプチャ example-1
この例では、宛先プラットフォームには、一定期間後に期限切れになる更新トークンがあります。この場合、パートナーは、refreshTokenExpiration カスタムフィールドを設定して、API 応答の 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 を使用した特別な更新トークンの提供 example-2
この例では、パートナーは、特別な更新トークンを提供するように宛先を設定します。さらに、アクセストークンの有効期限は、API 応答では返されないので、デフォルト値をハードコーディングできます(この場合は 3600 秒)。
"authenticationDataFields": [
{
"name": "refreshToken",
"value": "special_refresh_token"
},
{
"name": "expiresIn",
"value": 3600
}
]
例 3:宛先を設定する際のクライアント ID およびクライアントシークレットのユーザー入力 example-3
この例では、システムの前提条件の節に示すようにグローバルクライアント 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 設定をカスタマイズできます。
authenticationDataFields.nameauthenticationDataFields.titleauthenticationDataFields.descriptionauthenticationDataFields.type使用できる値:
string、boolean、integerauthenticationDataFields.isRequiredauthenticationDataFields.format"format":"password" を選択すると、Adobeは、認証データフィールドの値を暗号化します。 "fieldType": "CUSTOMER" と共に使用された場合、これも、ユーザーがフィールドに入力する際に UI で入力を非表示にします。authenticationDataFields.fieldTypeauthenticationDataFields.valueauthenticationDataFields.type から選択したタイプに一致します。authenticationDataFields.authenticationResponsePathアクセストークンの更新 access-token-refresh
アドビは、ユーザーがプラットフォームにログインし直す必要なしに、期限切れのアクセストークンを更新するシステムを設計しています。このシステムは、新しいトークンを生成できるので、宛先に対するアクティベーションは、お客様にとってシームレスに継続されます。
アクセストークンの更新を設定するには、更新トークンを使用して、アドビが新しいアクセストークンを取得できる、テンプレート化された HTTP リクエストを設定する必要がある可能性があります。アクセストークンの有効期限が切れている場合、アドビは、お客様から提供されたテンプレート化されたリクエストを受け取り、指定されたパラメーターを追加します。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 で以下のパラメーターを使用して、トークン更新プロセスをカスタマイズできます。
accessTokenRequest.destinationServerTypeURL_BASED.を使用します。accessTokenRequest.urlBasedDestination.url.templatingStrategyaccessTokenRequest.urlBasedDestination.url.valueの値に対してテンプレートを使用する場合は、PEBBLE_V1を使用します。- フィールド
accessTokenRequest.urlBasedDestination.url.valueの値が定数である場合は、NONEを使用します。
accessTokenRequest.urlBasedDestination.url.valueaccessTokenRequest.httpTemplate.requestBody.templatingStrategyaccessTokenRequest.httpTemplate.requestBody.valueの値に対してテンプレートを使用する場合は、PEBBLE_V1を使用します。- フィールド
accessTokenRequest.httpTemplate.requestBody.valueの値が定数である場合は、NONEを使用します。
accessTokenRequest.httpTemplate.requestBody.valueaccessTokenRequest.httpTemplate.httpMethodPOST です。accessTokenRequest.httpTemplate.contentType例:
application/x-www-form-urlencoded または application/json。accessTokenRequest.httpTemplate.headersaccessTokenRequest.responseFields.templatingStrategyaccessTokenRequest.responseFields.valueの値に対してテンプレートを使用する場合は、PEBBLE_V1を使用します。- フィールド
accessTokenRequest.responseFields.valueの値が定数である場合は、NONEを使用します。
accessTokenRequest.responseFields.valueaccessTokenRequest.validations.nameaccessTokenRequest.validations.actualValue.templatingStrategyaccessTokenRequest.validations.actualValue.valueの値に対してテンプレートを使用する場合は、PEBBLE_V1を使用します。- フィールド
accessTokenRequest.validations.actualValue.valueの値が定数である場合は、NONEを使用します。
accessTokenRequest.validations.actualValue.valueaccessTokenRequest.validations.expectedValue.templatingStrategyaccessTokenRequest.validations.expectedValue.valueの値に対してテンプレートを使用する場合は、PEBBLE_V1を使用します。- フィールド
accessTokenRequest.validations.expectedValue.valueの値が定数である場合は、NONEを使用します。
accessTokenRequest.validations.expectedValue.valueテンプレート規則 templating-conventions
前の節で示したように、認証のカスタマイズに応じて、認証応答のデータフィールドにアクセスする必要がある可能性があります。 これを行うために、アドビが使用する Pebble テンプレート言語についてよく理解し、OAuth 2 実装をカスタマイズするための以下のテンプレート規則を参照してください。
{{ authData.accessToken }}{{ response.body.access_token }}{{ response.status }}{{ response.headers.server[0] }}{{ userContext.sandboxName }}{{ userContext.sandboxId }}{{ userContext.imsOrgId }}{{ userContext.client }} // the client executing the authorization attempt
次の手順 next-steps
この記事を読むことで、Adobe Experience Platformでサポートされている OAuth 2 認証パターンを理解し、OAuth 2 認証サポートによる宛先の設定方法を知ることができました。 次に、Destination SDK を使用して、OAuth 2 をサポートする宛先を設定できます。次の手順については、Destination SDK を使用した宛先の設定を参照してください。