Authentication in the Virtual Observatory#

Status:

AuthVO 1.0 WD 2025-05-27

Acknowledgments#

1 Introduction#

Historically many services in the VO have operated primarily or entirely in anonymous mode. However authentication and associated authorization are becoming increasingly necessary in the VO, for instance to manage data rights and as an operational necessity for auditing and limiting service usage in the era of science platforms.

Where the client is browser-based a service can often integrate information about the authentication methods required with the web page or web application through which it is accessed.

But a desktop VO client such as Aladin, TOPCAT or Python typically interacts with VO services differently, in one of two ways:

  1. Searches the registry for a service, then makes VO-compliant requests to that service (e.g. TAP)

  2. Is presented with a URL, then retrieves the data from that URL (e.g. DataLink)

In the first, TAP-like, case additional information is available to the client in the form of the Registry record for the service in question, as defined by VOResource [VOResource1.0] and its service-specific extensions. This could in principle contain metadata describing the authentication method along with any required ancillary information such as login endpoints. Even if only the TAP service URL is available (for instance because the user has typed it in rather than acquired it from a Registry search) the VOSI Capabilities endpoint can be reliably located (/capabilities is a sibling of /sync in TAP), so that relevant VOResource information could be retrieved from the VOSI Capabilities document supplied by the service.

However in the second, DataLink-like, case there is no information about where to find a corresponding registry record or VOSI document, or even a guarantee or likelihood that such a record exists. The URL in question may not even have come from a DataLink query, it could simply be a pointer to a protected resource like a FITS file or VOTable in a secured filestore. Such a URL may have been acquired from a VO query in the application wishing to dereference it, in which case some authentication context may be available, but it may equally be read from a VOTable transmitted by SAMP or saved in an earlier session, or obtained from an unrelated application; in other words the application requiring the resource at a URL may have no information about the VO service which produced that URL. Then the only opportunity to acquire information about how to authenticate is by examining the URL itself, or by HTTP communications with that URL.

An authentication method like HTTP Basic (RFC 7617) can be used in this scenario, since all negotiation involving user credentials and permits — request and supply of username and password — is done directly over the HTTP connection from which the resource is requested. More modern/secure/flexible authentication methods however tend to rely on additional interaction with other, unspecified, endpoints prior to the request itself. For instance OAuth2 requires presentation of a Bearer Token to retrieve protected resources from a given URL, but there is no way given only that URL to determine where or how to acquire this token; in a typical OAuth2 usage scenario such information is known up front by the components making the request.

No industry standard mechanism appears to exist to solve the problem of how a client can authenticate without such up-front information. This document therefore proposes some VO-standard mechanisms by which a service can advertise to clients all the information required to authenticate, in particular how to exchange user credentials for an authentication permit, given only the URL for a suitably compliant protected resource.

To address this, this document defines (Section 3 Authentication Schemes) some VO-specific authentication schemes for use in WWW-Authenticate challenges. It also describes (Section 4 Challenge/Response Use in the VO) how to discover the authentication requirements for VO services, and some arrangements for working with optional authentication.

The intent of this document is not to define new authentication mechanisms parallel to pre-existing standards, but to provide missing components that facilitate use of such existing standards from certain VO contexts, especially by non-browser clients. Authenticated services in the VO are not expected to change their authentication frameworks to any “VO-sanctioned” technology, but by implementing the proposals here they can become usable in a broader range of scenarios. VO services however are not required to use any of the mechanisms proposed in this document; if they can establish the client interoperability they require using other mechanisms, or a combination of VO and other mechansisms, they are free to do so.

Given that, as explained above, the VOResource record can only be discovered in some (TAP-like) and not other (DataLink-like) authentication scenarios, it is no longer recommended to base discovery of authentication methods on the securityMethod element defined by VOResource, as described by SSO 2.0. Instead, the proposal here is recommended for both TAP-like and DataLink-like scenarios.

1.1 Role within the VO Architecture#

Fig. AuthVO:fig:archdiag shows the role this document plays within the IVOA architecture [IVOAArchitecture2.0].

AuthVO provides a way to advertise authentication methods associated with existing VO services. For services like TAP TAP that comply with VOSI VOSI to offer service description documents at locations defined by DALI DALI, clients can discover these methods using an up-front query to the VOSI capabilities endpoint. For non-VOSI services such as DataLink [DataLink1.0] such discovery is done reactively.

1.2 Terminology#

The following terms are used with specific meanings in this document:

protected

A service or resource that can only be accessed by authenticated users, or will allow greater levels of access to authenticated users over anonymous users

permit

Information that a client can supply with an HTTP request to prove its authenticated identity; may for instance be a token, cookie or certificate

credentials

Secret information known to a user, such as a username and password, that can be used to acquire a permit

authentication domain

A set of HTTP endpoints sharing the same authentication arrangements; the same permit is applicable to all members of the same domain and should not be presented to endpoints outside that domain

challenge

A structured invitation to authenticate using a particular permit type, presented within a WWW-Authenticate header

authentication scheme

A particular type of challenge with its own rules and syntax

The terms challenge and authentication scheme are defined by RFC 9110 and explained further in Section 2.1 Challenge/Response Framework.

2 Challenge and Response#

The standard way to negotiate authentication over HTTP is using authentication challenges supplied in HTTP responses.

2.1 Challenge/Response Framework#

The basics of authentication over HTTP can be found in section 11 of RFC 9110 [std:RFC9110]; that document obsoletes RFC 7235 [std:RFC7235] which presented an earlier version of this protocol. More detail can be found in those documents, but for convenience the basics are outlined here:

  • An HTTP response may include one or more WWW-Authenticate headers to indicate that authentication is possible. The content of these headers is one or more challenges, each describing how the client can authenticate according to a named authentication scheme.

  • A 401 (Unauthorized) response MUST include at least one such challenge

  • Other (e.g. 200 OK, 403 Forbidden) responses MAY include such challenges

  • The client may use the challenge information to decide how to authenticate itself to the server in subsequent requests. This can be done by supplying the Authorization header with scheme-specific content. In case of multiple challenges, the client is free to choose one.

  • The form of a challenge is:
    <auth-scheme-name> [<scheme-specific-parameters>]
  • The form of the WWW-Authenticate header is:
    WWW-Authenticate: <challenge> [<challenge> ...]

The details of a number of these authentication schemes (<auth-scheme-name> strings and their associated parameters and semantics) are defined in IETF documents, for instance “basic” (RFC 7617 Reschke [std:RFC7617]) “digest” (RFC 7616 Shekh-Yusef et al. [std:RFC7616]) and “bearer” (RFC 6750 Jones and Hardt [std:RFC6750]). RFC 9110 section 11.1 says “New and existing authentication schemes are specified independently and ought to be registered” (with IANA), but it does not say that they MUST be so registered.

2.2 Authentication Schemes in the VO#

Where one of the standard authentication schemes is suitable for use by a particular VO service and its clients, it should be used. For instance Basic or Digest authentication provide all required information about the authentication procedure within the headers, since the client simply supplies (somewhat obscured) username and password to the target service in subsequent requests. If these schemes are used it is highly recommended to require a TLS connection (HTTPS not HTTP) to avoid interception of the credentials.

Services using OAuth2 generally make use of the Bearer scheme. In this case the challenged client supplies a bearer token in subsequent requests, but the challenge provides no information about how to acquire such a token which means it is not suitable for clients lacking prior knowledge about the target service, as described in Section 1 Introduction.

Other methods of authentication over HTTP also exist and are used by VO services, for instance use of cookies and of X.509 certificates. In standard usage these do not use WWW-Authenticate challenges, and again prior knowledge about the service (how to acquire a suitable cookie or certificate) is required by the client to use them.

This document defines in 3.2 VO-Specific Scheme Definitions some VO-specific authentication schemes that solve these problems by supplying the missing information to clients in scheme-specific challenge parameters.

3 Authentication Schemes#

The authentication schemes defined in this section generally define:

  1. How clients are to present a permit in future requests to a service — this is defined by the identity of the scheme

  2. How they are to acquire such a permit — this is communicated by the scheme-specific parameters

Acquiring a permit (such as a cookie, certificate or token) typically requires supplying credentials known to the user (such as a username and password) in a particular way to a particular endpoint. Common parameters describing this activity are given in Section 3.3 Common Challenge Parameters for VO Schemes: access_url for the credential submission endpoint and standard_id for the credential submission method.

3.1 Scope#

A major consideration for these schemes is authentication scope, that is some rule about the domain (set of endpoints) within which an acquired permit is valid. The permit is confidential information and so must not be leaked to services outside the domain. But users may want to access multiple resources within the same domain and should not be made to present their credentials multiple times where not necessary. The client may also be managing multiple permits for multiple different domains at once. So the permit must be delivered with sufficient implicit or explicit scoping information for the client to tell for each subsequent request whether that permit should be presented, i.e. whether it falls within that permit’s domain. The nature and form of this scoping information is scheme-specific.

3.2 VO-Specific Scheme Definitions#

This section describes some custom Authentication Schemes for use in WWW-Authenticate challenges, intended for use within the VO.

3.2.2 #

The ivoa_x509 authentication scheme indicates that the service will accept X.509 client certificates as authentication permits, and optionally describes how to acquire a suitable certificate.

The standard usage model for X.509 certificates is that a person or organisation obtains a certificate from a Certification Authority (CA) once its identification has been verified by a Registration Authority.

A client in posession of a client certificate can then use it to sign TLS (HTTPS) connections, and the service can examine the signature to authenticate the identity of the client. Such authentication will succeed if the service trusts the signing CA.

Scheme name:

ivoa_x509

Parameters:

  • access_url (optional) — indicates where to get a suitable certificate, see Section 3.3.1

  • standard_id (required iff access_url is present) — indicates how to authenticate at access_url, see Section 3.3.2

Login response (if used):

PEM-encoded X.509 certificate chain including private key

Scope:

Origin of challenge URL

The ivoa_x509 challenge exists in two forms: with and without the access_url/standard_id parameter pair. These optional parameters advise the client how to obtain a certificate for use within the domain of the challenge if it does not already have one.

For either form of the challenge, if the client is in possession of a certificate signed by a CA it expects the service to trust, it may use it to sign requests to protected resources within the domain of the challenge.

If the client does not hold any such certificate, and the access_url/standard_id pair is present, it may obtain one by presenting credentials to the endpoint given by the access_url parameter, in the form defined by the standard_id parameter. If authentication is successful, a 200 OK response must be returned whose body is an X.509 certificate chain including its private key, in PEM format. The Content-Type header of this response should be “application/x-pem-file”. If authentication fails, a 401 or 403 response should be returned. Once in possession of the returned certificate, the client can use it to sign subsequent requests to protected resources. Certificates obtained in this way may not be usable in all X.509 contexts (i.e. may not be signed by a widely trusted CA), but should be usable within the domain of the current challenge.

Since client certificates achieve authentication by signing requests using public key cryptography, they cannot be stolen by third parties, so there are no security issues associated with attempting to use them to access services outside of the intended authentication domain. However using them for inapplicable services is inefficient and clumsy so some scoping is desirable. The authentication domain of a certificate acquired using this scheme is considered to be the Origin of the URL from which the challenge was received. Origin is defined by section 4.3.1 of RFC 9110 and is a normalised triple of URI scheme, hostname, and port.

There is an example in Section 5.3 Mandatory authentication with certificates.

3.3 Common Challenge Parameters for VO Schemes#

Authentication schemes described in Section 3.2 VO-Specific Scheme Definitions rely on a stage where the user “logs in” by exchanging credentials (a username and password) for a permit. This section defines scheme parameters that tell the client exactly where and how to present these credentials. The content of the response is scheme-specific.

3.3.1 #

This parameter reports where to log in: the value is the endpoint at which exchange of user credentials for a permit takes place.

3.3.2 #

This parameter explains how to log in: it defines the protocol for exchanging user credentials for a permit. Username and password are supplied in the HTTP request as described below, and the response returns a scheme-specific permit. Currently defined values are:

ivo://ivoa.net/sso#BasicAA

The Basic Authentication scheme defined by RFC 7617 is used to authenticate. It is STRONGLY RECOMMENDED to use this over HTTPS not HTTP, since the username and password are transmitted without encryption.

ivo://ivoa.net/sso#tls-with-password

The username and password are presented using a POST request over an HTTPS connection. These items are passed as the values of parameters “username” and “password” respectively, transmitted in application/x-www-form-urlencoded format.

3.4 Bearer Tokens#

Bearer Tokens form the permit for the OAuth2 authorization framework, which is used by a number of VO data providers. A bearer token is an opaque string; in order to use one, the client simply presents the token following the keyword “Bearer” in an Authorization HTTP request header, as described by RFC 6750.

Various methods of token acquisition are defined by OAuth2 and associated standards, but at time of writing it’s not clear which if any of these are suitable for use by clients lacking prior knowledge of the services for which they are intended, and no standard scoping mechanisms seem to be defined.

This document does not therefore currently recommend any way in which non-browser VO clients can use Bearer Tokens, but it is hoped that progress will be made on this in future.

4 Challenge/Response Use in the VO#

4.1 Authentication Modalities#

VO services can behave in three different ways with respect to authentication:

No authentication:

all access is anonymous

Mandatory authentication:

anonymous access is always rejected, but once authenticated, user requests may be successful (subject to authorization)

Optional authentication:

anonymous requests may succeed, but authentication is possible and service behaviour may differ for anonymous and authenticated access; for instance a TAP service may expose more tables or relax usage limits for authenticated users

The standard HTTP rules for authentication cover the cases of no authentication and mandatory authentication: if a client requests a resource for which it is not authenticated, the response should return a 401 Unauthorized code with an associated WWW-Authenticate challenge (or possibly a 403 Forbidden, optionally with a challenge).

To cover all three cases, including allowing clients to determine that authentication may be an option before presenting a possibly lengthy query, VOSI-compliant services should implement the following behaviour for both GET and HEAD requests to their VOSI-capabilities endpoint:

  • No authentication: return 200

  • Mandatory authentication: return 401/403 with one or more WWW-Authenticate challenges

  • Optional authentication: return 200 with one or more WWW-Authenticate challenges

VO clients can then probe the capabilities endpoint using an HTTP HEAD or GET request to find out whether an authentication attempt should be required or offered to the user, prior to making queries on the service.

4.2 Client Behaviour#

Given the rules in Section 4.1 Authentication Modalities, client requests to potentially authenticated URLs should fall into one of the following categories:

Anonymous

A client with no capability to authenticate operates in Anonymous mode. Any attempt to retrieve protected resources will fail.

Reactive

An unauthenticated client requiring a resource simply requests it anonymously. If the request is successful (typically an HTTP 200 OK response, perhaps via some 3xx redirects), no authentication is attempted. However, if the response is a 401 or 403 accompanied by one or more supported challenges, the client chooses a challenge it is prepared to use, and negotiates challenge-specific authentication as described above. On successful authentication, the acquired permit is used to retrieve the resource, and is also cached alongside its domain for future use. In case of a 401 or 403 without any challenges supported by the client, or if authentication fails, retrieval of the resource fails.

Proactive

Once a client has authenticated to a domain, it should accompany any subsequent request to a resource in the same domain with the permit that it has cached from that domain. In this way, the user is not required to present credentials multiple times for the same domain.

Preemptive

When talking to a VOSI-compliant service that may provide optional authentication, the client should first probe the VOSI-Capabilities endpoint using a HEAD or GET request. In case of a 401 or 403 response it should require the user to authenticate using one of the presented challenges, cache the permit, and make subsequent requests to that service in Proactive mode; if that authentication fails then the service cannot be used. In case of a 200 response it should check the response for challenges; if a supported challenge is present it may give the user the option to authenticate, and if successful cache the permit and make subsequent requests in Proactive mode. If no challenges are present (no authentication), or if the user elects not to authenticate, or if optional authentication fails, it should make subsequent requests in Anonymous or Reactive mode.

When using a VOSI-compliant service like TAP, an authentication-capable client should initially probe the capabilities in preemptive mode. For all other requests it should check whether the URL belongs to any of the domains for which it has a cached permit, and query in reactive or proactive mode accordingly.

4.3 Authentication Confirmation: X-VO-Authenticated#

The case of optional authentication presents the question of how a client knows whether it is authenticated or not. Since a service with optional authentication can return a successful (200 OK) result to both an authenticated and unauthenticated client, the client cannot use the HTTP response code to determine whether an authentication attempt has been successful.

It is therefore RECOMMENDED that services include the header X-VO-Authenticated, with a value giving the client’s authenticated identity, in all responses to an authenticated client, and especially in response to any intial authentication attempt. Responses to unauthenticated clients MUST NOT contain this header.

4.4 Compatibility with other VO Standards#

Section 4.1 Authentication Modalities of this document makes use of HEAD requests to the capabilities endpoint, but VOSI 1.1 VOSI only requires capabilities to support GET. If a client finds that HEAD is not supported (405 Method Not Allowed) it may assume that optional authentication is not in place.

Section 4.1 Authentication Modalities also allows a GET or HEAD request to the capabilities endpoint to result in a 401 Unauthorized or 403 Forbidden failure, but VOSI 1.1 Section 2 and TAP 1.1 Section 2.2 both require the capabilities endpoint to be accessible anonymously.

The SSO 2.0 recommendation SSO requires that protected services record their authentication requirements via a element in their VOResource record. This document does not align with SSO 2.0, and elements are no longer required or recommended.

A service implementing the behaviour described here may therefore be forced into conflict with existing VO documents. Future evolution of those documents may act to resolve this conflict.

4.5 Limitations#

This document does not currently make explicit provision for expiry of permits. Use of an expired permit will probably look like an authentication failure (401), so clients may simply try to re-authenticate in such a case. In some cases scheme-specific expiry information may be supplied with a permit. Future versions of this document may tackle this in more detail.

5 Examples#

This section contains examples of communications between clients and authenticating services. Client behaviour is represented using the command-line HTTP client curl; this means that the HTTP headers of the query are not shown in the examples, but they can be examined by repeating the curl invocations with the –verbose flag. The “-D -” flag causes response headers to be shown. Some of the non-essential headers have been removed for the sake of brevity, and some line-breaks imposed for readability.

5.1 Reactive authentication with HTTP Basic Authentication#

Request a resource anonymously:

% curl -D - https://example.org/data/release/table99.vot
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Gormenghast"
Content-Type: text/plain

Please log in.

This gives a 401 Unauthorized response with a standard Basic challenge (RFC 7617). We therefore resubmit the query with a username and password:

% curl --user gertrude:xxxx -D - https://example.org/data/release/table99.vot
HTTP/1.1 200 OK
X-Vo-Authenticated: gertrude
Content-Type: application/x-votable+xml

<?xml version='1.0' encoding='utf-8'?>
<VOTABLE version="1.5" ...
...
</VOTABLE>

We can then use the same permit (encoded username and password) preemptively for other resources within the same domain (defined in this context by RFC 7617 as locations in the same directory or its descendants):

% curl --user gertrude:xxxx -D - https://example.org/data/release/image101.fits
HTTP/1.1 200 OK
X-Vo-Authenticated: gertrude
Content-Type: application/fits

SIMPLE  =                    T / Standard FITS format ...
...

There is nothing VO-specific about this example.

5.2 Optional authentication with cookies#

Probe the VOSI-capabilities endpoint of a TAP service to check for authentication modality (Section 4.1 Authentication Modalities):

% curl --head https://gea.esac.esa.int/tap-server/tap/capabilities
HTTP/1.1 200 OK
Content-Type: text/xml;charset=UTF-8
WWW-Authenticate: ivoa_cookie standard_id="ivo://ivoa.net/sso#tls-with-password",
                              access_url="https://gea.esac.esa.int/tap-server/login"

The 200 OK response with a challenge means that optional authentication is available. We choose to authenticate. The ivoa_cookie challenge is recognised (Section 3.2.1 ) with standard_id of tls-with-password (Section 3.3.2 ), so transmit user credentials by POSTing username and password parameters to the access_url:

% curl -D - --data username=gertrude --data password=xxxx \
       https://gea.esac.esa.int/tap-server/login
HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=474DEF8CBB046D47294; Path=/tap-server; Secure; HttpOnly
Content-Type: text/plain; charset=UTF-8

OK

The response comes back with a cookie in the header. We use this for subsequent requests to the same domain (as defined by Path and other relevant parameters in the returned Set-Cookie header in accordance with RFC 6265):

% curl -D - --header 'Cookie: JSESSIONID=474DEF8CBB046D47294' \
       https://gea.esac.esa.int/tap-server/tap/async
HTTP/1.1 200 OK
X-VO-Authenticated: gertrude
Content-Type: text/xml;charset=UTF-8

<?xml version="1.0" encoding="UTF-8"?>
<uws:jobs  xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0">
  <uws:jobref id="1726835528535O" > ... </uws:jobref>
  ...
</uws:jobs>

5.3 Mandatory authentication with certificates#

Probe the VOSI-capabilities endpoint of a TAP service to check for authentication modality (Section 4.1 Authentication Modalities):

% curl --head https://abc.example.net/tap/capabilities
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer
www-authenticate: ivoa_x509
www-authenticate: ivoa_x509 standard_id="ivo://ivoa.net/sso#BasicAA",
                  access_url="https://xyz.example.net/cert/generate"

The 401 Unauthorized response means that authentication is required to access the service. The Bearer challenge (RFC 6750) means we can authenticate with a Bearer Token if we have or know how to get one, but we don’t. The unparameterised ivoa_x509 challenge means the client can, in principle, authenticate with a certificate from any valid CA and not just one issued by the endpoint in the parameterised challenge. Without having such a certificate however we can use the parameterised ivoa_x509 challenge (Section 3.2.2 ) which advises one way to acquire a suitable certificate. It has a standard_id of BasicAA (Section 3.3.2 ) so we transmit user credentials using HTTP Basic Authentication to the access_url:

% curl --user gertrude:xxxx -D - https://xyz.example.net/cert/generate
HTTP/1.1 200 OK
x-vo-authenticated: gertrude
content-disposition: inline; filename="cert.pem"
content-type: application/x-pem-file
strict-transport-security: max-age=63072000

-----BEGIN CERTIFICATE-----
MIIEYzCCAkugAwIBAgIHAJ7opoSjuDANBgkqhkiG9w0BAQsFADBWMQswCQYDVQQG
EwJDQTEZMBcGA1UECAwQQnJpdGlzaCBDb2x1bWJpYTENMAsGA1UECgwEQ0FEQzEd
...
5/tPtFk=
-----END CERTIFICATE-----

The response is a PEM-encoded client certificate, which we copy to a local file, gertcert.pem. This can then be used to sign subsequent requests to the same service:

% curl --cert gertcert.pem -D - https://abc.example.net/tap/async
HTTP/1.1 200 OK
x-vo-authenticated: gertrude
content-type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<uws:jobs xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" ...>
  ...
</uws:jobs>

Appendices#

A Changes from Previous Versions#

No previous versions yet.