ユーザーAPIキーの仕様

<div data-theme-toc="true"> </div>

Discourse には、非常に厳密なプロトコルに従うことで**ユーザーごと**に APIキーを生成するシステムがあります。この機能により、モデレーターを関与させることなく、Discourse インスタンスへの「アプリケーション」アクセスが容易になります。

### 大まかな説明

大まかに言うと、次のようになります。

1. クライアント(デスクトップアプリ、ブラウザプラグイン、モバイルアプリ)が秘密鍵/公開鍵ペアとリダイレクトURLを生成します。

2. クライアントがDiscourseのルートにリダイレクトし、公開鍵をDiscourseに渡します。

3. Discourseがユーザーにアプリの使用承認を求めます。

4. DiscourseがユーザーAPIキーを生成します。

5. Discourseが、公開APIキーを使用して暗号化されたペイロード(ユーザーAPIキーを含む)をリダイレクトURLに返します。

### 詳細

ユースケース:

1. エンドユーザーに代わってDiscourseサイトをポーリングし、複数のサイトにわたる通知数を取得するデスクトップアプリケーション。

2. エンドユーザーに代わってDiscourseサイトをポーリングし、プッシュ通知を処理するモバイルアプリケーション。

3. エンドユーザーに関するさまざまなDiscourseサイトのダッシュボードを提供するWebアプリケーション。

4. 会社の一般的なアプリの一部としてDiscourseを利用するサードパーティアプリとのカスタムインテグレーション。例:Discourseコミュニティの通知をhopscotchアプリに統合する。

設計:

### サイト設定

- **allow_user_api_key_scopes**: ユーザーAPIキーに許可されるアクセススコープ。スコープは[こちら](https://github.com/discourse/discourse/blob/main/app/models/user_api_key_scope.rb)で定義されています。利用可能な組み込みスコープは、`read`、`write`、`message_bus`、`push`、`one_time_password`、`notifications`、`session_info`、`bookmarks_calendar`、`user_status` です(プラグインは追加のスコープを登録する場合があります)。
- **user_api_key_allowed_groups**: ユーザーAPIキーの生成を許可されるグループを制御します(デフォルトは管理者、モデレーター、および trust_level_0)。

- **allowed_user_api_push_urls**: プッシュ通知のターゲットとして許可されるサイトのリスト。
- **allowed_user_api_auth_redirects**: ユーザーAPIキー生成後の許可されたリダイレクト先。

### グローバル設定

- **max_user_api_reqs_per_minute**: 20
- **max_user_api_reqs_per_day**: 2880

### UX要素

ユーザーAPIキーが許可されている場合、Discourseはユーザーページに**アプリ**タブを表示します。

**アプリ**タブには、次のものがリストされます。

- アプリケーションの名前(例:「Discourse Notifier」)
- 最終使用日
- 承認日
- 許可されたアクセススコープのリスト
- 任意のキーを簡単に取り消すための**アクセスを取り消す**ボタン

#### APIキー認証UI

すべてのキーは、何が起こっているかを明確に説明するページでエンドユーザーによって明示的に承認される必要があります。たとえば、次のようになります。

> 「Discourse Notifier」は、あなたのアカウントへの次のアクセスを要求しています。
> - 通知の読み取りとクリア
> - ユーザーセッション情報の読み取り
> - ワンタイムログイントークンの作成
>
> [承認する]

### APIキー生成フロー

APIは、ユーザー側での単一のGETリクエストのみを必要とします。

https://sitename.com/user-api-key/new


> :exclamation: Discourse 2.1以降、これらのユーザーAPIキーは、長期間使用されない場合、自動的に有効期限が切れるようになりました。サイト設定:`revoke user api keys unused days` はデフォルトで180に設定されています。

パラメータ:

* **auth_redirect**: 生成されたトークンと共にリダイレクトするURL。
* **application_name**: リクエストを行っているアプリケーションの名前(ユーザーアカウントの「アプリ」タブに表示されます)。
* **client_id**: クライアントの固有の識別子。
* **nonce**: クライアントによって生成された一意のnonce。クライアントが応答の信頼性を検証できるように、暗号化されたペイロードでエコーバックされます。
* **scopes**: キーに許可されているアクセススコープのコンマ区切りのリスト。利用可能なスコープの全リストについては、`allow user api key scopes` を参照してください。
* **push_url**: プッシュ通知のターゲットとなるURL(`push` または `notifications` がスコープに含まれている場合に必要かつ有効)。
* **public_key**: クライアントによって生成されたキーペアの公開部分。
* **padding** (オプション): ペイロードの暗号化に使用するRSAパディングモード。受け入れられる値は `pkcs1` (デフォルト) または `oaep` です。新しいアプリケーションには OAEP が推奨されます。

`auth_redirect` に正しいパラメータを指定して `/user-api-key/new` が呼び出された後、2つのことが起こる可能性があります。

1. ユーザーがログインしていない場合、ログインにリダイレクトされます(ログイン後、承認を再開します)。
2. ユーザーがログインすると、承認UIが表示されます。

承認が許可されると、システムは `auth_redirect` で定義されたURLにリダイレクトされ、生成されたユーザーAPIキー(`key`)、`nonce`、プッシュステータス(`push`)、APIバージョン(`api`)を含むJSONオブジェクトを含む暗号化された `payload` パラメータが含まれます。`one_time_password` スコープが要求された場合、個別の暗号化された `oneTimePassword` クエリパラメータも含まれます。セキュリティ向上のため、`client_id` はエコーバックされません。

### APIバージョンの確認

Discourse のキー使用 API はバージョン管理されています。クライアントは、`https://sitename.com/user-api-key/new` に HEAD リクエストを行うことで、Discourse サイトの API バージョンを確認できます。応答には、サイトの API のバージョン番号を含む `Auth-Api-Version` という名前のヘッダーが含まれます。

### API の利用

クライアント API の利用方法は、現在の管理者 API とは多少異なります。

クライアントは次の2つのヘッダーを指定できます。

`User-Api-Key` (必須): 生成されたキー

および

`User-Api-Client-Id` (オプション): これを指定すると、データベース内のこの api_key に保存されている「クライアント ID」が更新されます。

これらのヘッダーを指定すると、クライアントは通常どおり API に対してリクエストを実行できます。

### ワンタイムログインパスワードの生成

バージョン4以降、APIには特別なスコープである `one_time_password` スコープが含まれており、クライアントはこのユーザーAPIキーを使用してワンタイムパスワードを生成できます。クライアントが上記のステップに従ってAPIキーを生成する際にこのスコープを含めると、暗号化された `oneTimePassword` が、クライアントへのリダイレクトで個別のクエリパラメータとして含まれます。

または、クライアントは次のパラメータを使用して `/user-api-key/otp` への GET リクエストを行うことができます。

- auth_redirect
- application_name
- public_key
- padding (オプション)

そして `User-Api-Key` ヘッダーを使用します。

このリクエストはDiscourse内の画面にリダイレクトされ、ユーザーにサイトへのアクセスを許可するように求められます。ユーザーが承認すると、サイトは `auth_redirect` で定義されたURLにリダイレクトされ、クライアントがサイトへのログインに使用できるワンタイムパスワードを含む暗号化された `oneTimePassword` パラメータが含まれます(ワンタイムパスワードは10分間のみ有効です)。

### APIキーの取り消し

APIキーを取り消すには、`User-Api-Key` ヘッダーを付け、パラメータなしで `/user-api-key/revoke` に POST リクエストを送信します。

---

*最終確認者 @SaraDev [date=2022-07-12 time=17:00:00 timezone="America/Los_Angeles"]*
「いいね!」 30
Generating User Api Keys with REST API
Discourse Login & Registeration
Discourse sso login using Rest API
Custom Push Notifications: allowed user api push urls
Beta testing the iOS mobile app
Can non-admin user issue their own API key?
How can I get user details via the user api key?
Authorization from a desktop application (and base domain site)
Secure way of encrypting payload in Javascript for user authentification
API CORS Headers Incorrect
Generating User Api Keys with REST API
Get back Username with API Key?
Automatic Login from iOS/Android app
Is there any documentation on the User/Mobile API?
Delegated authentication for Discourse Mobile app
Generating User Api Keys with REST API
Passing draft text into a new response
Discourse Hub "connect"
Generate User API Keys for testing
Consolidated API Requests in the thousands yet our site has no active API keys listed, is this a concern?
Having issue accessing the Discourse APIs from react app
Discourse REST API Documentation
Having issue accessing the Discourse APIs from react app
CORS error accessing API from javascript application
Does Discourse have support for PAT tokens?
API key creation
Access via Discourse API, key and/or user rejected
Feasibility of allowing a User Api Key client to register a valid auth_redirect
Implement discourse Apple login using API
Thousands of user api requests and invalidation
Are User API Keys Not Generated When Logging in via Login Link?
Confusion about API Authenticated User
Confusion about API Authenticated User
Generate User Api Key Without User Approval
How to use discourse api in react native?
How can I allow users to like posts using RESTapi
'Clip To Discourse' Chrome Extension
Dexo - A Native iOS Client for Discourse
'Clip To Discourse' Chrome Extension
"Api-Key" and "Api-Username" for try.discourse.org?
Unable to create "Single User" level API key, always defaults to "All Users"
Discourse index
Authentication Protocol re: App Integration
Embed Discourse in a native app?
Request header field User-Api-Key is not allowed by Access-Control-Allow-Headers
Request header field User-Api-Key is not allowed by Access-Control-Allow-Headers
Request header field Content-Type is not allowed by Access-Control-Allow-Headers
Improve BAD CSRF error message when making API calls with content-type application/json
Create apikey for user programmatically as admin
How to fix 'Cannot read property '_links' of undefined'
Acess-Control-Allow-Headers CORS Error with API after updating discourse
Allow API use by regular users, not just admins
The purpose of the 2 Discourse API systems
Bot writer's tip: Processing every post
Using Zapier without being admin
Per User API Keys Not Working
Acess-Control-Allow-Headers CORS Error with API after updating discourse
Work with discourse users on an SPA

There are places I’ve strongly considered writing a delayed post tool, so I can compose a bunch of “word of the day” type things to keep going while I’m on vacation. Doing it without proper API access and pretending to be a browser seems somewhat more complicated than on other forum software.

(Just as an example of another use case.)

That is a good example, but keep in mind, our default will be only to enable read tokens, not write ones. Site admins will have to opt to allow write tokens.

Completely agree that the _t cookie hacks are a huge problem.

「いいね!」 2

Does max_user_api_calls_per_key_day setting apply to admin-created keys at /admin/api?

「いいね!」 1

Nope only to user api keys, we can look at adding extra limits for standard Api keys, it is a good safeguard

「いいね!」 1

To be clear, this is not implemented yet, correct?

No, it’s there (for almost 2,5 years now) - Admin - Settings - User API.

「いいね!」 4

As of Discourse 2.1 these user api keys now auto-expire if left unused for long periods of time, correct @sam?

「いいね!」 2

Correct the site setting: expire user api keys days is set to 180 out of the box.

「いいね!」 2

Okay, but you have to have admin access to see that page yes? And as an admin, it seems I can only create 1 key, so can’t create many keys for different users. confused.

「いいね!」 1

What are you trying to accomplish? It’s not clear because there is this (user api keys) and regular API tokens (which is what I think you are after) that admins can create for multiple users, but you have to do that from the individual user’s page inside of the admin dashboard by clicking on the “generate” button on the “API Key” field.

「いいね!」 4

Thanks! Yes, “regular API tokens” for users is what i was after. I’m sure I’d seen that a million times, and never realized it was there. :heavy_check_mark:

「いいね!」 3

Hey everyone I’m not sure if this was resolved? I see that it’s possible to create an “All Users” and (per user) level API token as an admin, but I’m interested in giving a user the power to generate his/her own token. Has there been work done on this? It sounds like the original thread was getting at this idea, and then it was lost. Thanks!

Download the mobile App and then add a site, that uses the user api key system you have to follow a very strict workflow, no plans to expose arbitrary generation of keys in user prefs

「いいね!」 3

Thank you! I downloaded the app, and then realized that the sites I belong to don’t have this enabled (I’ve been testing on my local machine with the Dockerized discourse). Just to make sure we are talking about the same thing - I’m interested in generating tokens to use just a scoped subset of functions (and not global API keys to do all the things). Is this what you are talking about?

It seems like, given that there is an endpoint to generate tokens, it would be logical to provide this function (to users with a certain trust level, for example) from within the site. Otherwise, it would need to be the case that the site generates some external page (with a server to hide an admin token) to generate the keys for the user. Is it the case that 1. there is no internal generation of tokens for the user (and why not?) and 2. Nobody has created some external app (javascript, flask, anything really) to perform this action?

「いいね!」 1

Yes.

Possibly, conceptually

  1. This is tricky to consume cause you need to use custom HTTP headers (by design)

  2. It would be very hard to educate even TL3 users about what the point is of this thing.

I prefer not to ship UI for this in core, but maybe you should write a plugin for your specific use case?

Can you explain a bit more about the “why” here?

The design of the system centers around “I have an external dedicated program”, “this program knows how to follow Discourse protocol”, “It asks for token”

API keys (non user ones) are much easier to consume cause you just append them after the ?

「いいね!」 4

Can I pass the API key generated from the user page on this? I was trying to use that API key and seeing ‘You are not permitted to view the requested resource.’ error on /categories.json API request

Hi guys

Apologies if this is duplication but I am having trouble digesting the steps there even though they are very well put together

I have a discourse installation on https://forum.domain.com and a site on https://development.domain.com from which I need to make calls to the discourse installation to pull and set some data.

All requests work from postman with Api-Username and Api-Key - no problem

However for cross origin requests using JS discourse doesnt allow the Api-Username leading me down the path of the flow described in this thread i.e. using the User-Api-Key and the User-Api-Client-Id

I basically require a description of paramaters PUBLIC_KEY,NONCE,CLIENTID used in the sample request below and where I can get them…

https://forum.domain.com/user-api-key/new?public_key=PUBLIC_KEY&nonce=NONCE&scopes=SCOPES&client_id=CLIENTID&application_name=DEVELOP&auth_redirect=XXX

Finally will this flow allow for seamless api requests from my https://development.domain.com to https://forum.domain.com without the need for authentication.

PS I have SSO set up between the forum and the site from which the requests are being made so the user will be logged in…

Thanks for any guidance

One sec, is this a per user thing? Are you allowing arbitrary users to do this?

Our server API supports header based auth these days so it can work with CORS just like the user api keys do. You would use the user api keys if you want to restrict scopes and allow end users to generate the keys vs admins.

「いいね!」 2

I wouldn’t see each user requiring a separate key no… One admin key should do what I need.

I can consume the api no problem through postman. For example a GET to /notifications.json?username=alanmurphy returns the data no problem using just api-key as a header.

If I trigger that request from the console of a discourse installation I get data back no problem also i.e.

var xhr = new XMLHttpRequest();
xhr.addEventListener(“readystatechange”, function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open(“GET”, “https://**********.com/notifications.json?username=alanmurphy”);
xhr.setRequestHeader(“api-key”, “d06ca53322d1fbaf383a6394d6c229e56871342d2cad953a0fe26c19df7645ba”);
xhr.setRequestHeader(“api-userame”, “system”);
xhr.send();

All Good:+1:

However, if I do this from the sub-domain I am wishing to contact discourse from, it tells me that it has been blocked by CORS policy: Request header field api-key is not allowed by Access-Control-Allow-Headers.

The allowed headers are:

Content-Type, Cache-Control, X-Requested-With, X-CSRF-Token, Discourse-Visible, User-Api-Key, User-Api-Client-Id

If I could just get guidance on what auth params to pass for cross origin requests and where to get them that would be very helpful.

Ps. My discourse is set up to allow Cross Origin requests from the domain so I believe it is purely a headers issue

Thanks

「いいね!」 1