HTTP 認証設定について理解する

REST API を提供しているサービスの中には、API を呼び出す際に認証が必要なものがあります。Questetra BPM Suite では、認証に必要な情報を「HTTP 認証設定」として登録しておくと、HTTP リクエストを送信する際にその情報を送付できます。

この記事では、HTTP 認証設定の追加方法（1 章）、複数のアプリで共有できる範囲（2 章）、モデリング要素からの参照方法（3 章）を説明します。

HTTP 認証設定を参照して HTTP リクエストを送信するモデリング要素は、次のとおりです。

1. HTTP 認証設定を追加する

HTTP 認証設定の画面は、ワークフローアプリ詳細画面の［▼アプリ］>［HTTP 認証設定］メニューから開きます。メッセージ送信中間イベント（HTTP）などの工程の設定画面にある［設定はこちらから］ボタンからも開けます。特定の外部サービスと連携するサービスタスクの［設定はこちらから］では、別の画面が開きます（1-5 を参照）。

画面は認証タイプごとのタブに分かれています。各タブには「アプリ固有の設定」と「全アプリで共有される設定」の 2 つの一覧があり、一覧ごとの［追加］をクリックして認証設定を追加します。この 2 つの一覧の違いは「2. HTTP 認証設定の共有範囲」で説明します。なお、全アプリで共有される設定を追加・編集できるのは、システム管理者だけです。認証設定は、アプリの複製やアーカイブのエクスポートの対象にはなりません。

認証タイプは次の 5 つです。呼び出す API の仕様に合わせて選択します。

どの認証タイプでも、任意で「メモ」を入力できます。

［OAuth2 JWT ベアラーフロー］は、Questetra が提供している一部のサービスタスクだけが使うタイプで、メッセージ送信中間イベント（HTTP）からは指定できません。入力する内容は、その設定を使うサービスタスクのマニュアルを参照してください。以下、残りの 4 タイプの設定方法を説明します。

1-1. ［OAuth２］タイプ

OAuth2 にはいくつかの種類（認可フロー）があるのですが、［OAuth2］タイプは、OAuth2 の認可フローのうち、grant-type が Authorization Code であるものに対応しています。HTTP リクエストの送信時には、Authorization ヘッダに Authorization: Bearer {管理されているアクセストークン} が追加されます。

a. 呼び出される相手サービス側での準備

Authorization Code での認可を行うには、相手サービス側で Questetra BPM Suite を OAuth クライアントとして登録しておく必要があります。対象のサービスによって異なりますが、多くの場合、サービス内に API のリクエストを受け付けるアプリケーションを作成・登録します。

アプリケーションの設定時に「コールバック URL」（「リダイレクト URI」と呼ばれることもあります）の入力を求められます。コールバック URL は次のとおりです。［OAuth2］タブの下部にも表示されています。

• https://s.questetra.net/oauth2callback
  • Trial モード（無料お試し）の場合: https://f.questetra.net/oauth2callback

アプリケーションの設定を完了すると、相手サービス側で次の値を確認できるようになります。これらの値を HTTP 認証設定に登録します。

• クライアント ID（「コンシューマ鍵」「APP ID」などと呼ばれることもあります）
• クライアントシークレット（「クライアント機密コード」「コンシューマの秘密」などと呼ばれることもあります）

b. HTTP 認証設定の追加

［OAuth2］タブで［追加］をクリックし、次の項目を入力して［保存］をクリックします。

c. トークンの取得

保存すると、一覧に認証設定が追加されます。次に、HTTP リクエストの際に使われるトークンを取得します。

一覧の「トークンの有無」列にある［トークンの取得］をクリックすると、相手サービスのログイン画面に移ります（ブラウザで既にログインしている場合は次の画面に進みます）。ログインすると、サービスへのアクセスの認可を求める画面が表示されるので、許可します。相手サービスによっては「信頼されていないクライアントからの接続です」といったメッセージが表示されますが、そのまま許可して問題ありません。

トークンを取得できると、「トークンの有無」列に取得済みであることが表示されます。

トークンを取得できない場合は、設定に不備がないかを確認してください。設定に不備が見当たらない場合は、相手サービスの認可フローに Questetra BPM Suite が対応していない可能性があります。相手サービスの OAuth に関するドキュメントを確認してください。

1-2.［OAuth2 クライアント資格情報フロー］タイプ

［OAuth2 クライアント資格情報フロー］タイプは、grant-type が Client Credentials である認可フローに対応しています。このタイプでは、ユーザの認証は行わず、クライアントアプリの認証だけを行います。トークンエンドポイントにトークンリクエストを送り、アクセストークンを受け取る方式です。この場合も、相手サービス側で Questetra BPM Suite を OAuth クライアントとして登録しておく必要があります。

［OAuth2 クライアント資格情報フロー］タブで［追加］をクリックし、次の項目を入力して［保存］をクリックします。認可エンドポイントに認可リクエストを行わないため、「認可エンドポイントURL」の項目はありません。それ以外は［OAuth2］タイプと同じです。

［OAuth2］タイプと異なり、保存後に［トークンの取得］を行う必要はありません。なお、トークンリクエストでクライアント ID とシークレットを送る方式のうち、対応しているのはパラメータで送る方式だけです。Authorization ヘッダで送る方式には対応していません。

1-3. ［トークン直接指定］タイプ

相手サービスによっては、アプリケーションの設定画面などで、OAuth2 で最終的に取得されるものと同等のトークンが直接発行されます。この場合は［トークン直接指定］タブで［追加］をクリックし、「名前」と「トークン」を入力して［保存］をクリックします。

メッセージ送信中間イベント（HTTP）やスクリプトタスクから参照すると、Authorization ヘッダに Authorization: Bearer {設定されている文字列} が追加されます。

1-4. ［Basic 認証］タイプ

アカウント ID（ユーザ名やメールアドレスなど）とパスワードを使う認証方法です。［BASIC 認証］タブで［追加］をクリックし、「名前」「ユーザ名」（いずれも必須）と「パスワード」を入力して［保存］をクリックします。

HTTP リクエストの送信時には、Authorization ヘッダに Authorization: Basic {BASE64 エンコードされたユーザ名:パスワード} が追加されます。

相手サービスの API で Basic 認証が許可されていれば利用できますが、OAuth2 に比べて安全性は劣ります。可能であれば OAuth2 を使ってください。

1-5. 外部サービス専用の画面から追加する

Questetra が提供しているサービスタスクのうち、特定の外部サービスと連携するものは、専用の画面で認証設定を追加します。これらの外部サービスには、Questetra BPM Suite があらかじめ OAuth クライアントとして登録されているため、1-1 の a（相手サービス側での準備）は不要です。

工程の設定画面で認証設定の項目にある［設定はこちらから］をクリックすると、その外部サービス専用の画面が開きます。

この画面には、共有範囲ごとに 3 つの一覧があります。

特別な理由がなければ「ユーザに紐づく設定」を使ってください（画面にも同じ案内が表示されます）。アプリ固有の設定・全アプリで共有される設定を作る場合は、［追加］をクリックし、「名前」を入力して［保存］をクリックします。認可エンドポイント URL・トークンエンドポイント URL・スコープなどは登録済みのため、入力は不要です。そのあと、1-1 の c と同じ手順で［トークンの取得］をクリックします。

この画面で作った設定は、［▼アプリ］>［HTTP 認証設定］の一覧には表示されません（「2. HTTP 認証設定の共有範囲」を参照）。

2. HTTP 認証設定の共有範囲

HTTP 認証設定を作る画面は 2 つあり、どちらの画面で作ったかによって、設定が表示される一覧が分かれます。一方の画面で作った設定は、もう一方の画面の一覧には表示されません。工程の設定画面で選択できる設定も、この区分に従います（3-1 を参照）。

共有範囲は次の 3 種類です。

2-1. アプリ固有の設定

設定したアプリの中であれば、複数の工程で同じ設定を使えます（条件は 2-4 を参照）。他のアプリでは、同じ工程を使う場合でも使えません。アプリ管理者であれば、設定の作成者でなくても編集できます。

2-2. 全アプリで共有される設定

作成者以外のシステム管理者も編集できます。

たとえば Box 用の設定を 1 つ作れば、Box と連携する工程を含むどのアプリでも使えるので、アプリごとに認証設定を作る必要はありません。Slack など別のサービスと連携する工程には、そのサービス用の設定を別に作ります（条件は 2-4 を参照）。

2-3. ユーザに紐づく設定

外部サービス専用の画面にだけある種類で、［OAuth2］の認証に使います。特別な理由がなければ、この種類を使ってください。

アプリ管理者は、自分が管理者であるアプリで作成できます。アプリの編集画面でサービスタスクの設定画面を開き、認証設定の項目の［設定はこちらから］をクリックします。「ユーザに紐づく設定」の一覧に自分の行があるので、［トークンの取得］をクリックして、連携する外部サービスからトークンを取得します。［追加］の操作は不要です。

トークンを取得するまで、この設定は本人にしか表示されず、認証としても機能しません。一覧に他のユーザが並ぶのは、その人がすでにトークンを取得している場合だけです。

トークンを取得すると、本人がアプリ管理者になっているアプリのうち、その外部サービスと連携する工程を使うすべてのアプリで、工程の設定画面からこの設定を選択できるようになります（3-1 を参照）。同じアプリの他のアプリ管理者も、この設定を使えます。たとえば、アプリ A でトークンを取得したユーザがアプリ B のアプリ管理者でもあれば、アプリ B の他のアプリ管理者も、この設定をアプリ B で使えます。このとき、アプリ B の他のアプリ管理者が、アプリ A のアプリ管理者である必要はありません。

トークンを取得したユーザがアプリ管理者から外れたアプリでは、この設定を参照している工程は使えなくなります。

なお、この設定は外部サービスごとに別々です。Gmail と Box の両方と連携するなら、それぞれの画面でトークンを取得します。

2-4. 共有できる条件

アプリ固有の設定と全アプリで共有される設定は、次の 2 つの条件を満たす工程で共有できます。

• 認証タイプが同じであること。 たとえば［OAuth2］用の共有設定は、［BASIC 認証］を必要とする工程では使えません。使える認証タイプは工程によって異なり、［OAuth2］しか使えないものも、どのタイプでも使えるものもあります。合わない設定を指定すると、アプリのリリース時にエラーになります。
• 呼び出す API が同じであること。 同じ会社のサービスでも、API が異なれば設定は共有できません。たとえば「Gmail: メール取得」と「Google BigQuery: データ追加」はどちらも Google のサービスと連携しますが、接続する API が異なるので、Google BigQuery API 用の設定を Gmail API の認証には使えません。なお、メッセージ送信中間イベント（HTTP）やスクリプトタスクでは、API が異なる設定も指定できてしまいます。

2-5. 共有するときの注意

共有された［OAuth2］タイプの認証設定で HTTP リクエストを送ると、トークンを取得したときに認可を行ったユーザとして API にアクセスします。たとえば A さんが取得したトークンを、別のアプリで B さんが使うと、そのアプリからのリクエストは A さんの権限で外部サービスにアクセスします。

複数人でワークフローアプリを設計している場合などは、セキュリティやプライバシーに注意してください。また、認証設定を取り違えないよう、設定名は識別しやすい名前にしてください。

3. HTTP 認証設定を参照する

各モデリング要素から HTTP 認証設定を参照します。参照する方法はモデリング要素によって異なります。

3-1. サービスタスク

工程の設定画面にある認証設定の項目で、設定の名前を選択します。項目の表記は工程によって異なります。

• 「HTTP認証設定を選択してください」
• 「通信許可設定（OAuth2）を選択してください」
• 「C1: OAuth2 設定」

選択肢に並ぶ設定は、工程によって次の 2 通りに分かれます。

• 特定の外部サービスと連携する工程（「Gmail: メール取得」「Box: ファイルアップロード」など）: 項目の［設定はこちらから］で開く外部サービス専用の画面で作った設定だけが、選択肢に並びます（1-5 を参照）。
• それ以外の工程: ［▼アプリ］>［HTTP 認証設定］の画面で作った設定が選択肢に並びます。

選択肢では、アプリ固有の設定は名前だけが表示されます。全アプリで共有される設定とユーザに紐づく設定は、「全アプリで共有される設定 : {名前}」「ユーザに紐づく設定 : {ユーザ名}」のように、共有範囲が先頭に付いて表示されます。

なお、選択ではなく、設定名を記入する方式の工程もあります。

関連ドキュメント

自動処理工程を追加する（アドオン）

3-2. メッセージ送信中間イベント（HTTP）

工程の設定画面の［ヘッダ］タブで［Authorization ヘッダを指定する］をオンにすると、認証設定の名前を選択できるようになります。

関連ドキュメント

メッセージ送信中間イベント (HTTP)

3-3. スクリプトタスク

HTTP リクエストを組み立てるときに、次のように認証設定の名前を指定します。

let request = httpClient.begin(); // HttpRequestWrapper
request = request.authSetting( "XXX_認証設定名_XXX" );

関連ドキュメント

• R2300: スクリプトタスクで利用できる Java クラス
• authSetting のサンプル（サービスタスク定義（Addon-XML）のスクリプト）