Blog
ホーム

OAuth JWT における同意の取得

Larry Kluger
Larry KlugerLead Developer Advocate
概要5分で読み終わります

本ブログでは、OAuth JWT Grant 認証における同意の取得について解説しています。ドキュサインのLead Developer AdvocateであるLarry Kluger、およびLead Software EngineerのJosh Wiseによる記事をご覧ください。

目次

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

この 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 KlugerLead Developer Advocate
この著者の他の投稿

関連記事

システム構築の特効薬?APIとは何なのか

安達 智洋
安達 智洋

電子署名を試してみませんか?Docusign eSignature の無料トライアルをご活用ください。

無料で試すお問い合わせ
Person smiling while presenting