OAuth 2.0トークン

Workato の API プラットフォームユーザーは、自身の認証を OAuth 2.0 (クライアント資格情報付与) 仕様に基づいて行うことができます。静的なトークンの代わりに、クライアントは OAuth 2.0フローによって取得したアクセストークンを使って API リクエストを実行します。ユーザーは、まず Workato のトークン要求エンドポイントからアクセストークンを取得します。その後は、そのアクセストークンを使用して Workato API エンドポイントに対する API 呼び出しを実行できます。

OAuth 2.0の設定方法

手順	説明
1.	アクセスプロファイルを作成します。認証方法として OAuth 2.0 を選択します。 アクセスプロファイル - OAuth 2.0による認証方法
2.	アクセスプロファイルの資格情報 ( [Client ID] と [Client secret] ) をコピーします。 アクセスプロファイル - OAuth 2.0の資格情報

アクセストークンの要求

パラメータ	説明
grant_type	必須。トークン要求の認証メカニズムです。client_credentials とする必要があります。
client_id	必須。アクセスプロファイルから取得されたクライアント ID です。
client_secret	必須。アクセスプロファイルから取得されたクライアントシークレットです。

Workato のトークン要求エンドポイントに POST リクエストを送信します。トークン要求には、クライアントの資格情報と grant_type パラメータを含める必要があります。RFC (opens new window) では、クライアントの資格情報はエンコードし、Basic Auth ヘッダーとして送信することが推奨されています。その際、ユーザー名には client_id、パスワードには client_secret を使用します。下の例を参照してください。

POST /oauth2/token HTTP/1.1
Host: apim.workato.com
Authorization: Basic ${Base64(<CLIENT_ID>:<CLIENT_SECRET>)}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

サポートされているその他の形式

これに合致する形式は、一部の HTTP クライアントではサポートされていません。そこで、Workato では代わりになる以下のような形式にも対応しています。

Content-Type の一貫性

Content-Type ヘッダーは必須であり、ペイロードの形式に一致している必要があります。そうでない場合、リクエストは拒否されます。

JSON 形式

POST /oauth2/token HTTP/1.1
Host: apim.workato.com
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "<CLIENT_ID>",
  "client_secret": "<CLIENT_SECRET>"
}

URL エンコードされた本文

POST /oauth2/token HTTP/1.1
Host: apim.workato.com
Content-Type: application/x-www-form-urlencoded

client_secret=<CLIENT_SECRET>&client_id=<CLIENT_ID>&grant_type=client_credentials

複合データ型

POST /oauth2/token HTTP/1.1
Host: apim.workato.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="grant_type"

client_credentials
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="client_id"

<CLIENT_ID>
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="client_secret"

<CLIENT_SECRET>
----WebKitFormBoundary7MA4YWxkTrZu0gW

Postman (opens new window) のようなツールを使用してアクセストークンを生成することも可能です。

Postman によるアクセストークンの生成

トークン要求エンドポイント

Workato の各データセンターに対応するトークン要求エンドポイントは以下の通りです。

米国 (US)

https://apim.workato.com/oauth2/token

欧州連合 (EU)

https://apim.eu.workato.com/oauth2/token

日本 (JP)

https://apim.jp.workato.com/oauth2/token

シンガポール (SG)

https://apim.sg.workato.com/oauth2/token

API プラットフォームの所有者がカスタムドメインを有効にしている場合、トークン要求エンドポイントはカスタムドメインの後に続けて指定します。たとえば、カスタムドメインが api.boltcompany.com なら、トークン要求エンドポイントは https://api.boltcompany.com/oauth2/token になります。

OAuth 2.0アクセストークンの取得

アクセストークン要求が正常に送信されると、Workato の認証サーバーは次のプロパティを含む JSON オブジェクトを返信します。

{
    "access_token": "eyJhbGciOiJIUzI1NiIsImtpZCI6ImFlZTM5NGExZTZiOGZmY2VhZGZhZmRhZDk4ZTJjZTdhNDE0YmU3NWU2ODcyNmNkOTQ3YjBjMmU3OTI1MTUzNGQiLCJ0eXAiOiJKV1QifQ.eyJzdWIiOiJhZWUzOTRhMWU2YjhmZmNlYWRmYWZkYWQ5OGUyY2U3YTQxNGJlNzVlNjg3MjZjZDk0N2IwYzJlNzkyNTE1MzRkIiwiZXhwIjoxNjQ5MzAzMDM4LCJuYmYiOjE2NDkyOTk0MzgsImlhdCI6MTY0OTI5OTQzOH0.TJySFOomyLkvyQHbvQBtm6qGj0bLDqSuUBqbkTSbXm4",
    "token_type": "bearer",
    "expires_in": 3600
}

有効期限

アクセストークンには3,600秒という有効期限がありますこれを超えると有効期限切れとなり、以降は使用できなくなります。クライアントが API リクエストを引き続き実行するには、新しいアクセストークンを生成する必要があります。

/oauth2/token に対してリクエストがあるごとに、独自の有効期限を持つ新しいアクセストークンが生成されます。

API リクエストで OAuth 2.0アクセストークンを使用する

OAuth 2.0アクセストークンを使用して、Workato API エンドポイントに対する API 呼び出しを実行してみましょう。

Bearer 認証スキームを使用して、認証ヘッダーから取得したアクセストークンを指定します。API リクエストの実行方法の詳細は、こちらをご覧ください。

curl -XGET 'https://apim.workato.com/prefix/collection/endpoint/call?email=john-doe%40acme.com'\
-H 'Authorization: Bearer <ACCESS_TOKEN>'

クライアントの資格情報の更新

クライアントシークレットは更新できます。これは、セキュリティ体制を強化するために、定期的に実行することが推奨されます。当然のことながら、古いクライアントシークレットは更新の後、機能しなくなります。さらに、以前に生成されたアクセストークンもクライアントシークレットとともに失効します。