OAuth
この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。
最終更新日 2024年04月01日(月)
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
) に基づいて構築されています。この記事では、両方のコンポーネントについて説明します。
プレフィックス付き OAuth トークン
Heroku OAuth アクセストークンには、HRKU-
というプレフィックスが付きます。
前のトークンの例: "57dce771-afad-4c41-a8a5-d10b7fbc743c"
プレフィックス付きトークンの例: "HRKU-57dce771-afad-4c41-a8a5-d10b7fbc743c"
プレフィックス付きトークンを使用すると、HRKU-
プレフィックスを検索して、コードやログから漏洩した可能性のあるトークンを特定するのに役立ちます。
ストア内に HRKU-
プレフィックスのないトークンがある場合、このトークンは変更が実装されてから再生成されていません。トークンを再生成すると、HRKU-
プレフィックスが付きます。
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":"HRKU-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":"HRKU-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": "HRKU-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": "HRKU-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"
}
リソースと例
- Platform API リファレンス
- OAuth クライアントと承認を管理するための Heroku CLI プラグイン
- OAuth をデモンストレーションする Ruby のサンプルアプリ
- OAuth をデモンストレーションする Go のサンプルアプリ
- Heroku のための OmniAuth の戦略
- Ruby Rack ミドルウェア Heroku Bouncer
- Python WSGI ミドルウェア