APIエンドポイントを使ったフローの呼び出し

APIエンドポイントは、外部ソースの変化によってトリガーされるフローのタイプです。

接続アプリケーションに関連付けられるイベントによって開始されるフローとは異なり、これらのフローはいつでもトリガーできます。外部クライアントがエンドポイントを呼び出すと、フローが実行され、クライアントはそのフロー実行からの出力を受信します。

唯一の要件は、外部のクライアントが有効なセキュリティ資格情報を使って指定のエンドポイントを呼び出すことです。Okta WorkflowsのAPIエンドポイントを保護するには、次の3つの方法があります。

OAuth 2.0で保護する

早期アクセスリリース。「セルフサービス機能を有効にする」を参照してください。

APIエンドポイントフローは、スコープ設定されたアクセストークンの承認にOAuth 2.0を使用することによって保護されます。管理者は、APIを呼び出す必要があるすべてのアプリ統合に適切なスコープを追加します。この機能では、プライベートJSONウェブトークン(JWT)を使用することによってOAuthクライアント資格情報付与タイプをサポートします。フローは、Okta認証サーバーがアクセストークンを受信して承認した後にトリガーされます。

この方式では、カスタム認証サーバーはサポートされません。

OAuth 2.0で保護する」を参照してください。

クライアントトークンで保護する

APIエンドポイントフローはWebhookとして登録され、固有のクライアントトークンによって保護されます。APIエンドポイントフローには、リクエスト元のサービスが呼び出しURLを介して適切なクライアントトークンを渡した場合にのみアクセスできます。呼び出しURLはフローエイリアスを使用して構築します。

クライアントトークンで保護する」を参照してください。

なし(パブリックサービス)

APIエンドポイントフローは、誰でも呼び出しURLを使用してパブリックに利用できます。呼び出しURLはフローエイリアスを使用して構築します。

セキュリティなし(パブリックサービス)」を参照してください。

APIエンドポイントの保護方法は、[API endpoint settings(APIエンドポイントの設定)]ダイアログで変更できます。

フローを呼び出すと、フロー出力がレスポンスオブジェクトとして送信されます。

OAuth 2.0で保護する

早期アクセスリリース。「セルフサービス機能を有効にする」を参照してください。

セキュアなOAuth 2.0クライアント資格情報交換を使用してフローのAPIエンドポイントを呼び出すには、次の手順を使用します。このプロセスにはJWT秘密鍵が必要です。

APIサービス統合アプリを作成する

APIサービス統合アプリを作成することは、保護されたフローを呼び出すための最適な方法です。このアプリの唯一の目的は、フローを呼び出して出力を呼び出し元のリクエストに返すことです。

  1. Admin Consoleで、[Applications(アプリケーション)][Applications(アプリケーション)]に移動します。

  2. [Create App Integration(アプリ統合を作成)] をクリックします。

  3. [API Services(APIサービス)]を選択して[Next(次へ)]をクリックします。

  4. [App integration name(アプリ統合の名前)]を入力し、[Save(保存)]をクリックしてアプリ統合を作成します。

    独自のAPIサービスを構築する場合は、Okta開発者用ドキュメントの「APIサービス統合を構築する」を参照してください。

  5. アプリケーションのリストで、新しいAPIサービスアプリを開きます。

  6. [一般]タブの[クライアント資格情報]ペインで、[Public key / Private key(公開鍵/秘密鍵)]オプションを選択します。

  7. [Add key(鍵を追加)]をクリックし、ダイアログで[Generate new key(新しい鍵を生成)]をクリックします。この秘密鍵の値をローカルシステムにコピーします。クライアントが認証サーバーを呼び出したときに、この秘密鍵を使用してクライアントからのペイロードに署名します。Okta認証サーバーは、対応する公開鍵を使用して資格情報を検証し、アクセストークンを生成します。サービスアプリケーションの作成の詳細については、「サービスアプリを使用してOkta向けOAuthを実装する」と「クライアント認証用のJWTを構築する」を参照してください。

  8. [Okta API Scopes(Okta APIスコープ)]タブで、okta.workflows.invoke.manageスコープの[Grant(付与)]をクリックします。権限ダイアログで、[Grant Access(アクセスを付与)]をクリックしてアクションを確定します。

    独自のカスタムAPIサービスを構築する場合は、このスコープを追加します。呼び出しが適切に機能するにはこのスコープが必要であるからです。

APIエンドポイント設定を構成する

既存のAPIエンドポイントフローについては、フロー作成ステップをスキップできます。代わりに、[APIエンドポイント]イベントカードの下部に表示されている[Endpoint settings(エンドポイント設定)]アイコン APIエンドポイント設定アイコン。 をクリックします。

  1. Workflowsコンソールでフローを作成し、[Add event(イベントを追加)]をクリックします。

  2. [フローを開始するためのアプリを選択]ダイアログで、[API Endpoint(APIエンドポイント)]を選択します。

  3. [APIエンドポイント設定]ダイアログで、セキュリティレベルとして[Secure with OAuth 2.0(OAuth 2.0で保護)]を選択します。

  4. [Invoke URL(呼び出しURL)]がリクエストを受信したときにフローをトリガーできるアプリ統合を選択します。

    • [Any(すべて)]:適切なスコープが設定されているすべてのアプリ統合がフローをトリガーできます。

    • [Select from list(リストから選択)]:ドロップダウンメニューを使用して、フローをトリガーできる特定のアプリ統合を選択します。各統合には適切なスコープが必要です。

      リストをフィルターするには、フィールド内で統合の名前の入力を開始します。リストから統合を削除するには、アプリ名の横にある「X」をクリックします。

  5. [Close(閉じる)]jをクリックして、変更したエンドポイント設定を確定します。

APIエンドポイントフローをテストする

OAuthで保護されているエンドポイントをテストするには、PostmanクライアントなどのOAuthクライアントを使用する必要があります。

Postmanでは、https://${yourOktaDomain}/oauth2/v1/tokenにあるOkta orgのOAuthトークンエンドポイントに対してGETリクエストまたはPOSTリクエストを実行できます。

リクエストが認証されると、認証サーバーは、[Invoke URL(呼び出しURL)]にあるエンドポイントにクエリを実行してフローを呼び出すために使用できるアクセストークンを返します。

クライアントトークンで保護する

登録済みのWebhookを介してフローを呼び出すには、次の手順を使用します。

既存のAPIエンドポイントフローについては、フロー作成ステップをスキップできます。代わりに、[APIエンドポイント]イベントカードの下部に表示されている[Endpoint settings(エンドポイント設定)]アイコン APIエンドポイント設定アイコン。 をクリックします。

  1. Workflowsコンソールでフローを作成し、[Add event(イベントを追加)]をクリックします。

  2. [フローを開始するためのアプリを選択]ダイアログで、[API Endpoint(APIエンドポイント)]を選択します。

  3. [APIエンドポイント設定]ダイアログで、セキュリティレベルとして[Secure with client token(クライアントトークンで保護)]を選択します。

  4. このオプションを選択すると、登録済みのWebhookを識別するための[Client token(クライアントトークン)]が生成されます。この固有のクライアントトークンは、[Invoke URL(呼び出しURL)]フィールドと[Resume URL(再開URL)]フィールドにエイリアス値として自動的に追加されます。

  5. [copy(コピー)]をクリックして、[Invoke URL(呼び出しURL)]フィールドにURLを保存します。

  6. [Close(閉じる)]jをクリックして、変更したエンドポイント設定を確定します。

APIエンドポイントフローをテストする

フローを呼び出すには、[Invoke URL(呼び出しURL)]に対してGETリクエストまたはPOSTリクエストを実行します。リクエストの本文でデータを送信する必要がある場合は、POSTメソッドを使用します。

必要に応じて、以下のいずれかの方法でリクエストを認証します。

  • 指定した[Client token(クライアントトークン)]を、clientTokenクエリパラメーターを使って渡す。これはデフォルトの動作です。

  • 指定した[Client token(クライアントトークン)]を、x-api-client-tokenヘッダーの値として渡す。これは、最も安全なオプションです。ただし、clientTokenクエリパラメーターと併用しないでください。

セキュリティなし(パブリックサービス)

フローをパブリックサービスとして呼び出すには、次の手順を使用します。

既存のAPIエンドポイントフローについては、フロー作成ステップをスキップできます。代わりに、[APIエンドポイント]イベントカードの下部に表示されている[Endpoint settings(エンドポイント設定)]アイコン APIエンドポイント設定アイコン。 をクリックします。

  1. Workflowsコンソールでフローを作成し、[Add event(イベントを追加)]をクリックします。

  2. [フローを開始するためのアプリを選択]ダイアログで、[API Endpoint(APIエンドポイント)]を選択します。

  3. [APIエンドポイント設定]ダイアログで、セキュリティレベルとして[None (public service)(なし(パブリックサービス))]を選択します。

  4. [Invoke URL(呼び出しURL)]フィールドのURLをコピーします。

  5. [Close(閉じる)]jをクリックして、変更したエンドポイント設定を確定します。

APIエンドポイントフローをテストする

フローを呼び出すには、[Invoke URL(呼び出しURL)]に対してGETリクエストまたはPOSTリクエストを実行します。リクエストの本文でデータを送信する必要がある場合は、POSTメソッドを使用します。

このセキュリティレベルでは、フローを呼び出すためにリクエストで認証オプションを渡す必要はありません。

関連項目

関数:APIエンドポイント

フローエイリアス

フロークライアントトークン