==================== Authentication in the Virtual Observatory ==================== :Status: AuthVO 1.0 WD 2025-05-27 .. role:: raw-latex(raw) :format: latex .. .. _`AuthVO:acknowledgments`: Acknowledgments =============== .. _`AuthVO:sec:intro`: 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: #. Searches the registry for a service, then makes VO-compliant requests to that service (e.g. TAP) #. 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 :doc:`VOResource <../VOResource/VOResource>` :cite:p:`2008ivoa.spec.0222P` 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 :doc:`TAP <../TAP/TAP>` service URL is available (for instance because the user has typed it in rather than acquired it from a Registry search) the :doc:`VOSI <../VOSI/VOSI>` Capabilities endpoint can be reliably located (``/capabilities`` is a sibling of ``/sync`` in :doc:`TAP <../TAP/TAP>`), so that relevant :doc:`VOResource <../VOResource/VOResource>` information could be retrieved from the :doc:`VOSI <../VOSI/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 :doc:`VOSI <../VOSI/VOSI>` document, or even a guarantee or likelihood that such a record exists. The URL in question may not even have come from a :doc:`DataLink <../DataLink/DataLink>` query, it could simply be a pointer to a protected resource like a FITS file or :doc:`VOTable <../VOTable/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 :doc:`VOTable <../VOTable/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 :ref:`AuthVO:sec:authschemes`) some VO-specific authentication schemes for use in ``WWW-Authenticate`` challenges. It also describes (Section :ref:`AuthVO:sec:cr-use`) 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 :doc:`VOResource <../VOResource/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 :doc:`VOResource <../VOResource/VOResource>`, as described by :doc:`SSO <../SSO/SSO>` 2.0. Instead, the proposal here is recommended for both TAP-like and DataLink-like scenarios. .. _`AuthVO:role-within-the-vo-architecture`: 1.1 Role within the VO Architecture ----------------------------------- .. container:: float :name: AuthVO:fig:archdiag .. raw:: latex \centering `role_diagram.pdf `__ Fig. :ref:`AuthVO:fig:archdiag` shows the role this document plays within the IVOA architecture :cite:p:`2021ivoa.spec.1101D`. AuthVO provides a way to advertise authentication methods associated with existing VO services. For services like :doc:`TAP <../TAP/TAP>` :doc:`TAP <../TAP/TAP>` that comply with :doc:`VOSI <../VOSI/VOSI>` :doc:`VOSI <../VOSI/VOSI>` to offer service description documents at locations defined by :doc:`DALI <../DALI/DALI>` :doc:`DALI <../DALI/DALI>`, clients can discover these methods using an up-front query to the :doc:`VOSI <../VOSI/VOSI>` capabilities endpoint. For non-VOSI services such as :doc:`DataLink <../DataLink/DataLink>` :cite:p:`2015ivoa.spec.0617D` such discovery is done reactively. .. _`AuthVO:terminology`: 1.2 Terminology --------------- The following terms are used with specific meanings in this document: .. raw:: latex \todo{MT: Are these OK? Do they align with established usage? Are there better choices?\\ BM: I haven't heard use of 'permit' before, but it seems like a good choice to me.} 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 :ref:`AuthVO:sec:challenge-response`. .. _`AuthVO:challenge-and-response`: 2 Challenge and Response ======================== The standard way to negotiate authentication over HTTP is using authentication challenges supplied in HTTP responses. .. _`AuthVO:sec:challenge-response`: 2.1 Challenge/Response Framework -------------------------------- The basics of authentication over HTTP can be found in section 11 of RFC 9110 :cite:p:`std:RFC9110`; that document obsoletes RFC 7235 :cite:p:`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: | `` []`` - | The form of the ``WWW-Authenticate`` header is: | ``WWW-Authenticate: [ ...]`` .. raw:: latex \todo{ Do we need to worry about 407 and proxy-authenticate? I don't {\em think\/} so. } The details of a number of these authentication schemes (```` strings and their associated parameters and semantics) are defined in IETF documents, for instance “``basic``” (RFC 7617 :cite:t:`std:RFC7617`) “``digest``” (RFC 7616 :cite:t:`std:RFC7616`) and “``bearer``” (RFC 6750 :cite:t:`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. .. _`AuthVO:authentication-schemes-in-the-vo`: 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 :ref:`AuthVO:sec:intro`. 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 :ref:`AuthVO:sec:voschemes` some VO-specific authentication schemes that solve these problems by supplying the missing information to clients in scheme-specific challenge parameters. .. _`AuthVO:sec:authschemes`: 3 Authentication Schemes ======================== The authentication schemes defined in this section generally define: #. How clients are to present a permit in future requests to a service — this is defined by the identity of the scheme #. 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 :ref:`AuthVO:sec:common-params`: ``access_url`` for the credential submission endpoint and ``standard_id`` for the credential submission method. .. _`AuthVO:sec:scope`: 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. .. _`AuthVO:sec:voschemes`: 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. .. _`AuthVO:sec:ivoa-cookie`: 3.2.1 :raw-latex:`\mbox{\tt ivoa\_cookie}` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``ivoa_cookie`` authentication scheme indicates that the service will accept cookies as authentication permits, and describes how to acquire such cookies. Scheme name: ``ivoa_cookie`` Parameters: :raw-latex:`\mbox{}` - ``access_url`` (required) — indicates where to get the cookie, see Section :ref:`AuthVO:sec:access-url` - ``standard_id`` (required) — indicates how to authenticate at ``access_url``, see Section :ref:`AuthVO:sec:standard-id` Login response: ``Set-Cookie`` header Scope: As defined by RFC 6265 Cookies are text strings received in the ``Set-Cookie`` response header of some HTTP exchange, and presented via the ``Cookie`` request header of subsequent requests to the same service. This procedure is defined in RFC 6265 :cite:p:`std:RFC6265`. A parallel mechanism using the ``Set-Cookie2`` and ``Cookie2`` headers was also defined by an earlier version of the cookie protocol defined in RFC 2965 :cite:p:`std:RFC2965`, but this is now deprecated and rarely used. To use this scheme, the client must present a username and password 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 including a ``Set-Cookie`` header containing one or more cookies suitable as an authentication permit. If authentication fails, a 401 or 403 response should be returned. Once in possession of the returned cookie or cookies, the client can present them in a ``Cookie`` header as defined by RFC 6265 for subsequent requests to protected resources. If multiple cookies were received, they should all be presented. Cookies come with an associated scope, defined by the content of the ``Set-Cookie`` header in conjunction with RFC 6265, so compliant cookie-handling libraries are able to determine the domain for a given cookie. There is an example in Section :ref:`AuthVO:sec:cookie-example`. .. _`AuthVO:sec:ivoa-x509`: 3.2.2 :raw-latex:`\mbox{\tt ivoa\_x509}` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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: :raw-latex:`\mbox{}` - ``access_url`` (optional) — indicates where to get a suitable certificate, see Section :ref:`AuthVO:sec:access-url` - ``standard_id`` (required iff ``access_url`` is present) — indicates how to authenticate at ``access_url``, see Section :ref:`AuthVO:sec:standard-id` 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. .. raw:: latex \todo{ I've made up this tentative scoping rule for certificates without wider consultation. It's what the AUTH library currently does. Could use Protection Space like Basic Auth instead of Origin, which just aggregates a Realm with the Origin. Realm is not currently one of the parameters of this scheme, but it could be added if anybody thought it was worth while. } There is an example in Section :ref:`AuthVO:sec:x509-example`. .. _`AuthVO:sec:common-params`: 3.3 Common Challenge Parameters for VO Schemes ---------------------------------------------- Authentication schemes described in Section :ref:`AuthVO:sec:voschemes` 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. .. _`AuthVO:sec:access-url`: 3.3.1 :raw-latex:`\mbox{\tt access\_url}` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This parameter reports where to log in: the value is the endpoint at which exchange of user credentials for a permit takes place. .. _`AuthVO:sec:standard-id`: 3.3.2 :raw-latex:`\mbox{\tt standard\_id}` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. .. raw:: latex \todo{ These {\tt standard\_id} values are defined by the (obsolete?) SSO 2.0 standard. It would make more sense if they were owned by this document, but at time of writing these values are already in use in (a few) deployed services, so it could be painful to change them. } .. _`AuthVO:bearer-tokens`: 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. .. _`AuthVO:sec:cr-use`: 4 Challenge/Response Use in the VO ================================== .. _`AuthVO:sec:modalities`: 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 :doc:`TAP <../TAP/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. .. _`AuthVO:client-behaviour`: 4.2 Client Behaviour -------------------- Given the rules in Section :ref:`AuthVO:sec: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 :doc:`TAP <../TAP/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. .. _`AuthVO:authentication-confirmation-x-vo-authenticated`: 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. .. raw:: latex \todo{Or should this header only be required for initial login?} .. _`AuthVO:compatibility-with-other-vo-standards`: 4.4 Compatibility with other VO Standards ----------------------------------------- Section :ref:`AuthVO:sec:modalities` of this document makes use of HEAD requests to the capabilities endpoint, but :doc:`VOSI <../VOSI/VOSI>` 1.1 :doc:`VOSI <../VOSI/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 :ref:`AuthVO:sec:modalities` also allows a GET or HEAD request to the capabilities endpoint to result in a 401 Unauthorized or 403 Forbidden failure, but :doc:`VOSI <../VOSI/VOSI>` 1.1 Section 2 and :doc:`TAP <../TAP/TAP>` 1.1 Section 2.2 both require the capabilities endpoint to be accessible anonymously. The :doc:`SSO <../SSO/SSO>` 2.0 recommendation :doc:`SSO <../SSO/SSO>` requires that protected services record their authentication requirements via a :raw-latex:`\xmlel{SecurityMethod}` element in their :doc:`VOResource <../VOResource/VOResource>` record. This document does not align with :doc:`SSO <../SSO/SSO>` 2.0, and :raw-latex:`\xmlel{SecurityMethod}` 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. .. _`AuthVO:limitations`: 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. .. _`AuthVO:examples`: 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. .. _`AuthVO:reactive-authentication-with-http-basic-authentication`: 5.1 Reactive authentication with HTTP Basic Authentication ---------------------------------------------------------- Request a resource anonymously: .. raw:: latex \footnotesize :: % 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: .. raw:: latex \footnotesize :: % 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 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): .. raw:: latex \footnotesize :: % 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. .. _`AuthVO:sec:cookie-example`: 5.2 Optional authentication with cookies ---------------------------------------- Probe the VOSI-capabilities endpoint of a :doc:`TAP <../TAP/TAP>` service to check for authentication modality (Section :ref:`AuthVO:sec:modalities`): .. raw:: latex \footnotesize :: % 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 :ref:`AuthVO:sec:ivoa-cookie`) with ``standard_id`` of ``tls-with-password`` (Section :ref:`AuthVO:sec:standard-id`), so transmit user credentials by POSTing ``username`` and ``password`` parameters to the ``access_url``: .. raw:: latex \footnotesize :: % 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): .. raw:: latex \footnotesize :: % 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 ... ... .. _`AuthVO:sec:x509-example`: 5.3 Mandatory authentication with certificates ---------------------------------------------- Probe the VOSI-capabilities endpoint of a :doc:`TAP <../TAP/TAP>` service to check for authentication modality (Section :ref:`AuthVO:sec:modalities`): .. raw:: latex \footnotesize :: % 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 :ref:`AuthVO:sec:ivoa-x509`) which advises one way to acquire a suitable certificate. It has a ``standard_id`` of ``BasicAA`` (Section :ref:`AuthVO:sec:standard-id`) so we transmit user credentials using HTTP Basic Authentication to the ``access_url``: .. raw:: latex \footnotesize :: % 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: .. raw:: latex \footnotesize :: % curl --cert gertcert.pem -D - https://abc.example.net/tap/async HTTP/1.1 200 OK x-vo-authenticated: gertrude content-type: text/xml ... Appendices ========== .. _`AuthVO:changes-from-previous-versions`: A Changes from Previous Versions ================================ No previous versions yet.