ClientTokenとOAuth Access

ここでは、Maprayで開発した地図アプリを公開する場合や、複数人で開発する場合などに、Mapray Cloudのリソースにアクセスする権限を制限する方法と、その仕組みを説明します。

Maprayで地図アプリを開発する際、

一般の人に公開したい
複数の人で開発したい

といった、Mapray Cloudで管理している自身のリソース(2D、3D、点群、都市データなど)に、地図アプリから他者がアクセスできるようにしたいことがあります。

しかし、そのために自身のアカウントのID・パスワード、またはAPI Keyを共有すると自身のリソースの削除、変更、アカウント情報の悪用の恐れなどがあります。
そこでClientTokenを利用することで、リソースのアクセス権限を制限して、安全に他者がアクセスできるようにできます。

例を上げると、

詳細な3Dモデルを表示する地図アプリを開発した。公開したいが、3Dモデルを変更されたくないので、3Dデータの読み込み権限だけつけたClientTokenを利用して公開する。
チームで地図アプリを開発する。Aさんには2Dデータ関係をお願いするから、2Dデータの変更権限をつけたClientToken、Bさんには3Dデータ関係をお願いするから、3Dデータの変更権限をつけたClientTokenを利用して開発してもらう。

リソースの管理者は、このように適切な権限をClientTokenに付与することによって、リソースの不正アクセスや攻撃を行われた場合でも、被害を最小限に抑えることができます。

1. OAuth対応

Mapray Cloudと開発したアプリケーションの連携は、セキュリティを確保するためにOAuthに則って行われています。

OAuthを簡単に説明すると、

トークンを利用した認証をする
トークンの権限を制限できるため、万が一盗まれても被害が少ない
認可コードフローで安全にトークンを取得
トークンには有効期限があり、万が一盗まれても期限が過ぎると使えない

このような特徴を持った、アクセストークンの要求と、その応答を標準化したものが「OAuth2.0」です。OAuthの詳細は技術文書RFC 6749で定義されています。

Mapray Cloudでは、OAuthに則って、

ClientTokenを利用した認証の仕組み
TokenScopeによる権限の制限
認可コードフローでAccessTokenの取得
AccessTokenには有効期限があり、リフレッシュトークンで再発行を行う

このようなセキュリティに配慮した仕組みを導入することで、データを保護しています。

1.1. OAuth Accessの概略

アクセスまでの大まかな流れのイメージをつかむために、概略を示します。

「ユーザ」は、リソースサーバのデータを利用したい人です。
「リソースサーバ」は、データを管理するサーバです。
「認可サーバ」は、ユーザの認証とAccessTokenの発行するサーバです。
「クライアント」は、ユーザのデータを利用したい地図アプリケーションを動かすサーバです。
「開発者」は、クライアントのアプリケーションの開発者です。

Mapray Cloudと地図アプリの連携の場合、「リソースサーバ」と「認可サーバ」の役割を Mapray Cloud 、「クライアント」を 地図アプリ が担っています。

ユーザが連携をしたいとき、
クライアントは、Mapray Cloudに権限を要求します。
Mapray Cloudは権限を与えていいか確認をとり、
ユーザはClientTokenを利用して認証します。
認証されるとMapray CloudはクライアントにAccessToken発行します。
クライアントはAccessTokenを利用して、
Mapray Cloudのリソース(2D、3D、点群、都市データなど)にアクセスできるようになります。

また、ClientTokenとAccessTokenの違いはそれぞれ以下のようになっています。

ClientToken: Mapray Cloudから開発者が生成するトークンです。
ランダムに生成される文字列で、ユーザ認証に用いるパスワードの代わりに使用する鍵です。
ClientToken自体は アクセス権限があることを示すものではありません。
AccessToken: ClientTokenをもとに内部的に発行されるトークンです。
ランダムに生成される文字列で、 リソースのアクセス権限があることを示すもの です。
権限はClientTokenに設定されているTokenScopesをもとに決まります。

以上がMapray Cloudのリソースにアクセスするまでの概略です。概略では省略しましたが、AccessTokenは「認可コードフロー」と呼ばれるフローで取得します。
また、概略の 2. や 6. のクライアントが要求を行う部分などは開発者による実装が必要になります。

2. WebアプリケーションでMapray Cloudにアクセスする

実際に、ClientTokenの発行から、WebアプリでMapray Cloudにアクセスするまでの一連の流れを説明します。

2.1. 事前準備

開発者は事前準備として、以下を行ってください。

アカウント作成: アカウントの作成方法については解説ページをご参照ください。
Organization作成: Organizationは1人以上のユーザが所属し、Dataset(2D、3D、点群、都市データなど)やTokenが紐づく単位です。
OrganizationIDが後ほど必要になります。作成方法については解説ページをご参照ください。
Redirect URL設定: Redirect URLはOAuth認証の後にクライアントがリダイレクトするURLです。
WebアプリはRedirect URLのページで、認可レスポンスに対する処理を行う必要があります。
開発者はリダイレクトして欲しいページを用意し、そのURLを設定してしてください。
設定方法については解説ページをご参照ください。

2.2. ClientToken生成

「ClientToken」とは、ランダムに生成される文字列で、ユーザ認証に用いるパスワードの代わりに使用する鍵です。
AccessTokenの権限はClientTokenを発行するときに選択する「TokenScopes」をもとに決まります。

2.2.1. TokenScopesによる権限の制限

「TokenScopes」とは、操作が可能な範囲、権限です。

生成するときに選択する「TokenScopes」をもとにClientTokenの権限は決まります。ClientToken生成時に、下のような画面が表示されるので、付与したいTokenScopesを選択します。

Public Scopes: データの読み出し権限です。2D Read、3D Read、PointCloud Readなどがあります。
Secret Scopes: データの新規作成や更新、アカウントに紐づいた情報についての書き込み権限です。
Secret Scopesはデータの変更権限を含むため、これを選択したClientTokenは、生成時の一度しか表示されません。

例えば、2D Readと2D Createを選択してClientToken生成した場合、ClientTokenの権限は、2D Readと2D Createとなります。そのため、ClientTokenからは2Dデータの削除や、3Dデータにアクセスすることは不可能となります。
また、ClientTokenは複数生成することが可能です。目的に応じてClientTokenの権限を設定し、使い分けることで、柔軟な運用が可能になります。

2.2.2. ClientTokenの生成手順

ClientTokenを生成するまでの手順を説明します。

ClientTokenはMapray Cloudから生成します。
「Tokens」ページの、「ClientToken」タブから、「Create a ClientToken」ボタンをクリックします。
「Client token name」に任意の名前を入力します。2文字以上128文字以下で入力してください。
ClientTokenに付与したい権限の「TokenScopes」を選択して、「Create」ボタンをクリックします。
ClientTokenを確認します。「TokenScopes」で、「Secret Scopes」を選択していない場合はこの画面から確認します。
また、「TokenScopes」で、「Secret Scopes」を選択していた場合、ClientTokenは生成時のときに出るこの画面からのみ確認でき、生成時以降この画面は 再度表示できません。 必ずこれを記録して、適切に管理するようにご注意ください。

ClientTokenのTokenScopesや名前はいつでも変更、削除が可能です。もし、ClientTokenが流出した場合、TokenScopesに設定されている権限の操作が出来てしまうため、削除して再発行を行ってください。

ClientTokenを発行するときに「Token restrictions」を指定することも可能です。「Token restrictions」はアクセス元IP制限に使用します。ただし、モバイルアプリのように、パブリックのインターネット経由でアクセスする場合は、IPが変動し制限できないため、入力しないようお願いします。

2.3. AccessToken発行

AccessTokenの発行は、直接AccessTokenを渡さずに、認可コード介してAccessTokenを取得する「認可コードフロー」で行います。「認可コード」とは、 数分程度で有効期限が切れ、一度しか使えない 短命のコードです。

また、Mapray Cloudで発行される認可コードの有効期限は 10分 となっています。

認可コードフローでAccessTokenを発行するまでの流れを説明します。

2.3.1. 認可リクエスト

ユーザはクライアントが連携するか尋ねるので応答します。
クライアントは、あらかじめ渡されているOrganizationID、ClientToken、redirect URLをもとに、Mapray Cloudに認可リクエストを送ります。

2.1. 開発者はクライアントに、OrganizationID、ClientToken、redirect URLをあらかじめ渡しておき、Mapray Cloud(認可エンドポイント)に認可リクエストを送るように実装する必要があります。

2.3.2. OAuth認証

Mapray Cloudは渡されたOrganizationID、ClientToken、redirect URLを検証し、問題なければユーザに認可画面を表示します。

1.1. Mapray Cloudはこのような認可画面を表示します。
ユーザは認可画面でOrganizationID、パスワードにClientTokenの値を入れ、承認します。

2.3.3. 認可コードの発行

Mapray Cloudは認可レスポンスを返し、クライアントはredirect URLに遷移して、そこで認可レスポンスを受け取ります。

1.1. 開発者は、この認可レスポンスを受け取り、URLパラメータの処理を行い、認可コードを取得するページをあらかじめ作成し、redirect URLに設定しておく必要があります。

2.3.4. AccessTokenの発行

クライアントは認可レスポンスに含まれる認可コードと交換で、Mapray CloudにAccessTokenを発行してもらいます。このときAccessTokenの権限は、ClientTokenに設定されている権限をもとに決まります。

1.1. 開発者は、Mapray Cloud(トークンエンドポイント)に認可コード送信し、AccessTokenを取得するように実装する必要があります。また、認可コードは10分で有効期限が切れるため、それまでにAccessTokenを取得してください。

認可コードフローでAccessTokenを発行するまでの流れはこのようになっています。

認可コードを介する理由は、 認可レスポンスのURLの中にAccessTokenを直接埋め込むことには漏洩のリスクがある ためです。そのため、10分で有効期限が切れて、一度しか使えない認可コードを介してAccessTokenを取得するようになっています。また、redirect URLを事前に設定しておくことで、認可コードを決められたページ以外から利用できないようにしています。

このように、認可コードを介してAccessTokenを取得することで、安全な仕組みを実現しています。

2.4. リソースアクセス

クライアントはAccessTokenを送信してリソースを要求します。

1.1. 開発者は、AccessTokenを送信してリソースにアクセスするように実装する必要があります。
Mapray CloudがAccessTokenをデータ利用できる権限があるか確認して、クライアントにデータを渡します。このとき、権限のないデータにはアクセスできないようになっています。

2.5. リフレッシュトークン

「リフレッシュトークン」とは、有効期限の長いAccessTokenと同時に発行される、ランダムに生成される文字列です。

リソースの要求をするたびにAccessTokenを送信すると、ネットワーク上を流れる頻度が高くなり、漏洩のリスクも高まります。そのため、AccessTokenには短い有効期限が設定されていて、仮に漏洩しても有効期限が過ぎると使えない仕組みになっています。しかし、有効期限が切れるたびにAccessTokenを再発行するのは手間がかかるため、リフレッシュトークンを利用して内部的に再発行します。リフレッシュトークンは、再発行する際にのみネットワーク上を流れるため、漏洩のリスクは低くなっています。

AccessToken: 有効期限が短いトークンで、送信の頻度が高く、漏洩のリスクが高いです。
また、Mapray Cloudで発行されるAccessTokenの有効期限は 1時間 です。
リフレッシュトークン: 有効期限が長いトークンで、再発行の際にのみ送信され、漏洩のリスクが低いです。
また、Mapray Cloudで発行されるリフレッシュトークンの有効期限は 60日 です。

各トークンの特徴はこのようになっていて、リフレッシュトークンを使用して、AccessTokenを定期的に更新することでその欠点を補っています。

2.5.1. リフレッシュトークンで再発行する

リフレッシュトークンを利用して再発行するまでの流れを説明します。

Mapray Cloudは、AccessTokenとリフレシュトークンを発行し、クライアントがデータにアクセスする際はAccessTokenを送信します。
AccessTokenの有効期限が切れると、クライアントはリフレッシュトークンを送信します。

2.1. 開発者は、AccessTokenの有効期限が切れて使えなくなった際に、リフレッシュトークンをMapray Cloud(トークンエンドポイント)に送信するように実装する必要があります。
Mapray Cloudは、リフレッシュトークンを検証し、問題なければ再びAccessTokenとリフレッシュトークンを発行し、新しいAccessTokenでデータにアクセスが可能になります。