ブログを読む

OAuth JWT における同意の取得

JWT Consent

例えば、あなたの会社で新しい DocuSign アプリケーションを開発しているとします。開発の目的が、サービス統合であったり、（望ましいOAuth Auth Code Grantフローの要件である）ユーザーのブラウザをリダイレクトする方法がなかったため、OAuth JWT Grant 認証フローを採用することにしました。

テストを開始したところ、アプリケーションが consent_required エラーとなりました。どうしたら、このエラーを解消できるのでしょうか？

回答：同意が必要です

クライアントID（インテグレーションキー）を使ってユーザーのアクセストークンを取得するには、ユーザーがクライアント ID に同意を与える必要があります。同意は、特定のユーザーの 1 つ以上のパーミッションスコープを取得するために、クライアント ID に付与されます。

DocuSign eSignature REST API で JWT Grant フローを使用するためには、クライアント ID に、ユーザの署名および偽装（signature と impersonation）のスコープが付与されなければなりません。アプリケーションが使用する DocuSign API や API メソッドによっては、他のスコープも必要となる場合があります。例えば、DocuSign Click API の管理メソッドには click.manage スコープが必要です。

同意の付与：複数の選択肢

DocuSign は、インテグレーションキーへの同意を与えるために、3つの異なるソフトウェアのパターンを提供しています。

  1. 管理者の同意：これは、ユーザー側からのアクションが不要なため、顧客側の開発者にとっては最良のオプションになります。しかし、この同意パターンは、一般的に ISV には使用できず、DocuSign 管理者の作業が多くなり、一部の料金プランにしか含まれない製品機能が必要になります。
  2. ユーザー個別の同意：このオプションには前提条件がなく、顧客側の開発者や ISV の顧客が使用することができます。しかし、JWT Grant（後述）を介して偽装される各ユーザーによる特定のステップが必要です。前提条件がないため、この同意方法は、アプリケーションを開発またはテストする際に使用されます。
  3. サードパーティ（ISV）アプリケーションのための管理者同意：管理者同意パターンは、ISV が追加の AP Iプロトコルを実装した場合にのみ、サードパーティのアプリケーションで使用することができます。（その他の管理者同意の前提条件も適用されます）こういった前提条件があるため、この同意パターンはあまり使用されていません。

管理者による同意の付与 

ユーザーの管理負担を軽減するために、DocuSign では、アプリケーションに必要な同意をユーザーに代わって管理者として付与することを推奨しています。この方法は、一括同意（Blanket concent）とも呼ばれています。この方法では、権限を与えられた組織管理者が、個々のユーザーに代わって、クライアント ID（およびその ID を使用するアプリケーション）に同意を与えることができます。 管理者による同意を利用する方法：

  1. お使いのアカウントには、Access Management with SSO 機能が含まれている必要があります。管理者による同意には SSO の設定は必ずしも必要ありませんが、SSO を含む製品機能が必要です。テストの際に必要となる、お客様の開発者用デモアカウント（demo.docusign.net）にこの機能が含まれていない場合は、go-live@docusign.com 宛に電子メールを送り、お客様のアカウントにこの機能を追加してください。その際、開発者用デモアカウント ID を忘れずに記入してください。もしくは弊社の担当営業までご連絡ください。
  2. DocuSign 管理ツールを使って、メールの DNS ドメインを予約する必要があります。詳しくは「DocuSign管理者による組織管理 - ドメイン」のページをご参照ください。ドメインは、DocuSign 開発者用デモシステム（テスト・開発用）でも、本番の DocuSign アカウントでも予約することができます。
  3. ユーザーのメールドメインは、予約されたメールドメインと一致する必要があります。
  4. インテグレーターキーの管理アカウントは、DocuSign 組織内のアカウントである必要があります。

組織管理者は、DocuSign 管理機能（DocuSign Admin、eSignature 管理画面ではない）を使用して、アプリケーションのクライアント ID に管理者権限で同意を与えることができます。署名と偽装（signature impersonation）の両方のスコープに同意を与える必要があります。詳細は「接続アプリ」に関するページをご覧ください。

個別に同意を付与する

お客様のアカウントに上記の前提条件が含まれていない場合や、開発者用のデモアカウントでメールドメインを申請していない場合は、管理者による同意を使用することができません。このような場合は、ユーザーが個別に同意を得る必要があります。

同意を得るためには、JWT Grant アプリケーションによって偽装されるユーザーに、ブラウザで特定の URL を開いてもらいます。この URL は、1回限りで使用されるものを提供してください。

ユーザーが URL を開くと、DocuSign との認証を求められます。認証後、ユーザーはフォームを介してアプリケーションに同意するよう求められます。

Consent Dialog

図1: JWT Example Application へのコンセントを個別に与えるためのポップアップ画面。ユーザーは2つの異なる権限（signature と impersonation）に対して同意を与えることになり、それぞれがこの画面の箇条書きの項目として表示されています。

個別の同意のためのインテグレーションキーの準備

インテグレーションキーで個別に同意を取得するためには、2つの設定を行う必要があります。

  1. 暗黙の付与ではなく、認証コードの付与を使用するようにインテグレーションキーを設定します。
  2. インテグレーションキーのリダイレクト URI を設定します。詳細は以下を参照してください。

個別の同意のためのURL

同意のための URL は、実際にはアプリケーションの OAuth Authentication Code grant フローを開始するために使用される URL と同じです。しかし、この場合 Authentication Code Grant フローの最初の部分のみが使用されます。アプリケーションは、認証コード自体を受け取らない、または無視することになります。

アプリケーションのすべてのユーザーが同じ同意のための URL を使用します。これにはアプリケーションのクライアント ID が含まれ、ユーザー個別のものではありません。アプリケーションは、ユーザーにこの URL を提供する必要があります。フォーマットは以下のようになります。

SERVER/oauth/auth?response_type=code &scope=signature%20impersonation&client_id=CLIENT_ID &redirect_uri=REDIRECT_URI
  • SERVER は、https://account.docusign.com（本番環境）またはhttps://account-d.docusign.com（開発者デモ用サンドボックス環境）です。
  • CLIENT_ID は、あなたのアプリケーションのインテグレーションキーです。
  • REDIRECT_URI は URI です。これは、DocuSign eSignature Administration ツールでアプリケーションのインテグレーションキーに対して定義したリダイレクト URI の1つと正確に一致する必要があります。URI の値はエンコードする必要があります。

この URL では、署名と偽装（signature impersonation）の2つのスコープに対する個別の同意を求めます。%20 は、スペース文字のエンコード値です。

これに対し、DocuSign は利用者を認証し、アプリケーションのクライアント ID に、要求された2つのスコープを付与することへの同意を求めます。その後、DocuSign は、ユーザを redirect_uri にリダイレクトします。

redirect_uri ページは、単に "Thank you for granting consent to the XYZ application " とだけ表示させることができます。リダイレクトページでは、（クエリパラメータとして含まれている）認証コードを使用してはいけないことを覚えておいてください。

ユーザーから同意を得ると、アプリケーションは OAuth JWT フローを使ってユーザーに偽装することができるようになります。ユーザーの同意は、DocuSign データベースに記録されます。クッキーなどでクライアントに保存されることはありません。

同意のための URL の配布

JWT Grant フローを使用するほとんどのアプリケーションは、サービスインテグレーションであり、Web インターフェイスを持たないため、同意のための URL をユーザーに簡単に配布することはできません。同意の URL を配布する一般的な方法としては、アプリケーションがユーザーに同意の URL をメールで送信する方法があります。また、アプリケーションの情報ページに同意用 URL をリンクとして載せ、ユーザーに開く（クリックする）ように依頼する方法もあります。

管理者の同意を ISV アプリケーションに付与する

もしあなたが JWT  Grant フローを使用する独立系ソフトウェアベンダー（ISV）の場合、アプリケーションのインテグレーションキーの管理アカウントは、あなたの会社が管理する DocuSign アカウントである必要があります。この場合、顧客が管理者としての同意を使用できるようにするには、アプリケーションに特別な同意 API フローを実装する必要があります。（あなたのアカウントでインテグレーションキーが管理されているためです。）このプロセスについては、「OAuth Consent」のページで詳しく説明しています。

管理者による同意には、Access Management with SSO の機能と、上記の設定が必要なため、すべてのエンドユーザーが管理者による同意を使用できるわけではありません。このようなお客様をサポートするために、ISV はバックアップとして個別の同意もサポートする必要があります。

注：偽装や同意に関する問題を回避するために、ISV は可能な限りAuthorization Code Grant フローを使用することを推奨しています。

同意の付与に関する詳細は、以下のページやドキュサイン本社の開発者向けSNSアカウントでも紹介していますので、合わせてご覧ください。

-----------------------------------------------------------------------------------------------------

本記事は Larry Kluger と Josh Wise によるブログ 「OAuth JWT: Granting Consent」の抄訳となります。Larry Kluger は、DocuSign の Lead Developer Advocate です。ソフトウェア開発者、プロダクトマネージャー、エバンジェリストとして、長年にわたり技術業界で活躍してきました。受賞歴のある講演者でもあり、講演や開発者コミュニティを通してメンバーとの交流を行っています。また、Josh Wise は、DocuSign で本人確認や認証に関する製品を担当するリード・ソフトウェア・エンジニアです。このチームは、認証プロトコル、SSO、受信者認証、DocuSign Identify を含む、DocuSign のすべての認証ソリューションを担当しています。Josh は Identify フレームワークの設計や、DocuSign ID Verification の統合を担当しました。また、DocuSign の 標準電子署名や TSP パートナープログラムの API 構築にも携わっています。

Larry Kluger
筆者
Larry Kluger
Lead Developer Advocate
公開
関連トピック

関連記事