IVOA SSO profile: architecture
Version 0.1

IVOA WG Internal Draft 2005 May 11

Working Group:
Guy Rixon


Status of this Document

This is a Working Draft. The first release of this document was 2005 May 11.

This is an IVOA Working Draft for review by IVOA members and other interested parties. It is a draft document and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than "work in progress.

A list of current IVOA Recommendations and other technical documents can be found at http://www.ivoa.net/Documents/.



1. Introduction

This specification defines a way of supporting access control for services in the IVO. It defines the interfaces between user agents (programmes with UIs such as desktop applications and web portals), payload services (those which give access to resources used in science, e.g. DAL services and VOStores) and general agents (clients making requests to services, e.g. workflow executors).

Two sorts of interfaces are defined:

  1. services provided just to support access control;
  2. additions or changes to payload services that enable access control .

2. Assumptions

The architecture is to provide single-sign-on (SSO) authentication in the sense that signing on once per interactive session via a particular UI 'unlocks' all access right across the virtual observatory that have been pre-arranged for a given user for use via that UI. This is an absolute requirement; however, detailed wording of the requirement. There is another interpretation of SSO authentication that is less restricted: signing on once per interactive session in any conforming UI unlocks all rights (as above) for all UIs run by the same user in that session. This is a desirable feature but is harder to achieve. The current architecture does not explicitly achieve it.

Users are registered and given access rights in the virtual observatory according to their membership of on-line communities and of groups within those communities. The arrangements for this, and the underlying trust model for authentication, are discussed in a companion document [Trust model].

Users sign on to the IVO by supplying to passwords to their user agents and having the agents forward the passwords to the communities. In return, the agents receive credentials to use when authenticating to services.

Authentication of software agents to services is by means of digital signatures. The validity of the signatures is ensured using a public-key infrastructure (PKI) which supplies the agents with identity warrants signed by certificate authorities (CAs). [SSO introduction].

Secured access to payload resources follows a three part process.

  1. Payload service determines and authenticates the identity of the software agent requesting access. This is not the identity of the user for whom the agent acts and it varies between agents acting for the same user.
  2. Payload service obtains 'attributes' stating the access that has been delegated by the user to the agent.
  3. Payload service makes an authorization decision based on the attributes.
User's attributes are considered to be public. The system need not keep them secret, but must not allow them to be changed inappropriately.

The indirection between agent identity and user identity is there to give flexibility. Not all agents working for the same user need have the same level of delegated access. The names that CAs allow in identity warrants may not be the preferred form known to payload services.

The SSO system allows delegation of (part of) a job between software agents and thus allows agents to delegate (some of) their access rights. This is a requirement; it is not sufficient to assume that user agents always talk directly to payload services and that there is no onward communication. Therefore, any payload service may choose to act as an agent and the SSO system must allow for this.

Payload services may be either stateless or stateful. 'Stateful' means that the service distinguishes and remembers information supplied by different clients. 'Stateless' means that all information supplied by clients is either pooled and applied to all subsequent requests, or that such information is discarded after each request is processed. Since the SSO system must work for stateless services, the architecture cannot be based on building up state over several messages; e.g. protocols that delegate credentials to an agent in one request for use in a subsequent (e.g. [Rixon1], [Rixon2]) do not work in all necessary cases. Instead, the delegation process must be part of existing requests to the delegates.

3. Components and interfaces

Figure 3.1 shows the principal software components in the SSO system and indicates the places at which they run. 'Community site' is any institution managing a community of users; there will be many of these. 'Portal site' is any running a web portal.

Deployment diagramFigure 3.1

The community site is shown as running some Shibboleth components [Shibboleth]. This allows a community to exploit an existing Shibboleth installation (e.g. Campus infrastructure provided by the parent university), and reduces the amount of code needed in the IVO-specific services of the community. Standard Shibboleth is not sufficient for IVO needs (see [Shibboleth critique] for a discussion), so the community also runs other services developed by and for the virtual observatory movement. The IVOA services at the community act as a facade for Shibboleth services. Therefore, community can choose to implement all its functions in IVO-specific code without using Shibboleth.

Figure 3.2 shows the relevant interfaces supported by the components. These are all interfaces to on-line services rather than in-process calls to objects. 'Methods' in these interfaces are implemented as operations on SOAP services or service endpoints in REST services.

Component diagramFigure 3.2

The dependencies between agents and services at the top of figure 3.2 represents a typical chain of delegation. There is a pure client (driven directly via its UI, a pure service, and an intermediate agent. These might be, respectively, a desktop application, a DAL service and a VOStore; see Annex A for more details of this particular case. The exact number of links in this chain will vary between use cases.

The user agent, agent and service components in figure 3.2 supply objects of the classes in figure 3.3. Each communicating entity is either a UserAgent with a UI or a PayloadAgent; a pure payload service is a special case of a PayloadAgent that does not make requests to other services. Each class also has the ability to generate a cryptographic key-pair which will be used for authentication. This function is not exposed in a public method but is used inside the agent. The agent generates its own key-pair when needed, and keeps the private key in memory for the agent's lifetime. In this system, private keys are never committed to disc or passed to other agents or services.

Class diagram for agentsFigure 3.3

The Payload interface represents the interfaces provided by payload services, e.g. SkyNode or VOStore. Access to Payload may be authenticated using X.509 certificates supplied by the community; this is the basic access that the SSO system is protecting. The SSO system extends Payload with extra semantics; it does not add any new methods and it does not add any extra interfaces to payload services.

The SignOnUI interface represents the UI controls for entering the user name and password. Since this interface is present on the user agent, not on the community services directly (because one user may run many user agents from the same account), the SignOnUI also needs the name of the community where signing on can be processed. This can be given either as part of the user-name  or as a separate datum.

The community component supplies an object of the type shown in figure 3.4. It contains the CA certificate used to sign agents' certificates, as discussed in the trust model [Trust model]

Class diagram for community interfacesFigure 3.4

The CertificateService interface returns X.509 certificates in response to authenticated requests. Authentication to this interface can be by password (for user agents signing in) or by certificate (for agents renewing time-limited certificates) or by presentation of a delegation token (for delegation of rights between agents; see below) .

The AttributeService interface on the community supplies attributes as SAML assertions (i.e. SAML statements digitally signed by the community) in response to SAML queries. Requests to this interface need not be authenticated.

The DelegationService allows one agent to delegate its access rights to another agent. An authenticated request to this interface returns a delegation token that can be passed in a call to Payload on the subordinate agent. The subordinate can then use the delegation to authenticate to the CertificateService at the community.

The shibboleth-origin component in figure 3.2 represents the services specified by Shibboleth for the origin site. These are defined in the Shibboleth architecture [Shibboleth architecture] and their internal structure is not of interest here.

The AttributeService interface on the Shibboleth installation has the same syntax as that on the community, so, to first order, requests to the latter can be passed through unchanged to the former. However, Shibboleth installations do not regard attributes as publically readable by default, so the community may need to authenticate to the Shibboleth service. The exact means of authentication may vary from site to site. Since IVO communities will be matched one-for-one with Shibboleth installations, this variation is manageable.

The SignOnService interface on the Shibboleth installation processes authentication requests and returns SAML assertions containing SAML authentication statements. In doing so, it typically requires the requesting agent to authenticate using the user's SSO user-name and password (the exact protocol for this authentication is a bizarre kludge made necessary by Shibboleth's awkward design parameters). The community calls this interface when an agent signs on to the system, in order to get the SAML subject from the returned SAML assertion. This subject is the used to make the name in the certificate returned by the  CertificateService. When the SignOnService issues a SAML assertion, it links the SAML subject of the assertion to the user's attributes. Thereafter, for the lifetime of the SAML assertion, the SAML subject may be used as a key to look up attributes in the Shibboleth AttributeService.

4. Procedures

4.1 Signing on to the VO at a community

A user enters user name (including community name) and password into a UI. Figure 4.1 shows the subsequent sequence of events.

Sequence diagram for user signing onFigure 4.1

The UserAgent authenticates to the SSOService with the user's SSO name and password. The IVO SSOService passes these on to the Shibboleth SSO service (see below for details) and receives a SAML assertion containing a SAML authentication statement. The IVO SSO service extracts the subject of this statement and uses the name therein as a handle for the UserAgent. The name given by Shibboleth is an opaque string. The only assumption that the IVO SSO service can make about this string is that it has never been issued in any other SAML assertion.

The Shibboleth object associates the handle given in the SAML assertion with the attributes of the named user, such that subsequent calls to the Shibboleth attribute service can retrieve the user's attributes by giving the handle.

The IVO SSOService creates an X.509 identity certificate using the handle given by Shibboleth. The exact encoding of the handle in the certificate is TBD in a later draft of this specification, but it must be possible to extract the Shibboleth handle from the distinguished name in the certificate in a standard way. The certificate contains the public key given by the UserAgent; this matches the private key created and held by that agent. The SSOService signs the certificate using its CA key and returns it to the UserAgent. The certificate is held in memory by the UserAgent and discarded along with the private key when that agent exits.

If the community does not use Shibboleth, then the SSOService generates handles internally and associates them with user attributes in local storage. The rest of the use case is the same as with Shibboleth.

4.2 Authenticating to a service

4.2.1 SOAP service

An UserAgent which has previously signed on at a SSOService and thus has a certificate and private key, needs to make a request to a restricted service. Figure 4.2.1 shows the sequence of events for a web service where the request to the PayloadAgent is an XML document; this covers SOAP services.

Sequence diagram for agent authenticating to web serviceFigure 4.2.1

The UserAgent first gets the user's attributes from the SSOService. It does this by making a SAML request in which the subject is the handle from the agent's current certificate. The attributes come back in a SAML assertion signed with the community's CA key. The agent doesn't need to understand this assertion as it is passed on unchanged to the payload service.

If the community is using Shibboleth, the SSOService in the IVO facade delegates the SAML request to the Shibboleth attribute-service.

The agent requests service at the PayloadAgent. It includes in the request document a digital signature using its current certificate; this proves that the messages comes from an entity entitled to use the handle in the certificate. The PayloadAgent checks this signature and also checks that the certificate is signed by a CA (or chain of CAs) that the payload site trusts. If no problems are found, the PayloadAgent has authenticated the UserAgent's handle.

The PayloadAgent doesn't know a priori how to map from the UserAgent's handle to the local accounts under which the request can be executed. Therefore, the UserAgent includes in the request the SAML assertion containing the user's attributes. The PayloadAgent works out the mapping from the attributes. The assertion should include the following attributes.

From this information, the PayloadAgent makes an authorization decision on the request for service. Note that the final decision is always made at the payload site. The community cannot over-rule the payload site to allow more access than the service provider has authorized.

The PayloadAgent trusts the SAML assertion because it is signed by the community CA (which the PayloadAgent trusts) and because the subject of the assertion is the handle which the PayloadAgent has just authenticated.

Typically, the PayloadAgent has pre-arranged accounts for groups in the community in question. Therefore, the PayloadAgent reasons as follows.

  1. I trust the signatory of the assertion, so I accept that the assertion truly applies to its subject.
  2. The subject of the assertion is the authenticated handle from the certificate, so I accept that the assertion applies to the sender of the request.
  3. The assertion includes a delegated-rights-to-user-account attribute, so I accept that the access is on behalf of that user.
  4. The user concerned is a member of groups x, y and z, and group y has an account on this site.
  5. Group y has the appropriate access for the request, therefore I accept the request.

A few PayloadAgents, notably VOStores, may work with individual user-accounts rather than group accounts. In this case, steps 1..3 are the same and a followed by a test of the access rights of the user account.

The request to the PayloadAgent carrys the certificate, the signature and the SAML assertions in the SOAP header, in the encoding specified by the WS-Security standard.

4.2.2 REST service

If the PayloadAgent is a REST service or similar, such that it cannot accept an XML document as a request, then an alternative means of sending the attributes is needed. Figure 4.2.2 shows the sequence of events.

Sequence diagramfor authentication to REST serviceFigure 4.2.2

Instead of the UserAgent calling for the attributes, the PayloadAgent calls the SSOService to get them. The PayloadAgent has to infer the location of the SSOService from the information in the request.

In general, it is not possible to include a digital signature in a request to a REST service. Instead, the UserAgent establishes an HTTPS connection to the PayloadAgent with client authentication by certificate. This associates a form of digital signature with the request in a secure way. The PayloadAgent needs to retrieve the UserAgent's certificate (or at least the handle from the certificate) in order to make the link with the AttributeService.

4.3 Delegating all rights to a subordinate agent


4.4 Delegating specific rights to a subordinate agent


Annex A:  Example of delegation: use of VOStore via DAL service


Annex B: details of the community-Shibboleth interaction



[Rixon1] Guy Rixon, Possible IVO security architecture for 2005, http://wiki.astrogrid.org/bin/view/Astrogrid/SecurityArchitectureFor2005

[Rixon2] Guy Rixon, Delegation of a user's identity to software agent, http://wiki.astrogrid.org/bin/view/Astrogrid/IdentityDelegation

[Shibboleth] Internet 2 project, Shibboleth web-site, http://shibboleth.internet2.edu/

[Shibboleth critique] Guy Rixon, Review of Shibboleth v0.1, http://www.ivoa.net/internal/IVOA/IvoaGridAndWebServices/shibboleth-review-v0.1.html

[Shibboleth architecture] Scott Cantor (ed), Shibboleth architecture: protocols and profiles, http://shibboleth.internet2.edu/docs/draft-mace-shibboleth-arch-protocols-latest.pdf

[SSO introduction] Guy Rixon, Single-Sign-On Authentication for the IVO: introduction and description of principles v0.1, http://www.ivoa.net/internal/IVOA/IvoaGridAndWebServices/SSO-introduction.htm

[Trust model] Guy Rixon, IVOA SSO profile: trust model v0.1, http://www.ivoa.net/internal/IVOA/IvoaGridAndWebServices/trust-model-v0.1.html