OAuth

最終更新日 2023年01月10日(火)

OAuth は、アカウントへの自分自身やサードパーティからのアクセスを承認したり、取り消したりする方法を提供します。サードパーティは、これを使用して、アプリケーションの監視やスケーリングなどのサービスを提供できます。また、OAuth で取得されたこれらのトークンを使用して、マシン上の独自のスクリプトまたは他のアプリケーションへのアクセスを許可することもできます。

Heroku Platform API では、推奨される認証メカニズムとして OAuth バージョン 2.0 が実装されます。特定の API エンドポイントについての詳細は、「Platform API Reference​」(Platform API リファレンス) を参照してください。

Heroku ユーザーにサービスを提供するサードパーティは、Web アプリケーション承認​を実装する必要があります。個人用の OAuth トークンを使用したいユーザーは、代わりに直接承認​を使用する必要があります。

クライアントライブラリとの統合

既存のクライアントライブラリと統合するには、次のエンドポイントを使用する必要があります。

  • トークン: https://id.heroku.com/oauth/token
  • 承認: https://id.heroku.com/oauth/authorize

Web 以外のフローを実行するか、または使用法をカスタマイズする必要がある場合は、詳細情報や手順が続きます。

アーキテクチャについて

OAuth の承認は、Web 承認フローまたは Heroku API からの 2 つの方法のどちらかで生成できます。Web 承認フロー (ドメイン id.heroku.com​) は、一般的な OAuth の規則を簡単にサポートするように設計されており、広範に使用されているライブラリからアクセスできます。この Web フローをサポートするコンポーネント自体は、すべての OAuth データの正規のソースである Heroku API (ドメイン api.heroku.com​) に基づいて構築されています。この記事では、両方のコンポーネントについて説明します。

Web アプリケーション承認

Web アプリケーション承認では、サードパーティは Heroku ユーザーのリソースへのアクセスを求め、それを取得することができます。その後、これを使用して Heroku プラットフォーム上でサービスや機能を提供できます。

クライアントの登録

クライアントは、Heroku や承認しているユーザーに対してサードパーティインテグレータを識別するものです。クライアントを登録する場合は、コールバック URL と名前を指定します。この名前は承認が要求されたときにユーザーに表示されるため、サードパーティのサイトまたはアプリケーションを識別する名前を選択します。

クライアントを登録する方法には、ダッシュボード​上 (最も簡単)、Heroku CLI の oauth コマンド​、API の直接の使用​の 3 つがあります。

クライアントを登録すると、Heroku ユーザーを承認するために使用する ID とシークレットが取得されます。

OAuth のフロー

このセクションでは、アプリで Heroku ユーザーのアカウントへのアクセスを取得できるようにするための承認に必要なフローについて説明します。

Heroku へのリダイレクト

アプリから、承認するユーザーをリダイレクトします。

GET https://id.heroku.com/oauth/authorize?client_id={client-id}&response_type=code&scope={scopes}&state={anti-forgery-token}

OAuth クライアントのパブリック識別子である client-id​ をリクエストに含めます。また、response_type​ を含め、それを現在サポートされている唯一の付与タイプである code​ に設定することも忘れないでください。

scope​ URL パラメータは、要求している承認スコープのスペースで区切られた (かつ URL エンコードされた) リストです。後述の使用可能なスコープ​を参照してください。

state​ パラメータは、Heroku の OAuth プロバイダーとアプリの間の状態を保持するために使用される一意の文字列です。Heroku がユーザーをアプリの redirect_uri​ にリダイレクトバックすると、このパラメータの値がレスポンスに含まれます (以下を参照)。このパラメータの値は、クロスサイトリクエストフォージェリ​ (CSRF) から保護するためのフォージェリ対策トークンである必要があります。

リダイレクトバック

ユーザーはその後、クライアントリダイレクト URI に基づいてリダイレクトバックされます。

GET {redirect-uri}?code={code}&state={anti-forgery-token}

トークンの交換

リダイレクト URL からコードが与えられると、トークンを取得できるようになります。

POST /oauth/token

curl の例

$ curl -X POST https://id.heroku.com/oauth/token \
-d "grant_type=authorization_code&code=01234567-89ab-cdef-0123-456789abcdef&client_secret=01234567-89ab-cdef-0123-456789abcdef"

レスポンス

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "access_token":"01234567-89ab-cdef-0123-456789abcdef",
  "expires_in":28799,
  "refresh_token":"01234567-89ab-cdef-0123-456789abcdef",
  "token_type":"Bearer",
  "user_id":"01234567-89ab-cdef-0123-456789abcdef",
  "session_nonce":"2bf3ec81701ec291"
}

後続のリクエストの承認ヘッダーでは、アクセストークンの token​ 値を使用します。たとえば、トークン 01234567-89ab-cdef-0123-456789abcdef​ の場合は、ヘッダーを Authorization: Bearer 01234567-89ab-cdef-0123-456789abcdef​ に設定します。

直接承認フローによって取得されたアクセストークンは期限切れになりません。

トークンの更新

アクセストークンは、発行されてから 8 時間後に期限切れになります。更新トークンを使用すると、初期のアクセストークンの交換と同様に、新しいアクセストークンのリクエストを作成できます。更新トークンは期限切れになまりせん。

POST /oauth/token

curl の例

$ curl -X POST https://id.heroku.com/oauth/token \
-d "grant_type=refresh_token&refresh_token=036b9495-b39d-4626-b53a-34399e7bc737&client_secret=fa86a593-d854-4a3f-b68c-c6cc45fb6704"

レスポンス

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 1200

{
  "access_token":"811235f4-16d3-476e-b940-ed5dfc7d6513",
  "expires_in":7199,
  "refresh_token":"036b9495-b39d-4626-b53a-34399e7bc737",
  "token_type":"Bearer",
  "user_id":"01234567-89ab-cdef-0123-456789abcdef",
  "session_nonce":"2bf3ec81701ec291"
}

以降のリクエストは、Authorization​ ヘッダーにアクセストークンの token​ 値を追加し、タイプ Bearer​ を指定することによって認証する必要があります。たとえば、アクセストークン 01234567-89ab-cdef-0123-456789abcdef​ の場合は、リクエストヘッダーを Authorization: Bearer 01234567-89ab-cdef-0123-456789abcdef​ に設定する必要があります。

スコープ

この API では、次のスコープがサポートされています。

  • global​: すべてのアカウント、アプリ、リソースへの読み取りと書き込みのアクセス。CLI を使用するときに取得されるデフォルトの承認​と同等です。
  • identity​: ​アカウント情報​への読み取り専用アクセス。
  • read​ と write​: アカウント情報と環境設定を除く、すべてのアプリとリソースへの読み取りと書き込みのアクセス。このスコープでは、データベース接続文字列などのランタイムシークレットへのアクセスを必ずしも取得しなくてもアカウントへのアクセスを要求できます。
  • read-protected​ と write-protected​: アカウント情報を除く、すべてのアプリとリソースへの読み取りと書き込みのアクセス。このスコープでは、データベース接続文字列などのランタイムシークレットへのアクセスを含むアカウントへのアクセスを要求できます。

直接承認

直接承認は、ユーザーが自分で承認を作成するときのより簡単なワークフローを提供するために使用されます。これにより、期限が切れそうなトークンと、有効期限のないトークンの交換が可能になります。

トークン交換リクエスト

多要素認証​は Heroku の必須のセキュリティ機能であるため、アカウントは有効期限のないトークンと交換するために Heroku プラットフォーム API トークンを渡す必要があります。この目的でユーザー名とパスワードを交換することはできません。

POST /oauth/authorizations

API トークンは heroku auth:token​ コマンドを使用して取得できます。

次に、以下のトークンを含めることによって直接承認リクエストを作成できます。

$ curl -X POST https://api.heroku.com/oauth/authorizations \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer <token retrieved from heroku auth:token>" \
-H "Content-Type: application/json" \
-d "{\"description\":\"sample authorization\"}"

この承認を他のものと区別しやすくするために、説明を含めます。Web フローと同じように、承認の範囲をアカウントの特定のアクセス許可に指定することができます。

トークン交換のレスポンス

上記の直接承認トークン交換リクエストのレスポンスは、次の例のようになります。

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 1200

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "client": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example",
    "redirect_uri": "https://example.com/auth/heroku/callback"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "refresh_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "scope": [
    "global"
  ],
  "updated_at": "2012-01-01T12:00:00Z"
}

以降のリクエストは、承認ヘッダーでアクセストークンの token​ 値を使用する必要があります。たとえば、トークン 01234567-89ab-cdef-0123-456789abcdef​ の場合は、ヘッダーを Authorization: Bearer 01234567-89ab-cdef-0123-456789abcdef​ に設定します。

直接承認フローによって取得されたアクセストークンは期限切れになまりせん。

承認の取り消し

承認を取り消すと、関連付けられたトークンがそれ以上リクエストを作成できなくなります。

DELETE /oauth/authorizations/{authorization-id}

curl の例

$ curl -X DELETE https://api.heroku.com/oauth/authorizations/$AUTHORIZATION_ID \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer 01234567-89ab-cdef-0123-456789abcdef"

レスポンス

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 1200

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "client": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example",
    "redirect_uri": "https://example.com/auth/heroku/callback"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "refresh_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "scope": [
    "global"
  ],
  "updated_at": "2012-01-01T12:00:00Z"
}

リソースと例