認証の作成
ThingWorx Flow はあらゆる認証スキームを処理できます。OAuth のための単純な処理メカニズムが備わっており、コンフィギュレーションによって設定できます。その他の認証は接続に分類され、接続オブジェクトを介してサービスに接続する場合にコネクタ開発者がコーディングする必要があります。
ほとんどのサービスはなんらかの形式での認証を必要とします。add connection コマンドと add OAuth コマンドを使用して認証メカニズムを追加できます。ThingWorx Flow CLI と ThingWorx Flow サーバーは OAuth 2.0 および OAuth 1.0 による認証をサポートしています。
一般的に使用される認証方法について以下のリストで説明します。
• 基本認証 - HTTP プロトコルに組み込まれている単純な認証スキーム。リクエストを行う際にユーザー名とパスワードを指定する必要があります。
• API キー認証 - データにアクセスできます。たとえば、このメカニズムではキー値ペアがクエリー文字列パラメータまたはヘッダーとして送信されます。
• OAuth ベースの認証 - パスワードを公開せずにユーザーのアカウント情報を外部サービスで使用可能にする、トークンベースの認証方法。たとえば、アカウントにログインすることによって、サービスのリソースにアクセスできます。
たとえば、Windchill では基本認証と OAuth ベースの認証が使用されています。
OAuth の作成
OAuth を作成するには、次の操作を行います。
1. コマンドプロンプトから、次のコマンドを実行します。
a. cd <user project root directory>
b. flow add oauth <oauth name>
 |
OAuth 名にハイフン (-) 以外の特殊文字を含めてはなりません。たとえば、OAuth 名は <コネクタ名>-<OAuth 名> とします。
|
OAuth コマンドでは次のオプションを使用できます。
|
オプション
|
説明
|
データ型
|
|---|---|---|
|
--version
|
バージョン番号を表示します。
|
[ブール]
|
|
--help
|
ヘルプを表示します。
|
[ブール]
|
|
--parentDir, -d
|
プロジェクトの親ディレクトリ。
|
[デフォルト: "."]
|
|
--logLevel, -1
|
ログレベルを設定します。
|
[デフォルト: "info"]
|
|
--useV1
|
OAuth バージョン 1 のコンフィギュレーションが使用されていることを示します。
|
[デフォルト: false]
|
新規フォルダ <コネクタ名-OAuth 名> が <プロジェクトディレクトリ>/auth/oauth/ に作成され、config.json ファイルが格納されます。
たとえば、Gmail に関連する操作をワークフローで使用する場合、最初に Gmail アカウントにログインしてから、次の図に示すように、自分の代わりに特定のタスクを実行するよう ThingWorx Flow ワークフローを承認する必要があります。
上の図に示すアクセスパラメータを config.json ファイルで設定します。設定が完了した config.json ファイルは次のようになります。
{
"_id": "56a0df8552199d8d51e0280d",
"created_at": "2017-04-11T14:08:59.858Z",
"updated_at": "2017-04-11T14:08:59.858Z",
"uid": "oau652869757c50d1cfbd1061",
"category": "Google",
"name": "google_gmail",
"title": "Gmail",
"icon": "google-mail",
"__v": 0,
"version": "v1",
"oauth2_params_other": [
"{\"access_type\":\"offline\"}"
],
"oauth2_params_scope": [
"{\"https://www.googleapis.com/auth/gmail.labels\":\"Manage mailbox labels\"}",
"{\"https://www.googleapis.com/auth/gmail.insert\":\"Insert mail into your mailbox\"}",
"{\"https://www.googleapis.com/auth/gmail.modify\":\"All read/write operations except immediate, permanent deletion of threads and messages, bypassing Trash.\"}",
"{\"https://www.googleapis.com/auth/gmail.readonly\":\"Read all resources and their metadata—no write operations.\"}",
"{\"https://www.googleapis.com/auth/gmail.compose\":\"Create, read, update, and delete drafts. Send messages and drafts.\"}",
"{\"https://www.googleapis.com/auth/gmail.send\":\"Send email on your behalf\"}"
],
"oauth2_validate_method": "GET",
"oauth2_validate_headers": [
"{\"Authorization\":\"Bearer {access_token}\"}",
"{\"Content-Type\":\"application/json\"}"
],
"oauth2_validate_url": "https://www.googleapis.com/gmail/v1/users/me/labels",
"oauth2_refresh_data": [
"{\"grant_type\":\"refresh_token\"}",
"{\"refresh_token\":\"{refresh_token}\"}"
],
"oauth2_refresh_url": "/token",
"oauth2_token_data": [
"{\"grant_type\":\"authorization_code\"}"
],
"oauth2_token_url": "/token",
"oauth2_auth_query": [
"{\"response_type\":\"code\"}",
"{\"approval_prompt\":\"force\"}",
"{\"access_type\":\"{access_type}\"}"
],
"oauth2_auth_url": "/auth",
"oauth2_no_state": false,
"env_production_params": [
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}",
"{\"client_id\":\"{{{production.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{production.CLIENT_SECRET}}}\"}"
],
"env_pre_prod_params": [
"{\"client_id\":\"{{{pre_prod.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{pre_prod.CLIENT_SECRET}}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"env_staging_params": [
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}",
"{\"client_id\":\"{{{staging.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{staging.CLIENT_SECRET}}}\"}"
],
"env_development_params": [
"{\"client_id\":\"{{{development.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{development.CLIENT_SECRET}}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"env_local_params": [
"{\"client_id\":\"{{{local.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{local.CLIENT_SECRET}}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"base_url": "https://accounts.google.com/o/oauth2",
"oauth_type": "OAuth2",
"development_phase": "gold",
"advanced_enabled": true,
"express_enabled": true,
"deleted_at": null,
"published": true
}
"_id": "56a0df8552199d8d51e0280d",
"created_at": "2017-04-11T14:08:59.858Z",
"updated_at": "2017-04-11T14:08:59.858Z",
"uid": "oau652869757c50d1cfbd1061",
"category": "Google",
"name": "google_gmail",
"title": "Gmail",
"icon": "google-mail",
"__v": 0,
"version": "v1",
"oauth2_params_other": [
"{\"access_type\":\"offline\"}"
],
"oauth2_params_scope": [
"{\"https://www.googleapis.com/auth/gmail.labels\":\"Manage mailbox labels\"}",
"{\"https://www.googleapis.com/auth/gmail.insert\":\"Insert mail into your mailbox\"}",
"{\"https://www.googleapis.com/auth/gmail.modify\":\"All read/write operations except immediate, permanent deletion of threads and messages, bypassing Trash.\"}",
"{\"https://www.googleapis.com/auth/gmail.readonly\":\"Read all resources and their metadata—no write operations.\"}",
"{\"https://www.googleapis.com/auth/gmail.compose\":\"Create, read, update, and delete drafts. Send messages and drafts.\"}",
"{\"https://www.googleapis.com/auth/gmail.send\":\"Send email on your behalf\"}"
],
"oauth2_validate_method": "GET",
"oauth2_validate_headers": [
"{\"Authorization\":\"Bearer {access_token}\"}",
"{\"Content-Type\":\"application/json\"}"
],
"oauth2_validate_url": "https://www.googleapis.com/gmail/v1/users/me/labels",
"oauth2_refresh_data": [
"{\"grant_type\":\"refresh_token\"}",
"{\"refresh_token\":\"{refresh_token}\"}"
],
"oauth2_refresh_url": "/token",
"oauth2_token_data": [
"{\"grant_type\":\"authorization_code\"}"
],
"oauth2_token_url": "/token",
"oauth2_auth_query": [
"{\"response_type\":\"code\"}",
"{\"approval_prompt\":\"force\"}",
"{\"access_type\":\"{access_type}\"}"
],
"oauth2_auth_url": "/auth",
"oauth2_no_state": false,
"env_production_params": [
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}",
"{\"client_id\":\"{{{production.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{production.CLIENT_SECRET}}}\"}"
],
"env_pre_prod_params": [
"{\"client_id\":\"{{{pre_prod.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{pre_prod.CLIENT_SECRET}}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"env_staging_params": [
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}",
"{\"client_id\":\"{{{staging.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{staging.CLIENT_SECRET}}}\"}"
],
"env_development_params": [
"{\"client_id\":\"{{{development.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{development.CLIENT_SECRET}}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"env_local_params": [
"{\"client_id\":\"{{{local.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{local.CLIENT_SECRET}}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"base_url": "https://accounts.google.com/o/oauth2",
"oauth_type": "OAuth2",
"development_phase": "gold",
"advanced_enabled": true,
"express_enabled": true,
"deleted_at": null,
"published": true
}
| | OAUTH_ENDPOINT_OAUTH_RETURN では、deploymentConfig.json ファイルの値に基づいて、Flow サーバーによって自動的にファイルが生成されます。 |
以下の表に、config.json ファイルの各種の重要なフィールドと重要性を示します。
プロパティ | 説明 |
|---|---|
base_url | ベース URL。詳細については、ID プロバイダ (IdP) のドキュメントを参照してください。 |
oauth_type | このプロパティは編集しないでください。 デフォルトでは、CLI によって OAuth2 コンフィギュレーションが生成されます。OAuth1 コンフィギュレーションを生成するには、–useV1 オプションを使用します。 |
oauth2_params_scope | このアプリケーションによって定義されるスコープ。これによって、システムに対して実行可能な操作が決まります。トークンは、ユーザーがアプリケーションにアクセスを付与したスコープを持ちます。 |
oauth2_auth_url | アプリケーションのユーザー名とパスワードのプロンプト画面を生成します。 この値として、絶対 URL、またはベース URL に対する相対 URL を指定できます。 |
oauth2_auth_query | 認証 URL に対してリクエストを行う際に IdP が必要とするパラメータ。 |
oauth2_token_url | アクセストークンまたはリフレッシュトークンをリクエストするときに使用します。この値として、絶対 URL、またはベース URL に対する相対 URL を指定できます。 |
oauth2_token_data | oauth2_token_url に送信する必要があるデータが含まれています。 |
oauth2_refresh_url | リフレッシュトークンを生成します。一部の IdP はリフレッシュトークンをリクエストする際にトークン URL と同じ URL を使用します。 |
oauth2_refresh_data | oauth2_refresh_url に送信する必要があるデータが含まれています。 |
oauth2_validate_url | トークンを検証します |
oauth2_validate_headers | oauth2_validate_url へのリクエストで送信されるヘッダー。 |
oauth2_validate_method | HTTP メソッドを使用して検証リクエストを行います。 |
このコンフィギュレーションファイルには、ThingWorx Flow が各種 OAuth2 オペレーションを実行する際に使用する情報が含まれています。
このプロパティ値は文字列の配列なので、エスケープが必要です。値は定数値にすることも、テキスト置換を使用することもできます。env_local_params、env_staging_params、および env_production_params では、展開に基づいて各種パラメータの値を変えることができます。
config.json ファイルでは client_id と client_secret が重要な情報です。
OAuth コンフィギュレーションに機密情報やテナント固有の情報が含まれていてはなりません。これにはクライアント ID とクライアントシークレットが含まれています。この情報は以下のように指定します。
"env_pre_prod_params": [
"{\"client_id\":\"{{pre_prod.CLIENT_ID}}\"}",
"{\"client_secret\":\"{{pre_prod.CLIENT_SECRET}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"env_staging_params": [],
"env_development_params": [
"{\"client_id\":\"{{development.CLIENT_ID}}\"}",
"{\"client_secret\":\"{{development.CLIENT_SECRET}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"env_local_params": [
"{\"client_id\":\"{{local.CLIENT_ID}}\"}",
"{\"client_secret\":\"{{local.CLIENT_SECRET}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"{\"client_id\":\"{{pre_prod.CLIENT_ID}}\"}",
"{\"client_secret\":\"{{pre_prod.CLIENT_SECRET}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"env_staging_params": [],
"env_development_params": [
"{\"client_id\":\"{{development.CLIENT_ID}}\"}",
"{\"client_secret\":\"{{development.CLIENT_SECRET}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"env_local_params": [
"{\"client_id\":\"{{local.CLIENT_ID}}\"}",
"{\"client_secret\":\"{{local.CLIENT_SECRET}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
情報が展開に固有でない場合、local や development などの展開名を接頭辞として追加してはなりません。
Google API を使用するアプリケーションの作成方法については、
API コンソールのヘルプを参照してください。その他のアプリケーションについては、IdP またはシステムのドキュメントを参照してください。
既成のコネクタでの OAuth の設定
ThingWorx Flow には、承認を実行するために OAuth を必要とする多数のコネクタが付属しています。最初のステップでは、OAuth ロードファイルを作成します。すべての OAuth コンフィギュレーション、またはその一部のみを有効にできます。OAuth ロードファイルのフォーマットは次のとおりです。
{
"onedrive": {
"OneDrive": {
"CLIENT_ID": "<client-id-here>"
"CLIENT_SECRET": "<client-secret-here>"
}
}
"trello": {
"Trello": {
"CONSUMER_KEY":"<consumer-key-here>",
"CONSUMER_SECRET":"<consumer-secret-here>"
}
}
}
"onedrive": {
"OneDrive": {
"CLIENT_ID": "<client-id-here>"
"CLIENT_SECRET": "<client-secret-here>"
}
}
"trello": {
"Trello": {
"CONSUMER_KEY":"<consumer-key-here>",
"CONSUMER_SECRET":"<consumer-secret-here>"
}
}
}
上記のファイルで、トップレベルにあるキーはコネクタの名前です。OAuth2 コンフィギュレーションと OAuth1 コンフィギュレーションの例としては OneDrive が挙げられます。
各コネクタの client-id と client-secret を取得するには、
ドキュメントを参照してください。次のレベルには、OAuth コンフィギュレーションの表示名があります。このテキストが OAuth2 ドロップダウンに「Add <表示名> login」として表示されます。
OAuth をシステムにロードするには、flow-deploy ツールを使用します。コネクタと表示名に基づいた対応するコンフィギュレーションが存在する場合はそのコンフィギュレーションが更新され、存在しない場合は新しいコンフィギュレーションが作成されます。
既成のその他のコネクタ用に OAuth を設定する方法については、ThingWorx ヘルプセンターを参照してください。
展開が正常に完了すると、新規の OAuth が使用可能になります。