Relationship Cards

Higgins Report 19 September 2009

Paul Trevithick <>


Relationship cards are a kind of Information Card designed to allow a person to initiate the creation of a data sharing relationship between a card issuer that has some data and a relying party that wishes to gain access to it. R-Cards leverage the user-centric and security characteristics to bootstrap the relationship. Unlike traditional Information Cards R-cards support a persistent, dynamic data connection wherein the relying party can dynamically request the latest data values.

Status of this document

DRAFT 0.51

This document is an analysis provided by the authors and carries no endorsement by the Eclipse Foundation. Please send comments to the author.


This document describes work that has been underway within the Eclipse Higgins Project for the last few years. Over that time the ideas behind relationship cards (r-cards) have co-evolved with the implementation work. As we put the ideas to code, the ideas were refined and reworked. Although a full reference implementation is not yet complete, the concepts have matured sufficiently, and seem stable enough that this document can be used to share the ideas and receive feedback from a wider audience.

While the work describe here may be applicable more broadly, relationship cards are focused set of problems and solutions in the realm of what might be call personal identity management.

Work on r-cards has benefited greatly from the rich discussion in the general area of digital identity that has been going on in a number of venues. R-cards are consistent with what is often called user-managed or user-centric identity wherein as much control as possible is shifted to the end user. Examples of thinking along this line include Cameron’s Laws of Identity, and the OECD’s Properties of Identity. Of particular note is Blakley’s Relationship?? Title [X]. Many of the ideas in that paper are shared by those of us working on r-cards.

The inability to move identity information over the net in any makes it stay in sync with friends and colleagues in any open, standardized way. Lacking an interoperable identity and relationship layer, social network sites (e.g. Facebook, LinkedIn, etc.) partially solve this problem using a centralized architecture. The result is walled gardens that have terms of service wish huge asymetries as to the relative rights of the user vs. the silo. As has been widely discussed, he person’s data is free flow into the silo, but not out. For a further discussion of the end-user experience challenges on the Web see

A point of view shared by many within the identity industry is that the situation just described is caused by the lack of an Internet-wide identity layer that individuals, websites and web services can rely on. Creating such a layer is enormously complex due to the range of societal, legal, regulatory, privacy-related, security, and technical dimensions that must be considered. Further, it can't be owned or controlled by any one firm but must instead be created by open collaboration between the many stakeholders.

R-cards have been designed to be consistent with the architectural principles that are gradually emerging for this identity layer. This document focuses on the r-card user metaphor, their XML representation, and how they relate to so-called identity providers and relying parties

User-Permissioned Data Sharing

R-cards provide permissioned, user-controlled, sharing digital data sharing of identity information such as a person's interests, preferences, affiliations, as well as relationships with other people, friends and organizations.

A person either creates their own r-card filling in claim values or downloads one from an issuer website that manages a set of claims on the user's behalf. When the person goes to a website that accepts r-cards they can "send" the r-card to the site. In this way the user gives the website the ability to not only know the current values of the attributes/claims but also the permission to periodically fetch the latest values whenever they are needed without having to explicitly ask each time. At any time the user can "cut the cord" and disallow the site access to any further updates.

R-Cards and Digital Identities

A person can be said to have a composite digital identity. This identity is the combination multiple personas that the person chooses to employ in various contexts. In different contexts the same natural person may engage in relationships with others as a father, an employee, a patient, resident of Second Life, and a character on a WII game console. In each context the person engages with different sets of “others”. Sometimes the other is a website. Sometimes the "other" is a person (or, more correctly, a digital representation of some aspect of that person).

An r-card is a representation of a single digital identity. If the digital identity is not resident on your computer or in a web service that you control, then the r-card instead of actually containing the digital information, acts as a pointer to it. We call this a managed r-card because the identity data it represents isn't stored in the XML of card itself, it is managed external to the card (e.g. in Facebook or an enterprise directory, or in a Gmail address book) and pointed to by the card. In the case where the identity data (i.e. a set of attributes) is stored within the r-card XML the card is called a personal r-card.

Since these managed identities are stored in different kinds of data stores, using a variety data formats and schemas, and are accessed using different network protocols, it is clear that r-cards employ a very abstract notion of a pointer. This pointer is implemented as a URI that supports discovery of the metadata necessary to dereference the URI across a range of wire protocols to a data object and discover in a common schema metamodel the schema it conforms to. We will return to these details later.

Extending IMI Information Cards

The data sharing ideas that motivated the design of r-cards were the centerpiece of the original vision for Higgins in 2003-2004. In 2005 members of the Higgins team were introduced to the Information Card ideas being pioneered by Kim Cameron and his team at Microsoft. Between Higgins and Microsoft was a shared a belief that virtual, visual cards in a virtual electronic wallet could be a good metaphor for digital identity and that a common metaphor was needed. There was a shared a belief that the user should be at center of the flow of information; in the notions of user-centricity. And there was a shared belief that an open, distributed architecture was required based on standardized protocols and that there should be no centralization (other than perhaps at the user). As a result we immediately recognized that Kim's Information Cards could be a foundation for r-card data sharing if used in a specific way. The Relationship card is in essence a profile of Information Cards.

Of key importance is that the strong cryptographic foundations of basic Information Cards provide a mechanism to bootstrap the trust necessary to initiate a more intimate, dynamic and potentially bi-directional data sharing relationship between two parties exploited by r-cards.

Over the years Microsoft, IBM and others have contributed to the OASIS Identity Metasystem Interoperability TC the protocols for Information Cards. Numerous public interoperability demonstrations have been held, and an ecosystem has emerged around the technology. In 2008 the Information Card Foundation was founded by founding members including Microsoft, Equifax, PayPal, Oracle, Novell, Google, Deutche Telekom, Azigo and others.

The rest of this section assumes a familiarity with the OASIS IMI [X] specifications. For readers not familiar with it, a primer is found at the end of this document

As has been described, a card can be thought of as either containing a Digital Identity as in the case of a personal i-card, or holding a pointer to a digital identity as in the case of a managed card. When imported into a Card Selector the user can "send" these (personal or managed) cards to a Relying Party (RP). This has the effect of sending a security token containing claims about the digital identity to the RP. In this user-managed manner, the RP requests a set of claims and the user releases a matching set and conveys them to the RP.

...explain about how this PKI foundation bootstraps trust...

The same process of releasing claims about digital identity can be performed using an r-card. However, if the RP requests the special "r-card" claim, called "resource-udr", and if the user consents to release, the RP will gain the value of the resource-udr claim. The resource-udr claim is different from most claims, wherein the value is a literal (e.g. a name or postal code) and can be used directly. Instead the value of the resource-udr claim is a reference. It is a pointer that can be dereferenced over the network to the entity whose attributes define the digital identity of the card. The resource-udr claim references an entity object, analogously to how a URL references an HTML document in the Web. The referenced entity is a data object described by the Higgins context Data Model that consists of a set of Attributes.

Dynamic values. By providing a reference to this entity to the RP, the card issuer is creating a durable connection from the RP to the entity such that the RP can request at any time the latest values of these attributes. Although it is true that this connection can be severed either by the user or the card issuer at any time, while it has not been severed, the RP can request the most up-to-date values of the claim.

Read/write access. The r-card enables the RP to not only read the latest values attributes, but it may enable the RP to write some or all of these attribute values. The attribute-by-attribute permissioning is controlled by the access control policy of the card issuer. By contrast, regular, non-relationship, cards have claim values that are read-only.

NOTE: In Higgins 2.0 at present we only support a coarse-grained access control model. Each r-card points to a data set (called aa context). One party is authorized to write the data-set, and multiple named parties (on an access control list) are authorized to read the data set.

Managed Relationship Cards

We will first describe the connection between a managed card and its associated Security Token Service (STS). Using the same framework we then describe the connection between a managed r-card and its associated STS as well as its associated Attribute Service (AS).

Managed Card and STS

Shown below is an instance of a managed card and its associated STS. The card XML contains, among other things, an endpoint reference (EPR) and a CardId string. This EPR is the network address of the card's associated STS. When the card was originally generated this EPR and CardId were written into the card XML and are immutable. As shown above the entire card can be thought of as a kind of human-friendly pointer. This pointer points to what we'll call an account object in the STS. The STS maintains a separate account for each card.

When the card is imported into a selector, and the user "sends" it to the Relying Party (RP), the selector sends a request message to this STS. This request asks for for a security token containing a set of attributes or claims. This request includes the CardId (the entire "pointer"). The STS may use any method at all to generate these claims, and they may be dependent on the claims contained in the request, and/or other external factors. But in the case of interest here, the STS is acting as a claim authority "about" the entity resented by the account. The STS retrieves claim values from this account and encodes them into the security token object that it returns.

One last point about these claims. The card itself contains a list of the types of claims it "supports." A card might support a "first name" and a "last name" claim as well as a "frequent flyer" claim. These claims define the types of the values that will be returned in the token generated by the STS. In a selector-based interaction the RP defines the set of claims (both required and optional) and the selector/user choose a card that supports these claim types. The selector then requests a token with these claims from the STS.

We have just described the basics of how all managed cards and their STSes interrelate. We now describe an STS with the same external behavior, but a different internal architecture.

Managed Card and AS-based STS

Shown below is our now familiar managed card pointing to its STS as before. What's different is that this STS has delegated the storage of the account claims to a separate Personal Data Store referred to here as an Attribute Service (AS). Like the STS itself, the AS (PDS) is a separate web service. The account object in this design holds a network resolvable reference to an entity in some context managed by the AS. This reference is called an entity UDI and is described more fully later.

This layered design has the advantage that the AS service provides an abstraction over one or more data sources and thereby provides a separation of concerns. The STS can now focus on handling the token request messages and generating tokens. It delegates to the AS the issues of access to underlying data stores. The AS provides a common API for data access across a range of alternative data sources and technologies. An AS could, for example, have a connector to an LDAP store and the STS above is shielded from knowing anything about how to access an LDAP store. This is two layer design is used by both the Higgins STS IdP and the Higgins SAML2 IdP with the exception that in both cases the "upper" STS portion directly consumes the IdAS java interfaces, as opposed to using a looser, network connection to a "real" AS web service.

With this design, when the STS receives a request for a token, it resolves the request to the account object. It resolves the entity UDI to an entity and its containing context "container" and retrieves one or more attributes from the entity. These are the values that it embeds in the security token that it generates and returns.

We're now at the end of our discussion of managed cards and we've set the stage for a discussion of how managed r-cards fit into the same framework.

Managed R-Card and AS-based STS

In the diagram below we've switched the managed card for a special kind of managed card, the managed r-card. As before the entire card acts as a kind of pointer to an STS and within it an account. This is the same as before. And shown in red is the other pointer, the entity UDI held by the account object and pointing to the entity.

Different from a managed card, a managed r-cards always supports a special claim called resource-udr. If the RP lists resource-udr as a required claim, the selector will only display cards that support this claim, i.e. managed r-cards. If the RP lists this claim as optional then the user may have a choice of sending a managed r-card or regular card.

We now walk through a specific scenario to illustrate how the R-Card, the STS and AS interact. Let's presume that the RP, in addition some regular claims also requires the resource-udr claim. Further, let's assume that the user clicks (and thus "sends") the r-card that is shown below. The selector will request a token from the STS and include the resource-udr as one of the claims that must be returned in the generated token. The request will, as before, include the CardId and thus identify the card's specific account object that is to be the source of the claim values.

The STS gets the value of all of the regular claims from the entity object in just the same way it would if it had been a managed card. What's different is how the value of the resource-udr claim is handled. Instead of retrieving the value from the entity, it simply uses the entity UDI as the value of the resource-udr claim.

When the RP receives the token, in validates it and then extracts the values of the claims. By returning the entity UDI as the value of the resource-udr claim, the RP now has the network, resolvable address of the entity. As a consequence it can attempt (at any time) to retrieve the (current) value of the attributes of this entity. This direct data access is shown in the diagonal red line above.

We mentioned that the STS can return the entity UDI directly. But it may instead return an inline XRD. If during the complete UDI-to-entity resolution process the entity UDI resolves as a first step to an XRDS document, then rather than returning the entity UDI the STS may return the XRD section from within that XRDS document. This optional approach is useful in situations where the AS wishes (e.g. for security reasons) to keep the contents of the XRD private and only visible to authorized parties.

Personal Relationship Cards

Personal r-cards are personal cards that have a resource-udr claim. Unlike relationship managed cards, personal cards contain within themselves the values of claims. Thus personal r-cards contain both the resource-udr claim and its value.

The value of the resource-udr is a dereferenceable pointer to an entity

Note: In some implementations the card itself is represented by an entity and instead of pointing to some other entity, the resource-udr points to the entity of card itself. Special care must be applied to access control so that consumers of this resource-udr are not allowed to update (or worse still delete) the attributes of this entity that describe the card itself!

The resource-udr claim

From a file format point of view, any i-card that supports the claim is an r-card. See ICF Claim Catalog for more information about this claim type.

The value of the resource-udr claim is either an entity UDI or an "inline" XRD document as would normally be found in a standalone XRDS container document.

A UDI is a string (URI, XRI, or Cool URI) that somehow can be dereferenced to point to a data element, in some data store over some network protocol. In r-cards the UDI is always an entity UDI, that is, it always points to a digital object called an entity in some data source called a context as described in an abstract data model called the Higgins Data Model. (HDM)

We used the term "abstract" regarding the data model, because the physical data source is almost undoubtedly not already in HDM. A data service must be employed to map the data in the underlying "real" data store to the abstract model.

The Higgins project has implemented such a data service, both as a local Java interface and as a web service. The former is called IdAS and the latter the Attribute Service. Any system that wishes to support r-cards must use a service that abstracts away the underlying data model and presents the data in the HDM. In the HDM objects are called entities, (with associated attributesthat are stored in containers called contexts

If the value of the resource-udr is an entity UDI then then the UDI resolution process is performed. If the RP (or any other party) wishes to use IdAS [X] to resolve the Higgins IdAS UDI Resolution component can be used.

If, on the other hand, the UDI value is an XRDS document, then this document provides all of the information necessary for resolve the entity without first dereferencing an UDI to get to this document as is done as the first step in UDI resolution.

R-Card Schema

This section describes the data schema of the card itself. Please not that this is distinct from the data schema (in CDM) of the data object to which it points.

Required Card Claim

The r-card itself must support the following claim.

claim The value of this claim is either an inline XRD that contains a UDI pointer, or it is just UDI pointer to a data object


An r-card inherits from its managed card basis a linear set, S1, of claim type URIs supported by the STS. The semantics of these claims are unchanged from normal managed cards: the issuer defines the maximal set of supported claims; the actual set of claims encoded in a security token is some or all of this maximal set of claims.

The target entity to which the r-card's resource-udi claim points has a schema consisting of a linear set, S2, of attribute type URIs. To reduce confusion in this document we call S2 attributes as opposed to the S1 claims

The S2 schema may be retrieved by dereferencing the entity UDI (e.g. using Higgins IdAS) and querying the schema of the context containing the entity


  1. Every member (claim/attribute type URI) of S1 is also member of S2. [The converse isn't necessarily true. That is, S2 may be a superset of S1].
  2. For any member of S2 that is also a member of S1, the data type of the value(s) of the attribute must be restricted to the set of allowed claim value types defined by the managed card specifications.
  3. The data type of attributes in S2 that are not also a member of the S2 set of claims, are not limited to those defined by the managed card specifications. [For example, these S2-only attributes may have complex, structured values.]

Claim vs. Attribute values

The value(s) of a claim in S1 (as returned in a security token) is not guaranteed to be the same as the value(s) of the corresponding attribute in S2. This is due to the fact that S2 attributes are dynamic and thus may vary over time. Best practice is that at any given point in time the values should be the same.

Example Entity and Context Objects

TODO: this section should not show an r-card that is itself represented within the CDM model. That's confusing and irrelevant for this paper. Need to redraw the image so that the r-card is "outside" of the context and pointing into it!

The following diagrams show a sample r-card (and the entity to which it points, and that entity's containing context):

As you can see the context, in addition to having attributes such as "appDescription", etc. also has a context-wide appParam with a single attribute/value of a postal code "02467" (perhaps all of the r-cards issued that point to this context are to organize a neighborhood block party!). The "Sample_R-Card" could have been in any context, but the Sample_entity_for_Sample_R-Card is contained in the context shown above. It shows the appEnabled attribute as true (enabled). It also has its own appParameter_Set with the two attributes foaf:firstName and foaf:gender.

Disjunction: Context vs. Entity Attribute URIs

This section describes a constraint on the design and implementation of contexts containing r-card entities and the entities to which these r-cards. point.

Relying parties must be able to request both entity and context attributes. For them to be able to do this the card must advertise its list of supported attributes (claims). Since both entity and context attributes are mixed together in the same list, we need some way to tell them apart.

To resolve this, we impose this attribute naming constraint:

  1. The set of context URIs and the set of entity URIs must be disjoint.

Implications for RPs: RPs that choose to access attributes using the resource-udr entity UDI must remember to look for a given attribute value on both the entity pointed to by the resource-udr, as well as its containing context.


  1. entity UDI through IdAS to an IEntity. sample code for resolution. More discussion of IdAS
  2. r-cards implementations in the wild
  3. r-cards and ID-WSF
  4. r-cards and OpenID
  5. r-cards and LOD
  6. r-cards and authentication: e.g.: Because an r-card sets up a data sharing relationship that extends outside the boundaries of the exchange of a security token associated with the card (i.e., the current managed and/or personal card functionality), the RP receiving the r-card must authenticate to the attribute service hosting the target entity. See the Higgins Attribute Service 1.1 for a discussion of authentication issues.
  7. r-cards and access control. IdAS implementation
  8. r-cards and access management: unsolved challenges: UMA, etc.
  9. r-cards and backwards compatibility with CardSpace.A great deal of emphasis has been placed on making sure that r-cards are backward and forward compatible with the i-cards defined by the OASIS IMI TC [X]. Explain how r-cards gracefully degrade when used with non r-card capable selectors.
  10. ...lots more...

APPENDIX: An Information Card Primer

System Components

I-cards are enabled by a browser add-on called an identity selector as shown in the illustration below. This selector acts as a kind of digital wallet holding a set of visual i-cards. Both commercial and open source selectors are available today in versions compatible with IE, Firefox and Safari browsers and compatible with Microsoft Windows™, Apple OSX™ and Linux operating systems. The CardSpace™ selector ships with Microsoft Vista™ and has been available since early 2007. Other commercial selectors are available from Novell (DigitalMe™) and Azigo both of which are based on the open source Eclipse Higgins code base.


Information Card Components

The Azigo Higgins selector relies on a hosted I-Card Web Service as shown below that, among other things, synchronizes cards across a single user’s multiple browsers and devices

Cards are issued by an issuing website as shown above. This site makes them available to users as downloadable links. Issuing sites also implement a Token Service that generates security tokens as requested by the selector when the user attempts to use the issued card at a relying site. Commercial Token Service offerings have been announced by IBM Tivoli, and others.

The relying Website is a site that may capable of accepting i-cards for sign in, payment, age verification, or other purposes. Two small changes are required in the site to make it i-card compatible. First the site must add a few lines of HTML to their site that indicates the set of attributes, called claims, required by the site. Second, the site must be able to validate a security token when it is posted to the site via the user’s browser and selector.

Generic I-Card User Experience

In brief, the relevant user experience involves the user: (1) downloading or activating an infocard selector to work with their browser, (2) downloading i-cards from card issuing sites into the selector “wallet”, and (3) visiting relying websites where the user simply clicks on an icon to open up their selector and display the set of cards the site will accept for the resource the user is trying to access. The user selects the card they wish to use, and a secure, digitally-signed token is transmitted to the site to grant the user access.

Just as a browser can read web pages from any web server, a selector can collect cards from any card-issuing website. At each site, the user is authenticated and his/her claims verified using whatever method that site chooses to employ. Once satisfied, the site generates an infocard that the user imports into their selector by clicking a download link.

In the case of the managed i-cards discussed here, it is important to understand that the card itself contains only metadata (a description of other data)—not the actual claim values. The managed card is an XML document with elements that include the name of the card, the background image of the card, and the set of the types (but not the values) of attributes supported by the card and its associated token service endpoint. A card could, for example, indicate that it supports the claim types of first name, last name, postal code, and email address. More to the point, the card might hold a claim type whose Boolean value is the truth of the statement that the card holder is less than 16 years of age.

Instead of relying on usernames, passwords and form filling, sites that accept i-cards rely on digitally signed tokens provided by the user’s selector. To request such a token, the site displays the standard icon shown below on the home page (or any other page where data is needed).

Information Card Icon

When the user clicks on this icon, their i-card browser extension retrieves an HTML or XML description of the site’s policy specifying the set of required and optional claims it needs. The browser then opens up the user’s selector in a window showing only the card(s) whose set of supported claim types is the same set (or a superset) of the claims requested.

The user selects one of the cards by clicking on it and authenticates to the card as required (which may involve typing in a password). The selector sends the authentication materials to a token service (typically co-resident with the data systems supporting the card issuing website). The token service returns a token that is signed using encryption keys derived from the SSL domains of both the relying site and the issuing site. The selector then POSTs this token to the relying site.

For example, if the relying site had requested a Boolean claim as to whether the user was less than 16 years of age, and the user selected a card that supported this claim type and the user was properly authenticated to submit it, then the relying site would receive that Boolean value in a digitally signed token from the issuing site. By verifying the signature, the relying site can now trust this assertion to the extent that it trusts the issuing site.