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

Difference between revisions of "R-Card"

(Example R-Card and Context)
 
(15 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}
 
{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}
 
[[Image:Higgins_logo_76Wx100H.jpg|right]]
 
[[Image:Higgins_logo_76Wx100H.jpg|right]]
== Version ==
+
See http://www.eclipse.org/higgins/documents/relationship-cards.html
This page defines a Higgins [[R-Card]] ("relationship card") as implemented in Higgins 1.1.
+
 
+
=== Edit History ===
+
*--[[User:Ptrevithick.gmail.com|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-Card]]s. It assumes that the reader is familiar with personal ([[P-Card]]) and managed ([[M-Card]]) [[I-Card]]s. For more information about [[I-Card]]s refer to the [http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=imi OASIS IMI TC] and the [http://informationcard.net Information Card Foundation].
+
 
+
At a high level [[I-Card]]s are are representations of [[Digital Identity|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 [[Attribute]]s.
+
 
+
'''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-Card]]s) and personal cards (aka [[P-Card]]s) can have relationship qualities and thus be considered [[R-Card]]s. 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-Card]]s. 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.
+
 
+
[[Image:R-card-v2-p1.png|center]]
+
 
+
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.
+
 
+
[[Image:R-card-v2-p2.png|center]]
+
 
+
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-Card]]s 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.
+
 
+
[[Image:R-card-v2-p3.png|center]]
+
 
+
Different from a managed card, a managed [[R-Card]]s 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-Card]]s. 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-Card]]s (aka [[R-P-Card]]s) are [[P-Card]]s that have a resource-udr claim. Unlike relationship [[M-Card]]s personal cards contain within themselves the values of claims. Thus [[R-P-Card]]s 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 [https://wiki.informationcard.net/index.php/Claim_Catalog#2009 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 [http://en.wikipedia.org/wiki/XRDS 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 [http://www.azigo.com/company/dev/udi/ 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===
+
# 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].
+
# 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.
+
# 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-Card]]s must implement in order to allow these cards to support scriptability. [[R-Card]]s that do not support this minimum schema (and are thus not scriptable) are called ''legacy'' [[R-Card]]s.
+
 
+
Note: Prepend <nowiki>"http://www.eclipse.org/higgins/ontologies/2009/4/i-card.owl#"</nowiki> to all of the following 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 &lt;script&gt; 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&nbsp;
+
::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/&lt;appId&gt;.
+
:;appParams
+
::0..1 - an optional set of attributes and values use to initialize the app. These attributes and values should be combined with those found on the appParams attribute of the Context and made available to the app on startup. This appParams holds parameters that are likely to vary across the [[R-Card]]s in the Context.
+
 
+
===Required Entity Attributes===
+
 
+
:;appEnabled
+
::1..1 - boolean value - if true the"action" script (app) of this card is enabled
+
:;appParams
+
::0..1 - an optional set of attributes and values use to initialize the app. These attributes and values should be combined with those found on the appParams attribute of the Context and made available to the app on startup. This appParams holds parameters that are common across all the [[R-Card]]s in the Context.
+
 
+
=== Example R-Card and Context  ===
+
 
+
The following diagrams show a sample Context, a sample R-Card (and the entity to which it refers):
+
 
+
[[Image:Context-image.png]][[Image:Sample-r-card-v3.png]]
+
 
+
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. 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-Card]]s 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:
+
# 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 ==
+
* [[Relationship Brokering With R-Cards]] -- a tad outdated
+
* http://en.wikipedia.org/wiki/I-Card -- outdated
+
 
+
[[Category:Higgins Concepts]]
+

Latest revision as of 20:40, 18 July 2011

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

Higgins logo 76Wx100H.jpg

See http://www.eclipse.org/higgins/documents/relationship-cards.html

Back to the top