Skip to content
Browse files
Spec: Add more context about OAuth2 to the REST spec (#4843)
  • Loading branch information
rdblue committed May 23, 2022
1 parent feeb94b commit c8d66d66d57d60847babaa2532a95e656dc2a476
Showing 1 changed file with 40 additions and 1 deletion.
@@ -126,11 +126,42 @@ paths:

- Auth API
- OAuth2 API
summary: Get a token using an OAuth2 flow
operationId: getToken
Exchange credentials for a token using the OAuth2 client credentials flow or token exchange.

This endpoint is used for three purposes -

1. To exchange client credentials (client ID and secret) for an access token
This uses the client credentials flow.

2. To exchange a client token and an identity token for a more specific access token
This uses the token exchange flow.

3. To exchange an access token for one with the same claims and a refreshed expiration period
This uses the token exchange flow.

For example, a catalog client may be configured with client credentials from the OAuth2
Authorization flow. This client would exchange its client ID and secret for an access token
using the client credentials request with this endpoint (1). Subsequent requests would then
use that access token.

Some clients may also handle sessions that have additional user context. These clients would
use the token exchange flow to exchange a user token (the "subject" token) from the session
for a more specific access token for that user, using the catalog's access token as the
"actor" token (2). The user ID token is the "subject" token and can be any token type
allowed by the OAuth2 token exchange flow, including a unsecured JWT token with a sub claim.
This request should use the catalog's bearer token in the "Authorization" header.

Clients may also use the token exchange flow to refresh a token that is about to expire by
sending a token exchange request (3). The request's "subject" token should be the expiring
token. This request should use the subject token in the "Authorization" header.
@@ -468,11 +499,19 @@ paths:
Load a table from the catalog.

The response contains both configuration and table metadata. The configuration, if non-empty is used
as additional configuration for the table that overrides catalog configuration. For example, this
configuration may change the FileIO implemented used for the table.

The response also contains the table's full metadata.

The catalog configuration may contain credentials that should be used for subsequent requests for the
table. The configuration key "token" is used to pass an access token to be used as a bearer token
for table requests. Otherwise, a token may be passed using a RFC 8693 token type as a configuration
key. For example, "urn:ietf:params:oauth:token-type:jwt=<JWT-token>".
$ref: '#/components/responses/LoadTableResponse'

0 comments on commit c8d66d6

Please sign in to comment.