公開しているREST APIにカスタム認証を追加する
この記事は作成中です。この新しいバージョンはどの程度参考になりましたか。投票でお聞かせください。
OutSystemsでは、公開しているREST APIで使用する認証ロジックをカスタマイズできます。
これには、以下の手順を実行します。
-
［Logic］タブで、Integrationsフォルダを開きます。
-
変更する公開済みREST APIを選択し、そのAuthenticationプロパティを
Customに設定します。
その結果、OutSystemsはREST APIにOnAuthenticationコールバックアクションを作成します。このアクションは、このREST APIがリクエストを受け取るたびに、呼び出されたメソッドのアクションフローの前に実行されます。
-
OnAuthenticationコールバックアクションで、クライアントを認証するロジックを設計します。HTTPリクエストのURL、ヘッダー、または本文で受け取ったデータにアクセスする必要がある場合は、HTTPRequestHandlerエクステンションのGetFormValue、GetRequestHeader、またはGetRequestContentアクションを使用できます。
例: アプリIDとAPIキーを使用したREST API認証
この例の実装については、OutSystems Forgeで入手可能なHow to Add Custom Authentication to a REST APIモジュールをご覧ください。
以下の例では、APIキーとアプリIDの2つのセキュリティキーを使用し、公開済みREST APIのカスタム認証メソッドを定義します。
受信リクエストを認証するには、APIクライアントの各リクエストに2つの追加のHTTPヘッダーを含める必要があります。
X-Contacts-AppId: <app_id>
X-Contacts-Key: <api_key>
ここでは、以下のようになります。
<app_id>は、アプリケーション識別子です。<api_key>は、<app_id>によって識別されるアプリに関連付けられた秘密鍵です。この値は、パスワードと同様に取り扱う必要があります。
Contactsという既存のREST APIがあり、GetContactsというメソッドが含まれているとします。この例では、このAPIにカスタム認証メソッドを追加します。
以下のセクションでは、このカスタム認証メソッドの実装について説明します。
必要な依存関係を追加する
各APIリクエストのHTTPヘッダーを取得できるようにするため、HTTPRequestHandlerエクステンションのGetRequestHeaderアクションへの依存関係を追加します。
-
Service Studioで、公開済みREST APIを含むモジュールを開き、［Manage Dependencies...］を選択します。**
-
HTTPRequestHandlerエクステンションの「GetRequestHeader」サーバーアクションへの依存関係を追加します。
アプリIDとAPIキーのペアを保持するエンティティを作成してブートストラップする
アプリIDとキーの値のペアを保持するAPIKeyエンティティを作成します。正しく認証するには、APIKeyエンティティにレコードとして存在する値のペアがすべてのAPIリクエストに含まれている必要があります。
-
［Data］タブを開き、［Database］の下に、以下の2つのアトリビュートを持つ
APIKeyという名前のエンティティを作成します。- AppId（Textデータ型、長さ50）
- Key（Textデータ型、長さ100）
-
以下のようなレコードを1つ（以上）含むExcelファイルを作成し、このエンティティをブートストラップします。
AppId Key ghjfxdfAvs596vcGfsvf0ef1 6tsdgdjl9fsKDd5zsvnwmdjosDmrufbs93susadLHDvjfhbnwtTRbsnucnrb -
Service Studioの［Data］タブに戻り、APIKeyエンティティを右クリックして［Advanced > Update Action to Bootstrap Data from Excel...］を選択します。**
-
先ほど作成したExcelファイルを選択して［Open］をクリックし、ブートストラップの指示に従います。
受信した認証キーを検証するサーバーアクションを作成する
ApplicationIdとApplicationKeyの各入力パラメータが、APIKeyエンティティに含まれる有効な認証資格情報を定義しているかどうかを確認するサーバーアクションを作成します。この値のペアを含むレコードが存在する場合、認証を有効に設定します。
-
［Logic］タブで、HTTPヘッダーに含まれるキーを検証するValidateAPIKeyという名前の新しいサーバーアクションを作成します。
-
このサーバーアクションで、以下の入力パラメータと出力パラメータを定義します。
- 入力パラメータ
ApplicationId（Textデータ型、必須） - 入力パラメータ
ApplicationKey（Textデータ型、必須） - 出力パラメータ
Valid（Booleanデータ型）
- 入力パラメータ
-
サーバーアクションのフローを編集し、APIKeyエンティティをフローにドラッグし、このエンティティをソースとして使用するAggregateを作成します。
-
GetAPIKeys Aggregateをダブルクリックし、以下の2つのフィルタ条件を追加します。
APIKey.Key = ApplicationKeyAPIKey.AppId = ApplicationId
-
サーバーアクションのフローに戻り、Endの前にAssign要素を追加します。
-
Assignのプロパティで、以下の割り当てを設定します。
Variable =
Valid
Value =not GetAPIKeysByKey.List.Empty
カスタム認証ロジックを定義する
先ほど作成したValidateAPIKeyサーバーアクションを使用し、HTTPヘッダーの値を取得して有効な認証であるかどうかを確認する認証ロジックを設定します。
-
［Logic］タブの要素ツリーでContacts REST APIを選択します。
-
Authenticationプロパティを［
Custom］に設定します。Service Studioによって、REST API要素の下にOnAuthenticationコールバックアクションが新しく作成されます。
-
ツリーでOnAuthentication要素をダブルクリックして、ロジックフローを編集します。
-
Run Server Action要素をフローにドラッグし、「GetRequestHeader」サーバーアクションを選択します。
-
HeaderName入力パラメータを「
"X-Contacts-AppId"」（引用符を含む）に設定します。 -
要素名を「
GetRequestHeaderAppId」に変更します。
-
Run Server Action要素をもう1つフロー（End要素の前）にドラッグし、「GetRequestHeader」サーバーアクションを再び選択します。
-
HeaderName入力パラメータを「
"X-Contacts-Key"」に設定し、必要な他のHTTPヘッダー値を取得します。 -
要素名を「
GetRequestHeaderApiKey」に変更します。 -
ValidateAPIKeyサーバーアクションをフロー（Endの前）にドラッグし、入力パラメータを以下のように設定します。
- ApplicationId =
GetRequestHeaderAppId.Value - ApplicationKey =
GetRequestHeaderApiKey.Value
- ApplicationId =
-
フローのEndの前にIf要素を追加し、Conditionを「
ValidateAPIKey.Valid」にします。 -
Falseブランチに、新しいUser Exceptionを発生させるRaise Exception要素を追加します（Forgeのサンプル実装では、InvalidAPIKeyという名前のUser Exceptionを定義しています）。
-
認証が失敗した場合にREST APIクライアントに返されるエラーメッセージを入力します。
ヒント: 「OnAuthentication」コールバックアクションで例外が発生すると、クライアントに送信されるレスポンスにHTTP 500ステータスコードが設定されます。また、例外の発生前にHTTPRequestHandlerエクステンションの「SetStatusCode」サーバーアクションを呼び出して、代わりにカスタムステータスコードを使用することもできます。
完成したOnAuthenticationフローのサンプル実装を以下に示します。
認証をテストする
PostmanなどのAPIクライアントを使用して、カスタム認証メソッドのロジックをテストします。
-
公開済みREST APIのメソッド（この例では「GetContacts」メソッド）のURLを参照する新しいテストリクエストを、余分なヘッダーを含めずに作成します。
エラーが発生し、Raise Exception要素で定義したメッセージが表示されます。
-
［Headers］サブタブで認証に必要なヘッダーを追加し、想定どおりの回答が表示されるかどうかを確認します。
