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です。

一般的なワークフローは以下のとおりです。

  1. HEREプラットフォームでアプリケーションを作成または登録します。
  2. アプリケーションのOAuth 2.1資格情報を作成します。
  3. アプリの公開JWKをアップロードまたは登録します。
  4. 一致する秘密鍵を自身の安全な環境に保存します。
  5. 署名付きJWTクライアントアサーションを作成します。
  6. client_credentialsトークンリクエストを送信します。
  7. 返されたアクセストークンを使用してターゲットAPIを呼び出します。

OAuth 2.1では、OAuthのセキュリティに関するガイダンスが強化され、安全なデフォルト設定が基本となり、クライアントはすべてのトークンリクエストで認証を行うようになります。

前提条件

OAuth2.1を使用するには以下の要素が必要です。

  • マシン間で資格情報を使用するように設定されたHEREアプリケーション
  • アプリケーション用に登録済みのOAuth 2.1の資格情報
  • アプリケーションに関連付けられた公開JWK
  • サービスに保存されている対応する秘密鍵
  • HERE認可サーバーのトークンエンドポイントURL
  • 呼び出す予定のAPIに必要なスコープ
アイテム説明
クライアントIDHEREアプリケーション資格情報の一意の識別子。
JWKアプリケーション用に登録されたJSON Webキー形式の公開鍵。
秘密鍵登録済みのJWKと一致する秘密鍵。
トークンエンドポイントトークンを発行するためのHERE認可サーバーエンドポイント。
スコープトークンに要求する権限セット。

OAuth 2.1を使用して認証する方法

HEREプラットフォームでは、OAuth 2.1をアプリケーションの資格情報のオプションとして使用できます。選択すると、JWTベースのクライアント認証が有効になります。

プラットフォームWebアプリでOAuth 2.1資格情報を作成する方法

  1. [アクセスマネージャー]>[アプリ]に移動し、アプリケーションを選択します。[Register JWK](JWKを登録)をクリックします。
アプリケーションの現在のJWK
  1. 鍵の名前と、RSA秘密鍵の係数と指数を入力します。
RSA鍵の公開コンポーネントを入力する RSA鍵の公開コンポーネントを確認する 2つのJWKが使用されている
  1. [Submit](送信)をクリックして新しい JWK を作成します。
2つの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_endpoint
  • grant_types_supported
  • token_endpoint_auth_methods_supported
  • token_endpoint_auth_signing_alg_values_supported

想定されるマシン間通信向けのメタデータの要件として、以下に対するサポートが含まれます。

  • client_credentials grant_type
  • private_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のマシン間認証に推奨される方法です。


このページは役に立ちましたか?