HEREプラットフォームでのOAuth 2.1の使用(マシン間)
このガイドでは、HEREプラットフォームでのマシン間アクセスにOAuth 2.1を使用する方法について説明します。これは、ユーザーの操作を必要とせず、自動でアクセストークンを取得して実行されるバックエンドサービス、自動化処理、プラットフォーム間連携のワークロードを統合する開発者を対象としています。
OAuth 2.1は、ログインしているユーザーの操作を必要とせずに、サービスがHERE APIまたはHEREに接続されたリソースを呼び出す必要がある場合に推奨されます。一般的なユースケースは次のとおりです。
- バッチジョブ
- プラットフォーム統合
- データパイプライン
- スケジュールされた処理
- サービス間通信
必須のベースラインアルゴリズムは
RS256です。
人間のユーザーがサインインしてアクセスを許可する必要があるユースケースの場合は、クライアント資格情報の代わりにユーザー委任のOAuthフローを設定します。
概要
OAuth 2.1認証を使用する場合、アプリケーションはHEREに資格情報を登録し、秘密鍵を保存し、署名付きJWTアサーションを作成して、そのアサーションをトークンエンドポイントでアクセストークンと交換します。
推奨されるクライアント認証方法は、登録されたJSON Webキー(JWK)を使用するprivate_key_jwtです。
一般的なワークフローは以下のとおりです。
- HEREプラットフォームでアプリケーションを作成または登録します。
- アプリケーションのOAuth 2.1資格情報を作成します。
- アプリの公開JWKをアップロードまたは登録します。
- 一致する秘密鍵を自身の安全な環境に保存します。
- 署名付きJWTクライアントアサーションを作成します。
client_credentialsトークンリクエストを送信します。- 返されたアクセストークンを使用してターゲットAPIを呼び出します。
OAuth 2.1では、OAuthのセキュリティに関するガイダンスが強化され、安全なデフォルト設定が基本となり、クライアントはすべてのトークンリクエストで認証を行うようになります。
前提条件
OAuth2.1を使用するには以下の要素が必要です。
- マシン間で資格情報を使用するように設定されたHEREアプリケーション
- アプリケーション用に登録済みのOAuth 2.1の資格情報
- アプリケーションに関連付けられた公開JWK
- サービスに保存されている対応する秘密鍵
- HERE認可サーバーのトークンエンドポイントURL
- 呼び出す予定のAPIに必要なスコープ
| アイテム | 説明 |
|---|---|
| クライアントID | HEREアプリケーション資格情報の一意の識別子。 |
| JWK | アプリケーション用に登録されたJSON Webキー形式の公開鍵。 |
| 秘密鍵 | 登録済みのJWKと一致する秘密鍵。 |
| トークンエンドポイント | トークンを発行するためのHERE認可サーバーエンドポイント。 |
| スコープ | トークンに要求する権限セット。 |
OAuth 2.1を使用して認証する方法
HEREプラットフォームでは、OAuth 2.1をアプリケーションの資格情報のオプションとして使用できます。選択すると、JWTベースのクライアント認証が有効になります。
プラットフォームWebアプリでOAuth 2.1資格情報を作成する方法
- [アクセスマネージャー]>[アプリ]に移動し、アプリケーションを選択します。[Register JWK](JWKを登録)をクリックします。
- 鍵の名前と、RSA秘密鍵の係数と指数を入力します。
- [Submit](送信)をクリックして新しい JWK を作成します。
2つのJWKを使用するとキーローテーションの安全性が高まります。新しいキーを追加すると署名を新しい秘密鍵に切り替え、トラフィックが新しい鍵に移動した後に古いJWKを削除します。
公開JWKを登録する
HEREプラットフォームは、JWTクライアントのアサーションをアプリに関連付けられた公開JWKと照合して検証します。初期設定では、JWKを静的にアップロードする方法を推奨します。
RSA公開鍵の重要なコンポーネントは次のとおりです。
n- RSA公開係数e- RSA公開指数kid- 任意ですが強く推奨されるキー識別子。最大長は256文字です。使用できる文字は以下のとおりです。- 大文字:
[A-Z] - 小文字:
[a-z] - 数字:
0-9 - ピリオド:
. - アンダースコア:
_ - ハイフン:
-
- 大文字:
以下はRSA公開JWKの例です。
{
"kty": "RSA",
"kid": "rsa-key-1",
"alg": "RS256",
"use": "sig",
"n": "0vx7agoebGcQSuu...base64url-modulus...",
"e": "AQAB"
}登録する必要があるのは公開JWKのみであるため、秘密鍵をHEREプラットフォームにアップロードしないでください。
JWTクライアントアサーションを作成する
サービスはJWTを作成し、登録されているJWKと一致する秘密鍵で署名する必要があります。その後、JWTはトークンリクエストでclient_assertionとして送信されます。
アサーションには以下の主要なクレームを含める必要があります。
| クレーム | 定義 |
|---|---|
iss | 発行者。自己発行のクライアント認証の場合、これによりクライアントを識別します。 |
sub | 件名。クライアント認証では、これによりクライアントを識別します。 |
aud | オーディエンス。これにより認可サーバー(通常はトークンエンドポイント)を識別します。 |
iat | アサーションが発行または作成された時刻です。 |
exp | アサーションの有効期限です。 |
jti | リプレイ攻撃防止用の一意のトークン識別子です。 |
JWTヘッダーの例
{
"alg": "RS256",
"kid": "rsa-key-1",
"typ": "JWT"
}JWTペイロードの例
{
"iss": "your-client-id",
"sub": "your-client-id",
"aud": "https://account.api.here.com/oauth2/token",
"iat": 1760000000,
"exp": 1760000300,
"jti": "8f1c3b2a-2fd1-4f2b-a2f6-7d52f2d8d401"
}アサーションは以下の条件を満たす必要があります。
- 完全性が保護されている。
- 期限切れでない。
- 適切なオーディエンスをターゲットにしている。
client_idも送信する場合は、アサーション内に指定されたクライアントと一致している必要がある。
アクセストークンをリクエストする
トークンをリクエストするには、application/x-www-form-urlencodedを使用してトークンエンドポイントにPOSTリクエストを送信します。
curl --request POST "https://account.api.here.com/oauth2/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
--data-urlencode "client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6InJzYS1rZXktMSJ9.eyJpc3MiOiJ5b3VyLWNsaWVudC1pZCIsInN1YiI6InlvdXItY2xpZW50LWlkIiwiYXVkIjoiaHR0cHM6Ly9hY2NvdW50LmhlcmUuY29tL29hdXRoMi90b2tlbiIsImlhdCI6MTc2MDAwMDAwMCwiZXhwIjoxNzYwMDAwMzAwLCJqdGkiOiI4ZjFjM2IyYS0yZmQxLTRmMmItYTJmNi03ZDUyZjJkOGQ0MDEifQ.signature" \
--data-urlencode "scope=your-requested-scope"成功すると、サービスがターゲットAPIに提示できるアクセストークンが返されます。
{
"access_token": "eyJ...token...",
"token_type": "Bearer",
"expires_in": 86399,
"scope": "your-requested-scope"
}検出、メタデータ、プラットフォーム動作
クライアントは可能な限り認可サーバーのメタデータを使用します。マシン間の連携ワークフローでは、HEREはOAuth認可サーバーの検出とメタデータの規則をサポートしています。
OAuth 2.1クライアント資格情報の重要なメタデータフィールドには以下が含まれます。
token_endpointgrant_types_supportedtoken_endpoint_auth_methods_supportedtoken_endpoint_auth_signing_alg_values_supported
想定されるマシン間通信向けのメタデータの要件として、以下に対するサポートが含まれます。
client_credentialsgrant_typeprivate_key_jwt認証方法RS256署名アルゴリズム(将来的には他のアルゴリズムもサポート予定)
{
"issuer": "https://account.api.here.com",
"token_endpoint": "https://account.api.here.com/oauth2/token",
"token_endpoint_auth_methods_supported": [
"private_key_jwt"
],
"token_endpoint_auth_signing_alg_values_supported": [
"RS256"
],
"grant_types_supported": [
"client_credentials"
],
"response_types_supported": [
"token"
]
}HERE CLIを使用してOAuth 2.1資格情報を作成する方法
HERE CLIを使用してJWKを作成することもできます。詳細についてはドキュメントを参照してください。
セキュリティ要件とベストプラクティス
- すべてのリクエストにHTTPSを使用する。
- 秘密鍵は安全な鍵管理システムに保管する。
- 有効期間が短いJWTアサーションを使用する。
- アサーションごとに固有の
jtiを生成する。 - トークンのスコープはできるだけ狭くする。
- 定期的にキーをローテーションし、2つ目のJWKスロットを使用してダウンタイムを回避する。
- リクエストされたAPIがリクエストしたスコープを承認することを確認する。
本番環境でのマシン間クライアント認証では、資格情報の管理の容易さ、迅速なキーローテーション、高い監査性を実現するため、private_key_jwtを使用することを推奨します。
トラブルシューティング
| 問題 | 考えられる原因 | 考えられる修正方法 |
|---|---|---|
invalid_client | 無効なJWT署名、間違った鍵、間違った認証方法、クライアントの不一致 | kid、登録済みのJWK、署名アルゴリズム、iss/subがクライアントと一致していることを確認する |
invalid_grant | アサーションの形式が間違っている、期限切れである、またはその他の理由で無効である | exp、iat、aud、クロックスキュー、JWTの構造を確認する |
| トークンのリクエストが拒否される | 必須のフォームパラメーターが存在しない、またはリクエストがサポートされていないスコープを使用している | grant_type、client_assertion_type、client_assertion、スコープの値を確認する |
| JWTが認識されない | 不明なJWKまたはkidの不一致 | 公開JWKが正しいアプリ用に登録されており、kidヘッダーがそれと一致していることを確認する |
次のようなよくある実装ミスにも注意してください。
- アップロードされたJWKと一致しない秘密鍵で署名する。
- JWTで誤ったオーディエンス値を使用する。
- 同じアサーションを繰り返し利用する。
- 1回のリクエストで複数のクライアント認証方法を送信する。
- アプリが使用できるスコープよりも広いスコープをリクエストする。
よく寄せられる質問
OAuth 2.1クライアント資格情報を使用するにはユーザーのログインが必要ですか?
いいえ。このフローはアプリケーション自身に代わって動作するアプリケーション向けであるため、エンドユーザーのログイン手順は含まれません。
どの署名アルゴリズムを最初に使用するとよいですか?
必須のベースラインアルゴリズムであるRS256を使用してください。
複数の鍵を登録できますか?
はい、アプリごとに最大2つのJWKを使用できます。
クライアントシークレットとJWTアサーションのどちらを使うべきですか?
可能な限りJWTアサーションを使用してください。これはHERE OAuth 2.1のマシン間認証に推奨される方法です。
18 日前の更新