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 "Context Discovery"

m (IdAS Registries Proposal 2B moved to Context Discovery: Updated proposal that now refers to two other pages for specs and implementation)
(rewrite with links to new detail pages)
Line 1: Line 1:
===ContextualizedSubjectId (CSId)===
+
== Intro ==
* A CSId is a URI formed by concatenating a ContextId with an optional final segment consisting of a "/" and the SubjectId.  
+
This page explains the proposed process for context discovery in Higgins. It replaces the former IDAS Registry 2B proposal page. Note that this page only provides a general descripion and examples of the process. For specific implementation details, see:
* For example "@xyzcompany/drummond.reed" --drummond's entry in xyz company's HR database. In this case "@xyzcompany" is the ContextId and "drummond.reed" is the SubjectId
+
  
===Versions===
+
* [[ContextId]] for the formal ABNF definition of a Higgins ContextId.
*'''Version 6''': pt: added new term "CSId" (see above)
+
* [[ContextDiscoveryComponents]] for a description of the components that have been implemented for context discovery.
*'''Version 5''': pt: minor tweaks. Added a comment question at the very bottom of this page.
+
*'''Version 4''': pt: This draft reflects Paul and Drummond's 4.26.2007 conversation.
+
  
===Design Goals===
+
== General Process ==
In addition to all the previous design goals, here is one more that is behind this proposal
+
Context discovery in Higgins consists of the following four general steps:
* '''Higgins-ism free.''' Higgins is not in the service/protocol definition business. So the intuition here is that there shouldn’t be any higgins-isms in the XRDS documents used in what is termed here the ''Context Registry''. For example, if there is an OpenID service out there Higgins should be able to learn about it and connect to it without modification. [Note: there is Higgins-specific stuff in the ''Context Provider Registry'' (see below).
+
  
===CSIds===
+
# The process starts with passing the [[ContextId]] for which context discovery is needed to IdASRegistry.
Beyond what is written here [[ContextId]] this proposal includes the following additional conventions:
+
# IdASRegistry uses the [[ContextId]] to obtains a context descriptor (typically an XRDS file) that contains at least one context type, zero or more URIs, and an optional configuration map.  
# A CSId MUST be resolvable to a single Service Endpoint (SEP) in the XRDS document to which it's authority segment resolves. Note: in the case where the identifier of the XRDS document is a http(s): URL or file:// URI then it is cast into an XRI before being processed as described below (e.g. http://example.com/something would cast to $(http://example.com/something))
+
# From the context type, IdASRegistry finds a context factory that can instantiate a context for the given [[ContextId]].
# CSIds in Higgins are considered to be comprised of:
+
# IdASRegistry returns a context factory that has been configured.
## a first segment (called the ''authority'' segment in XRI) --this is the ContextId
+
## an optional second segment (the first segment of the XRI ''path'') (e.g. "+bizcard") --this is the SubjectId
+
## no third segment
+
# For XRI-type CSIds the ''authority'' segment is preceded by '=' or '@'.
+
# Any iname (i.e. just the authority segment of an XRI) is a legitimate CSId (consisting only of the first segment (the path segment is null. The null path value is used to select the SEP)
+
# We find the SEP block in the XRDS by matching on the path (even if null) to the <Path> element of an SEP
+
  
==Use Cases==
+
== Examples ==
The user is Paul. He's using a Higgins Identity Agent.
+
  
====Use case #1====
+
=== Example #1: Typing in an I-Name ===
Paul has a friend who tells him his iname is '=drummond'. Paul is using Higgins 3.0 (the year is 2009). This version has an i-card manager that allows him to type in this iname whereupon it inspects the many SEPs (SEPs: Service Endpoints: <Service> blocks in the XRDS document that =drummond resolves to) and then it looks at the type of each SEP and looks in the Context Provider Registry to see what service types are supported by this installation of Higgins, and dynamically generates N i-cards--one for each service type that Higgins understands. For example, one of the service types that this installation of Higgins understands is OpenID, and since Drummond has provisioned an OpenID service, Higgins will create a URI-i-card is whose ContextId is '=drummond/+openid'.  
+
Paul is using a version of Higgins Identity Agent that allows him to type the i-name of a friend, '''=drummond''' into his i-card manager. His i-card manager then calls IdASRegistry which performs the following steps:
 +
# Resolves the i-name into an XRDS document to discover the service endpoints (SEPs - the <Service> blocks in the XRDS document). From a Higgins standpoint, each SEP corresponds to a Higgins context descriptor.
 +
# Looks at the <Type> element of each SEP to discover its context type.
 +
# Looks in the Context Provider Registry for that Higgins installation to see what service types are supported by this installation.
 +
# Dynamically generates N i-cards -- one for each service type that Higgins understands. For example, one of the service types that this installation of Higgins understands is OpenID, and since =drummond has provisioned an OpenID service, Higgins will create a r-card is whose ContextId in ContextXRI format is '''=drummond/$context+openid'''.  
  
[''The preceding paragraph is just setting the stage. The next part is important'']
+
=== Example #2: Clicking on an R-Card ===
 +
Paul wants to view an r-card whose ContextId is '''=drummond/$context+bizcard'''. This supposedly has Drummond's business card attributes. The sequence is:
 +
# The i-card manager invokes IURICard.getContext() on this i-card.
 +
# The i-card object calls IdASRegistry.getContextFactory(contextId) to find an IContextFactory that can instantiate an IContext for the r-card's IContextId.
 +
# IdASRegistry obtains the context descriptor (in this case, an XRDS document retrieved via XRI resolution of '''=drummond/$context+bizcard''').
 +
# The context descriptor contains one or more context types, which are used by IdASRegistry to look up a suitable context factory.
 +
# The IContextFactory is returned to the i-card object, which then calls the factory's createContext(contextId) method in order to get back an IContext object for the i-card's IContextId.
  
Paul can now click on his new URI-i-card and inspect its attributes. Here's what happens:
+
=== Example #3: Token Received by Token Service ===
#The URI i-card passes the ContextId to "IdAS" and asks it to return an IContext
+
A ContextId, '''localhost/attstore/2386''' is stored in the metadata of the endpoint reference of the token service in the RST. It is received by the Token Service, passed to a Token Provider and used by that provider to open up an IContext using IdASRegistry. (Mike has verified that MSFT CardSpace preserves this EPR metadata so this same approach will work using Higgins or CardSpace Identity Agents.)
#What we'll call "IdAS" (probably IdAS.utils) calls XRI.resolve(ContextId) to return the SEP. We're telling the resolver to find the <Service> block that matches by matching on <Path> with the value provided. (See XRDS Files section below to see a description of the contents of xrds1).
+
#IdAS looks up the value of the <Type> element in the SEP (this will be used below)
+
#IdAS searches the Context Provider Registry to find a IContextFactory class name for the Type just found. It finds, for example org.eclipse.higgins.idas.cp.openid.
+
#That factory initializes itself with the factory config elements (column 3 in Provider Registry table)  
+
#We do a <factory>.getInstance reading the “Other <Service> elements” from column 4 in XRDS Files table for the contextConfig data
+
  
====Use case #2 ====
+
== Example XRDS Files ==
Paul wants to view an URI i-card whose ContextId is "=drummond/+bizcard". This supposedly has Drummond's business card attributes. Sequence:
+
See [[ContextDiscoveryComponents]] for example XRDS files.
#The i-card manager invokes IURICard.getContext() on this i-card
+
#The i-card object uses "IdAS" to get an IContext
+
#The i-card invokes an XRI resolver: XRI.resolve("=drummond/+bizcard")
+
#This resolves to the file "xrds2" and within it the SEP whose <Path> element matches "+bizcard".
+
#This SEP block contains the context-specific configuration elements that describe the Context. It also contains the value "+ldap" in the Type element
+
#We look up in the Context Provider Registry by type "+ldap" for a suitable Context Provider
+
 
+
====Use case #5 details====
+
This is an example of a ContextId that will be stored in the metadata of the endpoint reference of the token service in the RST. It will be received by the Token Service, passed to a Token Provider and used by that provider to open up an IContext using IdAS. Mike has verified that MSFT CardSpace preserves this EPR metadata so this same approach will work using Higgins or CardSpace Identity Agents.
+
 
+
{| class="wikitable" style="text-align:left; border="1" cellpadding="5" cellspacing="0"
+
|-style="background:#d6dee9; color:black"
+
! width="5%" border="1" align="left" valign="top" | Use Case
+
! width="10%" border="1" align="left" valign="top" | Kind of i-card
+
! width="10%" border="1" align="left" valign="top" | ContextId
+
! width="40%" border="1" align="left" valign="top" | Context Description
+
! width="10%" border="1" align="left" valign="top" | Resolves to
+
! width="20%" border="1" align="left" valign="top" | ...within which we find the <Service> block by
+
|-
+
|1
+
|Higgins URI i-card
+
|=drummond/+openid
+
|Drummond's i-name provider has provisioned OpenID services for this i-name. This i-name partially identifies a Context holding the attributes provided by OpenID auth
+
|xrds1
+
|matching <Path> element's value of "+openid"
+
|-
+
|2
+
|Higgins URI i-card
+
|=drummond/+bizcard
+
|Drummond has a (single-DS) Context that holds business card attributes.
+
|xrds2
+
|matching <Path> element's value of "+bizcard"
+
|-
+
|3
+
|Higgins URI i-card
+
|=drummond/+webSurfer
+
|Drummond uses HBX in his browser and in the Higgins i-card manager he has defined a single-DS Context with the set of attributes he's happy to share with run of the mill websites. It contains only non-identifying information.
+
|xrds3
+
|matching <Path> element's value of "+webSurfer"
+
|-
+
|4
+
|Higgins URI i-card
+
|@cordance/+Accounting
+
|Cordance (Drummond's employer) maintains a directory of all employees. A multi-DS Context.
+
|xrds4
+
|matching <Path> element's value of "+Accounting"
+
|-
+
|5
+
|Higgins CardSpace managed i-card
+
|localhost/attstore/2386
+
|This is the Context behind some card that the Higgins Token Service issued.
+
|xrds5
+
|matching <Path> element's value of "attstore/2386"
+
|}
+
.
+
 
+
==Context Registry==
+
'''Purpose:''' To map a ContextId to a Service Endpoint (SEP).
+
 
+
The registry leverages XRI resolution to one or more XRDS files. SEPs are chunks of XML in the XRDS file provide the metadata for the ContextId to which it resolves so that a Higgins Context Provider might be found and that could be told enough about the endpoint to present it as an IContext instance. The required <Type> element implies what protocol/API is involved. The optional <Schema> element is the URL of the OWL file that describes the schema used by the Context.
+
 
+
The following table shows the elements within the matched <Service> block:
+
{| class="wikitable" style="text-align:left; border="1" cellpadding="5" cellspacing="0"
+
|-style="background:#d6dee9; color:black"
+
! width="5%" border="1" align="left" valign="top" | XRDS File
+
! width="10%" border="1" align="left" valign="top" | <Type> element's value
+
! width="10%" border="1" align="left" valign="top" | <Path> element's value
+
! width="10%" border="1" align="left" valign="top" | <Schema> element's value
+
! width="40%" border="1" align="left" valign="top" | Other elements
+
|-
+
|xrds1
+
|http://openid.net/server/2.0
+
| +openid
+
|(not present)
+
|<URI>url-of-OP</URI>
+
|-
+
|xrds2
+
|xri-of-ldap
+
| +bizcard
+
|url-of-schema-for-this-vcard
+
|<SSL>True/False</SSL>,<port/>, and other LDAP-specific elements that identify the context dataset
+
|-
+
|xrds3
+
|xri-for-sql
+
| +webSurfer
+
|(not present)
+
|
+
|-
+
|xrds4
+
|xri-for-ldap
+
| +Accounting
+
|url-of-schema-for-this-departments-employee-directory
+
|<SSL>True/False</SSL>,<port/>, and other LDAP-specific elements that identify the context dataset
+
|-
+
|xrds5
+
|xri-for-ldap
+
| +attstore/2386
+
|
+
|<SSL>True/False</SSL>,<port/>, and other LDAP-specific elements that identify the context dataset
+
|}
+
.
+
 
+
Here is what the service endpoint description looks like in file 'xrds2':
+
<Service>
+
    <Type>xri-for-ldap</Type> 
+
    <Path select="true">bizcard</Path>
+
    <URI append="none">ldap-server-URL</URI>
+
    ...other ContextConfig elements...
+
</Service>
+
 
+
See http://iss.xdi.org/moin.cgi/IserviceEndpointDefinitions for more examples of I-Service Endpoint definitions.
+
 
+
==Context Provider Registry==
+
'''Purpose:''': To find a IContextFactory along with any factoryConfig metadata needed (if any) by searching by Type value found in the SEP for the Context as found in Context Registry described above.
+
 
+
This registry is also implemented using XRI resolution in two stages. It is configured to first look in the localhost registry and not finding a match there looks in a registry on the LAN (or even in the cloud).
+
 
+
Here's how it would work if the Type was xri-for-ldap: This registry would first construct an xri for the localhost registry and resolve using it. If no match was found it would construct the xri: @WISER*higgins_imp*(xri-for-ldap). It constructs this xri because the registry has been configured to know and trust @WISER as the registry of Context Providers. It "knows" that this organization has their registry at *higgins_imp and that they take a crossref to the Type as the final segment (could also be: @WISER*higgins_imp/xri-for-ldap)
+
 
+
In the above @WISER is just a place holder for 'an entity that is trusted by the community to, and has taken on the burden to, run a registry.'
+
 
+
{| class="wikitable" style="text-align:left; border="1" cellpadding="5" cellspacing="0"
+
|-style="background:#d6dee9; color:black"
+
! width="5%" border="1" align="left" valign="top" | Service Type
+
! width="10%" border="1" align="left" valign="top" | IContextFactory Class Name
+
! width="10%" border="1" align="left" valign="top" | other IContextFactory config data
+
|-
+
|http://openid.net/server/2.0
+
|org.eclipse.higgins.idas.cp.openid
+
|??
+
|-
+
|xri-for-ldap
+
|org.eclipse.higgins.idas.cp.jndi
+
|??
+
|-
+
|xri-for-sql
+
|org.eclipse.higgins.idas.cp.sql
+
|??
+
|}
+
.
+
 
+
'''[PaulT: I wonder if in the Context Provider Registry described below we could and should use both Type and Schema to find an appropriate Context Provider? (Instead of just using Type)]'''
+
 
+
Note: "xri-for-ldap" and "xri-for-sql" as used above will be defined by the OASIS XRI TC (they will probably look like say "+i-service*(+ldap)*($v*1.0)"  and "+i-service*(+sql)*($v*1.0)"
+

Revision as of 01:12, 19 July 2007

Intro

This page explains the proposed process for context discovery in Higgins. It replaces the former IDAS Registry 2B proposal page. Note that this page only provides a general descripion and examples of the process. For specific implementation details, see:

  • ContextId for the formal ABNF definition of a Higgins ContextId.
  • ContextDiscoveryComponents for a description of the components that have been implemented for context discovery.

General Process

Context discovery in Higgins consists of the following four general steps:

  1. The process starts with passing the ContextId for which context discovery is needed to IdASRegistry.
  2. IdASRegistry uses the ContextId to obtains a context descriptor (typically an XRDS file) that contains at least one context type, zero or more URIs, and an optional configuration map.
  3. From the context type, IdASRegistry finds a context factory that can instantiate a context for the given ContextId.
  4. IdASRegistry returns a context factory that has been configured.

Examples

Example #1: Typing in an I-Name

Paul is using a version of Higgins Identity Agent that allows him to type the i-name of a friend, =drummond into his i-card manager. His i-card manager then calls IdASRegistry which performs the following steps:

  1. Resolves the i-name into an XRDS document to discover the service endpoints (SEPs - the <Service> blocks in the XRDS document). From a Higgins standpoint, each SEP corresponds to a Higgins context descriptor.
  2. Looks at the <Type> element of each SEP to discover its context type.
  3. Looks in the Context Provider Registry for that Higgins installation to see what service types are supported by this installation.
  4. Dynamically generates N i-cards -- one for each service type that Higgins understands. For example, one of the service types that this installation of Higgins understands is OpenID, and since =drummond has provisioned an OpenID service, Higgins will create a r-card is whose ContextId in ContextXRI format is =drummond/$context+openid.

Example #2: Clicking on an R-Card

Paul wants to view an r-card whose ContextId is =drummond/$context+bizcard. This supposedly has Drummond's business card attributes. The sequence is:

  1. The i-card manager invokes IURICard.getContext() on this i-card.
  2. The i-card object calls IdASRegistry.getContextFactory(contextId) to find an IContextFactory that can instantiate an IContext for the r-card's IContextId.
  3. IdASRegistry obtains the context descriptor (in this case, an XRDS document retrieved via XRI resolution of =drummond/$context+bizcard).
  4. The context descriptor contains one or more context types, which are used by IdASRegistry to look up a suitable context factory.
  5. The IContextFactory is returned to the i-card object, which then calls the factory's createContext(contextId) method in order to get back an IContext object for the i-card's IContextId.

Example #3: Token Received by Token Service

A ContextId, localhost/attstore/2386 is stored in the metadata of the endpoint reference of the token service in the RST. It is received by the Token Service, passed to a Token Provider and used by that provider to open up an IContext using IdASRegistry. (Mike has verified that MSFT CardSpace preserves this EPR metadata so this same approach will work using Higgins or CardSpace Identity Agents.)

Example XRDS Files

See ContextDiscoveryComponents for example XRDS files.

Back to the top