oauth - herokaijp/devcenter GitHub Wiki

OAuth provides a way to authorize and revoke access to your account to yourself and third parties. Third parties can use this to provide services, such as monitoring and scaling your applications. You can also use these keys to grant access for your own scripts on your machine or applications.

OAuthは、あなたのアカウントへのアクセスを自身のアプリケーションとサードパーティーの。サードパーティは、アプリケーションをモニタリングしたり、スケールしたりするようなサービスを提供するのに、この技術を使うことが可能です。また、端末上に自身で作成したスクリプトやアプリケーションへのアクセスを承認するのにも使用可能です。

The Heroku Platform API implements OAuth version 2.0 as the preferred authentication mechanism. For further details of the specific API endpoints see the Platform API Reference.

HerokuのプラットホームAPIでは、より推奨される認証メカニズムとしてOAuthのバージョン2.0を実装しています。APIエンドポイントに関する詳細は、プラットホームAPIに関するレファレンスを参照して下さい。

Third parties who wish to provide services to Heroku users should implement web application authorization. Users who would like to use a personal OAuth token should instead use direct authorization.

Herokuのユーザーへサービスを提供したいと希望しているサードパーティーの方々は、[webアプリケーションによる承認]を実装するべきです。そうではなく、パーソナルなOAuthトークンを使いたいユーザーの場合は、ダイレクト承認を使うべきです。

Web application authorization

webアプリケーションによる承認

Web application authorization allows third parties to ask for and gain access to the resources of a Heroku user, which they can then use to provide services and features on top of the Heroku platform. webアプリケーション認証は、サードパーティー側へ、Herokuユーザーのリソースへを要求し、アクセス権を得ることを許可します。このことにより、Herokuのプラットホーム上でサービスと機能を提供することが可能となります。

Register client

クライアントの登録

The client is what identifies you, the third-party integrator, to Heroku and to authorizing users. When you register a client, you provide a callback URL and a name. The name is displayed to users when authorization is requested, so choose a name that identifies your site or application.

クライアントは、Herokuと認証中のユーザーへ、サードパーティーのインテグレーターであることを知らせます。クライアントの登録時、コールバック用のURLと名前を提示します。名前は承認がリクエストされた時に各ユーザーへ表示されますので、サイトやアプリケーションが判別出来るような名前を選んで下さい。

There are three ways to register a client: on dashboard (easiest), using the heroku-oauth CLI plugin or using the API directly.

クライアントの登録には、３つの方法があります。：１つ目はダッシュボード (もっとも簡単)を使う方法、２つ目はheroku-oauthのCLIプラグインを使う方法、３つ目はAPIを直接操作する方法です。

When you register a client, you get an ID and a secret that you use to authorize Heroku users against. クライアントの登録が完了すると、IDと秘密記号が与えられます。これらは、Herokuユーザーの承認時に使用されます。

OAuth flow

OAuthのフロー

This section describes the flow required to authorize your app to get access to a Heroku user's account. このセクションでは、Herokuユーザーのアカウントへアクセスするために、あなたのアプリケーションを承認させるのに必要なフローに関し、記述します。

Redirect to Heroku

Herokuへのリダイレクト

From your app, redirect the user to authorize: あなたのアプリケーションから、承認させるためにユーザーをリダイレクトさせて下さい。：

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

The scope URL parameter is a space-delimited (and url-encoded) list of the authorization scopes you are requesting. See available scopes below.

scopeというURLパラメータは、スペース区切りの形式（かつURLエンコードされています）で、あなたがリクエストする承認スコープのリストとなります。利用可能なスコープに関しては、Scopesの項を参照して下さい。

Redirect back

リダイレクト

The user will then be redirected back, based on the client redirect uri: その後でユーザーはリダイレクトされます。リダイレクト先は、クライアントのリダイレクトuriがもとになります。：

GET {redirect-uri}?code={code}

Token exchange

トークンの交換

Given the code from the redirect url, a token may now be acquired. リダイレクトURLからコードが提供されるので、トークンが取得されます。

POST /oauth/token

Curl Example

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"

Response

レスポンス

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",
  "session_nonce":"2bf3ec81701ec291"
}

Subsequent requests should authenticate by adding the access token's token value to the Authorization header and specifying type Bearer. For example, given the access token 01234567-89ab-cdef-0123-456789abcdef, request headers should be set to Authorization: Bearer 01234567-89ab-cdef-0123-456789abcdef.

連続的なリクエストはアクセストークンのtoken値を、Authorizationのヘッダーへ追加し、型をBearerと宣言することで認証するべきです。例えば、01234567-89ab-cdef-0123-456789abcdefというアクセストークンが発行された場合、リクエストヘッダーは、Authorization: Bearer 01234567-89ab-cdef-0123-456789abcdefとセットされるべきです。

Token refresh

トークンのリフレッシュ

Access tokens expire 8 hours after they are issued. The refresh token can be used to make a request for a new access token, similar to the initial access token exchange. Refresh tokens don't expire.

アクセストークンは発行後、8時間で消滅します。リフレッシュされたトークンは、新規のアクセストークンへのリクエストに使用されます。これは、初回のアクセストークンの交換と類似しています。リフレッシュされたトークンは、消滅しません。

POST /oauth/token

Curl example

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"

Response

レスポンス

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","session_nonce":"2bf3ec81701ec291"
}

Subsequent requests should authenticate by adding the access token's token value to the Authorization header and specifying type Bearer. For example, given the access token 01234567-89ab-cdef-0123-456789abcdef, request headers should be set to Authorization: Bearer 01234567-89ab-cdef-0123-456789abcdef.

Scopes

Scope（スコープ）

The following scopes are supported by the API: 下記のスコープが、APIによりサポートされています。：

• global: Full access to account and to control all apps and resources. Equivalent to API key.

• global: アカウントへのフルアクセス、及び全てのアプリケーションとリソースを制御することが可能。APIキーと同等となる。

• identity: Read-only access to account-info as exposed by the account API endpoint

• identity: アカウント情報へ読み取り専用のアクセスが可能。詳細は、アカウントAPIのエンドポイントを参照。

• read and write: Access to read and write info on account, apps and other resources, except configuration variables. This scope lets you request access to an account without necessarily getting access to runtime secrets such as database connection strings.

• read と write: アカウント情報、アプリケーション、その他リソースへの読み取りと書き込みが可能。但し、設定変数は対象外。このスコープは、アカウントへのアクセスをリクエストさせます。データベースの接続文字列のようなランタイムの機密情報へのアクセスを得る事無く。

• read-protected and write-protected: Same as above, but including access to config vars..

• read-protected と write-protected: 上記と同様ですが、設定変数へのアクセスも可能です。

Note that the read, write, read-protected and write-protected scopes do not grant access to account identity details such as email address.

read、 write、 read-protected、 write-protectedに関しては、emailアドレスのようなアカウントの詳細情報へのアクセスは許可されていませんので、ご注意下さい。

Direct authorization

ダイレクト承認

Direct authorization is used to provide a simpler workflow when users are creating authorizations for themself. It allows the exchange of username and password for a non-expiring token. These authorizations should be used in place of API keys in order to provide better granularity and the possibility of revocation.

ダイレクト承認はユーザーが自身に対し、承認を発行する際に、よりシンプルなワークフローを提供するために使われます。この技術は、失効していないトークンに対し、ユーザー名とパスワードの交換を許可します。これらの承認は、失効の粒度と可能性を提供するために、APIキーの代わりに使用されることになるでしょう。

Token exchange

トークンの交換

In order to acquire a direct authorization, a request is made to create an authorization while passing username and password in basic auth. A description may also be included to help distinguish this authorization from others, and like the web flow, the authorization can also be scoped to particular permissions on the account.

ダイレクト認証を取得するために、ベーシック認証でユーザー名とパスワードを入力させ、認証用のリクエストが生成されます。今認証されたものとそれ以外を判別するために、ユーザーの詳細情報が含まれます。また、Webフローのように、そのアカウントへの特別なアクセス許可が付与されます。

HTTP basic authentication must be constructed from the api token as :{api-token} (note the pre-pended colon), base64 encoded and passed as the Authorization header for each request, for example Authorization: Basic 0123456789ABCDEF=.

HTTPの基本認証は、api tokenを使う必要があります。書き方としては、:{api-token}（コロンを先頭に付ける必要があるのに注意して下さい）となり、base64でエンコードされ、リクエスト毎に認証ヘッダーを付加する必要があります。例えば、Authorization: Basic 0123456789ABCDEF=のような形式です。

POST /oauth/authorizations

Curl example

Curlの例

$ curl -X POST https://api.heroku.com/oauth/authorizations \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Basic 0123456789ABCDEF=" \
-H "Content-Type: application/json" \
-d "{\"description\":\"sample authorization\"}"

Response

レスポンス

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

{
  "access_token": {
    "expires_in": null,
    "id":         "01234567-89ab-cdef-0123-456789abcdef",
    "token":      "01234567-89ab-cdef-0123-456789abcdef"
  },
  "client": {
    "id":           null,
    "name":         null,
    "redirect_uri": null
  },
  "created_at":    "2012-01-01T12:00:00-00:00",
  "description":   "sample authorization",
  "grant": {
    "code":       null,
    "expires_in": null,
    "id":         null
  },
  "id":            "01234567-89ab-cdef-0123-456789abcdef",
  "refresh_token": {
    "expires_in": null,
    "id":         null,
    "token":      null
  },
  "scope":         "global",
  "updated_at":    "2012-01-01T12:00:00-00:00"
}

Subsequent requests should use the access token's token value base64 encoded and prepended with a colon in the Authorization header. For example, given the token 01234567-89ab-cdef-0123-456789abcdef, you'd base64 encode the string :01234567-89ab-cdef-0123-456789abcdef and set the header to Authorization: Bearer MDEyMzQ1NjctODlhYi1jZGVmLTAxMjMtNDU2Nzg5YWJjZGVm

Access tokens acquired through the direct authorization flow do not expire.

Revoking authorization

Revoking an authorization will block associated tokens from making further requests.

DELETE /oauth/authorizations/{authorization-id}

Curl example

$ curl -X DELETE https://api.heroku.com/oauth/authorizations/$AUTHORIZATION_ID \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer 0123456789ABCDEF="

Response

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

{
  "access_token": {
    "expires_in": null,
    "id":         "01234567-89ab-cdef-0123-456789abcdef",
    "token":      "01234567-89ab-cdef-0123-456789abcdef"
  },
  "client": {
    "id":           null,
    "name":         null,
    "redirect_uri": null
  },
  "created_at":    "2012-01-01T12:00:00-00:00",
  "description":   "sample authorization",
  "grant": {
    "code":       null,
    "expires_in": null,
    "id":         null
  },
  "id":            "01234567-89ab-cdef-0123-456789abcdef",
  "refresh_token": {
    "expires_in": null,
    "id":         null,
    "token":      null
  },
  "scope":         "global",
  "updated_at":    "2012-01-01T12:00:00-00:00"
}

Resources and examples

• Platform API Reference
• Heroku CLI plugin to manage OAuth clients and authorizations
• Ruby sample app demonstrating OAuth
• Go sample app demonstrating OAuth
• OmniAuth Strategy for Heroku
• Heroku Bouncer Rack Middleware
• log2viz log analyzer that uses OAuth