|
|
| (29 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| − | '''Version 2''': Both path and type are optional in the syntax of ContextIds; all that matters is that exactly one SEP is matched within the XRDS document (with or without path and type matching). Added new section 'Locally Deployed Context Provider Registry'.
| + | {{#eclipseproject:technology.higgins}} |
| | + | == Intro == |
| | + | This page explains the process for [[Context]] discovery in the [[Identity Attribute Service]]. Note that this page only provides a general descripion and examples of the process. For specific implementation details, see: |
| | | | |
| − | ===Design Goals===
| + | * [[Context Discovery Components]] for a description of the components that have been implemented for context discovery. |
| − | In addition to all the previous design goals, here is one more that is behind this proposal
| + | * [[ContextId]] --the formal ABNF definition |
| − | * '''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). | + | |
| | | | |
| − | ===ContextIds=== | + | == General Process == |
| − | Beyond what is written here [[ContextId]] this proposal includes the following additional conventions:
| + | Context discovery in Higgins consists of the following four general steps: |
| − | # A ContextId MUST be resolvable to a single Service EndPoint (SEP) block in the XRDS document to which it's authority segment resolves. (Note: this is true for both XRI-type and non-XRI ContextId URIs)
| + | |
| − | # ContextIds in Higgins are considered to be comprised of:
| + | |
| − | ## an ''authority'' segment
| + | |
| − | ## optionally followed a ''path'' segment (e.g. "/bizcard")
| + | |
| − | ## optionally followed by a ''type'' segment (e.g. "/+OPENID").
| + | |
| − | # For XRI-type ContextIds the ''authority'' segment is preceded by '=' or '@'. For non-XRI-type ContextIds the ''authority'' segment consists of
| + | |
| − | #* "http://", or "https://" followed by one or more domains and sub-domains (e.g. server1.eclipse.org)
| + | |
| − | #* or "file://" --should we allow this?
| + | |
| − | # If the ContextId ends in one of the following sub-strings, then this sub-string is considered the ''type'' segment:
| + | |
| − | ## +OPENID
| + | |
| − | ## +LDAP
| + | |
| − | ## +SQL
| + | |
| − | # Anything remaining to the right of the ''authority'' segment and to the left of the type sub-string is considered the ''path''
| + | |
| − | # iname to ContextId Mapping: Since one iname (e.g. =drummond) resolves to an XRDS that usually does have and could definitely have in the future multiple SEPs, inames are considered not fully qualified (see above). Either a Type or a Path (or both) MUST be appended to the root iname.
| + | |
| − | # We find the SEP block in the XRDS by matching on BOTH the path (if any) to the <Path> element and the type (if any) to the <Type> element
| + | |
| | | | |
| − | ====More about fully qualified XRIs====
| + | # The process starts with passing the [[ContextId]] for which context discovery is needed to IdASRegistry. |
| − | In Higgins a ContextId ''uniquely'' identifies a Context whereas an XRI (or URI) that resolves to a single XRDS document can, when looked at as "a provider of attribute sets" provide ''more than one'' set of attributes (effectively more than one Context) and thus does ''not'' uniquely identify a Context in the Higgins sense of the word.
| + | # 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. |
| | + | # From the context type, IdASRegistry finds a context factory that can instantiate a context for the given [[ContextId]]. |
| | + | # IdASRegistry returns a context factory that has been configured. |
| | | | |
| − | For example, the XRI '=drummond' may delegate to an OpenID service and simultaneously to a contact service. The set of attributes and their values provided by each of these two services may be different, and usually are. Thus simply having an XRI does not by itself provide enough information to uniquely specify which possible attribute set (which Context) we're talking about. [It is also true that this same XRI may have other services unassociated with providing attributes at all (e.g. messaging services), thus underscoring the need to further qualify the XRI from a Higgins perspective]
| + | == Examples == |
| | | | |
| − | ==Use Cases== | + | === Example #1: Typing in an I-Name === |
| − | The user is Paul. He's using a Higgins Identity Agent.
| + | 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'''. |
| | | | |
| − | ====Use case #1==== | + | === Example #2: Clicking on an R-Card === |
| − | 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 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. |
| | | | |
| − | [''The preceding paragraph is just setting the stage. The next part is important'']
| + | === 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.) |
| | | | |
| − | Paul can now click on his new URI-i-card and inspect its attributes. Here's what happens:
| + | == Example XRDS Files == |
| − | #The URI i-card passes the ContextId to "IdAS" and asks it to return an IContext
| + | See [[ContextDiscoveryComponents]] for example XRDS files. |
| − | #What we'll call "IdAS" (probably IdAS.utils) splits the ContextId into three segments: authority, path, and type as described above. So '=drummond/+OPENID' is spit into authority='=drummond', path=null, type='+OPENID' . Note: '+OPENID' is really just an alias for the xri-for-openid, namely, "http://openid.net/server/2.0".
| + | |
| − | #IdAS then calls XRI.resolveByPathAndType("=drummond", null, "http://openid.net/server/2.0"). The first arg is the iname, the third is the target service <type>. We're telling the resolver to find the <Service> block that matches by matching on <Type> with the value provided. (See XRDS Files section below to see a description of the contents of xrds1).
| + | |
| − | #IdAS searches Context Provider Registry to find a IContextFactory class name for the http://openid.net/server/2.0 service type, it finds org.eclipse.higgins.cp.openid.
| + | |
| − | #That factory initiates 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 ====
| + | |
| − | Paul wants to view an URI i-card whose ContextId is "=drummond/bizcard". This supposedly has Drummonds business card attributes. Sequence:
| + | |
| − | #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.resolveByPathAndType("=drummond", "bizcard", null)
| + | |
| − | #This resolves to the file "xrds2" and within it the SEP whose <Path> element matches "bizcard". (Note: in this example the ContextId uses only ''path'' matching to find the SEP)
| + | |
| − | #This SEP block contains the context-specific configuration elements that describe the context
| + | |
| − | #We look up in the Context Provider Registry by type "+LDAP" for a 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 <Type> element's value of "http://openid.net/server/2.0"
| + | |
| − | |-
| + | |
| − | |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" (since type is null, we don't also match on type)
| + | |
| − | |-
| + | |
| − | |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/+LDAP
| + | |
| − | |Cordance (Drummond's employer) maintains a directory of all employees. A multi-DS Context.
| + | |
| − | |xrds4
| + | |
| − | |matching BOTH <Path> element's value of "Accounting" AND the <Type> element's value of xri-for-ldap
| + | |
| − | |-
| + | |
| − | |5
| + | |
| − | |Higgins CardSpace managed i-card
| + | |
| − | |localhost/attstore/2386
| + | |
| − | |This is the Context behind some card that the Higgins Token Service issued.
| + | |
| − | |xrds5
| + | |
| − | |matching BOTH the <Path> element's value of "attstore/2386"
| + | |
| − | |}
| + | |
| − | .
| + | |
| − | | + | |
| − | ==Context Registry==
| + | |
| − | '''Purpose:''' To map a ContextId to a Service endpoint description.
| + | |
| − | | + | |
| − | The registry leverages XRI resolution to a set of XRDS files. <Service> blocks in the 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 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
| + | |
| − | |(not present)
| + | |
| − | |(not present)
| + | |
| − | |<URI>url-of-OP</URI>
| + | |
| − | |-
| + | |
| − | |xrds2
| + | |
| − | |(not present)
| + | |
| − | |bizcard
| + | |
| − | |url-of-schema-for-this-vcard
| + | |
| − | |<SSL>True/False</SSL>,<port/>, and other LDAP-specific elements that identify the context dataset
| + | |
| − | |-
| + | |
| − | |xrds3
| + | |
| − | |(not present)
| + | |
| − | |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
| + | |
| − | |(not present)
| + | |
| − | |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'. Remember, in this use case the ContextId has a null Type, so no matching on <Type> is used. Nevertheless, the <Type> element MUST be present because it is used to look up the Context Provider in the Context Provider Registry (see next section):
| + | |
| − | | + | |
| − | <Service>
| + | |
| − | <Type>xri-for-ldap-type</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 map a service Type to an IContextFactory, along with any factoryConfig metadata needed (if any). Implemented using XRI resolution.
| + | |
| − | | + | |
| − | Here's how it would work if the Type was xri-for-ldap: This Context Provider Registry would construct the xri: @WISER*higgins_imp*(xri-for-ldap). It constructs this xri because it has been configured to know and trust @WISER as the registry of Higgins 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.cp.openid
| + | |
| − | |??
| + | |
| − | |-
| + | |
| − | |xri-for-ldap
| + | |
| − | |org.eclipse.higgins.cp.jndi
| + | |
| − | |??
| + | |
| − | |-
| + | |
| − | |xri-for-sql
| + | |
| − | |org.eclipse.higgins.cp.slq
| + | |
| − | |??
| + | |
| − | |}
| + | |
| − | .
| + | |
| − | ==Locally Deployed Context Provider Registry==
| + | |
| − | '''Purpose:''': To maintain a list of the locally installed/available Context Providers
| + | |
| − | | + | |
| − | Perhaps the IContextFactory config data from this registry would be added to (override) the IContextFactory config data made available by the Context Provider Registry mentioned above.
| + | |
| − | | + | |
| − | {| class="wikitable" style="text-align:left; border="1" cellpadding="5" cellspacing="0"
| + | |
| − | |-style="background:#d6dee9; color:black"
| + | |
| − | ! width="50%" border="1" align="left" valign="top" | IContextFactory Class Name
| + | |
| − | ! width="50%" border="1" align="left" valign="top" | other IContextFactory config data
| + | |
| − | |-
| + | |
| − | |org.eclipse.higgins.cp.openid
| + | |
| − | |??
| + | |
| − | |-
| + | |
| − | |org.eclipse.higgins.cp.jndi
| + | |
| − | |??
| + | |
| − | |-
| + | |
| − | |org.eclipse.higgins.cp.slq
| + | |
| − | |??
| + | |
| − | |}
| + | |
| − | | + | |
| − | 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)"
| + | |
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:
