Community Accounts Protocol Version 3

Introduction

The accounts protocol governs a web service giving access to certain aspects of a user account in the Virtual Observatory. The protocol is an AstroGrid standard, supported by the community web-application and the AR. The web service is RESTful and uses HTTPS.

Version 3 of the protocol has three functions:

• the client may retrieve the user's proxy certificate;
• the client may enquire the URI of the user's home space;
• the client may change the password protecting the user's account.

"The user's proxy certificate" means a certificate chain including credentials stored for that user in the community service and starting with a proxy certificate matching a private key held by the client. "Retrieving the user's proxy certificate" means signing on to the virtual observatory.

"The user's home space" is a location in VOSpace that acts as a home directory for that user. It is the root of that user's VOSpace tree and is long lived (c.f. other. temporary VOSpaces that a user might own). Users registered in AstroGrid communities have exactly one home space as a matter of course.

The accounts protocol is a replacement for the SOAP contracts "Security Service" and "Policy manager" in earlier versions of the community.

Web resources

The protocol is RESTful, and involves a tree of web resources grown from a common root. In the current implementation of of the community web-application, this root is called accounts and is at the top level of the web application. This is a good convention, but the protocol does not require it; any web resource may be the root.

Below the root, there is one child-resource for each user in the community. The names of these second-tier resources are, identically and with case sensitivity, the names by which users log in to the community. E.g.

  /accounts/gtr
  /accounts/KonaAndrews

Each of these resources is created when the user is registered in the community. The means of creation is not part of the accounts protocol itself; other protocols in the community do this.

Beneath each web-resource representing a user there may be a child resource representing the user's certificate chain. Since the certificate chains provided by the community usually end in RFC3820 proxy-certificates, this resource has the URI /proxy relative to the user resource. The proxy resource is present if the user has a certificate chain (provided by the community's certificate authority) and absent otherwise. E.g.

  /accounts/KonaAndrews/proxy

The user's home space is represented by a resource with the URI /home relative to the user resource. This resource is present if the user's account has a home space. E.g.

  /account/KonaAndrews/home

Representations of the resources

The accounts resource and the resources representing users do not have representations in the current version of the protocol.

The proxy resource is represented as a certificate chain in PkiPath format as defined in RFC 4366, section 8. This is a DER-encoded sequence of X.509 certificates in which each element is the signatory for the preceding element. The MIME type is application/pkix-pkipath.

The certificate chain is available in two forms. The static form lists the certificates stored permanently for that user by the community. The ephemeral form adds to the static form an RFC-3280 impersonation proxy generated by the community using a public key provided with the request; this extra certificate comes first in the chain. The ephemeral form is used for signing on. The static form can be used to look up the user's formal identity.

The home space resource has no representation. Requests to this resource are redirected to the actual location in VOSpace.

HTTP operations

HTTP-GET on a proxy resource obtains the static form of the certificate chain (see above for definition).

HTTP-POST to a proxy resource obtains the ephemeral form of the certificate chain, provided that the following parameters are correctly provided.

• key: an RSA public key, provided in PEM format;
• password: the account password, undigested;
• lifetime: the duration, in whole seconds, for which the proxy certificate at the head of the chain is to be made valid.

HTTP-GET on a home resource causes an HTTP redirect to the home space. I.e., the home space location is reported as the Location header of the response. Since the home-space URI is normally in the vos scheme or the ivo scheme, the client cannot follow the redirection in the normal HTTP manner but must use VOSpace protocols as appropriate.

HTTP-POST to a user resource can change the user's password provided that the following parameters are correctly provided.

• oldPassword: the current password, undigested;
• newPassword: the replacement password, undigested.

The value of the oldPassword parameter must match the user's current password; if it does not, then the password is not changed. The new password must be at least seven characters long.

Security

Since the account passwords are sent as request parameters, the accounts protocol should use HTTPS endpoints.

Registration

In the IVO registry, a community indicates its support of the accounts protocol by registering a service capability with standardID="ivo://org.astrogrid/std/Community/accounts". This is a basic capability; there are no special metadata, and no schema, specific to the accounts protocol.

In the capability, the interface is of type ParamHTTP. The AccessURL has the attribute use="base" and is the URL to the root resource described above. The version attribute of the interface element must be set to 2. Absence of this attribute implies that the interface follows the CommunityAccountsProtocolVersion1.

How to sign on: a guide for developers of clients

The smart way to sign on is to use the code provided in the AR, which abstracts the accounts protocol. If you can't do that, and need to use the accounts protocol directly, this is the procedure.

Get the user-name, account password and community name from the user. You may also need to ask for the duration of validity of this session; or you can default that to, say, 24 hours.

Find the endpoint for the accounts service. Look in the registry for the community's registration. You are looking for a resource whose identifier contains the given community name and which has a capability with standardID="ivo://org.astrogrid/std/Community/accounts". Read the AccessURL from the capability: this is the URI for the "root" resource of the accounts protocol in that community.

Find the URI for the user's certificate chain. To the URI of the root resource, add a slash, then the user name, then /proxy.

Open a connection to the certificate-chain resource. It's normally an HTTPS connection, and the server is probably securing the connection with a self-signed certificate or a certificate signed by an academic certificate-authority; your SSL infrastructure won't trust this certificate by default. Normal practice here is to use SslWithoutServerAuthentication, assuming that the endpoint is trustworthy because it's in the IVO registry. You could, alternatively, make sure that your client trusts the community's specific certificate, or all certificates issued by the community's chosen CA. If the connection is plain HTTP, you might want to abort, reckoning that your user's password shouldn't be transmitted on an unencrypted connection.

Generate a key pair. The keys should be RSA keys.

Post an HTTP(S) request to the certificate chain resource. Send as parameters the public key generated in the previous step, the password, and the duration of validity of the session. The key needs to be in PEM format (DER encoding re-encoded in base 64, with header and trailer lines; the JDK can't do this for you, try org.bouncycastle.openssl.PEMWriter if you don't want to write your own implementation). The parameters need to be URL-encoded; in particular, the key will typically be corrupted in transmission if this is not done.

If the response code is 200, read the response body: this is the certificate chain. Parse the response body as MIME-type application/pkix-pkipath (java.security.cert.CertificateFactory can do this directly from the input stream).

If the response code is 404, that user has no credentials. You can't fix this in the client and you have to abort.

Assuming a 200 response and successful parsing, your client now holds a certificate chain. The first element is an RFC-3820 proxy matching the private key you generated earlier. There will be at least two certificates in the chain and there may be more.

The chain is anchored on a root certificate provided by the community. You need to obtain this be some other means; the accounts protocol doesn't supply it. Obtaining the trust anchor is supposed to be configuration of the client rather than something done each time the user signs on.

With the certificate chain, trust anchor and private key, you can authenticate the user's identity in requests to IVO services.

Future extensions to the protocol

The root resource should have a representation which is a list of known users. Posting to this resource might be a way to add a user, if the security arrangements can be worked out satisfactorily.

The user resources should have a representation which summarizes the account, possibly as a key-value pairs in a properties file. It might then be appropriate to allow updating the account by putting this representation.

There should be some standard way of obtaining the trust anchors, both that associated with the server's host certificate and that anchoring the user's certificate-chain.

-- GuyRixon - 06 Aug 2008