ヘルプセンター
ヘルプセンター

JWT認証を利用して限定公開する

読了時間：約 21 分

自社の会員サイトや社内ポータルにログイン済みの利用者に対して、ヘルプドッグ側でアカウントを作成せずに限定公開コンテンツを表示できます。自社システムで発行されたJWTトークンを使って認証を行い、ログイン状態を引き継いだままFAQサイト・問い合わせフォーム・AIチャットボットをご利用いただけます。

どんなことができる？

JWT認証を使うと、自社システムにログイン済みの利用者が、追加のログイン操作なしでヘルプドッグの限定公開コンテンツにアクセスできるようになります。

  • シングルサインオン: 自社システムにログインするだけで、FAQサイト・問い合わせフォーム・AIチャットボットにもそのままアクセスできます

  • 自動アカウント作成: 初回アクセス時に読者アカウントが自動作成されます。事前の登録作業は不要です

  • グループ単位のアクセス制御: JWT認証設定ごとに読者グループが自動作成され、限定公開コンテンツの閲覧対象をグループ単位で管理できます

メリット

  • パスワードの二重管理が不要になり、利用者の負担を軽減できます

  • ヘルプドッグへのアカウント手動登録が不要で、運用の手間を削減できます

  • 自社の認証基盤をそのまま活用できるため、セキュリティポリシーを統一できます

ご利用条件

項目

内容

対象プラン

エンタープライズ プロフェッショナル

必要な権限

チームオーナー

前提条件

JWT認証をご利用いただくには、自社システムにてJWTを発行するための 開発対応 が必要です。

設定手順

1. JWT認証設定を作成する

チーム設定 > 高度な認証 > JWT認証 を開き、「JWT認証を追加」ボタンをクリックします。

チーム設定＞高度な認証＞JWT認証

2. 基本設定を行う

以下の項目を入力します。

項目

説明

必須

JWT認証名

管理用の名前です。読者グループ名としても利用されます（最大50文字）

はい

ステータス

このJWT認証の有効/無効を切り替えます

はい

メモ

管理用のメモを入力できます（最大1,000文字）

いいえ

JWT認証の作成・編集

3. ログインボタンとURLを設定する

ステータスを「有効」にした場合、以下の項目の入力が必要です。

項目

説明

ログインボタンのテキスト

ログインページに表示されるボタンのテキストです（最大30文字）

リモートログインURL

ボタンをクリックした際にリダイレクトする自社のログインURLです

設定が完了したら「保存」をクリックします。

4. シークレットキーを発行する

「共有シークレットキー」セクションで「シークレットキーを追加」をクリックします。

発行されると、以下の2つの値が表示されます。

項目

説明

キーID（kid）

JWTヘッダーの kid に指定する値です

JWT署名用共有シークレットキー

JWTの署名に使用する秘密鍵です

重要: シークレットキーはこの画面を閉じると再表示できません。必ずコピーして安全に保管してください。

発行されたキーIDとシークレットキーは、JWT発行処理の実装時に必要になります。

共有シークレットキーの発行

5. JWT発行処理を実装する

自社システムに、以下の仕様でJWTの発行とヘルプドッグへの送信処理を実装してください。

全体の流れ

  1. 利用者がヘルプドッグのログインページで「ログイン」ボタンをクリックすると、リモートログインURLにリダイレクトされます。このとき、URLのクエリパラメータに helpdog_login_url が付与されます

  2. 自社システムで helpdog_login_url の値を取得・保持し、利用者を認証します

  3. 認証完了後、JWTを発行し、helpdog_login_url のURLに対してフォームPOSTで送信します

リモートログインURLに付与されるパラメータ

利用者がリダイレクトされる際、リモートログインURLに以下のクエリパラメータが付与されます。

パラメータ

説明

helpdog_login_url

ヘルプドッグの検証エンドポイントURL（state を含む）です。JWTの送信先として使用します

例: https://auth.example.com/login?helpdog_login_url=https%3A%2F%2F...%2Fauth%2Fjwt%2Fverify%3Fstate%3DeyJhbGci...

自社システムでは、このパラメータの値を取得して保持してください。利用者の認証完了後、このURLに対してJWTを送信します。

注意: helpdog_login_url の値はURLエンコードされています。多くのWebフレームワークではクエリパラメータ取得時に自動的にデコードされますが、手動でURLを解析する場合はデコードしてから使用してください。

JWTの仕様

ヘッダー

項目

値

alg

HS256

typ

JWT

kid

ヘルプドッグで発行されたキーID

ペイロード

クレーム

必須

説明

iat

はい

トークンの発行日時（UNIXタイムスタンプ、秒単位）。発行から5分以内のトークンのみ有効です

email

はい

利用者のメールアドレス。読者アカウントの特定・自動作成に使用されます

first_name

いいえ

利用者の名。読者アカウントの情報として保存されます

last_name

いいえ

利用者の姓。読者アカウントの情報として保存されます

署名: ヘルプドッグで発行されたシークレットキーを使用して、HS256（HMAC-SHA256）アルゴリズムで署名してください。

JWT生成のサンプルコード

以下は各言語でのJWT生成例です。

注意: JWTの生成は必ずサーバーサイドで行ってください。シークレットキーをフロントエンド（ブラウザ側）のコードに含めると、第三者にJWTを偽造されるおそれがあります。シークレットキーは環境変数に設定し、ソースコードに直接記述しないようにしてください。

Ruby（ruby-jwt）

require 'jwt'

secret_key = ENV.fetch('HELPDOG_JWT_SECRET_KEY')
kid = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' # ヘルプドッグで発行されたキーID

payload = {
iat: Time.now.to_i,
email: '[email protected]',
first_name: '太郎',
last_name: '山田'
}

token = JWT.encode(payload, secret_key, 'HS256', { typ: 'JWT', kid: kid })

PHP（firebase/php-jwt）

use Firebase\JWT\JWT;

$secretKey = getenv('HELPDOG_JWT_SECRET_KEY');
$kid = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'; // ヘルプドッグで発行されたキーID

$payload = [
'iat' => time(),
'email' => '[email protected]',
'first_name' => '太郎',
'last_name' => '山田',
];

$token = JWT::encode($payload, $secretKey, 'HS256', $kid);

JavaScript / Node.js（jsonwebtoken）

const jwt = require('jsonwebtoken');

const secretKey = process.env.HELPDOG_JWT_SECRET_KEY;
const kid = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'; // ヘルプドッグで発行されたキーID

const token = jwt.sign(
{
iat: Math.floor(Date.now() / 1000),
email: '[email protected]',
first_name: '太郎',
last_name: '山田',
},
secretKey,
{ algorithm: 'HS256', header: { typ: 'JWT', kid: kid } }
);

Python（PyJWT）

import jwt
import time
import os

secret_key = os.environ['HELPDOG_JWT_SECRET_KEY']
kid = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' # ヘルプドッグで発行されたキーID

payload = {
'iat': int(time.time()),
'email': '[email protected]',
'first_name': '太郎',
'last_name': '山田',
}

token = jwt.encode(payload, secret_key, algorithm='HS256', headers={'typ': 'JWT', 'kid': kid})

Go（golang-jwt）

package main

import (
"os"
"time"

"github.com/golang-jwt/jwt/v5"
)

func generateToken() (string, error) {
secretKey := []byte(os.Getenv("HELPDOG_JWT_SECRET_KEY"))
kid := "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" // ヘルプドッグで発行されたキーID

claims := jwt.MapClaims{
"iat": time.Now().Unix(),
"email": "[email protected]",
"first_name": "太郎",
"last_name": "山田",
}

token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
token.Header["typ"] = "JWT"
token.Header["kid"] = kid

return token.SignedString(secretKey)
}

ヘルプドッグへの送信

利用者の認証が完了したら、helpdog_login_url で受け取ったURLに対してJWTをフォームPOSTで送信してください。

パラメータ

送信方法

必須

説明

jwt

フォームボディ

はい

自社システムで発行した署名済みJWTトークン

state

クエリパラメータ（helpdog_login_url に含まれています）

はい

改変せず、そのまま使用してください

実装例（HTML + JavaScript）

利用者の認証が完了したページで、以下のようにフォームPOSTを自動送信します。helpdog_login_url の値をそのまま action に指定してください。

<form id="helpdog-jwt-form" method="POST" action="{helpdog_login_urlの値}">
<input type="hidden" name="jwt" value="{自社システムで発行したJWTトークン}" />
</form>
<script>document.getElementById("helpdog-jwt-form").submit();</script>

送信が成功すると、ヘルプドッグ側で自動的に利用者のブラウザがリダイレクトされ、限定公開コンテンツにアクセスできるようになります。

6. コンテンツの限定公開を設定する

JWT認証でアクセスを制限したいサイト・フォーム・ウィジェットの公開設定で、以下を行います。

  1. 公開範囲を「限定公開」に設定する

  2. 「社内システムや会員ログインを使って閲覧を許可する」セクションで、作成したJWT認証を有効にする

公開範囲の設定方法については、公開範囲を設定する をご覧ください。

7. 動作確認をする

JWT認証一覧画面の「JWT認証をテスト」ボタンをクリックすると、検証モーダルが表示されます。

発行したJWTトークンの文字列を貼り付けて「JWTを検証」をクリックすると、以下を確認できます。

  • トークンのフォーマットが正しいか

  • 署名が正しいか

  • 利用者情報（クレーム）が正しく読み取れるか

検証に成功すると、デコードされたヘッダーとペイロードが表示されます。エラーが表示された場合は、エラーメッセージの内容に従って修正してください。

利用者のログインの流れ

自社システムヘルプドッグ利用者自社システムヘルプドッグ利用者

  1. 利用者が限定公開コンテンツ（サイト、フォーム、ウィジェット）にアクセスします

  2. ログインページが表示され、JWT認証用のログインボタンが表示されます

  3. ボタンをクリックすると、自社のログインページ（リモートログインURL）に helpdog_login_url パラメータ付きで遷移します

  4. 自社システムで helpdog_login_url の値を取得・保持し、利用者を認証します

  5. 認証完了後、JWTを発行し、helpdog_login_url のURLに対してフォームPOSTで送信します

  6. ヘルプドッグがJWTを検証し、問題なければ利用者のブラウザが自動的にリダイレクトされ、限定公開コンテンツを閲覧できるようになります

読者グループの自動割り当て

JWT認証設定を作成すると、読者グループが自動的に作成されます。

  • グループ名はJWT認証名と同じです（JWT認証名を変更すると、グループ名も自動的に更新されます）

  • JWT認証を通じてログインした利用者は、自動的にこのグループに追加されます

  • このグループを使って、サイト・フォーム・ウィジェットの限定公開対象を制御できます

  • 割り当て先のグループを変更することはできません

読者グループの詳細については、読者・読者グループの管理 をご覧ください。

シークレットキーのローテーション

シークレットキーの定期的な入れ替え（ローテーション）に対応しています。以下の手順で安全に鍵を入れ替えられます。

  1. 「シークレットキーを追加」で新しいシークレットキーを発行する

  2. 新しいキーIDとシークレットキーを使って、JWT発行処理を更新する

  3. 「JWT認証をテスト」で、新しい鍵で発行されたJWTが正しく検証できることを確認する

  4. 古いシークレットキーを「無効にする」で無効化する

  5. 古い鍵が使われなくなったことを確認後、削除する

1つの認証設定に対して最大10個のシークレットキーを登録でき、複数を同時に有効にできます。旧キーと新キーを一定期間併用する運用も可能です。

よくある質問

Q. JWT認証はどのような用途に向いていますか？

独自のログイン基盤やID管理システムをお持ちで、そのログイン状態を引き継いでFAQサイト・問い合わせフォーム・AIチャットボットを利用させたい場合に向いています。ECサイトの会員向けFAQや、自社プロダクトに組み込んだヘルプページなどが代表的な用途です。

Q. 利用者のアカウントを事前に登録する必要がありますか？

いいえ、JITプロビジョニング（自動アカウント作成）がデフォルトで有効になっているため、利用者がJWT認証で初めてアクセスした際に読者アカウントが自動作成されます。事前の登録作業は不要です。

Q. シークレットキーを紛失した場合はどうすればよいですか？

シークレットキーは発行時のみ確認できます。紛失した場合は新しいシークレットキーを発行してください。古いキーを無効化し、新しいキーIDとシークレットキーでJWT発行処理を更新することで、シークレットキーのローテーションが可能です。

Q. JWT認証設定を削除するとどうなりますか？

認証設定を削除すると、紐づく読者グループも削除されます。ただし、その読者グループがサイト・フォーム・ウィジェットの限定公開の対象として使用されている場合は削除できません。先に公開設定からグループの指定を解除してから削除してください。

Q. メールアドレス認証とJWT認証は併用できますか？

はい、同じコンテンツに対してメールアドレス認証とJWT認証の両方を有効にできます。利用者はログインページでいずれかの認証方法を選択してアクセスします。

Q. テナントやシステムごとにログインURLが異なる場合はどうすればよいですか？

1つのJWT認証設定に登録できるリモートログインURLは1つだけです。利用者が所属するテナントやシステムによってログインURLが分かれている場合は、次の2通りの方法があります。

方法1: 共通のログインポータルで振り分ける

ログインボタンを1つにまとめたい場合におすすめです。自社側に 共通のログインポータル（振り分け用の中継ページ） を1つ用意し、そのURLをリモートログインURLに設定します。ポータルでは以下の処理を行います。

  1. ヘルプドッグから付与される 「helpdog_login_url」 パラメータを受け取り、値を保持します

  2. ポータル側で利用者を認証し、所属するテナントの正しいログインURLへ振り分けます。このとき 「helpdog_login_url」 の値を 変えずにそのまま 引き継いでください

  3. 認証完了後、JWTを発行し、保持しておいた 「helpdog_login_url」 のURLへフォームPOSTで送信します（送信方法は通常と同じです）

ポイントは、振り分けの過程で 「helpdog_login_url」（state を含む）を最後まで引き継ぐことです。「helpdog_login_url」 はURLエンコードされているため、別ページのクエリパラメータとして渡す際はエンコードが崩れないようご注意ください。

方法2: テナントごとにJWT認証設定を分ける

テナントごとに読者グループ（アクセス範囲）を分けたい場合は、テナントの数だけJWT認証設定を作成し、それぞれにリモートログインURLを設定します（1チームあたり最大10個まで）。この場合、ログインページにはテナントの数だけログインボタンが並び、利用者は自分のテナントのボタンを選んでログインします。

Q. JWTの有効期限はどのくらいですか？

JWTトークンは発行日時（iat）から5分以内のみ有効です。5分を超えたトークンは検証に失敗します。トークンはアクセスのたびにリアルタイムで発行するように実装してください。

Q. トークン検証でエラーが出た場合はどうすればよいですか？

検証モーダルに表示されるエラーメッセージを確認してください。主なエラーと対処法は以下のとおりです。

エラーメッセージ

対処法

フォーマットが不正です

JWTの生成処理が正しいか確認してください

ヘッダー（alg）には "HS256" を設定してください

署名アルゴリズムをHS256に変更してください

ペイロードに必須項目（email）がありません

JWTペイロードにemailクレームを追加してください

有効期限が切れています

新しいJWTを生成して検証してください

キーID（kid）が不正です

正しいキーIDが設定されているか確認してください

署名キーが一致しません

正しいシークレットキーで署名されているか確認してください

注意事項

  • JWT認証のご利用には、自社システムでJWTを発行するための 開発対応が必要 です

  • 1チームあたりのJWT認証設定数は最大10個です

  • シークレットキーは発行時のみ表示されます。画面を閉じる前に必ずコピーして安全に保管してください

  • シークレットキーを無効化・削除すると、そのキーを使用した認証は即座に失敗します。新しいキーへの切り替えが完了してから、古いキーを無効化・削除してください

  • JWTトークンは発行から5分以内のみ有効です。アクセスのたびにリアルタイムで発行するように実装してください

このページはお役に立ちましたか？
Helpdog ヘルプドッグ

ヘルプドッグ を利用しています