OAuth JWT における同意の取得
本ブログでは、OAuth JWT Grant 認証における同意の取得について解説しています。ドキュサインのLead Developer AdvocateであるLarry Kluger、およびLead Software EngineerのJosh Wiseによる記事をご覧ください。
例えば、あなたの会社で新しい 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つの異なるソフトウェアのパターンを提供しています。
管理者の同意：これは、ユーザー側からのアクションが不要なため、顧客側の開発者にとっては最良のオプションになります。しかし、この同意パターンは、一般的に ISV には使用できず、Docusign 管理者の作業が多くなり、一部の料金プランにしか含まれない製品機能が必要になります。
ユーザー個別の同意：このオプションには前提条件がなく、顧客側の開発者や ISV の顧客が使用することができます。しかし、JWT Grant（後述）を介して偽装される各ユーザーによる特定のステップが必要です。前提条件がないため、この同意方法は、アプリケーションを開発またはテストする際に使用されます。
サードパーティ（ISV）アプリケーションのための管理者同意：管理者同意パターンは、ISV が追加の AP Iプロトコルを実装した場合にのみ、サードパーティのアプリケーションで使用することができます。（その他の管理者同意の前提条件も適用されます）こういった前提条件があるため、この同意パターンはあまり使用されていません。
管理者による同意の付与
ユーザーの管理負担を軽減するために、Docusign では、アプリケーションに必要な同意をユーザーに代わって管理者として付与することを推奨しています。この方法は、一括同意（Blanket concent）とも呼ばれています。この方法では、権限を与えられた組織管理者が、個々のユーザーに代わって、クライアント ID（およびその ID を使用するアプリケーション）に同意を与えることができます。
管理者による同意を利用する方法：
お使いのアカウントには、Access Management with SSO 機能が含まれている必要があります。管理者による同意には SSO の設定は必ずしも必要ありませんが、SSO を含む製品機能が必要です。テストの際に必要となる、お客様の開発者用デモアカウント（demo.docusign.net）にこの機能が含まれていない場合は、go-live@docusign.com 宛に電子メールを送り、お客様のアカウントにこの機能を追加してください。その際、開発者用デモアカウント ID を忘れずに記入してください。もしくは弊社の担当営業までご連絡ください。
Docusign 管理ツールを使って、メールの DNS ドメインを予約する必要があります。詳しくは「Docusign管理者による組織管理 - ドメイン」のページをご参照ください。ドメインは、Docusign 開発者用デモシステム（テスト・開発用）でも、本番の Docusign アカウントでも予約することができます。
ユーザーのメールドメインは、予約されたメールドメインと一致する必要があります。
インテグレーターキーの管理アカウントは、Docusign 組織内のアカウントである必要があります。
組織管理者は、Docusign 管理機能（Docusign Admin、eSignature 管理画面ではない）を使用して、アプリケーションのクライアント ID に管理者権限で同意を与えることができます。署名と偽装（signature impersonation）の両方のスコープに同意を与える必要があります。詳細は「接続アプリ」に関するページをご覧ください。
個別に同意を付与する
お客様のアカウントに上記の前提条件が含まれていない場合や、開発者用のデモアカウントでメールドメインを申請していない場合は、管理者による同意を使用することができません。このような場合は、ユーザーが個別に同意を得る必要があります。
同意を得るためには、JWT Grant アプリケーションによって偽装されるユーザーに、ブラウザで特定の URL を開いてもらいます。この URL は、1回限りで使用されるものを提供してください。
ユーザーが URL を開くと、Docusign との認証を求められます。認証後、ユーザーはフォームを介してアプリケーションに同意するよう求められます。
図1: JWT Example Application へのコンセントを個別に与えるためのポップアップ画面。ユーザーは2つの異なる権限（signature と impersonation）に対して同意を与えることになり、それぞれがこの画面の箇条書きの項目として表示されています。
個別の同意のためのインテグレーションキーの準備
インテグレーションキーで個別に同意を取得するためには、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 構築にも携わっています。
