[Access Control] API 機能の利用方法 – HENNGE One ヘルプセンター

対象

Access Control をご利用中のお客様

目的

Access Control の API 機能の利用を開始するための手順を説明します。

注意事項

本記事の内容は 2025 年 3 月時点での製品仕様に基づき作成しており、以後予告なく変更される場合があります。
本機能のご利用には Access Control の管理者権限が必要です。
管理画面へのアクセス方法は以下の記事をご参照ください。
Access Control 管理画面へのアクセス方法
Access Control API にはレートリミットが設定されています。
詳細はレートリミットについてをご参照ください。
各エンドポイントの詳細については Developer Site をご参照ください。
https://developers.hennge.com/

手順

事前確認事項

Access Control API のエンドポイントは以下の通りです。

https://api.auth.hennge.com/{version-name}

{version-name} は利用したい API のバージョンを指定します。
例えば、20241126 バージョンの API をコールする際には https://api.auth.hennge.com/20241126 のように記述してください。
Access Control API で利用できる API バージョンは本ページ下部のライフサイクルをご確認ください。

認証クライアントの発行

1. Access Control 管理画面より [システム] - [API クライアント] にアクセスします。

メニュー.png

2. 画面右上の [+ クライアント追加] - [HAC API] を選択してください。

クライアント追加.png

3. API クライアントのスコープとメモを設定し、利用規約を確認しチェックを入れた状態で [保存] をクリックします。

APIクライアント設定.png

4. API クライアントが追加されるので、「クライアント秘密鍵」を記録します。
※ クライアント秘密鍵は API クライアント発行時にのみ表示され、ダイアログを閉じると再表示することはできません。
万が一クライアント秘密鍵を保存せずにダイアログを閉じた場合は、API クライアントを削除し再度新しい API クライアントを発行してください。

APIクライアント発行.png

アクセストークンの取得

作成した API クライアントを利用してアクセストークンを取得します。
※ Access Control API の認証フローは OAuth2.0 のクライアントクレデンシャルフローを採用しています。

トークンエンドポイントへのリクエスト (shell)

curl -L --request POST \
--url 'https://ap.ssso.hdems.com/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'authorization: Basic BASIC_CREDENTIALS' \
--data grant_type=client_credentials

トークンエンドポイントへのリクエスト (HTTP)

POST /oauth/token HTTP/1.1 
Host: https://ap.ssso.hdems.com 
Content-Type: application/x-www-form-urlencoded 
Authorization: Basic BASIC_CREDENTIALS

grant_type=client_credentials

※ BASIC_CREDENTIALS の値は API クライアントのクライアント ID とクライアント秘密鍵を Base64 エンコードして取得します。

・BASIC_CREDENTIALS の取得例

echo -n ${CLIENT_ID}:${CLIENT_SECRET} | base64

エンドポイントへのリクエスト

取得したアクセストークンを用いて Access Control API の各エンドポイントを利用できます。
各エンドポイントの詳細については Developer Site をご覧ください。
https://developers.hennge.com/

レートリミットについて

Access Control API にはレートリミットが設けられています。
API の種類及び利用プランにより、異なるレートリミットが適用されます。

API の種類	契約プラン
API の種類	HENNGE One IdP / HENNGE One Basic	HENNGE One IdP Pro / HENNGE One Pro
証明書関連 API (発行、失効、ダウンロード)	利用不可	5 リクエスト / 10 秒
ログ関連 API (ダウンロード)	利用不可	10 リクエスト / 10 秒
その他 API	10 リクエスト / 10 分	1000 リクエスト / 10秒

レートリミットを超過した場合、429 エラーがレスポンスされます。
また、レスポンスボディにレートリミットの制限が解除される日時が示されます。

・レスポンスボディ例

{
"detail": {
"reason": "too many requests",
"reset_time": "2023-01-01T00:00:00.000Z"
}
}

reset_time が示す日時を経過した後に API リクエストを再試行してください。

ライフサイクル

Access Control API はこのドキュメントに記載したライフサイクルに従ってバージョン管理されています。各バージョンのステージは不定期に更新されます。

・各バージョンのステージ一覧

バージョン名	ステージ	リリース日	最終更新日	EOL
20241126	GA	2025/02/10	2025/02/10	–
20230822	GA	2023/10/26	2023/10/26	–
20230221	Sunset	2023/02/21	2023/08/22	2025/08/25

・ステージの定義

ステージ	定義
Beta	Beta ステージにあるバージョンは動作の安定性やドキュメントの提供が保証されていないため、本番環境で運用するアプリケーションでの利用はおすすめしません。機能の動作テストやテスト環境での利用をおすすめします。
GA	GA ステージにあるバージョンは動作安定性とドキュメントの提供が保証されており、アプリケーションで利用するための最適なステージです。また、動作に問題が起きた際にはシステムの復旧対応を保証します。
Sunset	Sunset ステージにあるバージョンは動作安定性やドキュメントの提供も GA と同等に保証します。ただし、Sunset になったバージョンは動作停止する予定なので、新しいバージョンへの移行をおすすめします。
EOL	EOL のバージョンはすでに提供中止されています。バージョンの提供中止により、動作の安定性やドキュメントの提供は随時停止されることになります。 EOL のバージョンの利用はアプリケーションの動作に影響が出るため、速やかにバージョンの移行をする必要があります。

Access Control API の各バージョンのステージの更新については、下記ルールに従って行います。

各バージョンに下記のイベントが発生する際に、各バージョンのステージ一覧の表が更新されます。
- バージョンの Beta リリース
- バージョンの GA リリース
- バージョンの EOL 決定
バージョンの EOL が決定された際には、そのバージョンが Sunset ステージに入ります。
その他バージョンのステージ更新に関するルールは下記の通りです。
- バージョンの GA と Sunset の期間を合わせて、最短 12 ヶ月を保証します。
- EOL 予定日は、最短 EOL 予定日の 6 ヶ月前に公表することを保証します。