シングルサインオンは、システム内のユーザーを認証し、そのユーザーが認証されたことをZendeskに通知する機構です。JSON Webトークン(JWT)でシングルサインオンを使用する場合、サインイン時にユーザーがアイデンティティプロバイダによって自動的に検証されます。認証済みであると通知されたユーザーは、サインイン資格情報の入力を求められることなく、Zendeskにアクセスできるようになります。
Zendesk管理者としての役割は、SSOオプションを有効にすることです。この記事では、チームメンバー(管理者と、ライトエージェントと閲覧担当を含むエージェント)、エンドユーザー、またはその両方の認証に使用できる、複数のJWTシングルサインオン設定を有効にする方法について説明します。
シングルサインオンの基幹部分は、Zendeskがシステムから取得したサインインリクエストを信頼できるようにするセキュリティメカニズムです。Zendeskがアクセスを許可するのは、認証されたユーザーのみです。Zendesk SSOはJWTを使用して、ユーザー認証データの交換を保護しています。
会社のJWT認証システムの設定と管理は、通常は会社のITチームが担当します。ITチームの役割は、システムにZendesk向けSSOを実装することです。ITチームに、この記事内の以下のトピックをご紹介ください。
関連記事
ZendeskでのJWT SSOの動作
SSOを有効にすると、サインインリクエストはZendesk Supportの外部のサインインページにルーティングされます。
JWT SSO認証プロセスの手順:
- 認証されていないユーザーがZendesk Support URLにアクセスします。例:https://yoursubdomain.zendesk.com/
- ZendeskのSSO機構が、SSOが有効になっており、かつユーザーが認証されていないことを認識します。
- Zendeskは、未認証のユーザーがエンドユーザーであるかチームメンバーであるかを判断し、そのユーザーを組織の適切なリモートサインインページにリダイレクトします。例:https://mycompany.com/zendesk/sso
- リモートサーバーのスクリプトが、組織の独自のサインインプロセスを使用してユーザーを認証します。
- 認証システムによって、関連するユーザーデータが含まれるJWTリクエストが作成されます。
- 認証システムは、JWTペイロードを持つ次のZendeskエンドポイントにユーザーをリダイレクトします。
https://yoursubdomain.zendesk.com/access/jwt
- Zendeskはトークンを検証し、JWTペイロードからユーザーの詳細なデータを解析し、ユーザーにセッションを割り当てます。
このように、このプロセスはブラウザのリダイレクトと、JWTを使用した署名付きメッセージの回送に依存しています。リダイレクトは完全にブラウザで実行されるので、Zendeskと社内のシステムの間に直接リンクは存在せず、認証スクリプトを会社のファイアウォールの内側で安全に保持できます。
JWT SSOを有効にするための要件
社内のJWT認証システムを担当するチーム(通常はITチーム)と打ち合わせを行い、Zendeskから送信されるトラフィックはHTTPではなくHTTPS経由であることを確認します。
- 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シングルサインオンを有効にするには
- 管理センターで、サイドバーの「アカウント」をクリックし、「セキュリティ」>「シングルサインオン」を選択します。
- 「SSO設定を作成する」をクリックし、「JSON Webトークン」を選択します。
- 一意の構成名を入力します。
- 「リモートログインURL」に、Zendesk URLへのアクセスを試みるユーザーのリダイレクト先のURLを入力します。
brand_idパラメータが自動的にURLに追加されます。サインインを試みたときにユーザーが訪問していたZendesk Supportブランドを示します。
- (オプション)「リモートログアウト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/
- (オプション)「IPアドレス範囲」には、ユーザーを適切なサインインオプションにリダイレクトするためのIPアドレス範囲を列挙して入力します。
指定されたIPアドレス範囲から要求を行ったユーザーは、JWT認証サインインフォームにルーティングされます。指定されたIPアドレス範囲外から要求を行ったユーザーは、通常のZendeskのサインインフォームにルーティングされます。すべてのユーザーがJWT認証のサインインフォームにリダイレクトしたい場合は、アドレス範囲を指定しないでください。
- ユーザーに対して外部IDを使用している場合は、「外部IDの更新を許可しますか?」に対して「オン」を選択すると、Zendesk Support内で外部IDを更新できます。
- ITチームに共有シークレットを提供します。チームがJWTを実装する際に必要になります。重要:共有シークレットのセキュリティを保護してください。セキュリティが侵害された場合、あなたのSupportアカウントのすべてのデータが危険にさらされます。
- 「ユーザーのサインイン時にボタンを表示」を選択し、Zendeskサインインページに「SSOで続行」ボタンを追加します。
「ボタン名」フィールドに値を入力することで、ボタンラベルをカスタマイズできます。カスタムボタンラベルは、サインインページに複数のSSOボタンを追加する場合に便利です。詳細については、「「SSOで続行」ボタンをZendeskサインインページに追加する」を参照してください。
- 「保存」をクリックします。
デフォルトでは、エンタープライズSSO構成は非アクティブです。SSO構成をアクティブにするには、ユーザーに割り当てる必要があります。
ユーザーへのJWT SSOの割り当て
JWT SSO設定を作成したら、エンドユーザーかチームメンバー、またはその両方に割り当てることでSSO設定をアクティブにする必要があります。
SSO設定をチームメンバーまたはエンドユーザーに割り当てるには
- チームメンバーまたはエンドユーザーのセキュリティ設定を開きます。
- 認証オプションを表示するには、「外部認証」を選択します。
- 使用するSSO設定の名前を選択します。
シングルサインオンですべてのユースケースがカバーされるわけではないため、Zendesk認証はデフォルトで有効のままとなっています。
- ユーザーにサインインを許可する方法を選択します。
「エンドユーザーが選択」の場合、ユーザーはアクティブな認証方法を使用してサインインすることができます。詳しくは「ユーザーに提供するZendeskへのさまざまなサインイン方法」を参照してください。
「SSOにリダイレクト」では、プライマリのSSO構成を使用した認証のみになります。これらの認証オプションがアクティブであっても、ユーザーには追加のサインインオプションが表示されません。「SSOにリダイレクト」を選択すると、プライマリSSO設定を選択するための「プライマリSSO」フィールドが表示されます。
- 「保存」をクリックします。
JWT SSOを有効にした後のZendeskでのユーザーの管理
ZendeskでJWTシングルサインオンを有効にした場合、Zendesk外でユーザーに加えた変更はZendeskアカウントと自動的に同期されません。ユーザーは認証された時点でZendeskで更新されます。たとえば、社内のシステムにユーザーを追加すると、そのユーザーはZendeskにサインインした時点でZendeskアカウントに追加されます。社内システムでユーザーが削除された場合、そのユーザーはZendeskにサインインできなくなります。ただし、アカウントはZendeskに残されます。
デフォルトでは、シングルサインオンが有効になっている場合にZendeskに保存される唯一のユーザーデータは、ユーザーの名前とメールアドレスです。Zendesk内にパスワードは保管されません。このため、パスワードに関するZendeskからの自動メール通知はすべてオフにする必要があります。
より良いカスタマーエクスペリエンスを提供するために、ユーザーの名前とメールアドレス以外の情報もZendeskに保存することができます。これを行うには、追加のJWT属性を使用します。
Zendeskからのパスワード通知メールをオフにする
SAML、JWT、またはOpenID Connect(OIDC)のいずれかのシングルサインオンを使用してZendeskアカウントにアクセスしたすべての新規ユーザーに、ユーザープロフィールが作成されます。これらのユーザーはZendesk以外のパスワードを使用するIdPによって認証されるため、Zendeskに直接サインインする必要がありません。このため、パスワードなしでプロフィールが作成されます。
SSOを使ってZendeskにサインインした新規ユーザーは、IdPによって認証されるため、アカウント確認のメール通知を受け取ることはありません。ただし、IdPがユーザーを確認できなかった場合にメール通知が自動送信されないよう、これらの自動メール通知をオフにすることが推奨されます。SSOを使用する場合、ユーザー認証は常にIdPによって行われなければなりません。
パスワード通知メールをオフにするには
- 管理センターで、サイドバーのメンバーアイコン()をクリックし、「設定」>「エンドユーザー」を選択します。
- 「アカウントメール」セクションの「エージェントまたは管理者によって新規ユーザーが登録されたときにも登録完了通知メールを送信する」の選択を解除します。
- 「ユーザーが各自のパスワードを変更できるようにする」で、このオプションの選択を解除します。
共有シークレットの新規作成
シークレットが漏洩するなどした場合には、新しいJWT共有シークレットを発行し、ITチームまたは外部のIDプロバイダーに提供する必要があります。新しいJWT共有シークレットは、Zendesk管理センターで生成できます。この操作によって、新しいシークレットが生成され、古いシークレットが無効になります。ZendeskでSSOアカウント認証を引き続き機能させるには、新しい共有シークレットをITチームまたは外部のIDプロバイダーに通知する必要があります。
共有シークレットを新規作成するには
- 管理センターで、サイドバーの「アカウント」をクリックし、「セキュリティ」>「シングルサインオン」を選択します。
- 新しい共有シークレットを作成したいJWT設定にカーソルを合わせ、オプションメニューアイコン()をクリックし、「編集」を選択します。
- 設定ページの下部にある「共有シークレット」までスクロールし、「シークレットをリセットする」をクリックします。
確認メッセージが表示されます。
- 「シークレットをリセットする」をクリックして、リセットを確定します。
新しい共有シークレットがプレーンテキストで表示されます。
- 「コピー」をクリックして新しい共有シークレットのコピーを作成し、ITチームまたは外部のIDプロバイダーに渡します。
- 変更を保存します。
認証方法を切り替える
サードパーティのSSOメソッドを使用してZendeskでユーザーを作成および認証した後、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実装について詳しく説明します。
次のトピックについて説明します。
JWTアルゴリズム
JWTペイロードのヘッダーにJWTアルゴリズムとして、次のようにHS256を指定します。
{
"typ":"JWT",
"alg":"HS256"
}
HS256は、HMAC SHA 256を表します。これは、アメリカ国家安全保障局によって開発された256ビットの暗号化アルゴリズムです。
Zendesk JWTエンドポイント
ユーザーの認証に成功したら、JWTペイロードを作成し、JWTペイロードを含むPOSTリクエストを以下のZendeskエンドポイントに送信します。
https://yoursubdomain.zendesk.com/access/jwt
ペイロードはbase64でエンコードされ、クライアントからのフォーム送信によって送信される必要があります。クライアント側のAJAX、フェッチ、またはaxiosリクエストでペイロードを送信しても、クライアントの同一生成元ポリシーによってリクエストがブロックされるため、機能しません。サーバーからPOSTリクエストを行っても、ユーザーのブラウザで認証に使われるcookieが正しく設定されないため、機能しません。
JWTペイロードは、httpsプロトコルを使用してZendesk Supportサブドメインに送られる必要があります。以下に例を示します。
https://yoursubdomain.zendesk.com/access/jwt
ホストマッピングされたサブドメインはサポートされません。
JWT属性
ハッシュ(Ruby)または辞書(Python)を使用してJWT属性を送信します。JWTはbase64でエンコードする必要があります。以下は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の間で同期がとられます。
属性 | データのタイプ | 説明 |
---|---|---|
iat | 数字で表記した日付 | 発行時刻。トークンが生成された時刻。指定されたトークンが生成直後に確実に使用されるようにするために使用されます。この値は、UNIXエポックから経過した秒数である必要があります。Zendeskでは、最大3分のクロックスキューが許容されているため、必ずNTPまたは同様のプロトコルをサーバーに設定してください。 |
jti | 文字列 | JSON WebトークンのID。トークン反射攻撃を防御するためのトークンの一意のIDです。 |
文字列 | ユーザーが登録しているメールアドレス。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 | 文字列 | 文字列として指定された電話番号。 電話番号は、国際的なE.164電話番号計画に準拠する必要があります。例:+15551234567 E164番号とは、国番号、地域番号、加入者番号が付加された国際番号です。有効なE.164電話番号には、国際電話番号が含まれていなければなりません。 |
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。フローは次のとおりです。
- クリックすると、ZendeskはユーザーをリモートログインURLにリダイレクトし、次の
return_to
パラメータをURLに追加します。https://mycompany.com/zendesk/sso?return_to=https://mycompany.zendesk.com/tickets/123
- 認証システムはURLから
return_to
パラメータを受け取り、ユーザーの認証に成功すると、そのパラメーターをZendesk JWTエンドポイントに追加するか、リクエストの本文に追加します。以下に例を示します。https://mycompany.zendesk.com/access/jwt?&return_to=https://mycompany.zendesk.com/tickets/123
- Zendeskはこのパラメータを使用して、エージェントのチケットページを開きます。
return_to
パラメータは、エージェントインターフェイスの絶対URLと、ヘルプセンターの相対URLです。
return_to
アドレスに独自のURLパラメータが含まれている場合は、JWTトークンを送信する際に、スクリプトによってreturn_to値全体がURIでエンコードされるようにしてください。エラー処理
JWTログイン要求の処理中にエラーが発生した場合、発生した問題について説明するメッセージが表示されます。JWTインテグレーションの設定時にリモートログアウトURLを指定した場合は、そのURLにリダイレクトされ、メッセージとkindパラメータが渡されます。エラーが発生した場合、kindパラメータの値は常に"error"となります。リモートログアウトURLを設定し、Zendeskからのメッセージとエラーのタイプを記録することをお勧めします。発生しうるエラーの多くは、修正が必要なエラーです。たとえば、クロックのドリフト、レート制限超過、無効なトークンなどのエラーなどです。
フォーム提出例
JWTペイロードは、フォーム送信を使用してブラウザから以下のZendeskエンドポイントに送信する必要があります。
https://yoursubdomain.zendesk.com/access/jwt
Zendeskは、GitHubのZendesk JWT SSOリポジトリで、さまざまなテクノロジースタックの一連の例を提供しています。ブラウザ上でCookieが正しく設定され、リクエストがCORSによってブロックされないように、ブラウザからフォーム送信を使用してJWTペイロードを送信する必要があります。
レスポンス
レスポンスは200 OK
ステータスのHTMLである必要があります。レスポンスのフォーマットを次に示します。
<html><body>You are being <a href="">redirected</a>.</body></html>
href
がreturn_to
値と一致する場合、ユーザーは正常に認証され、cookieが設定されます。href
がhttps://SUBDOMAIN.zendesk.com/access/unauthenticated
で始まる場合、Zendeskはユーザーを認証できていません。
JWTの生成例
実際のJWTエンコーディングは非常に簡単で、ほとんどの最新の言語にはそれに対応したライブラリが用意されています。Zendeskでは、次のJWT SSO GitHubリポジトリで各種スタックに対応したコード例を多数公開しています。
JWT生成コードはサーバー実装用です。生成されたJWTをログインページに戻し、ブラウザからフォーム送信を開始することができます。
その他のスタックでJWTを実装する場合に、コード例をお寄せいただければ幸いです。この記事にコメントを付けることで、お客様の実装例を共有できます。
IISまたはADを実行していて、.NETソリューションの構築を希望しないお客様のために、Zendeskでは、Classic ASPでの完全な実装を提供いたします。この実装では、いくつかの変数を調整するだけで済みます。GitHubからASP認証スクリプトをダウンロードします。