JWTシングルサインオンの有効化

ファストパス：管理センター >「アカウント」>「セキュリティ」>「シングルサインオン」

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

Zendesk管理者としての役割は、SSOオプションを有効にすることです。この記事では、チームメンバー（管理者と、ライトエージェントと閲覧担当を含むエージェント）、エンドユーザー、またはその両方の認証に使用できる、複数のJWTシングルサインオン設定を有効にする方法について説明します。

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

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

• ZendeskでのJWT SSOの動作
• JWT SSOを有効にするための要件
• JWT SSOの有効化
• ユーザーへのJWT SSOの割り当て
• JWT SSOを有効にした後のZendeskでのユーザーの管理
• 共有シークレットの新規作成
• 認証方法を切り替える
• JWTに関する補足情報

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

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

関連記事

• Zendeskの各種シングルサインオン（SSO）オプション
• SAMLシングルサインオンの有効化
• ユーザーに提供するZendeskへのさまざまなサインイン方法
• SSOサービスの停止中にZendeskアカウントにアクセスする方法

ZendeskでのJWT SSOの動作

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

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

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

   https://yoursubdomain.zendesk.com/access/jwt

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

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

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

社内のJWT認証システムを担当するチーム（通常はITチーム）と打ち合わせを行い、Zendeskから送信されるトラフィックはHTTPではなくHTTPS経由であることを確認します。

ZendeskでJWT SSO方式を設定するには次の情報が必要となるので、ITチームから提供を受けてください。

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

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

要件を満たし、必要な情報がすべて揃っていることを確認したら、JWT SSOを有効にすることができます。

JWT SSOの有効化

管理者は、JWTシングルサインオンをエンドユーザーのみ、チームメンバーのみ（ライトエージェントと閲覧担当も含む）、または両方のグループに対して有効にすることができます。JWT SSO設定は複数作成できます。設定を開始する前に、必要な情報を会社のITチームから入手します。「JWT SSOを有効にするための要件」を参照してください。

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

1. 管理センターで、サイドバーの「アカウント」をクリックし、「セキュリティ」>「シングルサインオン」を選択します。
2. 「SSO設定を作成する」をクリックし、「JSON Webトークン」を選択します。
3. 一意の構成名を入力します。
4. 「リモートログインURL」に、Zendesk URLへのアクセスを試みるユーザーのリダイレクト先のURLを入力します。

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

5. （オプション）「リモートログアウトURL」には、Zendeskからサインアウトしたユーザーがリダイレクトされるページのログアウト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. 「ユーザーのサインイン時にボタンを表示」を選択し、Zendeskサインインページに「SSOで続行」ボタンを追加します。

   「ボタン名」フィールドに値を入力することで、ボタンラベルをカスタマイズできます。カスタムボタンラベルは、サインインページに複数のSSOボタンを追加する場合に便利です。詳細については、「「SSOで続行」ボタンをZendeskサインインページに追加する」を参照してください。

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

デフォルトでは、エンタープライズSSO構成は非アクティブです。SSO構成をアクティブにするには、ユーザーに割り当てる必要があります。

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

JWT SSO設定を作成したら、エンドユーザーかチームメンバー、またはその両方に割り当てることでSSO設定をアクティブにする必要があります。

SSO設定をチームメンバーまたはエンドユーザーに割り当てるには

1. チームメンバーまたはエンドユーザーのセキュリティ設定を開きます。
   • 管理センターで、サイドバーの「 アカウント」をクリックし、「セキュリティ」>「チームメンバーの認証」を選択します。
   • 管理センターで、サイドバーの「 アカウント」をクリックし、「セキュリティ」>「エンドユーザー認証」を選択します。
2. SSO設定をチームメンバーに割り当てる場合は、「外部認証」を選択して、認証オプションを表示します。

   これらのオプションは、すでにエンドユーザーに表示されています。

3. 「外部認証」セクションで「シングルサインオン（SSO）」をクリックし、使用したいSSO設定の名前を選択します。

   シングルサインオンですべてのユースケースがカバーされるわけではないため、Zendesk認証はデフォルトで有効のままです。

4. ユーザーにサインインを許可する方法を選択します。

   

   「エンドユーザーが選択」の場合、ユーザーはアクティブな認証方法を使用してサインインすることができます。詳しくは「ユーザーに提供するZendeskへのさまざまなサインイン方法」を参照してください。

   「SSOにリダイレクト」では、プライマリのSSO構成を使用した認証のみになります。これらの認証オプションがアクティブであっても、ユーザーには追加のサインインオプションが表示されません。「SSOにリダイレクト」を選択すると、プライマリSSO設定を選択するための「プライマリSSO」フィールドが表示されます。

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

JWT SSOを有効にした後のZendeskでのユーザーの管理

ZendeskでJWTシングルサインオンを有効にした場合、Zendesk外でユーザーに加えられた変更がZendeskアカウントと同期されます。たとえば、社内のシステムにユーザーを追加すると、そのユーザーは自動的にZendeskアカウントにも追加されます。社内システムから削除されたユーザーはZendeskにサインインできなくなりますが、Zendesk内にアカウントは残されます。

デフォルトでは、シングルサインオンが有効になっている場合にZendeskに保存される唯一のユーザーデータは、ユーザーの名前とメールアドレスです。Zendesk内にパスワードは保管されません。このため、パスワードに関するZendeskからの自動メール通知はすべて無効にする必要があります。「Zendeskからのパスワード通知メールを無効にする」を参照してください。

より良いカスタマーエクスペリエンスを提供するために、ユーザーの名前とメールアドレス以外の情報もZendeskに保存することができます。これを行うには、追加のJWT属性を使用します。

Zendeskからのパスワード通知メールを無効にする

ユーザーをZendeskアカウントに追加すると、メールアドレスの確認と、ユーザー名とパスワードの作成を求めるメール通知がユーザーに届く場合があります。

SAMLまたはJWTを使用してZendeskアカウントにアクセスしたすべての新規ユーザーに、ユーザープロフィールが作成されます。これらのユーザーはZendesk以外のパスワードによって認証されるため、Zendeskにサインインする必要がありません。このため、パスワードなしでプロフィールが作成されます。ただし、デフォルトでは、すべての新規ユーザーに、メールアドレスを確認し、ユーザー名とパスワードを指定するように求める通知が届いてしまいます。

これを防ぐには、以下のオプションの選択を解除する必要があります。

1. 管理センターで、サイドバーの「 メンバー」をクリックし、「設定」>「エンドユーザー」を選択します。
2. 「アカウントメール」セクションの「エージェントまたは管理者によって新規ユーザーが登録されたときにも登録完了通知メールを送信する」の選択を解除します。
3. 「ユーザーが各自のパスワードを変更できるようにする」で、このオプションの選択を解除します。

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

シークレットが漏洩するなどした場合には、新しいJWT共有シークレットを発行し、ITチームまたは外部のIDプロバイダーに提供する必要があります。新しいJWT共有シークレットは、Zendesk管理センターで生成できます。この操作によって、新しいシークレットが生成され、古いシークレットが無効になります。ZendeskでSSOアカウント認証を引き続き機能させるには、新しい共有シークレットをITチームまたは外部のIDプロバイダーに通知する必要があります。

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

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

1. 管理センターで、サイドバーの「アカウント」をクリックし、「セキュリティ」>「シングルサインオン」を選択します。
2. 新しい共有シークレットを作成したいJWT設定にカーソルを合わせ、オプションメニューアイコン（）をクリックし、「編集」を選択します。
3. 設定ページの下部にある「共有シークレット」までスクロールし、「シークレットをリセットする」をクリックします。

   

   確認メッセージが表示されます。

   

4. 「シークレットをリセットする」をクリックして、リセットを確定します。

   新しい共有シークレットがプレーンテキストで表示されます。

   

5. 「コピー」をクリックして新しい共有シークレットのコピーを作成し、ITチームまたは外部のIDプロバイダーに渡します。
6. 変更を保存します。

認証方法を切り替える

なお、サードパーティのSSO認証方式を使用してZendeskでユーザーを作成および認証した後、Zendesk認証に切り替える場合、これらのユーザーにはログインに使用できるZendeskパスワードが用意されていないことに注意する必要があります。これらのユーザーには、Zendeskサインインページからパスワードをリセットしてアクセスするように案内してください。

JWTに関する補足情報

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

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

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

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

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

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

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

• JWTアルゴリズム
• Zendesk JWTエンドポイント
• JWT属性
• リモートログインURLパラメーター（return_to）
• エラー処理
• JWT実装のコード例

JWTアルゴリズム

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

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

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

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

Zendesk JWTエンドポイント

ユーザーの認証に成功すると、JWTペイロードを含むPOSTリクエストを以下のZendeskエンドポイントに送信してユーザーをリダイレクトします。

https://yoursubdomain.zendesk.com/access/jwt

ペイロードはbase 64でエンコードされ、enctype=x-www-url-encodedのHTMLフォームと同等のURLエンコードされたjwtパラメータとしてリクエスト本文に送信される必要があります。

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

https://yoursubdomain.zendesk.com/access/jwt

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

JWT属性

ハッシュ（Ruby）または辞書（Python）を使用してJWT属性を送信します。JWTはbase64でエンコードする必要があります。以下はRubyを使用した例です。

payload = JWT.encode({
   :email => "[e-mail]", :name => "Bob", :iat => Time.now.to_i, :jti => rand(2<<64).to_s
}, "Our shared secret")

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

必要な属性

属性	説明
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属性を使用します。組織名は、カンマで区切った文字列として渡す必要があります。
organization_id	Zendesk APIで使用する組織の外部ID。organizationとorganization_idの両方が指定されている場合、organizationは無視されます。 「ユーザーに複数の組織に属することを許可する」オプションが有効になっている場合、追加される組織には元の組織が付属し、セカンダリ組織とみなされます。既存のメンバーシップは削除されません。 複数の組織IDを同時に渡す場合は、代わりにorganizations_ids属性を使用します。組織IDは、カンマで区切った文字列として渡す必要があります。
phone	文字列として指定された電話番号。
tags	ユーザーに対して設定されるJSON配列のタグ。これらのタグは、ユーザープロフィール内にすでにタグがある場合、それらのタグを置き換えます。
remote_photo_url	ユーザープロフィールに設定される写真のURL。
role	ユーザーのロール。この値には、end-user、agent、またはadminを設定できます。デフォルトはend_userです。ユーザーのロールがZendesk Supportでのロールと異なる場合、Zendesk Supportでのロールが変更されます。
custom_role_id	ユーザーのロールがエージェントの場合にのみ、適用されます。
user_fields	ユーザーに設定されるカスタムユーザーフィールドキーと値のJSONハッシュ。フィールド値を設定するにはカスタムユーザーフィールドが存在する必要があります。各カスタムユーザーフィールドは、ユーザーフィールドの管理設定にあるフィールドキーで識別されます。日付の値の形式は、yyyy-mm-ddです。 カスタムユーザーフィールドキーまたは値が無効な場合、フィールドを更新すると警告を表示せずに失敗しますが、ユーザーは引き続きログインできます。カスタムユーザーフィールドの詳細については、「ユーザープロフィールへのカスタムフィールドの追加」を参照してください。 メモ：null値をuser_fields属性に指定して送信すると、対応するフィールドから既存の値が削除されます。

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

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?&return_to=https://mycompany.zendesk.com/tickets/123

3. Zendeskはこのパラメータを使用して、エージェントのチケットページを開きます。

return_toパラメータは、エージェントインターフェイスの絶対URLと、ヘルプセンターの相対URLです。

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

エラー処理

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

JWT実装のコード例

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

• https://github.com/zendesk/zendesk_jwt_sso_examples

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

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