Skip to content

Latest commit

 

History

History
261 lines (182 loc) · 10.4 KB

ivoa-oauth.md

File metadata and controls

261 lines (182 loc) · 10.4 KB

Proposed ivoa-oauth challenge

Aims

  1. Allow use of existing off-the-shelf OAuth 2.x/OIDC authentication providers

    a. This implies minimal changes to any of the standard flows/grants

  2. Must work for non-browser clients

    a. Non-browser clients should not be required to call out a browser, nor run a web server for redirects (this covers situations where clients are running on a remote server or are otherwise unable to contact a browser directly)

  3. Fit in with SSO-next

    a. This could either go into SSO-next directly, or be published as a separate note

Definitions

  • OAuth 2 Authorization Server (from RFC 6749): The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

  • OAuth 2 Resource Server (from RFC 6749): The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.

    • In the VO context, this would be a TAP/SCS/etc. service.

  • OAuth 2 Client (from RFC 6749): An application making protected resource requests on behalf of the resource owner and with its authorization.

    • In the VO contact, this would be Aladin, pyvo, TOPCAT and similar clients (as would be expected).

  • RFC 6749: The OAuth 2.0 standard. Note that usage of Bearer is covered in RFC 6750. There are numerous extensions/additions/modifications on top of this. OAuth 2.1 is still in draft form, but merges in most of these extensions.

  • OpenID Connect Core 1.0: This is an extension of RFC 6749 which adds profile/identity related information. Usually this is abbreviated as OIDC (for Open ID Connect).

  • OpenID Connect Discovery 1.0: Allows for finding out what the endpoints are of an OIDC provider.

  • OpenID Connect Dynamic Client Registration 1.0: Allows for acquiring a client_id and client_secret.

  • RFC 8628: The Device Authorization Grant.

  • RFC 8414: Authorization Server Metadata. This is the OAuth 2.x version of OpenID Connect Discovery, and aims to be compatible with it.

  • RFC 7591: This is the OAuth 2.x version of OpenID Connect Dynamic Client Registration. There is a companion RFC RFC 7592.

  • RFC 8252: OAuth 2.0 for Native Apps.

    • As will be discussed, this is not written for apps outside the two mobile platforms.

  • VO Discovery Service: A new service which aims to be a minimal bridge between OAuth 2.x/OIDC Authorization servers and VO Clients that are not browser-based.

ivoa-oauth challenge (normative)

The ivoa-oauth challenge proceeds in 4 phases:

  1. The www-authenticate challenge containing the required information to find the appropriate VO Discovery Service from the OAuth 2.x resource server.

  2. The acquisition of the client_id and client_secret along with metadata from the VO Discovery Service.

  3. The acquisition of the access_token from the OAuth 2.x authorization server.

  4. The use of the access_token with the original OAuth 2.x resource server.

The www-authenticate challenge from the OAuth 2.x resource server

Following the framework outline in SSO-next, OAuth 2.x resource servers supporting the ivoa-oauth challenge should return the following header:

www-authenticate: ivoa-oauth discovery_url="https://<url of VO discovery service>"

Multiple services can use the same VO discovery service.

The URL used MUST be the discovery endpoint of the VO discovery service: redirects should be avoided as much as possible (validators should warn if a redirect is used).

discovery_url must be provided, there is no default discovery URL.

Multiple ivoa-oauth challenges may be provided, though if a resource server does provide multiple challenges, it is up to the resource server to disambiguate the access_tokens, clients are free to choose any of the VO discovery services provided.

The VO discovery service

The VO discovery service must provide two endpoints:

  1. A discovery endpoint, only accepting GET requests

  2. A registration endpoint, only accepting POST requests

The discovery endpoint

The discovery endpoint MUST return a JSON document with the following keys:

  • registration_url: the registration endpoint for this VO discovery endpoint

  • allowed_domains: the list of domains that any access_token that is acquired can be used against (as the use of cookies in responses lacks standardisation in the OAuth 2 space).

  • supported_grant_types: the list of supported grant types from https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml or as otherwise defined. urn:ietf:params:oauth:grant-type:device_code MUST be in that list.

  • device_authorization_endpoint: As per RFC 8414, the endpoint to get the device code.

  • token_endpoint: As per RFC 8414, the endpoint to get the access token.

The following additional keys may be provided:

  • oauth2_discovery_url: The URL of the authorisation servers OAuth 2 discovery endpoint (this should be provided when additional grant types are supported).

  • oidc_discovery_url: The URL of the authorisation servers OIDC discovery endpoint (this should be provided when additional grant types are supported).

  • allow_bearer: A boolean representing whether Bearer may be used for access_tokens against resource which are managed by this service. This exists solely to simply code that uses off-the-shelf libraries to handle OAuth2/OIDC (COMMENTARY: we may want to drop this anyway, if services would find this painful to support?).

The registration endpoint

The client must POST a JSON document with the following keys to the registration endpoint:

  • client_name: A human readable string to identify the client.

  • grant_types: A list containing a subset of the supported_grant_types that the returned access_token will be used for.

Additional keys may be specified as per RFC 7591 and OpenID Connect Dynamic Client Registration. We note that redirect_uris is optional given that redirect flows are problematic for the target clients, but that developers of VO discovery services should verify the behaviour of their systems where redirect flows are attempted using clients registered through their service.

The VO discovery service will return JSON with at least the following keys (as per RFC 7591 and OpenID Connect Dynamic Client Registration):

  • client_id

Additional keys may be returned as per RFC 7591 and OpenID Connect Dynamic Client Registration.

Acquiring the access token

Using the client_id and the device_authorization_endpoint and token_endpoint, RFC 8628 (Device Authorization Grant) should be followed to get the access token. No VO specific steps are required.

Using the access token

Following the SSO-next recommendation, the access token should be provided in the header with authorization field like authorization: ivoa-oauth <token> where <token> is replaced by the token. If allow_bearer was specified, then Bearer as per RFC 6750 can be used, in order simplify how clients manage the access and refresh tokens.

Discussion and commentary

The name ivoa-oauth

This name could be changed (would ivoa-oauth2 work in clients, currently none of the other standard challenges have numbers in their name), but ivoa-bearer was not used because it is plausible that other challenges might also use bearer tokens, and to avoid there being ambiguity around what the aim of the challenge was.

RFC 8252

RFC 8252 would sound like it would address the needs of the VO, but as can be seen by reading it, the focus of the RFC is to push back on the usage of web-views on mobile platforms, and there is minimal applicable advice to the VO (though VO client implementers may which to read it to understand the "vibe" of the groups providing commercial authentication servers).

Avoiding use of existing discovery and client registration protocols

Given that there is substantial overlap with the existing discovery and client registration protocols, why create our own. There are two main reasons, driving mainly by the aim to allow existing authentication servers:

  1. The existing providers may not implement one or both of the existing discovery protocols, and neither of the discovery protocols cover all the information that the VO Discovery Service does (and requiring the modification of an existing provider to also include the required information also has the same problem)

  2. The existing providers may not implement one or both of the client registration protocols, and existing providers generally have very basic policy options (if any) around client registration. By specifying a minimal registration protocol, we avoid possible issues with existing providers.

Requiring the availability of the Device Authorization Grant

Looking to the future of OAuth 2.x, where the Implicit Grant and the Resource Owner Password Credentials Grant are being removed, the Device Authorization Grant is the only standardised grant that works outside a browser. Hopefully new standardised grants are developed and supported which address the need to authenticate without a browser while being both secure and usable.

Use of JSON

Given the pre-existing use of JSON in the OAuth/OIDC ecosystem, JSON was chosen as the format used to avoid bringing in any additional dependencies.

Not requiring more fields in discovery endpoint

The aim is to put as minimal requirements on both clients and service providers as possible. Only the required information to perform the Device Authorization Grant is required, and if additional grants would be used, using an off-the-shelf library which accepts the client_id and the discovery endpoint (either the OAuth2 or OIDC URL) is a better path to go down, rather than something bespoke.