]> Apple Inc.

paresh_sawant@apple.com

capport api state token internet access notification This document specifies a new key in Captive Portal API State data structure. The purpose of the new key is to allow clients to perform the client authentication without user interaction.

Introduction As described in , the Captive Portal API data structure is specified in JavaScript Object Notation (JSON) . Requests and responses for the Captive Portal API use the "application/captive+json" media type. The original specification specifies key "user-portal-url" to convey the web portal URL to the client. Although in most cases client devices are capable of presenting the web portal to the user, there are types of devices that are not built to support the user interaction with the web portal. This document specifies a new key that allows client to perform the authentication without user interaction.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

API State Structure Enhancement shows the new key that can be optionally included in the top-level of the JSON structure returned by the API server.

Key	Type	Description
client-authentication-url	string	Provides the URL of the authentication server that MUST be accessed over TLS with which the client is authenticated without user interaction. Authentication Server authenticates clients using the HTTP authentication framework specified in . The server MUST NOT require user interaction on the client device. The client MUST have a credential to perform the authentication without user interaction.

Use Cases

• Devices that don't support user interaction or web interface, can join captive networks using "client-authentication-url" key. For example, IoT (Internet of Things) devices or speakers can join captive networks using the credentials provisioned to them.
• specifies "PrivateToken" HTTP authentication scheme. Use of "PrivateToken" HTTP authentication scheme can attest that the client behind the user agent is likely not a bot attempting to perform some form of automated attack such as credential stuffing.
• User experience improvements by not requiring user's interaction with the Captive Portal system every time client device connects the captive network. For example, many Captive Portal systems require users to accept the same terms of service or solve CAPTCHA or watch some commercial on every connection to captive network.

Example Interaction Upon discovering the URI of the API server, a client connected to a captive network will query the API server to retrieve information about its captive state and conditions to escape captivity. In this example, the client discovered the URI "https://example.org/captive-portal/api/X54PD39JV" using one of the mechanisms defined in . This example illustrates the use of "client-authentication-url" key, and therefore, excludes "user-portal-url" key from the JSON content sent by the API server. An API server may choose to send both the keys based on its policy and configuration. And the client can choose one of them or both to perform the authentication, based on its configuration and capability. To request the Captive Portal JSON content, a client sends an HTTP GET request: The server then responds with the JSON content for that client: Upon receiving this information, the client will use it to start an authentication session with the server (as specified by "client- authentication-url" key) to enable access to the external network. The client sends following HTTP request to begin the authentication: Upon receiving the HTTP request, the server selects appropriate authentication scheme to authenticate the client. This example shows "Bearer" authentication scheme defined in . specifies the list of authentication schemes. The server sends HTTP response message with 401 (Unauthorized) status code along with WWW-Authenticate header: In response to the received challenge, the client sends an access token in the "Authorization" request header using "Bearer" authentication scheme: If the access token is found valid, the server sends a response to the client. An example of such response is: On a successful HTTP authentication, the client SHOULD query the API server again to verify that it is no longer captive. When the client requests the Captive Portal JSON content after gaining external network access, the server responds with updated JSON content:

Security Considerations This document recommends security considerations specified in .

Privacy Considerations This document recommends privacy consideration specified in .

IANA Considerations IANA is requested to add the new key specified in .

References Normative References This document describes an HTTP API that allows clients to interact with a Captive Portal system. With this API, clients can discover how to get out of captivity and fetch state about their Captive Portal sessions. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. In many environments offering short-term or temporary Internet access (such as coffee shops), it is common to start new connections in a captive portal mode. This highly restricts what the user can do until the user has satisfied the captive portal conditions. This document describes a DHCPv4 and DHCPv6 option and a Router Advertisement (RA) option to inform clients that they are behind some sort of captive portal enforcement device, and that they will need to satisfy the Captive Portal conditions to get Internet access. It is not a full solution to address all of the issues that clients may have with captive portals; it is designed to be one component of a standardized approach for hosts to interact with such portals. While this document defines how the network operator may convey the captive portal API endpoint to hosts, the specific methods of satisfying and interacting with the captive portal are out of scope of this document. This document replaces RFC 7710, which used DHCP code point 160. Due to a conflict, this document specifies 114. Consequently, this document also updates RFC 3679. This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] Informative References This document defines an HTTP authentication scheme for Privacy Pass, a privacy-preserving authentication mechanism used for authorization. The authentication scheme specified in this document can be used by Clients to redeem Privacy Pass tokens with an Origin. It can also be used by Origins to challenge Clients to present Privacy Pass tokens.