日本語
  1. Zendeskヘルプ
  2. 製品共通
  3. 製品共通の機能
  4. SSO のセットアップ

JWT（JSON Webトークン）シングルサインオンの有効化

Charles Nadeau
  • 編集済み

すべてのプラン

ファストパス： 「管理センター」>「セキュリティ」

シングルサインオンは、システム内のユーザーを認証し、そのユーザーが認証されたことをZendeskに通知する機構です。JWTでシングルサインオンを使用する場合、サインイン時にユーザーがアイデンティティプロバイダによって自動的に検証されます。認証済みであると通知されたユーザーは、サインイン資格情報の入力を求められることなく、Zendeskにアクセスできるようになります。

シングルサインオンの基幹部分は、Zendeskがシステムから取得したサインインリクエストを信頼できるようにするセキュリティメカニズムです。Zendeskがアクセスを許可するのは、認証されたユーザーのみです。Zendesk SSOは、ユーザー認証データを安全に交換するJSON Webトークン（JWT）と呼ばれるテクノロジに基づいています。

この記事では、次のトピックについて説明します。

会社のJWT認証システムの設定と管理は、通常は会社のITチームが担当します。ITチームの役割は、システムにZendesk向けSSOを実装することです。ITチームに、この記事内の以下のトピックをご紹介ください。

関連記事

ZendeskでのJWT SSOの動作

SSOを有効にすると、サインインリクエストはZendesk Supportの外部のサインインページにルーティングされます。

JWT SSO認証プロセスの手順：

  1. 認証されていないユーザーがZendesk Support URLにアクセスします。例：https://your-subdomain.zendesk.com/。
  2. ZendeskのSSO機構が、SSOが有効になっており、かつユーザーが認証されていないことを認識します。
  3. Zendeskは、ユーザーを組織のリモートサインインページにリダイレクトします。例：https://mycompany.com/zendesk/sso.
  4. リモートサーバーのスクリプトが、組織の独自のサインインプロセスを使用してユーザーを認証します。
  5. 認証システムによって、関連するユーザーデータが含まれるJWTリクエストが作成されます。
  6. 認証システムは、JWTペイロードを持つ次のZendeskエンドポイントにユーザーをリダイレクトします。

    https://your-subdomain.zendesk.com/access/jwt

  7. JWTペイロードからユーザーの詳細なデータが解析され、ユーザーにセッションが割り当てられます。

このように、このプロセスはブラウザのリダイレクトと、JWTを使用した署名付きメッセージの回送に依存しています。リダイレクトは完全にブラウザで実行されるので、Zendeskと社内のシステムの間に直接リンクは存在せず、認証スクリプトを会社のファイアウォールの内側で安全に保持できます。

JWT SSOを有効にするための要件

JWT認証システムを担当している社内のチーム（通常はITチーム）に連絡をとり、以下の情報を入手してください。
  • ZendeskにアクセスしようとするZendeskユーザーのリダイレクト先のリモートログインURL
  • （オプション）ユーザーがZendeskからサインアウトした後に、ZendeskがユーザーをリダイレクトするページのログアウトURL
  • （オプション）ユーザーを適切なサインインオプションにリダイレクトするためのIPアドレス範囲のリスト。指定されたIPアドレス範囲から要求を行ったユーザーは、リモートJWTの認証サインインフォームにルーティングされます。指定されたIPアドレス範囲外から要求を行ったユーザーは、通常のZendeskのサインインフォームにルーティングされます。アドレス範囲を指定しないと、すべてのユーザーがリモート認証のサインインフォームにリダイレクトされます。

Zendesk方向のトラフィックがHTTPではなくHTTPS経由であることをチームに確認してください。

次に、Supportに情報を入力してシングルサインオンを有効にします。「JWT SSOの有効化」を参照してください。

ITチームが、ZendeskからSAML実装を設定するための追加情報を必要とする場合があります。その場合は、この記事の実装のためのテクニカルワークシートを参考にしてもらってください。

JWT SSOの有効化

JWTシングルサインオンは、エンドユーザーのみを対象、エージェント（スタッフメンバー）のみを対象、または両者を対象として有効にできます。JWTとSAMLの両方を使用している場合は、プライマリ認証方法として、どちらか1つを選択する必要があります。Zendeskにサインインすると、ユーザーはプライマリサインインページにリダイレクトされます。セカンダリサインインページに移動し、セカンダリの認証方法を使ってサインインすることもできます。詳細については、「エージェントとエンドユーザーに異なるSAMLおよびJWT SSO（シングルサインオン）を使用する方法」を参照してください。

JWTシングルサインオンを有効にするには、Zendesk Supportに管理者としてサインインする必要があります。

JWTシングルサインオンを有効にするには

  1. どの製品の場合でも、一番上のメニューバーでZendesk製品アイコン（）をクリックし、「管理センター」を選択します。
  2. 左側のサイドバーにあるセキュリティアイコン（）をクリックし、「シングルサインオン」タブをクリックします。
  3. 「JSON Webトークン」の場合は、「設定」をクリックします。
  4. 「リモートログインURL」に、Zendesk URLへのアクセスを試みるユーザーのリダイレクト先のURLを入力します。

    brand_idパラメータが自動的にURLに追加されます。サインインを試みたときにユーザーが訪問していたZendesk Supportブランドを示します。

  5. 「リモートログアウトURL」には、サインアウトしたユーザーに表示されるページのURLを入力します。

    email、external_id、およびbrand_idの各パラメータがURLに自動的に追加されます。メール情報と外部ID情報をURLに含めたくない場合は、ログアウトURLに空白のパラメータを指定します。例：

    https://www.xyz.com/user/signout/?email=&external_id=

    メモ： Ember.jsアプリケーションを使用している場合は、ハッシュの前に空白のパラメータを使用するようにログアウトURLを修正する必要があります。例：https://somedomain.com/?brand_id=&return_to=&email=#/zendesk-login/
  6. （オプション）「IPアドレス範囲」には、ユーザーを適切なサインインオプションにリダイレクトするためのIPアドレス範囲を列挙して入力します。

    指定されたIPアドレス範囲から要求を行ったユーザーは、JWT認証サインインフォームにルーティングされます。指定されたIPアドレス範囲外から要求を行ったユーザーは、通常のZendeskのサインインフォームにルーティングされます。すべてのユーザーがJWT認証のサインインフォームにリダイレクトしたい場合は、アドレス範囲を指定しないでください。

  7. ユーザーに対して外部IDを使用している場合は、「外部IDの更新を許可しますか？」に対して「オン」を選択すると、Zendesk Support内で外部IDを更新できます。
  8. ITチームに共有シークレットを提供します。チームがJWTを実装する際に必要になります。
    重要： 共有シークレットのセキュリティを保護してください。セキュリティが侵害された場合、あなたのSupportアカウントのすべてのデータが危険にさらされます。
  9. JWT SSOを設定したら「有効」をクリックして、このオプションをユーザーに割り当てられるようにします。
  10. 「保存」をクリックします。

ユーザーへのJWT SSOの割り当て

JWT SSOオプションを設定したら、エンドユーザーまたはスタッフメンバー、あるいはその両方に割り当てます。
  1. 管理センターで、「スタッフメンバー」または「エンドユーザー」タブをクリックし、「外部認証 」オプションを選択します。
  2. 「外部認証」セクションで「シングルサインオン」オプションとして「JSON Webトークン」を選択します。
  3. すべてのユーザーにシングルサインオン方式のみを使用させる場合は、Zendesk認証オプションの選択を解除します。

    すべてのZendeskパスワードが、24時間以内にアカウントから完全に削除されます。

  4. Zendeskのパスワードを無効にした場合は、サインインプロバイダがダウンしたときに、アカウントへのアクセス許可をアカウントオーナーまたは管理者（アカウントオーナーを含む）に限定するよう指定するメニューオプションを選択できます。

    アクセス権を取得するには、アカウントオーナーまたは管理者は、ワンタイムアクセスリンクを含むメールの受信をリクエストします。リンクをクリックすると、アカウントへのアクセス権が付与されます。パスワードは必要ありません。「パスワードが無効になっている場合にアカウントにアクセスする」を参照してください。

  5. 「保存」をクリックします。

共有シークレットの新規作成

場合によっては、新しいJWT共有シークレットを発行し、ITチームに提供する必要があります。たとえば、シークレットが漏洩した場合などです。Zendesk管理センターから新しいJWT共有シークレットを生成するには、JWT設定を無効にしてから再度有効にします。この操作によって、新しいシークレットが生成され、古いシークレットが無効になります。

重要： JWT設定を無効にすると、新しいシークレットが設定されるまで、ユーザーはJWT SSOを使用して認証できなくなります。このとき、ユーザーがバックアップの認証方法を使用できることを確認してください。

共有シークレットを新規作成するには

  1. どの製品の場合でも、一番上のメニューバーでZendesk製品アイコン（）をクリックし、「管理センター」を選択します。
  2. 左側のサイドバーにあるセキュリティアイコン（）をクリックし、「シングルサインオン」タブをクリックします。
  3. 「JSON Webトークン」の場合は、「編集」をクリックします。

    現在のJSON Webトークン設定が表示されます。

  4. 「有効」チェックボックスの選択を解除します。
  5. 変更を保存します。
  6. JSON Webトークンの横にある「設定」をクリックして、設定を再度開きます。

    設定ページの下部に、新しい共有シークレットがプレーンテキストで表示されます。

  7. 新しい共有シークレットのコピーを作成して、ITチームに渡します。
  8. 「有効」をクリックして、新しい共有シークレットを使用した設定を再度有効にします。
  9. 変更を保存します。

JWTに関する補足情報

JWTは最新のオープン標準であり、国際的な標準化組織IETFによって策定され、テクノロジ分野のトップクラスの企業（Microsoft、Facebook、Googleなど）による後援を受けています。

JWTの基本の構成要素は、非常に理解しやすいコンポーネントです。結果的に非常にシンプルになっている仕様は、http://tools.ietf.org/html/draft-jones-json-web-token-10で参照できます。JWT仕様にはオープンソース実装が多数あり、どれもほとんどの最新テクノロジに対応しています。言い換えると、JWTシングルサインオンは、さほど苦労することなく設定できるということです。

1つ注意が必要なのは、JWTペイロードは単にエンコードされ署名されているだけであり、暗号化されていないという点です。ハッシュテーブルには重要なデータを挿入しないでください。JWTは、文字列として転送されたJSONのシリアライズによって機能します。その後、この文字列はBASE64でエンコードされ、共有シークレットに依存するBASE64文字列のHMACが作成されます。これにより、受信者側でユーザーの検証に使用できる署名が生成されます。

実装のためのテクニカルワークシート

このセクションは、JWT認証システムを担当する社内のチームを読者として想定しています。このセクションで、Zendesk JWT SSO実装について詳しく説明します。

メモ： 古いバージョンのZendesk SSO（Zendeskリモート認証と呼ばれる）からJWTにアップグレードする場合には、同時に複数のSSO実装を有効にすることができます。Zendeskは、要求がJWT向けのものか別の種類のSSO向けのものかを識別し、それぞれの種類に応じて処理します。つまり、古いSSO実装を無効にする前に、JWTを有効にしてテストできます。

次のトピックについて説明します。

JWTアルゴリズム

JWTペイロードのヘッダーにJWTアルゴリズムとして、次のようにHS256を指定します。

{
  "typ":"JWT",
  "alg":"HS256"
}

HS256は、HMAC SHA 256を表します。これは、アメリカ国家安全保障局によって開発された256ビットの暗号化アルゴリズムです。

メモ： Zendeskは、RS256とES256のJWTアルゴリズムをサポートしていません。

Zendesk JWTエンドポイント

ユーザーの認証に成功すると、JWTペイロードとともにユーザーを次のZendeskエンドポイントにリダイレクトします。

https://your-subdomain.zendesk.com/access/jwt

ペイロードはbase64でエンコードされ、URLにクエリ文字列として追加されます。

JWTペイロードは、httpsプロトコルを使用してZendesk Supportサブドメインに送られる必要があります。例：

https://your-subdmain.zendesk.com/access/jwt?jwt={payload}

ホストマッピングされたサブドメインはサポートされません。

JWT属性

Base64エンコードされたハッシュ（Ruby）または辞書（Python）としてZendeskに属性を送信します。以下はRubyを使用した例です。

payload = JWT.encode({
   :email => "bob@example.com", :name => "Bob", :iat => Time.now.to_i, :jti => rand(2<<64).to_s
}, "Our shared secret")

Zendeskはユーザーを一意に識別するため、メールアドレスを必要とします。下記の表に記載されている必須の属性以外に、オプションで追加のユーザープロファイルデータを送信することもできます。これらのデータは、ユーザー管理システムとZendesk Supportの間で同期がとられます。

表 1.サポートされる属性
属性 必須 説明
iat ○ 発行時刻。トークンが生成された時刻。指定されたトークンが生成直後に確実に使用されるようにするために使用されます。この値は、UNIXエポックから経過した秒数である必要があります。Zendeskでは、最大3分のクロックスキューが許容されているため、必ずNTPまたは同様のプロトコルをサーバーに設定してください。
jti ○ JSON WebトークンのID。トークン反射攻撃を防御するためのトークンの一意のIDです。
email ○ ユーザーが登録しているメールアドレス。Zendesk Support内のユーザーレコードを一意に特定する際に使用されます。
name ○ ユーザーの名前。このユーザーに連動して、Zendesk Support内のユーザーが作成または更新されます。
external_id × ユーザーがメールアドレス以外の情報で一意に特定されていて、メールアドレスが変更される可能性がある場合、一意のIDをシステムから送信します。IDは文字列として指定します。
locale（エンドユーザーの場合）

locale_id（エージェントの場合）

 × 数値として指定されたZendesk Support内のロケール。
organization × ユーザーが所属する組織の名前。メモ：「エンドユーザーに複数の組織に属することを許可する」オプションが有効になっている場合、追加される組織には元の組織が付属し、セカンダリ組織とみなされます。既存のメンバーシップは削除されません。

複数の組織を同時に渡す場合は、organization_ids属性を使用します。組織は、カンマで区切った文字列で渡す必要があります。
organization_id × Zendesk APIで使用する組織の外部ID。organizationとorganization_idの両方が指定されている場合、organizationは無視されます。メモ：「エンドユーザーに複数の組織に属することを許可する」オプションが有効になっている場合、追加される組織には元の組織が付属し、セカンダリ組織とみなされます。既存のメンバーシップは削除されません。

複数の組織を同時に渡す場合は、代わりにorganizations_id属性を使用します。組織は、カンマで区切った文字列で渡す必要があります。
phone × 文字列として指定された電話番号。
tags × ユーザーに対して設定されるJSON配列のタグ。これらのタグは、ユーザープロフィール内にすでにタグがある場合、それらのタグを置き換えます。
remote_photo_url × ユーザープロフィールに設定される写真のURL。
role × ユーザーのロール。user、agent、またはadminを設定できます。デフォルトはuserです。ユーザーのロールがZendesk Supportでのロールと異なる場合、Zendesk Supportでのロールが変更されます。
custom_role_id × ユーザーのロールがエージェントの場合にのみ、適用されます。
user_fields ×

ユーザーに設定されるカスタムユーザーフィールドキーと値のJSONハッシュ。フィールド値を設定するにはカスタムユーザーフィールドが存在する必要があります。各カスタムユーザーフィールドは、ユーザーフィールドの管理設定にあるフィールドキーで識別されます。日付の値の形式は、yyyy-mm-ddです。

カスタムユーザーフィールドキーまたは値が無効な場合、フィールドを更新すると警告を表示せずに失敗しますが、ユーザーは引き続きログインできます。カスタムユーザーフィールドの詳細については、「ユーザープロフィールへのカスタムフィールドの追加」を参照してください。
メモ： null値をuser_fields属性に指定して送信すると、対応するフィールドから既存の値が削除されます。

リモートログインURLパラメーター（return_to）

Zendeskは、ユーザーをリモートログインページにリダイレクトするときに、return_to URLパラメータも渡します。このパラメータには、システムがユーザーを認証した後に、Zendeskがユーザーを返すページが含まれています。パラメータ（名前と値）をZendesk JWTエンドポイントに追加します。

たとえば、ログアウトしたエージェントが次のリンクをクリックしてSupportでチケットを開くとします。https://mycompany.zendesk.com/tickets/1232フローは次のとおりです。

  1. クリックすると、ZendeskはユーザーをリモートログインURLにリダイレクトし、次のreturn_toパラメータをURLに追加します。 
    https://mycompany.com/zendesk/sso?return_to=https://mycompany.zendesk.com/tickets/123
  2. 認証システムはURLから return_toパラメータ（名前と値）を受け取り、ユーザーの認証に成功した後、パラメータをZendesk JWTエンドポイントに追加します。例： 
    https://mycompany.zendesk.com/access/jwt?jwt=payload&return_to=https://mycompany.zendesk.com/tickets/123
  3. Zendeskはこのパラメータを使用して、エージェントのチケットページを開きます。

return_toパラメータには、エージェントインターフェイスの場合は絶対URLを指定し、ヘルプセンターの場合は相対URLを指定します。

return_toパラメータを渡すかどうかは任意に選択できますか、最善のユーザーエクスペリエンスのためにはこのパラメータを渡すことを推奨します。

メモ： return_toアドレスに独自のURLパラメータが含まれている場合、JWTトークンを送信する際に、return_to値全体がScript-URIによってエンコードされることを確認してください。

エラー処理

JWTログイン要求の処理中にエラーが発生した場合、発生した問題について説明するメッセージが表示されます。JWTインテグレーションの設定時にリモートログアウトURLを指定した場合は、そのURLにリダイレクトされ、メッセージとkindパラメータが渡されます。エラーが発生した場合、kindパラメータの値は常に"error"となります。リモートログアウトURLを設定し、Zendeskからのメッセージとエラーのタイプを記録することをお勧めします。発生しうるエラーの多くは、修正が必要なエラーです。たとえば、クロックのドリフト、レート制限超過、無効なトークンなどのエラーなどです。

JWT実装のコード例

実際のJWT実装は、非常にわかりやすく、多くの最先端の言語にライブラリが用意されています。Zendeskでは、以下のJWT SSO GitHubリポジトリで各種スタックに対応したコード例を多数公開しています。

その他のスタックでJWTを実装する場合に、コード例をお寄せいただければ幸いです。この記事にコメントを付けることで、お客様の実装例を共有できます。

IISまたはADを実行していて、.NETソリューションの構築を希望しないお客様のために、Zendeskでは、Classic ASPでの完全な実装を提供いたします。この実装では、いくつかの変数を調整するだけで済みます。ASP認証スクリプトをGithubのhttps://github.com/zendesk/zendesk_jwt_sso_examples/tree/master/bundlesからダウンロードします。

他にご質問がございましたら、リクエストを送信してください

0 コメント

ログインしてコメントを残してください。

関連記事

関連記事

Powered by Zendesk