ガイドAPIリファレンス
ガイド
  1. アイデンティティおよびアクセス管理
  2. 個人または組織のプラットフォームアカウントを管理する
  3. OAuth 2.0で認証する方法

OIDCトークン

OAuth 2.0を基盤とするOpenID Connect (OIDC) は、デバイストークンでログイン情報とプロファイル情報を提供し、OAuth 2.0アクセストークンを使用した承認も行います。

このガイドでは、サードパーティIDプロバイダーのデバイストークンをHEREデバイストークンと交換する方法について説明します。サードパーティのデバイストークンは、お客様とデバイスを識別するための、お客様固有の手段ですが、HEREサービスへのアクセスは許可しません。サードパーティのデバイストークンをHEREトークンと交換することで、お客様またはデバイスはHEREプラットフォームにアクセスできます。

詳細については、「OAuth 2.0トークン」を参照してください。

📘

注

通常、この機能は量産デバイス メーカーのみが使用します。

信頼されるドメインではトークンが適用されません。

組織管理者は、組織内のOIDC IDプロバイダーに発行者 (最大5つ) を指定できます。ただし、各アプリIDは1つのOIDC IDPのみをサポートできます。

デバイスアカウント

デバイスアカウントは、トークン交換APIを使用してサードパーティのOIDCデバイストークンをHEREデバイストークンと交換するときに確立されるIDです。

これはプロジェクトスコープトークンのみをサポートする特別なIDであるため、設定された統合HEREアプリのプロジェクトが常に対象とされます。

デフォルトでは、デバイスアカウントは承認されない限り、プロジェクトリソースにアクセスできません。これは、デフォルトでプロジェクト内の完全なアクセス権を持つユーザーやアプリとは異なります。

デバイストークンをHEREトークンと交換する

サードパーティのデバイストークンをHEREトークンと交換するには、次の手順が必要です。

ステップ1 - プラットフォームにサインインする

プラットフォーム組織 (レルム) が使用可能である必要があります。https://platform.here.com で HERE プラットフォーム アカウントにサインアップします。

ステップ2 - アプリを登録して資格情報を取得する

📘

注

CLIなどのHEREのSDKやツールの多くは、ユーザーのトークンの取得および使用を管理します。ほとんどの場合、ステップ2と3は省略できます。

OAuth 2.0トークンを使用するには、HEREプラットフォームにアプリを登録する必要があります。

アプリを登録する方法：

  1. ローカル開発環境で、ホームディレクトリ内に.hereフォルダーを作成します。
    • Mac/Linux ユーザーの場合、$HOME/.here となります。
    • Windows ユーザーの場合、C:\%HOMEPATH%\.here となります (ホーム ディレクトリが C ドライブにある場合)。
  2. HEREプラットフォームにサインインします。
  3. ランチャーから[アクセスマネージャー]を開きます。
  4. [アプリ] タブで、[新しいアプリを登録] をクリックし、求められた情報を入力します。
  5. [登録]をクリックします。プラットフォームで、一意のアプリ ID を持つ新しいアプリが作成されます。
  6. [資格情報]タブで、[OAuth 2.0]を選択し、[資格情報を作成]をクリックします。
  7. 開いたダイアログボックスで[ダウンロード]をクリックして、アプリのcredentials.propertiesファイルをダウンロードします。

このファイルには、ユーザーID、アプリID (here.client.idという名前)、OAuth 2.0トークンエンドポイントのURL、アクセスキーID、アクセスキーシークレットが含まれています。

なお、[Close](閉じる) をクリックすると、アクセスキーIDとアクセスキーシークレットにアクセスできなくなります。

  1. 最初のステップで作成した.hereフォルダーにcredentials.propertiesファイルをコピーします。

credentials.properties ファイルにはプラットフォーム資格情報が含まれています。プラットフォームCLIツールとライブラリは、このファイルにアクセスしてプラットフォームへのアクセスを管理します。これらのOAuth 2.0トークン資格情報を使用して、HERE REST APIに対して認証された呼び出しを行うこともできます。

プラットフォームCLI情報を使用する方法の詳細については、「Command Line Interface Developer Guide」(コマンドラインインターフェース開発者ガイド) を参照してください。

📘

注

アプリおよび関連する認証資格情報はアプリに固有のものであり、ユーザー権限やグループメンバーシップを継承しません。

ステップ3：アプリをプロジェクトに割り当てる

アプリマネージャーはアプリ作成時または作成後に、アプリのデフォルトプロジェクトを指定できます。デフォルトのプロジェクトを指定すると、アプリケーションからのリクエストの対象はそのプロジェクトに自動的に限定されるため、このアプリケーションの使用状況をプロジェクトレベルで確認できます。

  • プロジェクトマネージャーでプロジェクトからアプリを作成する場合、システムにより、作業中のプロジェクトにデフォルトプロジェクトが自動的に設定されます。

[アクセスマネージャー]からアプリを作成する場合、任意で[DEFAULT ACCESS TO A PROJECT](プロジェクトへのデフォルトアクセス) フィールドにプロジェクトを指定できます。

アプリ作成後にデフォルトプロジェクトを設定するには、[アクセスマネージャー]のアプリ詳細ページにアクセスし、[Edit app](アプリを編集) メニューオプションを選択して、[DEFAULT ACCESS TO A PROJECT](プロジェクトへのデフォルトアクセス) フィールドのプロジェクトを指定します。

📘

注

この機能を使用するには、[Allow access only in this project](このプロジェクト内でのみアクセスを許可) チェックボックスをオンにする必要があります。

プロジェクト内のアクセスを管理するためのチェックボックス アプリ作成時または作成後に[Allow access in only default project](デフォルトプロジェクト内でのみアクセスを許可) チェックボックスをオンにすると、デフォルトプロジェクトのスコープ内のリソースのみをリクエストするようアプリを設定することもできます。セキュリティが強化されるため、APIキーを使用するアプリではこの設定が推奨されます。

また、このオプションを使用すると、プロジェクトレベルでこのアプリケーションの使用状況を確認できます。

ステップ4 - OIDC IDプロバイダーを登録する

OIDCはOAuth2.0フレームワークを基盤としており、相互運用可能な認証プロトコルを備えているため、迅速な実装と開発が可能になります。

まず、OIDC IDプロバイダーを登録します。最大5つのOIDC IDプロバイダーを登録できます。各IDプロバイダーには、発行者URL (最大2つ) が必要です。

OIDC IDプロバイダーを登録する方法：

  1. HEREプラットフォームにサインインします。
  2. [Access Manager](アクセスマネージャー) セクションの[Identity providers](IDプロバイダー) タブの右上で、[Setup identity provider](IDプロバイダーを設定) を選択します。
  3. 使用するIDプロバイダーに関する情報を入力します。最大5つのIDプロバイダーを入力できます。
  4. 各IDプロバイダーについて、IDプロバイダーを選択して発行者を入力できます。IDプロバイダーのページで、[Add issuer](発行者を追加) を選択して、その発行者のURLを少なくとも1つ入力する必要があります。各IDプロバイダーには、最大2つの発行者を入力できます。

IDプロバイダーのリスト。

📘

注

アプリは1つのプロジェクトに制限する必要があります。

HEREでは、これらの要件で次のOIDCプロバイダーをサポートしています。

  • Jwks_uri がエンドポイントで定義されている。
  • 「alg」値をサポートする公開キー(RS256、RS384、RS512、ES256、ES384、ES512) が含まれている。
  • JWT トークン形式であること。
  • OIDC トークン「sub」 (デバイスの識別に使用されるサブジェクト) 内の必須の標準要求。
  • 「iss」 (発行者)。
  • 「iat」 (タイムスタンプ時に発行)。
  • 「exp」 (有効期限のタイムスタンプ)。
  • カスタム要求が必要。
  • 「client_id」 (HERE アプリ ID と一致)。

ステップ 5：OIDC IDプロバイダーをアプリIDに割り当てる

作成したアプリIDを選択し、[Identity provider](IDプロバイダー) オプションを選択して、IDプロバイダーをアプリに添付します。

📘

注

アプリおよび関連する認証資格情報は、アプリ専用です。アプリはユーザー権限やグループメンバーシップを継承しません。

ステップ6：OIDC IDプロバイダーを更新する

IDプロバイダーの所有者は、OIDCトークンのclient_idがHEREシステムで設定されたアプリのアプリIDと一致することを確認する必要があります。このclient_idは[アカウント設定]セクションにあるユーザーIDです。

ステップ 7：デバイストークンをHEREトークンと交換する

初めてトークンを取得すると、プロジェクト内にデバイスが自動的に作成されます。同じsub要求を持つOIDCトークンが後でトークン交換に使用される場合、同じデバイスがIDとなります。

デバイスはDevice CLIコマンドを使用して管理できます。

これでデバイストークンをHEREトークンと交換できるようになりました。デバイスアカウントトークンは常に、設定されたアプリが制限されている単一のプロジェクトにスコープが限定されます。

ステップ 8：トークンを使用する

これで、HERE APIへのリクエストを行うためのトークンを正常に取得できました。

RESTリクエストのHTTP承認ヘッダーにあるトークンをベアラートークンとして渡します。

Authorization: Bearer <token>

RESTリクエストの例

GET /maptile/2.1/maptile/newest/normal.day/13/4400/2686/256/png8
Host: 1.base.maps.ls.hereapi.com
Authorization: Bearer eyJhbGceOyJSAMPLEiIsImN0eSISAMPLEt7VTFIllwIM0cKNCjN2WCCTqlwEEmk-t3gx1BpqUFoeBSAMPLEvhj8nl-RBGcyoljY...
Cache-Control: no-cache

デフォルトでは、デバイスはサービスやリソースにアクセスできません。デフォルトであるプロジェクトリソースでもアクセスできません(これは、プロジェクト内のあらゆるデータへのアクセスがデフォルトで許可されているユーザーまたはアプリメンバーのデフォルト特性とは異なります)。

デバイスにリソースへのアクセスを許可するには、プロジェクトレベルのポリシーをプロジェクトに添付して、プロジェクトリソースを明示的に使用できるようにする必要があります (「アプリをプロジェクトに割り当てる」を参照してください)。この機能は、プロジェクトに添付されたプロジェクト ポリシーを管理する CLI (コマンド ライン インターフェース) のみの機能として使用できます。「プロジェクトのアクセス権」を参照してください。

20 日前の更新