HENNGE One
HENNGE Oneを業務アセットとして接続すると、HENNGE Access Controlのユーザーを管理できます。接続に使う情報、同期する項目、主なエラーと対処をまとめています。
概要
HENNGE Oneは、HENNGE株式会社が提供するクラウドセキュリティサービスです。Identity Edition、DLP Edition、Cybersecurity Editionの3つのエディションがあります。それぞれ使用できる機能が異なります。
この接続では、HENNGE OneのID管理機能にあたるHENNGE Access Controlのアカウントを管理します。
| 参照先 | リンク |
|---|---|
| 公式HP | HENNGE株式会社 |
| 開発者向けポータル | HENNGE Developers |
| APIドキュメント | About HENNGE Access Control API |
管理できること
| 項目 | 備考 |
|---|---|
| アカウント管理 | アカウントの作成・無効化、属性同期による属性更新、パスワード設定 |
| ロール、アクセスポリシーグループ、許可するサービスプロバイダーの管理 | 割当の付与・剥奪 |
管理対象
ユーザーをアカウントとして管理します。HENNGE Access Control管理画面の「ユーザー一覧」ページに表示されるものがユーザーです。
次の3つを割当として管理します。
| 割当 | 説明 |
|---|---|
| アクセスポリシーグループ | 認証の設定やSSOで許可するサービスを定義するグループ |
| ロール | 管理画面での操作権限を制御するロール |
| 許可するサービスプロバイダー | アクセスポリシーグループとは別に、ユーザー個別にSSOアクセスを許可するサービス |
割当の内容はHENNGE Access Control管理画面で確認できます。アクセスポリシーグループは「アクセスポリシーグループ」メニュー、「アクセス設定」と「許可するサービスプロバイダー」はユーザー詳細画面に表示されます。
接続に使う情報
OAuth 2.0認証を使います。HENNGE Access Control管理画面で発行したAPIクライアントのClient IDとClient Secretで接続します。
| 入力項目 | 必須 | 入力する内容 |
|---|---|---|
| 「クライアントID」 | 必須 | HENNGE Access Control管理画面で発行したAPIクライアントのClient ID |
| 「クライアントシークレット」 | 必須 | 同じAPIクライアントのClient Secret |
接続の準備
HENNGE Access Control側でAPIクライアントを作成し、Client IDとClient Secretを発行します。
-
HENNGE Access Control管理画面にアクセスします。
-
「API クライアント」メニューに移動します。
-
「クライアント追加」から「HAC API」をクリックします。
-
スコープを設定します。 設定する内容は「必要な権限」を参照してください。
-
「Description」を入力します。
-
「保存」をクリックします。 Client IDとClient Secretが表示されます。
-
表示されたClient IDとClient Secretを控えます。
必要な権限
APIクライアントに設定するスコープは、「ロール」割当でユーザー以外の割当項目を割り当てるかどうかによって異なります。
ユーザー以外の割当項目を割り当てない場合は、次のスコープを設定します。
| スコープ | 権限 | 用途 |
|---|---|---|
| ユーザー一覧 | 読み込み/書き込み | ユーザーの作成・更新・無効化・パスワード設定、アクセスポリシーグループ・許可するサービスプロバイダーの割当 |
| アクセスポリシーグループ | 読み込み専用 | アクセスポリシーグループ一覧の取得 |
| サービスプロバイダー設定 | 読み込み専用 | サービスプロバイダー一覧の取得 |
グローバル管理者や読み取り専用管理者など、ユーザー以外のロールを割り当てる場合は、上記のスコープに代えて次のスコープを設定します。
| スコープ | 権限 | 用途 |
|---|---|---|
| 全てのAPI | 読み込み/書き込み | 上記すべての操作に加え、ユーザー以外のロールの割当・剥奪 |
ロールの割当には「全てのAPI」の「読み込み/書き込み」が必要です。個別のスコープをすべて「読み込み/書き込み」に設定しても、タスクの実行中に権限不足でエラーが発生します。
アカウントの作成
HENNGE Access Control上に同一のユーザー名のアカウントがあるかどうかで、動作が変わります。
| 条件 | 動作 |
|---|---|
| 同一ユーザー名のアカウントがない | アカウントを新規作成します |
| 同一ユーザー名の有効なアカウントがある | そのアカウントの情報を更新します |
| 同一ユーザー名の無効化されたアカウントがある | そのアカウントを有効にして情報を更新します |
ユーザー名はHENNGE Access Control上のアカウントの一意識別子です。作成後は変更できません。既定では、YESODのメンバーのメールアドレスの@より前の部分を使います。
パスワードの設定に対応しています。パスワードなしでもアカウントは作成できます。その場合は、HENNGE Access Control管理画面からパスワードリセットを実行するか、パスワードレスのデバイス証明書を発行してください。
パスワードの決め方は、業務アセットの「アカウント設定」にある「初期パスワード」で設定します。パスワードの既定の式はPassword.generate(12, 16, 1, 3, 1, 3)です。
アカウントの削除
アカウントの削除タスクでは、アカウントの無効化を実行します。無効化したアカウントは、HENNGE Access Control管理画面のユーザー一覧画面で状態が「無効」と表示されます。
割当種別
| 割当種別名 | タイプ | 割当項目の例 | 備考 |
|---|---|---|---|
| アクセスポリシーグループ | Priority | DEFAULT、営業部ポリシー、開発部ポリシー など | 1ユーザーに1グループのみ割り当てられます |
| ロール | Priority | 「ユーザー」、「グローバル管理者」、「読み取り専用管理者」、「セキュアブラウザ管理者」、「証明書管理者」、「証明書 および セキュアブラウザ管理者」 | 1ユーザーに1ロールのみ割り当てられます |
| 許可するサービスプロバイダー | Multiple | Google Workspace、Microsoft 365、Salesforce など | アクセスポリシーグループとは別に、ユーザー個別にSSOアクセスを許可するサービスです。複数指定できます |
同期する項目
| 必須 | 項目 | キー | 型 | 既定の式 | 備考 |
|---|---|---|---|---|---|
| 必須 | ユーザー名 | user.username | String | String.substringBefore(user.email, "@") | アカウントの一意識別子です。作成後は変更できません |
| 必須 | メールアドレス | user.email | String | user.email | — |
| — | 表示名 | user.display_name | String | user.familyNameLocalPreferred + ' ' + user.givenNameLocalPreferred | — |
| 条件付き | 姓 | user.family_name | String | user.familyNameLocalPreferred | 姓・名の少なくとも片方には値が必要です。両方が空になる場合、作成・同期は失敗します |
| 条件付き | 名 | user.given_name | String | user.givenNameLocalPreferred | 姓・名の少なくとも片方には値が必要です。両方が空になる場合、作成・同期は失敗します |
| — | パスワード変更ポリシー | user.password_change_policy | String | — | default、never-expires、must-changeのいずれかです |
| — | Googleプロビジョニング対象外かどうか | user.exclude_from_google_provisioning | Boolean | — | trueに設定すると、Googleプロビジョニングの対象外になります |
| — | パスワードリセットメールアドレス | user.password_reset_email | String | — | セルフパスワードリセットに使うメールアドレスです |
| — | カスタム属性 | user.custom_attributes.<カスタム属性のID> | String | — | カスタム属性のIDは、HENNGE Oneで定義済みのIDと完全に一致させてください。未定義のIDを1つでも指定すると、作成・同期は失敗します。詳細はカスタム属性概要を参照してください |
対応していない項目
HENNGE Oneのアカウント項目のうち、次の項目には対応していません。
| 項目名 | 説明 | 対応していない理由 |
|---|---|---|
| OTPタイプ | 認証時にワンタイムパスワードを使って2段階認証を実施するための設定 | 更新するAPIはありますが、途中でユーザーによる確認が必要であるなど、YESODの現状の属性同期の仕様と相性が悪いためです |
| 非常用OTPトークン | パスワードを忘れた際に非常用の認証手段として使用できる使い切りのパスワード | 使い切りのため一度使用すると消滅する一方、YESODの属性同期では同期のたびに使用済みのトークンが新たに発行される動作になり、相性が悪いためです |
| このユーザーを Microsoft との同期の対象外にする | ユーザーのMicrosoftとの同期を無効化する設定 | 更新するAPIが用意されていないためです |
| デバイス証明書 | 特定のデバイスでのみアカウントを使用できるようにするための仕組み | APIはありますが、属性同期の仕様と相性が悪いためです |
グループプッシュ
グループプッシュには対応していません。
制限事項
レートリミット
HENNGE One APIには、プランに応じたレートリミットが設定されています。
| プラン | 制限 |
|---|---|
| HENNGE One Pro / HENNGE IdP Pro | 10秒あたり1000回の呼び出し |
| HENNGE One Basic / HENNGE IdP | 10分あたり10回の呼び出し |
レートリミットに達すると自動的にリトライしますが、一定回数リトライしても解消しない場合はエラーになります。
Basicプランはレートリミットが厳しく設定されています。ユーザー数が多い場合、タスクの実行や属性同期に時間がかかります。属性同期や「タスク一覧」画面で複数のタスクにチェックを入れて実行した場合は、可能な限りまとめて1回のAPIの呼び出しで処理します。処理時間が気になる場合は、チェックを入れてまとめて実行してください。
一括処理時のエラーの扱い
複数のメンバーをまとめて処理するとき、送信したメンバーのうち1名でもHENNGE Oneに受け付けられないデータを含んでいるとします。この場合、同じまとまりで送信した他の正常なメンバーの処理まで失敗することがあります。属性同期と、「タスク一覧」画面で複数のタスクにチェックを入れてまとめて実行する場合が該当します。まとめて送ったデータのいずれかに不備があると、HENNGE One側が呼び出し全体を受け付けないためです。
HENNGE One側の入力チェックで拒否されるのは、次のようなデータです。
- ユーザー名やメールアドレスが、HENNGE One上の別のアカウントと重複している
- HENNGE One上に存在しないユーザーを更新しようとした
- 「同期する項目」で、HENNGE Oneに定義されていないカスタム属性のIDを指定している
この場合は、失敗したメンバーのデータを修正してから再度実行すると、正常に処理されます。どのメンバーのどのデータに問題があるかは、エラーメッセージで確認してください。
なお、姓・名を両方とも空にしている場合や、属性式の評価に失敗している場合など、YESODがHENNGE Oneへ送信する前に検出できるエラーもあります。これらのエラーは対象のメンバーだけを失敗とし、他のメンバーは巻き込みません。
主なエラーと対処
タスクの実行、属性同期、業務アセットの接続で発生する主なエラーをまとめています。表の（ユーザー名）（リセット時刻）（ステータスコード）の部分には、実際には対象の値が入ります。
接続・認証に関するエラー
| メッセージ | 発生している事象 | 対処 |
|---|---|---|
| 「Client IDが設定されていません」 | 接続情報にClient IDが入力されていないため、接続を確立できません | 接続設定で「クライアントID」を入力します |
| 「Client Secretが設定されていません」 | 接続情報にClient Secretが入力されていないため、接続を確立できません | 接続設定で「クライアントシークレット」を入力します |
| 「HENNGE One APIの認証に失敗しました。Client IDとClient Secretを確認してください。」 | 入力されたClient ID・Client Secretが誤っているなどの理由で、HENNGE Oneの認証に失敗しました | HENNGE Access Control管理画面で発行したClient ID・Client Secretが正しいかを確認し、必要に応じて再発行して設定し直します |
| 「HENNGE One APIへのアクセスが拒否されました。APIクライアントのスコープを確認してください。」 | APIクライアントに必要なスコープが付与されていないため、操作が拒否されました | 「必要な権限」のスコープを確認します。「ロール」割当を使う場合は「全てのAPI」を「読み込み/書き込み」に設定します |
同期する項目に関するエラー
| メッセージ | 発生している事象 | 対処 |
|---|---|---|
| 「同一のユーザー名が既に存在します。（ユーザー名）」 | 新規作成しようとしたユーザー名が、HENNGE Access Control上の別のアカウントで既に使われています | ユーザー名（user.username）が一意になるよう「同期する項目」の式を見直します。同一ユーザー名の既存アカウントを更新してよい場合は、タスクを再実行します |
| 「HENNGE Oneに定義されていないカスタム属性が「同期する項目」に指定されています。HENNGE One の管理画面で定義されたカスタム属性を指定してください。」 | HENNGE One側に定義されていないカスタム属性のIDを「同期する項目」に指定したため、更新が拒否されました | HENNGE Oneの管理画面で定義済みのカスタム属性のIDと完全に一致するよう、「同期する項目」のキーを修正します |
| 「姓・名の少なくとも片方には値が必要です。両方を空にすることはできません。」 | 「同期する項目」の姓・名がどちらも空に評価されたため、HENNGE Oneへ送信する前に処理を中止しました | 「同期する項目」の姓（user.family_name）・名（user.given_name）の式を見直し、少なくとも片方に値が入るようにします |
| 「HENNGE One APIのリクエストのバリデーションに失敗しました。」 | 送信した値がHENNGE One側の入力チェックに違反しました | 「同期する項目」の式と評価結果を確認します。指定した値がHENNGE One側の入力チェックに合致しないケースが該当します |
| 「HENNGE One のパスワードリセットにはパスワードの設定が必要です。」 | パスワードリセットを実行しましたが、パスワードが発行されていません | 業務アセットの「アカウント設定」で、「初期パスワード」が「パスワードを設定する」になっていることを確認します |
通常のアカウント作成では、作成前に同一ユーザー名のアカウントがあるかを確認し、ある場合は更新に進みます。そのため「同一のユーザー名が既に存在します。」は通常の運用では発生しません。存在確認から作成の呼び出しまでのわずかな間に、外部から同一ユーザー名のアカウントが作成された場合にだけ発生します。
タスク実行に関するエラー
| メッセージ | 発生している事象 | 対処 |
|---|---|---|
| 「HENNGE One ユーザーが見つかりません: （ユーザー名）」 | 割当の付与・剥奪の対象アカウントが、HENNGE Access Control上に存在しません | 対象アカウントが存在することを確認します |
| 「ユーザーが見つかりません: （ユーザー名）」 | 割当の付与・剥奪の対象アカウントが、HENNGE Access Control上に存在しません | 対象アカウントが存在することを確認します |
| 「HENNGE One のアカウント更新がタイムアウトしました。ID: （ユーザー名）」 | アカウントの更新で、HENNGE One側の処理完了を待つ間にタイムアウトしました | 時間をおいて再実行します |
| 「HENNGE One のアカウント更新に失敗しました。ID: （ユーザー名）」 | 対象アカウントへの操作がHENNGE One側で失敗しました | 対象アカウントの「同期する項目」や割当の指定値を確認し、再実行します |
| 「アカウントの処理に失敗しました。ID: （ユーザー名）」 | 対象アカウントへの操作がHENNGE One側で失敗しました | 対象アカウントの「同期する項目」や割当の指定値を確認し、再実行します |
| 「HENNGE One APIのレート制限に達しました。（リセット時刻）以降に再実行してください。」 | HENNGE One APIのレートリミットに達し、一定回数リトライしても解消しませんでした | メッセージに記載された時刻以降に、タスクを再実行します |
| 「HENNGE One APIのレート制限に達しました。しばらく経ってから再実行してください。」 | HENNGE One APIのレートリミットに達し、一定回数リトライしても解消しませんでした | しばらく時間をおいてから、タスクを再実行します |
レートリミットのエラーは、Basicプランで発生しやすくなります。「制限事項」の「レートリミット」も参照してください。
タイムアウトのエラーが出ても、HENNGE One側では作成・更新の処理が続いている場合があります。HENNGE Access Control管理画面でアカウントの状態を確認してください。アカウント作成タスクがこのエラーで失敗した場合、初期パスワードはタスクの結果から確認できません。アカウントが作成されていた場合は、パスワードリセットを実行してパスワードを再発行してください。
HENNGE Oneには、単体のユーザーを作成・更新するAPIと、複数のユーザーをまとめて作成・更新するAPIがあります。「タスク一覧」画面で複数のタスクにチェックを入れて同時に実行すると、後者のAPIで呼び出しを集約し、呼び出しの回数と処理時間を短縮します。後者のAPIは処理の完了までに時間がかかるため、APIを呼び出した後に一定時間だけ完了を待機します。タイムアウトのエラーは、その待機時間内に完了を確認できなかった場合に発生します。
その他のエラー
| メッセージ | 発生している事象 | 対処 |
|---|---|---|
| 「HENNGE One APIでサーバーエラーが発生しました。」 | HENNGE One側でサーバーエラーが発生しました | 時間をおいて再実行します。継続する場合はHENNGE One側の状態を確認します |
| 「HENNGE One API呼び出しに失敗しました。（status=ステータスコード）」 | 上記のいずれにも該当しない理由で、API呼び出しが失敗しました | ステータスコードに応じて設定・データを確認します。解消しない場合はカスタマーサクセス担当までお問い合わせください |
| 「予期しないエラーが発生しました。サポートにお問い合わせください。」 | 上記のいずれにも該当しない理由で、タスクの処理が失敗しました | カスタマーサクセス担当までお問い合わせください |