Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

R-Card

Revision as of 17:16, 19 August 2009 by Ptrevithick.gmail.com (Talk | contribs) (Reguired Context Attributes)

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}

Higgins logo 76Wx100H.jpg

Version

This page defines a Higgins R-Card ("relationship card") as implemented in Higgins 1.1.

Edit History

  • --Ptrevithick.gmail.com 14:45, 19 August 2009 (UTC): added new section "Disjunction: Context vs. Entity Attribute URIs". I also tweaked the names of the attributes in the required, min schema

Introduction

This section provides an introduction to R-Cards. It assumes that the reader is familiar with personal (P-Card) and managed (M-Card) I-Cards. For more information about I-Cards refer to the OASIS IMI TC and the Information Card Foundation.

At a high level I-Cards are are representations of digital identities. 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.

The same process of releasing claims about a 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 enable 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. [Note: implementing this kind of fine-grained access control using declarative policy is the motivation for the Access Control in IdAS work.] By contrast, regular, non "R", cards have claim values that are read-only.

From Cards to Relationship Cards

Both managed cards (aka M-Cards) and personal cards (aka P-Cards) can have relationship qualities and thus be considered R-Cards. A managed R-Card is called a M-R-Card, and a personal R-Card is called a P-R-Card.

We will start with managed R-Cards. To explain them 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 M-R-Card) and its associated STS as well as its associated Attribute Service (AS).

M-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.

R-card-v2-p1.png

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.

M-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 Attribute Service (AS). Like the STS itself, the AS 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.

R-card-v2-p2.png

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.

R-card-v2-p3.png

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. M-R-Cards. If the RP lists this claim as optional then the user may have a choice of sending a managed or an M-R-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.

Relationship Personal Cards

Relationship P-Cards (aka R-P-Cards) are P-Cards that have a resource-udr claim. Unlike relationship M-Cards personal cards contain within themselves the values of claims. Thus R-P-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 http://schemas.informationcard.net/@ics/resource-udr/2009-03 claim is an R-Card. See ICF Claim Catalog for more information about this claim type. As mentioned, a P-Card with this claim is called a R-P-Card. An M-Card with this claim is called an M-R-Card.

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, Cool URI or anything else) that somehow can be dereferenced to a Context, Entity or Attribute. In the case of an R-Card it the UDI is always an Entity UDI that can be dereferenced to an Entity in some data Context. If the value of the resource-udr is an Entity UDI then then the UDI resolution process as defined here is performed. If the RP (or any other party) wishes to use IdAS to resolve the UDI, the 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.

Generic Claim and Attribute Schema

Definitions

  • 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 we call S2 attributes as opposed to the S1 claims
  • The S2 schema may be retrieved by dereferencing the Entity UDI (e.g. using IdAS) and querying the schema of the Context containing the Entity.

Axioms

  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.

Required Schema

This section describes the minimum schema that all new R-Cards must implement in order to allow these cards to support scriptability. R-Cards that do not support this minimum schema (and are thus not scriptable) are called legacy R-Cards.

R-card-schema-v8.png

Note: Prepend "http://www.eclipse.org/higgins/ontologies/2009/4/persona.owl#" to all of the attributes (e.g. hasAction, appService, etc.) to get the fully qualified attribute URI.

Required Card Claims

hasAction
claim This claim is present only to allow a relying party to essentially filter the cards that a selector displays down to only those that support "actions" (executable scripts). Its value is a ignored.

Reguired Context Attributes

Attributes of the R-Card's associated Context object:

appService
0..1 - uri value of the app serving service. If this parameter value is exactly "http[s]://init.kobj.net" then ABX 2.0 knows to contruct a Kynetx-compatible <script> block, inserting config and ruleId elements within it, set src=http[]s://init.kobj.net/js/shared/kobj-static.js, etc.
appJS
0..1 - Javascript itself. There MUST either be an appJS or an appService attribute (but not both)
appId 
1..1 string value uniquely identifies the app within the "developerId" namespace the id of this app. In other words the combination of the devID and the appId is globally unique. When using KNS this is the ruleID with special constraint that this ruleID is globally unique.
appDescription
1..1 string - a human readable description of the app. Note: If appServer == http[s]://init.kobj.net, then the KNS describe API can be used by a Context Provider implementation to provide this attribute value.
appVersion
1..1 string - a human readable version of the app. Note: If appServer == http[s]://init.kobj.net, then the KNS describe API can be used by a Context Provider implementation to provide this attribute value.
appSites
1..N strings - this is not a list of specific URIs, it is a list of strings to match in the domain name part of a URI. So urn:google would fire on maps.google.com, www.google.com, www.googleismyfavoritesite.com. For Kynetx-powered cards (i.e. if appServer = http[s]://init.kobj.net"), the values of this attribute should be dynamically fetched using the 'dispatch' method at URL: http://init.kobj.net/js/dispatch/<appId>.

Required Entity Attributes

appEnabled
1..1 - boolean value - if true the"action" script (see "app" above) of this card is enabled

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.

Authentication

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 Attribute Service 1.1 for a discussion of authentication issues.

Links

Back to the top