3.1. Device Authorization Request (设备授权请求)

🇬🇧 English

This specification defines a new OAuth endpoint: the device authorization endpoint. This is separate from the OAuth authorization endpoint defined in [RFC6749] with which the user interacts via a user agent (i.e., a browser). By comparison, when using the device authorization endpoint, the OAuth client on the device interacts with the authorization server directly without presenting the request in a user agent, and the end user authorizes the request on a separate device. This interaction is defined as follows.

The client initiates the authorization flow by requesting a set of verification codes from the authorization server by making an HTTP "POST" request to the device authorization endpoint.

The client makes a device authorization request to the device authorization endpoint by including the following parameters using the "application/x-www-form-urlencoded" format, per Appendix B of [RFC6749], with a character encoding of UTF-8 in the HTTP request entity-body:

client_id

REQUIRED if the client is not authenticating with the authorization server as described in Section 3.2.1. of [RFC6749].
The client identifier as described in Section 2.2 of [RFC6749].

scope

OPTIONAL. The scope of the access request as defined by Section 3.3 of [RFC6749].

For example, the client makes the following HTTPS request:

POST /device_authorization HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

client_id=1406020730&scope=example_scope

All requests from the device MUST use the Transport Layer Security (TLS) protocol [RFC8446] and implement the best practices of BCP 195 [RFC7525].

Parameters sent without a value MUST be treated as if they were omitted from the request. The authorization server MUST ignore unrecognized request parameters. Request and response parameters MUST NOT be included more than once.

The client authentication requirements of Section 3.2.1 of [RFC6749] apply to requests on this endpoint, which means that confidential clients (those that have established client credentials) authenticate in the same manner as when making requests to the token endpoint, and public clients provide the "client_id" parameter to identify themselves.

Due to the polling nature of this protocol (as specified in Section 3.4), care is needed to avoid overloading the capacity of the token endpoint. To avoid unneeded requests on the token endpoint, the client SHOULD only commence a device authorization request when prompted by the user and not automatically, such as when the app starts or when the previous authorization session expires or fails.

🇨🇳 中文

本规范定义了一个新的 OAuth 端点: 设备授权端点 (device authorization endpoint)。这与 [RFC6749] 中定义的 OAuth 授权端点是分开的,用户通过用户代理(即浏览器)与后者交互。相比之下,当使用设备授权端点时,设备上的 OAuth 客户端直接与授权服务器交互,而不在用户代理中呈现请求,最终用户在单独的设备上授权该请求。此交互定义如下。

客户端通过向设备授权端点发出 HTTP "POST" 请求,从授权服务器请求一组验证代码,从而启动授权流程。

客户端通过使用 "application/x-www-form-urlencoded" 格式(按照 [RFC6749] 的附录 B),在 HTTP 请求实体正文中使用 UTF-8 字符编码包含以下参数,向设备授权端点发出设备授权请求:

client_id (客户端标识符)

如果客户端未按照 [RFC6749] 第 3.2.1 节所述与授权服务器进行身份验证,则为必需 (REQUIRED)。
[RFC6749] 第 2.2 节中描述的客户端标识符。

scope (作用域)

可选 (OPTIONAL)。[RFC6749] 第 3.3 节定义的访问请求的作用域。

例如,客户端发出以下 HTTPS 请求:

POST /device_authorization HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

client_id=1406020730&scope=example_scope

来自设备的所有请求必须 (MUST) 使用传输层安全性 (TLS) 协议 [RFC8446] 并实施 BCP 195 [RFC7525] 的最佳实践。

发送的不带值的参数必须 (MUST) 被视为从请求中省略。授权服务器必须 (MUST) 忽略无法识别的请求参数。请求和响应参数禁止 (MUST NOT) 包含多次。

[RFC6749] 第 3.2.1 节的客户端身份验证要求适用于此端点上的请求,这意味着机密客户端(已建立客户端凭据的客户端)以与向令牌端点发出请求时相同的方式进行身份验证,公共客户端提供 "client_id" 参数来识别自身。

由于此协议的轮询性质(如第 3.4 节所述),需要小心避免令牌端点的容量过载。为避免对令牌端点的不必要请求,客户端应该 (SHOULD) 仅在用户提示时才开始设备授权请求,而不是自动开始,例如在应用启动时或先前的授权会话过期或失败时。

🇯🇵 日本語

この仕様は、新しい OAuth エンドポイントであるデバイス認可エンドポイント (device authorization endpoint) を定義します。これは、ユーザーがユーザーエージェント(すなわちブラウザ)を介して対話する [RFC6749] で定義された OAuth 認可エンドポイントとは別のものです。比較すると、デバイス認可エンドポイントを使用する場合、デバイス上の OAuth クライアントは、ユーザーエージェントでリクエストを提示することなく認可サーバーと直接対話し、エンドユーザーは別のデバイスでリクエストを認可します。この対話は次のように定義されます。

クライアントは、デバイス認可エンドポイントへの HTTP "POST" リクエストを作成して認可サーバーから検証コードのセットを要求することにより、認可フローを開始します。

クライアントは、[RFC6749] の付録 B に従って "application/x-www-form-urlencoded" 形式を使用し、HTTP リクエストエンティティボディに UTF-8 文字エンコーディングで次のパラメータを含めることにより、デバイス認可エンドポイントにデバイス認可リクエストを行います:

client_id (クライアント識別子)

[RFC6749] のセクション 3.2.1 で説明されているように、クライアントが認可サーバーで認証していない場合は必須 (REQUIRED)。
[RFC6749] のセクション 2.2 で説明されているクライアント識別子。

scope (スコープ)

任意 (OPTIONAL)。[RFC6749] のセクション 3.3 で定義されたアクセスリクエストのスコープ。

例えば、クライアントは次の HTTPS リクエストを行います:

POST /device_authorization HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

client_id=1406020730&scope=example_scope

デバイスからのすべてのリクエストは、トランスポート層セキュリティ (TLS) プロトコル [RFC8446] を使用し、BCP 195 [RFC7525] のベストプラクティスを実装しなければなりません (MUST)。

値なしで送信されたパラメータは、リクエストから省略されたかのように扱わなければなりません (MUST)。認可サーバーは、認識できないリクエストパラメータを無視しなければなりません (MUST)。リクエストおよびレスポンスパラメータは複数回含めてはなりません (MUST NOT)。

[RFC6749] のセクション 3.2.1 のクライアント認証要件がこのエンドポイントへのリクエストに適用されます。これは、機密クライアント(クライアント資格情報を確立したもの)がトークンエンドポイントへのリクエストを行うときと同じ方法で認証し、公開クライアントが自身を識別するために "client_id" パラメータを提供することを意味します。

このプロトコルのポーリングの性質(セクション 3.4 で指定)により、トークンエンドポイントの容量を過負荷にしないように注意が必要です。トークンエンドポイントへの不要なリクエストを避けるために、クライアントは、アプリが起動したときや以前の認可セッションが期限切れまたは失敗したときなど、自動的にではなく、ユーザーによって促されたときにのみデバイス認可リクエストを開始すべきです (SHOULD)。

🇫🇷 Français

Cette spécification définit un nouveau point de terminaison OAuth: le point de terminaison d'autorisation d'appareil (device authorization endpoint). Celui-ci est séparé du point de terminaison d'autorisation OAuth défini dans [RFC6749] avec lequel l'utilisateur interagit via un agent utilisateur (c'est-à-dire un navigateur). En comparaison, lors de l'utilisation du point de terminaison d'autorisation d'appareil, le client OAuth sur l'appareil interagit directement avec le serveur d'autorisation sans présenter la demande dans un agent utilisateur, et l'utilisateur final autorise la demande sur un appareil séparé. Cette interaction est définie comme suit.

Le client initie le flux d'autorisation en demandant un ensemble de codes de vérification au serveur d'autorisation en effectuant une requête HTTP "POST" au point de terminaison d'autorisation d'appareil.

Le client effectue une demande d'autorisation d'appareil au point de terminaison d'autorisation d'appareil en incluant les paramètres suivants en utilisant le format "application/x-www-form-urlencoded", conformément à l'Annexe B de [RFC6749], avec un encodage de caractères UTF-8 dans le corps de l'entité de la requête HTTP:

client_id (identifiant client)

REQUIS si le client ne s'authentifie pas auprès du serveur d'autorisation comme décrit dans la Section 3.2.1. de [RFC6749].
L'identifiant client comme décrit dans la Section 2.2 de [RFC6749].

scope (portée)

OPTIONNEL. La portée de la demande d'accès telle que définie par la Section 3.3 de [RFC6749].

Par exemple, le client effectue la requête HTTPS suivante:

POST /device_authorization HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

client_id=1406020730&scope=example_scope

Toutes les requêtes de l'appareil DOIVENT utiliser le protocole de sécurité de la couche de transport (TLS) [RFC8446] et implémenter les meilleures pratiques de BCP 195 [RFC7525].

Les paramètres envoyés sans valeur DOIVENT être traités comme s'ils avaient été omis de la requête. Le serveur d'autorisation DOIT ignorer les paramètres de requête non reconnus. Les paramètres de requête et de réponse NE DOIVENT PAS être inclus plus d'une fois.

Les exigences d'authentification du client de la Section 3.2.1 de [RFC6749] s'appliquent aux requêtes sur ce point de terminaison, ce qui signifie que les clients confidentiels (ceux qui ont établi des informations d'identification du client) s'authentifient de la même manière que lors de la création de requêtes au point de terminaison de jeton, et les clients publics fournissent le paramètre "client_id" pour s'identifier.

En raison de la nature de sondage de ce protocole (comme spécifié dans la Section 3.4), il faut faire attention à ne pas surcharger la capacité du point de terminaison de jeton. Pour éviter des requêtes inutiles sur le point de terminaison de jeton, le client DEVRAIT uniquement commencer une demande d'autorisation d'appareil lorsqu'il y est invité par l'utilisateur et non automatiquement, par exemple lorsque l'application démarre ou lorsque la session d'autorisation précédente expire ou échoue.

🇩🇪 Deutsch

Diese Spezifikation definiert einen neuen OAuth-Endpunkt: den Geräteautorisierungsendpunkt (device authorization endpoint). Dieser ist getrennt vom OAuth-Autorisierungsendpunkt, der in [RFC6749] definiert ist und mit dem der Benutzer über einen Benutzeragenten (d.h. einen Browser) interagiert. Im Vergleich dazu interagiert bei Verwendung des Geräteautorisierungsendpunkts der OAuth-Client auf dem Gerät direkt mit dem Autorisierungsserver, ohne die Anfrage in einem Benutzeragenten darzustellen, und der Endbenutzer autorisiert die Anfrage auf einem separaten Gerät. Diese Interaktion ist wie folgt definiert.

Der Client initiiert den Autorisierungsablauf, indem er einen Satz von Verifizierungscodes vom Autorisierungsserver anfordert, indem er eine HTTP-"POST"-Anfrage an den Geräteautorisierungsendpunkt stellt.

Der Client stellt eine Geräteautorisierungsanfrage an den Geräteautorisierungsendpunkt, indem er die folgenden Parameter im Format "application/x-www-form-urlencoded" gemäß Anhang B von [RFC6749] mit einer Zeichenkodierung von UTF-8 im HTTP-Anfrage-Entitätskörper einschließt:

client_id (Client-Identifikator)

ERFORDERLICH, wenn der Client sich nicht beim Autorisierungsserver authentifiziert, wie in Abschnitt 3.2.1. von [RFC6749] beschrieben.
Der Client-Identifikator, wie in Abschnitt 2.2 von [RFC6749] beschrieben.

scope (Bereich)

OPTIONAL. Der Bereich der Zugriffsanfrage, wie in Abschnitt 3.3 von [RFC6749] definiert.

Zum Beispiel stellt der Client die folgende HTTPS-Anfrage:

POST /device_authorization HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

client_id=1406020730&scope=example_scope

Alle Anfragen vom Gerät MÜSSEN das Transport Layer Security (TLS) Protokoll [RFC8446] verwenden und die Best Practices von BCP 195 [RFC7525] implementieren.

Parameter, die ohne Wert gesendet werden, MÜSSEN so behandelt werden, als wären sie aus der Anfrage weggelassen worden. Der Autorisierungsserver MUSS nicht erkannte Anfrageparameter ignorieren. Anfrage- und Antwortparameter DÜRFEN NICHT mehr als einmal enthalten sein.

Die Client-Authentifizierungsanforderungen von Abschnitt 3.2.1 von [RFC6749] gelten für Anfragen an diesem Endpunkt, was bedeutet, dass vertrauliche Clients (solche, die Client-Anmeldeinformationen eingerichtet haben) sich auf die gleiche Weise authentifizieren wie bei Anfragen an den Token-Endpunkt, und öffentliche Clients den "client_id"-Parameter bereitstellen, um sich zu identifizieren.

Aufgrund der Polling-Natur dieses Protokolls (wie in Abschnitt 3.4 angegeben) ist Vorsicht geboten, um eine Überlastung der Kapazität des Token-Endpunkts zu vermeiden. Um unnötige Anfragen an den Token-Endpunkt zu vermeiden, SOLLTE der Client eine Geräteautorisierungsanfrage nur beginnen, wenn er vom Benutzer dazu aufgefordert wird, und nicht automatisch, z.B. wenn die App startet oder wenn die vorherige Autorisierungssitzung abläuft oder fehlschlägt.

🇮🇹 Italiano

Questa specifica definisce un nuovo endpoint OAuth: l'endpoint di autorizzazione del dispositivo (device authorization endpoint). Questo è separato dall'endpoint di autorizzazione OAuth definito in [RFC6749] con cui l'utente interagisce tramite un agente utente (cioè un browser). In confronto, quando si utilizza l'endpoint di autorizzazione del dispositivo, il client OAuth sul dispositivo interagisce direttamente con il server di autorizzazione senza presentare la richiesta in un agente utente, e l'utente finale autorizza la richiesta su un dispositivo separato. Questa interazione è definita come segue.

Il client avvia il flusso di autorizzazione richiedendo un set di codici di verifica dal server di autorizzazione effettuando una richiesta HTTP "POST" all'endpoint di autorizzazione del dispositivo.

Il client effettua una richiesta di autorizzazione del dispositivo all'endpoint di autorizzazione del dispositivo includendo i seguenti parametri utilizzando il formato "application/x-www-form-urlencoded", secondo l'Appendice B di [RFC6749], con una codifica dei caratteri UTF-8 nel corpo dell'entità della richiesta HTTP:

client_id (identificatore client)

RICHIESTO se il client non si sta autenticando con il server di autorizzazione come descritto nella Sezione 3.2.1. di [RFC6749].
L'identificatore client come descritto nella Sezione 2.2 di [RFC6749].

scope (ambito)

OPZIONALE. L'ambito della richiesta di accesso come definito dalla Sezione 3.3 di [RFC6749].

Ad esempio, il client effettua la seguente richiesta HTTPS:

POST /device_authorization HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

client_id=1406020730&scope=example_scope

Tutte le richieste dal dispositivo DEVONO utilizzare il protocollo Transport Layer Security (TLS) [RFC8446] e implementare le migliori pratiche di BCP 195 [RFC7525].

I parametri inviati senza un valore DEVONO essere trattati come se fossero stati omessi dalla richiesta. Il server di autorizzazione DEVE ignorare i parametri di richiesta non riconosciuti. I parametri di richiesta e risposta NON DEVONO essere inclusi più di una volta.

I requisiti di autenticazione del client della Sezione 3.2.1 di [RFC6749] si applicano alle richieste su questo endpoint, il che significa che i client confidenziali (quelli che hanno stabilito credenziali client) si autenticano allo stesso modo di quando effettuano richieste all'endpoint token, e i client pubblici forniscono il parametro "client_id" per identificarsi.

A causa della natura di polling di questo protocollo (come specificato nella Sezione 3.4), è necessaria attenzione per evitare di sovraccaricare la capacità dell'endpoint token. Per evitare richieste non necessarie all'endpoint token, il client DOVREBBE iniziare una richiesta di autorizzazione del dispositivo solo quando richiesto dall'utente e non automaticamente, ad esempio quando l'app si avvia o quando la sessione di autorizzazione precedente scade o fallisce.

🇬🇧 English​

🇨🇳 中文​

🇯🇵 日本語​

🇫🇷 Français​

🇩🇪 Deutsch​

🇮🇹 Italiano​