€cdocutils.nodes document q)q}q(U nametypesq}q(X%identifying principals (aka subjects)qNXidentity management serviceqNXidentity managementqNXauthentication serviceq NX%authenticating and retrieving a tokenq NXteragridprincipalnamesq ˆXgrouperq ˆXsymbolic principalsq NXedupersonprincipalnameqˆXusing access tokensqNX hmac-sha1qˆXrsa-sha1qˆXoauth2.0qˆXfoafqˆXrfc4514qˆX,encoding session information in http headersqNXmaceqˆXportal delegationqNX2structure of metadata about authenticated sessionsqNX bearer tokensqˆXoauth1.0qˆX authenticated session managementqNX0authtoken references to an authenticated sessionqNXrc4510qˆX)session management (alternative scenario)qNX8identity management and authenticated session managementqNXorcidq ˆuUsubstitution_defsq!}q"Uparse_messagesq#]q$(cdocutils.nodes system_message q%)q&}q'(U rawsourceq(UU attributesq)}q*(Udupnamesq+]UlevelKUidsq,]Ubackrefsq-]UsourceXj/var/lib/jenkins/jobs/API_Documentation_trunk/workspace/api-documentation/source/design/Authentication.txtq.Uclassesq/]Unamesq0]UlineMFUtypeUERRORq1uUparentq2cdocutils.nodes list_item q3)q4}q5(h(X0`Bearer tokens`_ are unique string values issued by an authentication server that show that a client is authorized for access; anyone holding the bearer token can use it to gain access to a service. Service providers validate the token via either a call to the central authorization service or cryptographically using the public key that corresponds to the private key with which the authentication service signed the token. These tokens must be used with TLS, and care must be taken to not leak the tokens via e.g. logs, client storage locations, or via MITM attacks. * Pros: simple to implement on client, passed directly in Authorization header * Cons: Passed with every request, simple to capture, can use to steal session via replay attacks, may require centralized validation of tokens, requires TLS. h)}q6(h+]h/]h-]h,]h0]uh2cdocutils.nodes bullet_list q7)q8}q9(h(Uh)}q:(Ubulletq;X*h,]h-]h+]h/]h0]uh2cdocutils.nodes definition q<)q=}q>(h(Uh)}q?(h+]h/]h-]h,]h0]uh2cdocutils.nodes definition_list_item q@)qA}qB(h(XRBearer tokens * `Bearer tokens`_ are unique string values issued by an authentication server that show that a client is authorized for access; anyone holding the bearer token can use it to gain access to a service. Service providers validate the token via either a call to the central authorization service or cryptographically using the public key that corresponds to the private key with which the authentication service signed the token. These tokens must be used with TLS, and care must be taken to not leak the tokens via e.g. logs, client storage locations, or via MITM attacks. * Pros: simple to implement on client, passed directly in Authorization header * Cons: Passed with every request, simple to capture, can use to steal session via replay attacks, may require centralized validation of tokens, requires TLS. h2cdocutils.nodes definition_list qC)qD}qE(h(Uh)}qF(h+]h/]h-]h,]h0]uh2h3)qG}qH(h(XfBearer tokens * `Bearer tokens`_ are unique string values issued by an authentication server that show that a client is authorized for access; anyone holding the bearer token can use it to gain access to a service. Service providers validate the token via either a call to the central authorization service or cryptographically using the public key that corresponds to the private key with which the authentication service signed the token. These tokens must be used with TLS, and care must be taken to not leak the tokens via e.g. logs, client storage locations, or via MITM attacks. * Pros: simple to implement on client, passed directly in Authorization header * Cons: Passed with every request, simple to capture, can use to steal session via replay attacks, may require centralized validation of tokens, requires TLS. h2h7)qI}qJ(h(Uh2cdocutils.nodes section qK)qL}qM(h(Uh2hK)qN}qO(h(Uh2hUsourceqPh.UtagnameqQUsectionqRh)}qS(h+]h/]h-]h,]qTU8identity-management-and-authenticated-session-managementqUah0]qVhauUlineqWKUdocumentqXhUchildrenqY]qZ(cdocutils.nodes title q[)q\}q](h(X8Identity Management and Authenticated Session Managementq^h2hNhPh.hQUtitleq_h)}q`(h+]h/]h-]h,]h0]uhWKhXhhY]qacdocutils.nodes Text qbX8Identity Management and Authenticated Session Managementqc…qd}qe(h(h^h2h\ubaubcdocutils.nodes paragraph qf)qg}qh(h(XÆThe planning and design for DataONE cybersecurity is predicated on the fact that DataONE is a diverse collaboration of researchers, data providers, institutions, coordinating nodes, member nodes, data collections and other infrastructure components. As such, DataONE is inherently a virtual organization (VO). DataONE, as an entity, spans many physical organizations and administrative domains. The approach that DataONE follows for cybersecurity is one in which all sensitive operations and or data/metadata resources within the DataONE VO require users requesting access to the operation/resource to register and authenticate with the DataONE system before an evaluation of rights to the operation/resource can/will be performed. DataONE supports authentication through CILogon, inlcuding both its InCommon partners such as Universities and OAuth providers such as Google. Thus, any given user may have multiple identities which are verified through the authentication mechanisms from multiple providers, and these identities can then be mapped to one another to manage changes as users change institutions and roles. Once a user is authenticated and mapped to their DataONE identity, they can establish a session to pass credentials to DataONE services by either 1) passing a CILogon or DataONE-issed X.509 certificate to the service provider as part of SSL negotiation, or 2) by providing an authentication token that is provided in HTTP requests made to the DataONE nodes.qih2hNhPh.hQU paragraphqjh)}qk(h+]h/]h-]h,]h0]uhWKhXhhY]qlhbXÆThe planning and design for DataONE cybersecurity is predicated on the fact that DataONE is a diverse collaboration of researchers, data providers, institutions, coordinating nodes, member nodes, data collections and other infrastructure components. As such, DataONE is inherently a virtual organization (VO). DataONE, as an entity, spans many physical organizations and administrative domains. The approach that DataONE follows for cybersecurity is one in which all sensitive operations and or data/metadata resources within the DataONE VO require users requesting access to the operation/resource to register and authenticate with the DataONE system before an evaluation of rights to the operation/resource can/will be performed. DataONE supports authentication through CILogon, inlcuding both its InCommon partners such as Universities and OAuth providers such as Google. Thus, any given user may have multiple identities which are verified through the authentication mechanisms from multiple providers, and these identities can then be mapped to one another to manage changes as users change institutions and roles. Once a user is authenticated and mapped to their DataONE identity, they can establish a session to pass credentials to DataONE services by either 1) passing a CILogon or DataONE-issed X.509 certificate to the service provider as part of SSL negotiation, or 2) by providing an authentication token that is provided in HTTP requests made to the DataONE nodes.qm…qn}qo(h(hih2hgubaubhf)qp}qq(h(XKTo this end, three services support identity management and authentication:qrh2hNhPh.hQhjh)}qs(h+]h/]h-]h,]h0]uhWKhXhhY]qthbXKTo this end, three services support identity management and authentication:qu…qv}qw(h(hrh2hpubaubh7)qx}qy(h(Uh2hNhPh.hQU bullet_listqzh)}q{(h;X*h,]h-]h+]h/]h0]uhWKhXhhY]q|(h3)q}}q~(h(X}Identity Management - user account registration, identity mapping, group management, and management of authentication tokens h2hxhPh.hQU list_itemqh)}q€(h+]h/]h-]h,]h0]uhWNhXhhY]qhf)q‚}qƒ(h(X|Identity Management - user account registration, identity mapping, group management, and management of authentication tokensq„h2h}hPh.hQhjh)}q…(h+]h/]h-]h,]h0]uhWKhY]q†hbX|Identity Management - user account registration, identity mapping, group management, and management of authentication tokensq‡…qˆ}q‰(h(h„h2h‚ubaubaubh3)qŠ}q‹(h(X5Authentication - establishing the identity of a user h2hxhPh.hQhh)}qŒ(h+]h/]h-]h,]h0]uhWNhXhhY]qhf)qŽ}q(h(X4Authentication - establishing the identity of a userqh2hŠhPh.hQhjh)}q‘(h+]h/]h-]h,]h0]uhWKhY]q’hbX4Authentication - establishing the identity of a userq“…q”}q•(h(hh2hŽubaubaubh3)q–}q—(h(X_Authenticated Session Management - establishing a timed-session that identifies a DataONE user h2hxhPh.hQhh)}q˜(h+]h/]h-]h,]h0]uhWNhXhhY]q™hf)qš}q›(h(X^Authenticated Session Management - establishing a timed-session that identifies a DataONE userqœh2h–hPh.hQhjh)}q(h+]h/]h-]h,]h0]uhWKhY]qžhbX^Authenticated Session Management - establishing a timed-session that identifies a DataONE userqŸ…q }q¡(h(hœh2hšubaubaubeubhK)q¢}q£(h(Uh2hNhPh.hQhRh)}q¤(h+]h/]h-]h,]q¥Uidentity-managementq¦ah0]q§hauhWK"hXhhY]q¨(h[)q©}qª(h(XIdentity Managementq«h2h¢hPh.hQh_h)}q¬(h+]h/]h-]h,]h0]uhWK"hXhhY]q­hbXIdentity Managementq®…q¯}q°(h(h«h2h©ubaubhf)q±}q²(h(X`Identity Management for DataONE addresses the need to identify users that request the use of services and or data/metadata resources within DataONE (DataONE does recognize that not all services/resources require user identification, thus support for anonymous access to certain services/resources is possible using a Public identity). DataONE provides services for users to register their identity with DataONE in a user account so as to create a unique DataONE identifier, along with other attributes about that user. This account information may be used for authorization and logging DataONE transactions.q³h2h¢hPh.hQhjh)}q´(h+]h/]h-]h,]h0]uhWK$hXhhY]qµhbX`Identity Management for DataONE addresses the need to identify users that request the use of services and or data/metadata resources within DataONE (DataONE does recognize that not all services/resources require user identification, thus support for anonymous access to certain services/resources is possible using a Public identity). DataONE provides services for users to register their identity with DataONE in a user account so as to create a unique DataONE identifier, along with other attributes about that user. This account information may be used for authorization and logging DataONE transactions.q¶…q·}q¸(h(h³h2h±ubaubhf)q¹}qº(h(X/Users may have multiple identities as a result of distributed research endeavors at different participating organizations and or changes in organizational affiliation. Because of this, the DataONE Identity Management service will support user identity mappings, which allows users to authenticate using any one of their multiple identities, but still be recognized as the same DataONE identity. When a DataONE authenticated session begins, information pertaining to the user's identity is available for authorization purposes, which includes a listing of all mapped identities associated with that user; these mapped identities serve equally well for authorization decisions - that is, within DataONE access control policies, reference to any mapped identity is the same as using any other of the user's identities.q»h2h¢hPh.hQhjh)}q¼(h+]h/]h-]h,]h0]uhWK-hXhhY]q½hbX/Users may have multiple identities as a result of distributed research endeavors at different participating organizations and or changes in organizational affiliation. Because of this, the DataONE Identity Management service will support user identity mappings, which allows users to authenticate using any one of their multiple identities, but still be recognized as the same DataONE identity. When a DataONE authenticated session begins, information pertaining to the user's identity is available for authorization purposes, which includes a listing of all mapped identities associated with that user; these mapped identities serve equally well for authorization decisions - that is, within DataONE access control policies, reference to any mapped identity is the same as using any other of the user's identities.q¾…q¿}qÀ(h(h»h2h¹ubaubhf)qÁ}qÂ(h(XUDataONE also supports the use of ORCID_ identifiers both for authentication and within Access Policies. In this scenario, a user can either map their ORCID identifier to an existing CILogon Distinguished Name, or they can use ORCID as the primary mechanism for logging into DataONE, in which case the ORCID is the user's primary identifier.h2h¢hPh.hQhjh)}qÃ(h+]h/]h-]h,]h0]uhWK9hXhhY]qÄ(hbX!DataONE also supports the use of qÅ…qÆ}qÇ(h(X!DataONE also supports the use of h2hÁubcdocutils.nodes reference qÈ)qÉ}qÊ(h(XORCID_UresolvedqËKh2hÁhQU referenceqÌh)}qÍ(UnameXORCIDUrefuriqÎXhttp://orcid.orgqÏh,]h-]h+]h/]h0]uhY]qÐhbXORCIDqÑ…qÒ}qÓ(h(Uh2hÉubaubhbX. identifiers both for authentication and within Access Policies. In this scenario, a user can either map their ORCID identifier to an existing CILogon Distinguished Name, or they can use ORCID as the primary mechanism for logging into DataONE, in which case the ORCID is the user's primary identifier.qÔ…qÕ}qÖ(h(X. identifiers both for authentication and within Access Policies. In this scenario, a user can either map their ORCID identifier to an existing CILogon Distinguished Name, or they can use ORCID as the primary mechanism for logging into DataONE, in which case the ORCID is the user's primary identifier.h2hÁubeubhf)q×}qØ(h(XmIn addition, the Identity Management service provides a system for users to create, store, and modify groups of users that can be used in access control directives. Only the user creating a group will be allowed to delete the group or to change the group's membership. Service APIs for group management are outlined below in the Identity Management Service section.qÙh2h¢hPh.hQhjh)}qÚ(h+]h/]h-]h,]h0]uhWK>hXhhY]qÛhbXmIn addition, the Identity Management service provides a system for users to create, store, and modify groups of users that can be used in access control directives. Only the user creating a group will be allowed to delete the group or to change the group's membership. Service APIs for group management are outlined below in the Identity Management Service section.qÜ…qÝ}qÞ(h(hÙh2h×ubaubcdocutils.nodes note qß)qà}qá(h(XLThe Internet2 project has defined a product called Grouper that is a standalone group management utility and that publishes a web interface for interacting with the service. It allows users and organizations to create and manage groups. See Grouper_ and earlier work from Internet2 on group management through their MACE_ project.h2h¢hPh.hQUnoteqâh)}qã(h+]h/]h-]h,]h0]uhWNhXhhY]qähf)qå}qæ(h(XLThe Internet2 project has defined a product called Grouper that is a standalone group management utility and that publishes a web interface for interacting with the service. It allows users and organizations to create and manage groups. See Grouper_ and earlier work from Internet2 on group management through their MACE_ project.h2hàhPh.hQhjh)}qç(h+]h/]h-]h,]h0]uhWKFhY]qè(hbXóThe Internet2 project has defined a product called Grouper that is a standalone group management utility and that publishes a web interface for interacting with the service. It allows users and organizations to create and manage groups. See qé…qê}që(h(XóThe Internet2 project has defined a product called Grouper that is a standalone group management utility and that publishes a web interface for interacting with the service. It allows users and organizations to create and manage groups. See h2håubhÈ)qì}qí(h(XGrouper_hËKh2håhQhÌh)}qî(UnameXGrouperhÎXAhttps://spaces.internet2.edu/display/Grouper/Grouper+Web+Servicesqïh,]h-]h+]h/]h0]uhY]qðhbXGrouperqñ…qò}qó(h(Uh2hìubaubhbXC and earlier work from Internet2 on group management through their qô…qõ}qö(h(XC and earlier work from Internet2 on group management through their h2håubhÈ)q÷}qø(h(XMACE_hËKh2håhQhÌh)}qù(UnameXMACEhÎX+http://middleware.internet2.edu/dir/groups/qúh,]h-]h+]h/]h0]uhY]qûhbXMACEqü…qý}qþ(h(Uh2h÷ubaubhbX project.qÿ…r}r(h(X project.h2håubeubaubcdocutils.nodes target r)r}r(h(XN.. _Grouper: https://spaces.internet2.edu/display/Grouper/Grouper+Web+ServicesU referencedrKh2h¢hPh.hQUtargetrh)}r(hÎhïh,]rUgrouperr ah-]h+]h/]h0]r h auhWKLhXhhY]ubj)r }r (h(X5.. _MACE: http://middleware.internet2.edu/dir/groups/jKh2h¢hPh.hQjh)}r (hÎhúh,]rUmacerah-]h+]h/]h0]rhauhWKNhXhhY]ubj)r}r(h(X.. _ORCID: http://orcid.orgjKh2h¢hPh.hQjh)}r(hÎhÏh,]rUorcidrah-]h+]h/]h0]rh auhWKPhXhhY]ubhK)r}r(h(Uh2h¢hPh.hQhRh)}r(h+]h/]h-]h,]rU#identifying-principals-aka-subjectsrah0]rhauhWKShXhhY]r(h[)r}r(h(X%Identifying Principals (aka Subjects)r h2jhPh.hQh_h)}r!(h+]h/]h-]h,]h0]uhWKShXhhY]r"hbX%Identifying Principals (aka Subjects)r#…r$}r%(h(j h2jubaubhf)r&}r'(h(XÃPrincipals are users, groups of users, and system services within the DataONE system. They need to be represented in access policies, authentication sessions, and other places within the system.r(h2jhPh.hQhjh)}r)(h+]h/]h-]h,]h0]uhWKUhXhhY]r*hbXÃPrincipals are users, groups of users, and system services within the DataONE system. They need to be represented in access policies, authentication sessions, and other places within the system.r+…r,}r-(h(j(h2j&ubaubhf)r.}r/(h(XXThe values for identifiers representing principals are unique, persistent, non-reassignable strings. Within those constraints, it is useful to use a common convention for representing and scoping these principal names. In DataONE, Principals are currently represented in one of several forms, although future forms may add to these as needed:r0h2jhPh.hQhjh)}r1(h+]h/]h-]h,]h0]uhWKYhXhhY]r2hbXXThe values for identifiers representing principals are unique, persistent, non-reassignable strings. Within those constraints, it is useful to use a common convention for representing and scoping these principal names. In DataONE, Principals are currently represented in one of several forms, although future forms may add to these as needed:r3…r4}r5(h(j0h2j.ubaubh7)r6}r7(h(Uh2jhPh.hQhzh)}r8(h;X*h,]h-]h+]h/]h0]uhWK_hXhhY]r9(h3)r:}r;(h(XØX.509 Distinguished Names (DN) Examples of the syntax for the representation of principals in an DN include:: CN=Matt Jones A729,O=Google,C=US,DC=cilogon,DC=org UID=mbjones,O=NCEAS,DC=ecoinformatics,DC=org h2j6hPh.hQhh)}r<(h+]h/]h-]h,]h0]uhWNhXhhY]r=(hf)r>}r?(h(XX.509 Distinguished Names (DN)r@h2j:hPh.hQhjh)}rA(h+]h/]h-]h,]h0]uhWK_hY]rBhbXX.509 Distinguished Names (DN)rC…rD}rE(h(j@h2j>ubaubhf)rF}rG(h(XNExamples of the syntax for the representation of principals in an DN include::h2j:hPh.hQhjh)}rH(h+]h/]h-]h,]h0]uhWKahY]rIhbXMExamples of the syntax for the representation of principals in an DN include:rJ…rK}rL(h(XMExamples of the syntax for the representation of principals in an DN include:h2jFubaubcdocutils.nodes literal_block rM)rN}rO(h(X_CN=Matt Jones A729,O=Google,C=US,DC=cilogon,DC=org UID=mbjones,O=NCEAS,DC=ecoinformatics,DC=orgh2j:hQU literal_blockrPh)}rQ(U xml:spacerRUpreserverSh,]h-]h+]h/]h0]uhWKchY]rThbX_CN=Matt Jones A729,O=Google,C=US,DC=cilogon,DC=org UID=mbjones,O=NCEAS,DC=ecoinformatics,DC=orgrU…rV}rW(h(Uh2jNubaubeubh3)rX}rY(h(XÇORCID Identifiers Identifiers from ORCID are compatible with ISNI and take either a bare form or are embedded in an orcid.org URL:: 0000-0003-0077-4738 http://orcid.org/0000-0003-0077-4738 h2j6hPh.hQhh)}rZ(h+]h/]h-]h,]h0]uhWNhXhhY]r[(hf)r\}r](h(XORCID Identifiersr^h2jXhPh.hQhjh)}r_(h+]h/]h-]h,]h0]uhWKfhY]r`hbXORCID Identifiersra…rb}rc(h(j^h2j\ubaubhf)rd}re(h(XqIdentifiers from ORCID are compatible with ISNI and take either a bare form or are embedded in an orcid.org URL::h2jXhPh.hQhjh)}rf(h+]h/]h-]h,]h0]uhWKhhY]rghbXpIdentifiers from ORCID are compatible with ISNI and take either a bare form or are embedded in an orcid.org URL:rh…ri}rj(h(XpIdentifiers from ORCID are compatible with ISNI and take either a bare form or are embedded in an orcid.org URL:h2jdubaubjM)rk}rl(h(X80000-0003-0077-4738 http://orcid.org/0000-0003-0077-4738h2jXhQjPh)}rm(jRjSh,]h-]h+]h/]h0]uhWKkhY]rnhbX80000-0003-0077-4738 http://orcid.org/0000-0003-0077-4738ro…rp}rq(h(Uh2jkubaubeubeubhf)rr}rs(h(XÈWithin DataONE, values of :class:`Types.Subject` can be represented as the string form of a Distinguished Name (DN) as defined in RFC4514_. Distinguished Names are composed of a sequence of Relative Distinguished Names (RDNs), each of which is composed of an attribute type and a value. Subjects are serialized to strings with attribute types in upper case (a DataONE convention), case is preserved for all values. RDNs are separated by commas, and ordering is preserved. Values must be converted to strings following the encoding rules in section 2.4 of RFC4514_. In summary, Subjects in DataONE are often represented as Distinguished Names with the additional constraint that attribute types are in upper case.h2jhPh.hQhjh)}rt(h+]h/]h-]h,]h0]uhWKnhXhhY]ru(hbXWithin DataONE, values of rv…rw}rx(h(XWithin DataONE, values of h2jrubcsphinx.addnodes pending_xref ry)rz}r{(h(X:class:`Types.Subject`r|h2jrhPh.hQU pending_xrefr}h)}r~(UreftypeXclassUrefwarnr‰U reftargetr€X Types.SubjectU refdomainXpyrh,]h-]U refexplicit‰h+]h/]h0]Urefdocr‚Xdesign/AuthenticationrƒUpy:classr„NU py:moduler…NuhWKnhY]r†cdocutils.nodes literal r‡)rˆ}r‰(h(j|h)}rŠ(h+]h/]r‹(UxrefrŒjXpy-classreh-]h,]h0]uh2jzhY]rŽhbX Types.Subjectr…r}r‘(h(Uh2jˆubahQUliteralr’ubaubhbXR can be represented as the string form of a Distinguished Name (DN) as defined in r“…r”}r•(h(XR can be represented as the string form of a Distinguished Name (DN) as defined in h2jrubhÈ)r–}r—(h(XRFC4514_hËKh2jrhQhÌh)}r˜(UnameXRFC4514hÎX"http://tools.ietf.org/html/rfc4514r™h,]h-]h+]h/]h0]uhY]ršhbXRFC4514r›…rœ}r(h(Uh2j–ubaubhbX¡. Distinguished Names are composed of a sequence of Relative Distinguished Names (RDNs), each of which is composed of an attribute type and a value. Subjects are serialized to strings with attribute types in upper case (a DataONE convention), case is preserved for all values. RDNs are separated by commas, and ordering is preserved. Values must be converted to strings following the encoding rules in section 2.4 of rž…rŸ}r (h(X¡. Distinguished Names are composed of a sequence of Relative Distinguished Names (RDNs), each of which is composed of an attribute type and a value. Subjects are serialized to strings with attribute types in upper case (a DataONE convention), case is preserved for all values. RDNs are separated by commas, and ordering is preserved. Values must be converted to strings following the encoding rules in section 2.4 of h2jrubhÈ)r¡}r¢(h(XRFC4514_hËKh2jrhQhÌh)}r£(UnameXRFC4514hÎj™h,]h-]h+]h/]h0]uhY]r¤hbXRFC4514r¥…r¦}r§(h(Uh2j¡ubaubhbX•. In summary, Subjects in DataONE are often represented as Distinguished Names with the additional constraint that attribute types are in upper case.r¨…r©}rª(h(X•. In summary, Subjects in DataONE are often represented as Distinguished Names with the additional constraint that attribute types are in upper case.h2jrubeubhf)r«}r¬(h(XáThis approach enables simple string comparison to provide accurate results within the DataONE infrastructure and services and is fully compatible with existing services that utilize Distinguished Names as defined in RFC4510_.h2jhPh.hQhjh)}r­(h+]h/]h-]h,]h0]uhWKyhXhhY]r®(hbXØThis approach enables simple string comparison to provide accurate results within the DataONE infrastructure and services and is fully compatible with existing services that utilize Distinguished Names as defined in r¯…r°}r±(h(XØThis approach enables simple string comparison to provide accurate results within the DataONE infrastructure and services and is fully compatible with existing services that utilize Distinguished Names as defined in h2j«ubcdocutils.nodes problematic r²)r³}r´(h(XRFC4510_rµh2j«hPNhQU problematicr¶h)}r·(h,]r¸Uid2r¹ah-]h+]h/]h0]UrefidUid1rºuhWNhXhhY]r»hbXRFC4510_r¼…r½}r¾(h(Uh2j³ubaubhbX.…r¿}rÀ(h(X.h2j«ubeubj)rÁ}rÂ(h(XŠ.. _eduPersonPrincipalName: http://middleware.internet2.edu/eduperson/docs/internet2-mace-dir-eduperson-200806.html#eduPersonPrincipalNameh2jhPh.hQjh)}rÃ(hÎXnhttp://middleware.internet2.edu/eduperson/docs/internet2-mace-dir-eduperson-200806.html#eduPersonPrincipalNameh,]rÄUedupersonprincipalnamerÅah-]h+]h/]h0]rÆhauhWK~hXhhY]ubj)rÇ}rÈ(h(X‹.. _TeraGridPrincipalNames: http://www.teragridforum.org/mediawiki/index.php?title=SAML_NameIDs_for_TeraGrid#TeraGrid_Principal_Name_Formath2jhPh.hQjh)}rÉ(hÎXohttp://www.teragridforum.org/mediawiki/index.php?title=SAML_NameIDs_for_TeraGrid#TeraGrid_Principal_Name_Formath,]rÊUteragridprincipalnamesrËah-]h+]h/]h0]rÌh auhWK€hXhhY]ubj)rÍ}rÎ(h(X1.. _FOAF: http://xmlns.com/foaf/spec/#term_Personh2jhPh.hQjh)}rÏ(hÎX'http://xmlns.com/foaf/spec/#term_Personh,]rÐUfoafrÑah-]h+]h/]h0]rÒhauhWK‚hXhhY]ubj)rÓ}rÔ(h(X... _RC4510: http://tools.ietf.org/html/rfc4510h2jhPh.hQjh)}rÕ(hÎX"http://tools.ietf.org/html/rfc4510h,]rÖUrc4510r×ah-]h+]h/]h0]rØhauhWK„hXhhY]ubj)rÙ}rÚ(h(X/.. _RFC4514: http://tools.ietf.org/html/rfc4514jKh2jhPh.hQjh)}rÛ(hÎj™h,]rÜUrfc4514rÝah-]h+]h/]h0]rÞhauhWK†hXhhY]ubeubhK)rß}rà(h(Uh2h¢hPh.hQhRh)}rá(h+]h/]h-]h,]râUsymbolic-principalsrãah0]räh auhWKŠhXhhY]rå(h[)ræ}rç(h(XSymbolic Principalsrèh2jßhPh.hQh_h)}ré(h+]h/]h-]h,]h0]uhWKŠhXhhY]rêhbXSymbolic Principalsrë…rì}rí(h(jèh2jæubaubhf)rî}rï(h(XâIn addition to named users, access policies can refer to several special symbolic groups of users that do not need to be explicitly enumerated, but define classes of people in the system. The reserved symbolic principals are:rðh2jßhPh.hQhjh)}rñ(h+]h/]h-]h,]h0]uhWKŒhXhhY]ròhbXâIn addition to named users, access policies can refer to several special symbolic groups of users that do not need to be explicitly enumerated, but define classes of people in the system. The reserved symbolic principals are:ró…rô}rõ(h(jðh2jîubaubh7)rö}r÷(h(Uh2jßhPh.hQhzh)}rø(h;X*h,]h-]h+]h/]h0]uhWKhXhhY]rù(h3)rú}rû(h(XðVerified authenticated users * A user who has a valid authentication token and an 'isVerified' flag. This designation is be used to ensure that users are in fact who they claim to be. These accounts have originated from trusted affiliate organizations or identity services or have been manually verified by an administrator. The identity information when logged during read operations should be fully trusted. * Represented using the special principal **verifiedUser** h2jöhPh.hQhh)}rü(h+]h/]h-]h,]h0]uhWNhXhhY]rý(hf)rþ}rÿ(h(XVerified authenticated usersrh2júhPh.hQhjh)}r(h+]h/]h-]h,]h0]uhWKhY]rhbXVerified authenticated usersr…r}r(h(jh2jþubaubcdocutils.nodes block_quote r)r}r(h(Uh)}r (h+]h/]h-]h,]h0]uh2júhY]r h7)r }r (h(Uh)}r (h;X*h,]h-]h+]h/]h0]uh2jhY]r(h3)r}r(h(X|A user who has a valid authentication token and an 'isVerified' flag. This designation is be used to ensure that users are in fact who they claim to be. These accounts have originated from trusted affiliate organizations or identity services or have been manually verified by an administrator. The identity information when logged during read operations should be fully trusted. h)}r(h+]h/]h-]h,]h0]uh2j hY]r(hf)r}r(h(XEA user who has a valid authentication token and an 'isVerified' flag.rh2jhPh.hQhjh)}r(h+]h/]h-]h,]h0]uhWK’hY]rhbXEA user who has a valid authentication token and an 'isVerified' flag.r…r}r(h(jh2jubaubhf)r}r(h(X4This designation is be used to ensure that users are in fact who they claim to be. These accounts have originated from trusted affiliate organizations or identity services or have been manually verified by an administrator. The identity information when logged during read operations should be fully trusted.rh2jhPh.hQhjh)}r(h+]h/]h-]h,]h0]uhWK”hY]rhbX4This designation is be used to ensure that users are in fact who they claim to be. These accounts have originated from trusted affiliate organizations or identity services or have been manually verified by an administrator. The identity information when logged during read operations should be fully trusted.r …r!}r"(h(jh2jubaubehQhubh3)r#}r$(h(X9Represented using the special principal **verifiedUser** h)}r%(h+]h/]h-]h,]h0]uh2j hY]r&hf)r'}r((h(X8Represented using the special principal **verifiedUser**h2j#hPh.hQhjh)}r)(h+]h/]h-]h,]h0]uhWKšhY]r*(hbX(Represented using the special principal r+…r,}r-(h(X(Represented using the special principal h2j'ubcdocutils.nodes strong r.)r/}r0(h(X**verifiedUser**h)}r1(h+]h/]h-]h,]h0]uh2j'hY]r2hbX verifiedUserr3…r4}r5(h(Uh2j/ubahQUstrongr6ubeubahQhubehQhzubahQU block_quoter7ubeubh3)r8}r9(h(XõAuthenticated users * Any user who has a valid authentication token is considered a member of the authenticated users group. This designation can be used in particular to require that user identity has been established, but not necessarily verified as accurate. Authenticated users may be restricted from certain [read] operations depending on the data owners' policy regarding access for untrusted identities. * Represented using the special principal **authenticatedUser** h2jöhPh.hQhh)}r:(h+]h/]h-]h,]h0]uhWNhXhhY]r;(hf)r<}r=(h(XAuthenticated usersr>h2j8hPh.hQhjh)}r?(h+]h/]h-]h,]h0]uhWKœhY]r@hbXAuthenticated usersrA…rB}rC(h(j>h2j<ubaubj)rD}rE(h(Uh)}rF(h+]h/]h-]h,]h0]uh2j8hY]rGh7)rH}rI(h(Uh)}rJ(h;X*h,]h-]h+]h/]h0]uh2jDhY]rK(h3)rL}rM(h(X…Any user who has a valid authentication token is considered a member of the authenticated users group. This designation can be used in particular to require that user identity has been established, but not necessarily verified as accurate. Authenticated users may be restricted from certain [read] operations depending on the data owners' policy regarding access for untrusted identities. h)}rN(h+]h/]h-]h,]h0]uh2jHhY]rOhf)rP}rQ(h(X„Any user who has a valid authentication token is considered a member of the authenticated users group. This designation can be used in particular to require that user identity has been established, but not necessarily verified as accurate. Authenticated users may be restricted from certain [read] operations depending on the data owners' policy regarding access for untrusted identities.rRh2jLhPh.hQhjh)}rS(h+]h/]h-]h,]h0]uhWKžhY]rThbX„Any user who has a valid authentication token is considered a member of the authenticated users group. This designation can be used in particular to require that user identity has been established, but not necessarily verified as accurate. Authenticated users may be restricted from certain [read] operations depending on the data owners' policy regarding access for untrusted identities.rU…rV}rW(h(jRh2jPubaubahQhubh3)rX}rY(h(X>Represented using the special principal **authenticatedUser** h)}rZ(h+]h/]h-]h,]h0]uh2jHhY]r[hf)r\}r](h(X=Represented using the special principal **authenticatedUser**h2jXhPh.hQhjh)}r^(h+]h/]h-]h,]h0]uhWK¥hY]r_(hbX(Represented using the special principal r`…ra}rb(h(X(Represented using the special principal h2j\ubj.)rc}rd(h(X**authenticatedUser**h)}re(h+]h/]h-]h,]h0]uh2j\hY]rfhbXauthenticatedUserrg…rh}ri(h(Uh2jcubahQj6ubeubahQhubehQhzubahQj7ubeubh3)rj}rk(h(X1Public user * The Public user represents any user accessing services that does not have a valid session token, plus all of those who do have a valid token. If a token is found to be invalid, the user's privileges are immediately lowered to those of the symbolic 'public' user. For create, update, and delete operations, this typically means that the user has insufficient privileges to access the service. At times providers may want to provide public read access to resources. * Represented using the special principal **public** h2jöhPh.hQhh)}rl(h+]h/]h-]h,]h0]uhWNhXhhY]rm(hf)rn}ro(h(X Public userrph2jjhPh.hQhjh)}rq(h+]h/]h-]h,]h0]uhWK§hY]rrhbX Public userrs…rt}ru(h(jph2jnubaubj)rv}rw(h(Uh)}rx(h+]h/]h-]h,]h0]uh2jjhY]ryh7)rz}r{(h(Uh)}r|(h;X*h,]h-]h+]h/]h0]uh2jvhY]r}(h3)r~}r(h(XÐThe Public user represents any user accessing services that does not have a valid session token, plus all of those who do have a valid token. If a token is found to be invalid, the user's privileges are immediately lowered to those of the symbolic 'public' user. For create, update, and delete operations, this typically means that the user has insufficient privileges to access the service. At times providers may want to provide public read access to resources. h)}r€(h+]h/]h-]h,]h0]uh2jzhY]rhf)r‚}rƒ(h(XÏThe Public user represents any user accessing services that does not have a valid session token, plus all of those who do have a valid token. If a token is found to be invalid, the user's privileges are immediately lowered to those of the symbolic 'public' user. For create, update, and delete operations, this typically means that the user has insufficient privileges to access the service. At times providers may want to provide public read access to resources.r„h2j~hPh.hQhjh)}r…(h+]h/]h-]h,]h0]uhWK©hY]r†hbXÏThe Public user represents any user accessing services that does not have a valid session token, plus all of those who do have a valid token. If a token is found to be invalid, the user's privileges are immediately lowered to those of the symbolic 'public' user. For create, update, and delete operations, this typically means that the user has insufficient privileges to access the service. At times providers may want to provide public read access to resources.r‡…rˆ}r‰(h(j„h2j‚ubaubahQhubh3)rŠ}r‹(h(X3Represented using the special principal **public** h)}rŒ(h+]h/]h-]h,]h0]uh2jzhY]rhf)rŽ}r(h(X2Represented using the special principal **public**h2jŠhPh.hQhjh)}r(h+]h/]h-]h,]h0]uhWK±hY]r‘(hbX(Represented using the special principal r’…r“}r”(h(X(Represented using the special principal h2jŽubj.)r•}r–(h(X **public**h)}r—(h+]h/]h-]h,]h0]uh2jŽhY]r˜hbXpublicr™…rš}r›(h(Uh2j•ubahQj6ubeubahQhubehQhzubahQj7ubeubeubeubhK)rœ}r(h(Uh2h¢hPh.hQhRh)}rž(h+]h/]h-]h,]rŸUidentity-management-servicer ah0]r¡hauhWK´hXhhY]r¢(h[)r£}r¤(h(XIdentity Management Servicer¥h2jœhPh.hQh_h)}r¦(h+]h/]h-]h,]h0]uhWK´hXhhY]r§hbXIdentity Management Servicer¨…r©}rª(h(j¥h2j£ubaubhf)r«}r¬(h(XÚThe DataONE Identity Management service provides individuals with the ability to register a DataONE user account with the system and to set information into their profile. This process creates a new identifier value for the user that uniquely identifies them in DataONE from other DataONE users. This identifier is critical because it associates the user with an authenticated session for use when requesting services and or data/metadata resources from the DataONE nodes.r­h2jœhPh.hQhjh)}r®(h+]h/]h-]h,]h0]uhWK¶hXhhY]r¯hbXÚThe DataONE Identity Management service provides individuals with the ability to register a DataONE user account with the system and to set information into their profile. This process creates a new identifier value for the user that uniquely identifies them in DataONE from other DataONE users. This identifier is critical because it associates the user with an authenticated session for use when requesting services and or data/metadata resources from the DataONE nodes.r°…r±}r²(h(j­h2j«ubaubhf)r³}r´(h(XNThe general application flow for a user to use DataONE services is to first log into CILogon or ORCID with an identity of their choice, then to register that identity with DataONE by calling the :func:`CN_auth.registerAccount` service. An authorized third party (such as a site manager) can then call :func:`CN_auth.verifyAccount` to verify that the real name, email address, and other biographical information about the Person are correct. A user with more than one Identity can call :func:`CN_auth.mapIdentity` to link those two identities together as equivalent identities. Once this registration process is complete, future authentication steps with CILogon will produce X.509 certificates that contain this biographical and account information in the returned certficate, all of which can be used by services to make authorization decisions.h2jœhPh.hQhjh)}rµ(h+]h/]h-]h,]h0]uhWK¾hXhhY]r¶(hbXÃThe general application flow for a user to use DataONE services is to first log into CILogon or ORCID with an identity of their choice, then to register that identity with DataONE by calling the r·…r¸}r¹(h(XÃThe general application flow for a user to use DataONE services is to first log into CILogon or ORCID with an identity of their choice, then to register that identity with DataONE by calling the h2j³ubjy)rº}r»(h(X:func:`CN_auth.registerAccount`r¼h2j³hPh.hQj}h)}r½(UreftypeXfuncj‰j€XCN_auth.registerAccountU refdomainXpyr¾h,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWK¾hY]r¿j‡)rÀ}rÁ(h(j¼h)}rÂ(h+]h/]rÃ(jŒj¾Xpy-funcrÄeh-]h,]h0]uh2jºhY]rÅhbXCN_auth.registerAccount()rÆ…rÇ}rÈ(h(Uh2jÀubahQj’ubaubhbXK service. An authorized third party (such as a site manager) can then call rÉ…rÊ}rË(h(XK service. An authorized third party (such as a site manager) can then call h2j³ubjy)rÌ}rÍ(h(X:func:`CN_auth.verifyAccount`rÎh2j³hPh.hQj}h)}rÏ(UreftypeXfuncj‰j€XCN_auth.verifyAccountU refdomainXpyrÐh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWK¾hY]rÑj‡)rÒ}rÓ(h(jÎh)}rÔ(h+]h/]rÕ(jŒjÐXpy-funcrÖeh-]h,]h0]uh2jÌhY]r×hbXCN_auth.verifyAccount()rØ…rÙ}rÚ(h(Uh2jÒubahQj’ubaubhbX› to verify that the real name, email address, and other biographical information about the Person are correct. A user with more than one Identity can call rÛ…rÜ}rÝ(h(X› to verify that the real name, email address, and other biographical information about the Person are correct. A user with more than one Identity can call h2j³ubjy)rÞ}rß(h(X:func:`CN_auth.mapIdentity`ràh2j³hPh.hQj}h)}rá(UreftypeXfuncj‰j€XCN_auth.mapIdentityU refdomainXpyrâh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWK¾hY]rãj‡)rä}rå(h(jàh)}ræ(h+]h/]rç(jŒjâXpy-funcrèeh-]h,]h0]uh2jÞhY]réhbXCN_auth.mapIdentity()rê…rë}rì(h(Uh2jäubahQj’ubaubhbXN to link those two identities together as equivalent identities. Once this registration process is complete, future authentication steps with CILogon will produce X.509 certificates that contain this biographical and account information in the returned certficate, all of which can be used by services to make authorization decisions.rí…rî}rï(h(XN to link those two identities together as equivalent identities. Once this registration process is complete, future authentication steps with CILogon will produce X.509 certificates that contain this biographical and account information in the returned certficate, all of which can be used by services to make authorization decisions.h2j³ubeubh7)rð}rñ(h(Uh2jœhPh.hQhzh)}rò(h;X*h,]h-]h+]h/]h0]uhWKÊhXhhY]ró(h3)rô}rõ(h(XO:func:`CN_auth.registerAccount` Register an identity with the DataONE IdentityService. When a user attempts to use a given identity at DataONE, the user must first register the identity and provide biographical information including their real name, real email address, and other identifying attributes. Takes a Person description including principal, givenName, familyName, and email address as input (other elements from the Person description such as isMemberOf, equivalentIdentity, and verifiedBy are ignored during registration because these elements are populated by other services). h2jðhPh.hQhh)}rö(h+]h/]h-]h,]h0]uhWNhXhhY]r÷(hf)rø}rù(h(X:func:`CN_auth.registerAccount`rúh2jôhPh.hQhjh)}rû(h+]h/]h-]h,]h0]uhWKÊhY]rüjy)rý}rþ(h(júh2jøhPh.hQj}h)}rÿ(UreftypeXfuncj‰j€XCN_auth.registerAccountU refdomainXpyrh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWKÊhY]rj‡)r}r(h(júh)}r(h+]h/]r(jŒjXpy-funcreh-]h,]h0]uh2jýhY]rhbXCN_auth.registerAccount()r…r }r (h(Uh2jubahQj’ubaubaubhf)r }r (h(X-Register an identity with the DataONE IdentityService. When a user attempts to use a given identity at DataONE, the user must first register the identity and provide biographical information including their real name, real email address, and other identifying attributes. Takes a Person description including principal, givenName, familyName, and email address as input (other elements from the Person description such as isMemberOf, equivalentIdentity, and verifiedBy are ignored during registration because these elements are populated by other services).r h2jôhPh.hQhjh)}r(h+]h/]h-]h,]h0]uhWKÌhY]rhbX-Register an identity with the DataONE IdentityService. When a user attempts to use a given identity at DataONE, the user must first register the identity and provide biographical information including their real name, real email address, and other identifying attributes. Takes a Person description including principal, givenName, familyName, and email address as input (other elements from the Person description such as isMemberOf, equivalentIdentity, and verifiedBy are ignored during registration because these elements are populated by other services).r…r}r(h(j h2j ubaubeubh3)r}r(h(XŠ:func:`CN_auth.verifyAccount` Verify that an Person is an accurate portrayal of the real-life name and identity of the named individual. h2jðhPh.hQhh)}r(h+]h/]h-]h,]h0]uhWNhXhhY]r(hf)r}r(h(X:func:`CN_auth.verifyAccount`rh2jhPh.hQhjh)}r(h+]h/]h-]h,]h0]uhWKÕhY]rjy)r}r(h(jh2jhPh.hQj}h)}r(UreftypeXfuncj‰j€XCN_auth.verifyAccountU refdomainXpyrh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWKÕhY]r j‡)r!}r"(h(jh)}r#(h+]h/]r$(jŒjXpy-funcr%eh-]h,]h0]uh2jhY]r&hbXCN_auth.verifyAccount()r'…r(}r)(h(Uh2j!ubahQj’ubaubaubhf)r*}r+(h(XjVerify that an Person is an accurate portrayal of the real-life name and identity of the named individual.r,h2jhPh.hQhjh)}r-(h+]h/]h-]h,]h0]uhWK×hY]r.hbXjVerify that an Person is an accurate portrayal of the real-life name and identity of the named individual.r/…r0}r1(h(j,h2j*ubaubeubh3)r2}r3(h(XŸ:func:`CN_auth.mapIdentity` Create an equivalence mapping between the identities listed for the users authenticated and represented by session1 and session2. h2jðhPh.hQhh)}r4(h+]h/]h-]h,]h0]uhWNhXhhY]r5(hf)r6}r7(h(X:func:`CN_auth.mapIdentity`r8h2j2hPh.hQhjh)}r9(h+]h/]h-]h,]h0]uhWKÚhY]r:jy)r;}r<(h(j8h2j6hPh.hQj}h)}r=(UreftypeXfuncj‰j€XCN_auth.mapIdentityU refdomainXpyr>h,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWKÚhY]r?j‡)r@}rA(h(j8h)}rB(h+]h/]rC(jŒj>Xpy-funcrDeh-]h,]h0]uh2j;hY]rEhbXCN_auth.mapIdentity()rF…rG}rH(h(Uh2j@ubahQj’ubaubaubhf)rI}rJ(h(XCreate an equivalence mapping between the identities listed for the users authenticated and represented by session1 and session2.rKh2j2hPh.hQhjh)}rL(h+]h/]h-]h,]h0]uhWKÜhY]rMhbXCreate an equivalence mapping between the identities listed for the users authenticated and represented by session1 and session2.rN…rO}rP(h(jKh2jIubaubeubh3)rQ}rR(h(X§:func:`CN_auth.confirmMapIdentity` Confirm an equivalence mapping between the identities listed for the users authenticated and represented by session1 and session2. h2jðhPh.hQhh)}rS(h+]h/]h-]h,]h0]uhWNhXhhY]rT(hf)rU}rV(h(X":func:`CN_auth.confirmMapIdentity`rWh2jQhPh.hQhjh)}rX(h+]h/]h-]h,]h0]uhWKßhY]rYjy)rZ}r[(h(jWh2jUhPh.hQj}h)}r\(UreftypeXfuncj‰j€XCN_auth.confirmMapIdentityU refdomainXpyr]h,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWKßhY]r^j‡)r_}r`(h(jWh)}ra(h+]h/]rb(jŒj]Xpy-funcrceh-]h,]h0]uh2jZhY]rdhbXCN_auth.confirmMapIdentity()re…rf}rg(h(Uh2j_ubahQj’ubaubaubhf)rh}ri(h(X‚Confirm an equivalence mapping between the identities listed for the users authenticated and represented by session1 and session2.rjh2jQhPh.hQhjh)}rk(h+]h/]h-]h,]h0]uhWKáhY]rlhbX‚Confirm an equivalence mapping between the identities listed for the users authenticated and represented by session1 and session2.rm…rn}ro(h(jjh2jhubaubeubh3)rp}rq(h(X†:func:`CN_auth.getSubjectInfo` Get the information about a Person, their equivalent identities, and the Groups to which they belong. h2jðhPh.hQhh)}rr(h+]h/]h-]h,]h0]uhWNhXhhY]rs(hf)rt}ru(h(X:func:`CN_auth.getSubjectInfo`rvh2jphPh.hQhjh)}rw(h+]h/]h-]h,]h0]uhWKähY]rxjy)ry}rz(h(jvh2jthPh.hQj}h)}r{(UreftypeXfuncj‰j€XCN_auth.getSubjectInfoU refdomainXpyr|h,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWKähY]r}j‡)r~}r(h(jvh)}r€(h+]h/]r(jŒj|Xpy-funcr‚eh-]h,]h0]uh2jyhY]rƒhbXCN_auth.getSubjectInfo()r„…r…}r†(h(Uh2j~ubahQj’ubaubaubhf)r‡}rˆ(h(XeGet the information about a Person, their equivalent identities, and the Groups to which they belong.r‰h2jphPh.hQhjh)}rŠ(h+]h/]h-]h,]h0]uhWKæhY]r‹hbXeGet the information about a Person, their equivalent identities, and the Groups to which they belong.rŒ…r}rŽ(h(j‰h2j‡ubaubeubh3)r}r(h(XV:func:`CN_auth.listSubjects` Query for a matching set of users, groups, and systems. h2jðhPh.hQhh)}r‘(h+]h/]h-]h,]h0]uhWNhXhhY]r’(hf)r“}r”(h(X:func:`CN_auth.listSubjects`r•h2jhPh.hQhjh)}r–(h+]h/]h-]h,]h0]uhWKéhY]r—jy)r˜}r™(h(j•h2j“hPh.hQj}h)}rš(UreftypeXfuncj‰j€XCN_auth.listSubjectsU refdomainXpyr›h,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWKéhY]rœj‡)r}rž(h(j•h)}rŸ(h+]h/]r (jŒj›Xpy-funcr¡eh-]h,]h0]uh2j˜hY]r¢hbXCN_auth.listSubjects()r£…r¤}r¥(h(Uh2jubahQj’ubaubaubhf)r¦}r§(h(X7Query for a matching set of users, groups, and systems.r¨h2jhPh.hQhjh)}r©(h+]h/]h-]h,]h0]uhWKëhY]rªhbX7Query for a matching set of users, groups, and systems.r«…r¬}r­(h(j¨h2j¦ubaubeubh3)r®}r¯(h(X|:func:`CN_auth.createGroup` Create a named group of users. Throws IdentifierNotUnique if the group name is already in use. h2jðhPh.hQhh)}r°(h+]h/]h-]h,]h0]uhWNhXhhY]r±(hf)r²}r³(h(X:func:`CN_auth.createGroup`r´h2j®hPh.hQhjh)}rµ(h+]h/]h-]h,]h0]uhWKíhY]r¶jy)r·}r¸(h(j´h2j²hPh.hQj}h)}r¹(UreftypeXfuncj‰j€XCN_auth.createGroupU refdomainXpyrºh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWKíhY]r»j‡)r¼}r½(h(j´h)}r¾(h+]h/]r¿(jŒjºXpy-funcrÀeh-]h,]h0]uh2j·hY]rÁhbXCN_auth.createGroup()rÂ…rÃ}rÄ(h(Uh2j¼ubahQj’ubaubaubhf)rÅ}rÆ(h(X^Create a named group of users. Throws IdentifierNotUnique if the group name is already in use.rÇh2j®hPh.hQhjh)}rÈ(h+]h/]h-]h,]h0]uhWKïhY]rÉhbX^Create a named group of users. Throws IdentifierNotUnique if the group name is already in use.rÊ…rË}rÌ(h(jÇh2jÅubaubeubh3)rÍ}rÎ(h(X :func:`CN_auth.addGroupMembers` Add the listed array of members to the named group, if and only if the user represented in token originally created the group. h2jðhPh.hQhh)}rÏ(h+]h/]h-]h,]h0]uhWNhXhhY]rÐ(hf)rÑ}rÒ(h(X:func:`CN_auth.addGroupMembers`rÓh2jÍhPh.hQhjh)}rÔ(h+]h/]h-]h,]h0]uhWKòhY]rÕjy)rÖ}r×(h(jÓh2jÑhPh.hQj}h)}rØ(UreftypeXfuncj‰j€XCN_auth.addGroupMembersU refdomainXpyrÙh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWKòhY]rÚj‡)rÛ}rÜ(h(jÓh)}rÝ(h+]h/]rÞ(jŒjÙXpy-funcrßeh-]h,]h0]uh2jÖhY]ràhbXCN_auth.addGroupMembers()rá…râ}rã(h(Uh2jÛubahQj’ubaubaubhf)rä}rå(h(X~Add the listed array of members to the named group, if and only if the user represented in token originally created the group.ræh2jÍhPh.hQhjh)}rç(h+]h/]h-]h,]h0]uhWKôhY]rèhbX~Add the listed array of members to the named group, if and only if the user represented in token originally created the group.ré…rê}rë(h(jæh2jäubaubeubh3)rì}rí(h(Xç:func:`CN_auth.removeGroupMembers` Remove the listed array of members from the named group, if and only if the user represented in token originally created the group or is an equivalent identity of the user who created the group. h2jðhPh.hQhh)}rî(h+]h/]h-]h,]h0]uhWNhXhhY]rï(hf)rð}rñ(h(X":func:`CN_auth.removeGroupMembers`ròh2jìhPh.hQhjh)}ró(h+]h/]h-]h,]h0]uhWK÷hY]rôjy)rõ}rö(h(jòh2jðhPh.hQj}h)}r÷(UreftypeXfuncj‰j€XCN_auth.removeGroupMembersU refdomainXpyrøh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWK÷hY]rùj‡)rú}rû(h(jòh)}rü(h+]h/]rý(jŒjøXpy-funcrþeh-]h,]h0]uh2jõhY]rÿhbXCN_auth.removeGroupMembers()r…r}r(h(Uh2júubahQj’ubaubaubhf)r}r(h(XÂRemove the listed array of members from the named group, if and only if the user represented in token originally created the group or is an equivalent identity of the user who created the group.rh2jìhPh.hQhjh)}r(h+]h/]h-]h,]h0]uhWKùhY]rhbXÂRemove the listed array of members from the named group, if and only if the user represented in token originally created the group or is an equivalent identity of the user who created the group.r…r }r (h(jh2jubaubeubeubcdocutils.nodes figure r )r }r (h(Uh2jœhPh.hQUfigurerh)}r(h+]h/]h-]h,]h0]uhWKþhXhhY]rcdocutils.nodes image r)r}r(h(X .. figure:: images/ident_01.png h2j hPh.hQUimagerh)}r(UuriXdesign/images/ident_01.pngrh,]h-]h+]h/]U candidatesr}rU*jsh0]uhWKþhY]ubaubhf)r}r(h(Xd**Figure 1.** Identity Service is used to register an existing identity with DataONE. In this example, the same user has two distinct pre-existing identities. We register the primary identity with DataONE. We then request that a secondary identity is mapped to the same Types.Subject. The user must then confirm this equivalence between the two identities.h2jœhPh.hQhjh)}r(h+]h/]h-]h,]h0]uhWKÿhXhhY]r(j.)r}r(h(X **Figure 1.**h)}r(h+]h/]h-]h,]h0]uh2jhY]r hbX Figure 1.r!…r"}r#(h(Uh2jubahQj6ubhbXW Identity Service is used to register an existing identity with DataONE. In this example, the same user has two distinct pre-existing identities. We register the primary identity with DataONE. We then request that a secondary identity is mapped to the same Types.Subject. The user must then confirm this equivalence between the two identities.r$…r%}r&(h(XW Identity Service is used to register an existing identity with DataONE. In this example, the same user has two distinct pre-existing identities. We register the primary identity with DataONE. We then request that a secondary identity is mapped to the same Types.Subject. The user must then confirm this equivalence between the two identities.h2jubeubcdocutils.nodes comment r')r(}r)(h(X&@startuml images/ident_01.png title Register two existing accounts as equivalent identities participant "CILogon" as cilogon participant "Client" as client << Application >> note right of client Client controlled by User who has two identities end note participant "IdentityService" as ident << CNode >> group username@NCEAS 'authenticate as primary id client -> cilogon:authenticate with primary identity client <- cilogon: X.509 'register this identity with DataONE client -> ident: registerAccount(Types.Session, Types.Person) ident --> client: Types.Subject client -> client:logout (dispose X.509) end ... group username@UCSB 'authenticate as secondary id client -> cilogon:authenticate with secondary identity client <- cilogon: X.509 'list existing Subjects client -> ident:listSubjects() ident --> client:Types.SubjectList client -> client:select equivalent Types.Subject 'request to map identity with existing Subject client -> ident: mapIdentity(Types.Session, Types.Subject) ident --> client: boolean note left request must be confirmed before equivalence is final end note client -> client:logout (dispose X.509) end ... group username@NCEAS 'authenticate as primary id client -> cilogon:authenticate with primary identity client <- cilogon: X.509 'confirm mapping identity with DataONE client -> ident: confirmMapIdentity(Types.Session, Types.Subject) ident --> client: boolean note left equivalence is confirmed end note client -> client:logout (dispose X.509) end @endumlh2jœhPh.hQUcommentr*h)}r+(jRjSh,]h-]h+]h/]h0]uhWM<hXhhY]r,hbX&@startuml images/ident_01.png title Register two existing accounts as equivalent identities participant "CILogon" as cilogon participant "Client" as client << Application >> note right of client Client controlled by User who has two identities end note participant "IdentityService" as ident << CNode >> group username@NCEAS 'authenticate as primary id client -> cilogon:authenticate with primary identity client <- cilogon: X.509 'register this identity with DataONE client -> ident: registerAccount(Types.Session, Types.Person) ident --> client: Types.Subject client -> client:logout (dispose X.509) end ... group username@UCSB 'authenticate as secondary id client -> cilogon:authenticate with secondary identity client <- cilogon: X.509 'list existing Subjects client -> ident:listSubjects() ident --> client:Types.SubjectList client -> client:select equivalent Types.Subject 'request to map identity with existing Subject client -> ident: mapIdentity(Types.Session, Types.Subject) ident --> client: boolean note left request must be confirmed before equivalence is final end note client -> client:logout (dispose X.509) end ... group username@NCEAS 'authenticate as primary id client -> cilogon:authenticate with primary identity client <- cilogon: X.509 'confirm mapping identity with DataONE client -> ident: confirmMapIdentity(Types.Session, Types.Subject) ident --> client: boolean note left equivalence is confirmed end note client -> client:logout (dispose X.509) end @endumlr-…r.}r/(h(Uh2j(ubaubj )r0}r1(h(Uh2jœhPh.hQjh)}r2(h+]h/]h-]h,]h0]uhWM>hXhhY]r3j)r4}r5(h(X .. figure:: images/ident_02.png h2j0hPh.hQjh)}r6(UuriXdesign/images/ident_02.pngr7h,]h-]h+]h/]j}r8U*j7sh0]uhWM>hY]ubaubhf)r9}r:(h(XŽ**Figure 2.** Identity Service is used to register an existing identity with DataONE. In this example, the user has an identity affiliation that is not initially trusted. We register the identity with DataONE as unverified. An administrator needs to verify the Person details before the identity is considered fully verified. Some DataONE actions will be restricted until verification is completed.h2jœhPh.hQhjh)}r;(h+]h/]h-]h,]h0]uhWM?hXhhY]r<(j.)r=}r>(h(X **Figure 2.**h)}r?(h+]h/]h-]h,]h0]uh2j9hY]r@hbX Figure 2.rA…rB}rC(h(Uh2j=ubahQj6ubhbX Identity Service is used to register an existing identity with DataONE. In this example, the user has an identity affiliation that is not initially trusted. We register the identity with DataONE as unverified. An administrator needs to verify the Person details before the identity is considered fully verified. Some DataONE actions will be restricted until verification is completed.rD…rE}rF(h(X Identity Service is used to register an existing identity with DataONE. In this example, the user has an identity affiliation that is not initially trusted. We register the identity with DataONE as unverified. An administrator needs to verify the Person details before the identity is considered fully verified. Some DataONE actions will be restricted until verification is completed.h2j9ubeubj')rG}rH(h(XM@startuml images/ident_02.png title Register untrusted account and verify it participant "CILogon" as cilogon participant "Client" as client << Application >> note right of client Client controlled by User and by Admin end note participant "IdentityService" as ident << CNode >> group username@google 'authenticate as primary id client -> cilogon:authenticate with untrusted identity client <- cilogon: X.509 'register this identity with DataONE client -> ident: registerAccount(Types.Session, Types.Person) ident --> client: Types.Subject client -> client:logout (dispose X.509) end ... group admin@UCSB 'authenticate as secondary id client -> cilogon:administrator authenticate client <- cilogon: X.509 client -> ident:getSubjectInfo(Types.Session, Types.Subject) ident --> client:Types.Person note left Administrator must verify Person details end note 'request to map identity with existing Subject client -> ident: verifyIdentity(Types.Session, Types.Subject) ident --> client: boolean client -> client:logout (dispose X.509) end @endumlh2jœhPh.hQj*h)}rI(jRjSh,]h-]h+]h/]h0]uhWMlhXhhY]rJhbXM@startuml images/ident_02.png title Register untrusted account and verify it participant "CILogon" as cilogon participant "Client" as client << Application >> note right of client Client controlled by User and by Admin end note participant "IdentityService" as ident << CNode >> group username@google 'authenticate as primary id client -> cilogon:authenticate with untrusted identity client <- cilogon: X.509 'register this identity with DataONE client -> ident: registerAccount(Types.Session, Types.Person) ident --> client: Types.Subject client -> client:logout (dispose X.509) end ... group admin@UCSB 'authenticate as secondary id client -> cilogon:administrator authenticate client <- cilogon: X.509 client -> ident:getSubjectInfo(Types.Session, Types.Subject) ident --> client:Types.Person note left Administrator must verify Person details end note 'request to map identity with existing Subject client -> ident: verifyIdentity(Types.Session, Types.Subject) ident --> client: boolean client -> client:logout (dispose X.509) end @endumlrK…rL}rM(h(Uh2jGubaubj )rN}rO(h(Uh2jœhPh.hQjh)}rP(h+]h/]h-]h,]h0]uhWMnhXhhY]rQj)rR}rS(h(X .. figure:: images/ident_03.png h2jNhPh.hQjh)}rT(UuriXdesign/images/ident_03.pngrUh,]h-]h+]h/]j}rVU*jUsh0]uhWMnhY]ubaubhf)rW}rX(h(Xß**Figure 3.** Identity Service is used to manage groups. The group creator is initially the only user able to add and remove group members. List editing permissions must be granted for other group members to edit the group.h2jœhPh.hQhjh)}rY(h+]h/]h-]h,]h0]uhWMohXhhY]rZ(j.)r[}r\(h(X **Figure 3.**h)}r](h+]h/]h-]h,]h0]uh2jWhY]r^hbX Figure 3.r_…r`}ra(h(Uh2j[ubahQj6ubhbXÒ Identity Service is used to manage groups. The group creator is initially the only user able to add and remove group members. List editing permissions must be granted for other group members to edit the group.rb…rc}rd(h(XÒ Identity Service is used to manage groups. The group creator is initially the only user able to add and remove group members. List editing permissions must be granted for other group members to edit the group.h2jWubeubj')re}rf(h(X@startuml images/ident_03.png title Group management participant "CILogon" as cilogon participant "Client" as client << Application >> note right of client Client controlled by group administrator end note participant "IdentityService" as ident << CNode >> group admin@UCSB 'authenticate as admin id client -> cilogon:authenticate admin identity client <- cilogon: X.509 'create group client -> ident: createGroup(Types.Session, Types.Subject) ident --> client: Types.Identifier 'add members client -> ident: addGroupMembers(Types.Session, Types.Subject, Types.SubjectList) ident --> client: Types.Identifier note left Administrator can edit group end note 'remove members client -> ident: removeGroupMembers(Types.Session, Types.Subject, Types.SubjectList) ident --> client: Types.Identifier client -> client:logout (dispose X.509) end @endumlh2jœhPh.hQj*h)}rg(jRjSh,]h-]h+]h/]h0]uhWM“hXhhY]rhhbX@startuml images/ident_03.png title Group management participant "CILogon" as cilogon participant "Client" as client << Application >> note right of client Client controlled by group administrator end note participant "IdentityService" as ident << CNode >> group admin@UCSB 'authenticate as admin id client -> cilogon:authenticate admin identity client <- cilogon: X.509 'create group client -> ident: createGroup(Types.Session, Types.Subject) ident --> client: Types.Identifier 'add members client -> ident: addGroupMembers(Types.Session, Types.Subject, Types.SubjectList) ident --> client: Types.Identifier note left Administrator can edit group end note 'remove members client -> ident: removeGroupMembers(Types.Session, Types.Subject, Types.SubjectList) ident --> client: Types.Identifier client -> client:logout (dispose X.509) end @endumlri…rj}rk(h(Uh2jeubaubeubhK)rl}rm(h(Uh2h¢hPh.hQhRh)}rn(h+]h/]h-]h,]roUauthentication-servicerpah0]rqh auhWM•hXhhY]rr(h[)rs}rt(h(XAuthentication Serviceruh2jlhPh.hQh_h)}rv(h+]h/]h-]h,]h0]uhWM•hXhhY]rwhbXAuthentication Servicerx…ry}rz(h(juh2jsubaubhf)r{}r|(h(XžDataONE is working closely with the CILogon project to streamline and incorporate user identities that originate from academic and commercial institutions in the U.S. that are members of the InCommon federation or through more globally accessible identity providers like Google, Facebook, and Yahoo!. CILogon acts as an intermediary broker of "short-lived" identity assertions that are made by users verifying their identity through their home institution or identity provider service. These assertions are converted by CILogon into a longer-lived and more commonly recognized X.509 identity certificate, which can then be reused a number of times when interacting with DataONE. A benefit of adopting identity management through CILogon is that users who regularly identify themselves through their home institution or other identity service will now be able to access DataONE resources without yet another identity to manage.r}h2jlhPh.hQhjh)}r~(h+]h/]h-]h,]h0]uhWM—hXhhY]rhbXžDataONE is working closely with the CILogon project to streamline and incorporate user identities that originate from academic and commercial institutions in the U.S. that are members of the InCommon federation or through more globally accessible identity providers like Google, Facebook, and Yahoo!. CILogon acts as an intermediary broker of "short-lived" identity assertions that are made by users verifying their identity through their home institution or identity provider service. These assertions are converted by CILogon into a longer-lived and more commonly recognized X.509 identity certificate, which can then be reused a number of times when interacting with DataONE. A benefit of adopting identity management through CILogon is that users who regularly identify themselves through their home institution or other identity service will now be able to access DataONE resources without yet another identity to manage.r€…r}r‚(h(j}h2j{ubaubhf)rƒ}r„(h(XAThe DataONE Authentication Service provides a set of services for validating the identity of users and services and then establishing limited duration sessions that are represented by an X.509 cryptographically-signed certificate or an an authentication API key. A single session is always associated with a single user. The Authentication Service uses various methods to validate the identity of a user in the system, and then produces SubjectInfo and potentially a session certificate in the form of a X.509 certificate that contains the relevant properties for that session.r…h2jlhPh.hQhjh)}r†(h+]h/]h-]h,]h0]uhWM¥hXhhY]r‡hbXAThe DataONE Authentication Service provides a set of services for validating the identity of users and services and then establishing limited duration sessions that are represented by an X.509 cryptographically-signed certificate or an an authentication API key. A single session is always associated with a single user. The Authentication Service uses various methods to validate the identity of a user in the system, and then produces SubjectInfo and potentially a session certificate in the form of a X.509 certificate that contains the relevant properties for that session.rˆ…r‰}rŠ(h(j…h2jƒubaubhf)r‹}rŒ(h(XThe CILogon service supports authentication by redirecting authentication requests to a pre-approved list of Identity Providers associated with user's home institutions. The main source of these Identity Providers are the institutions that are members of the InCommon federation. Users only need to authenticate with their home institution, thereby protecting user credentials by preventing 3rd party clients and services from handling those credentials, and rather only passing the credentials to the user's trusted institutional provider.rh2jlhPh.hQhjh)}rŽ(h+]h/]h-]h,]h0]uhWM®hXhhY]rhbXThe CILogon service supports authentication by redirecting authentication requests to a pre-approved list of Identity Providers associated with user's home institutions. The main source of these Identity Providers are the institutions that are members of the InCommon federation. Users only need to authenticate with their home institution, thereby protecting user credentials by preventing 3rd party clients and services from handling those credentials, and rather only passing the credentials to the user's trusted institutional provider.r…r‘}r’(h(jh2j‹ubaubhf)r“}r”(h(X In general, the user will initiate the request for a session from DataONE through either a dedicated DataONE desktop application or through a web-browser connected to a DataONE web server. After contacting CILogon, the user will be redirected to their institutional provider, which in turn will certify that the user successfully authenticated to CILogon. CILogon then will contact the DataONE Identity service to gather biographical attributes and additional identity attributes such as group memberships and equivalent identities, and produce an X.509 certificate containing these attributes and with a limited duration. This certificate represents a “valid session†via the digitally signed “authentication token†(see below) that is generated by DataONE upon authenticating the user by one of the above mechanisms. The certificate is then returned to the user for subsequent interactions with DataONE, and can be provided to services that need identity information information necessary to perform authorization processing.r•h2jlhPh.hQhjh)}r–(h+]h/]h-]h,]h0]uhWM·hXhhY]r—hbX In general, the user will initiate the request for a session from DataONE through either a dedicated DataONE desktop application or through a web-browser connected to a DataONE web server. After contacting CILogon, the user will be redirected to their institutional provider, which in turn will certify that the user successfully authenticated to CILogon. CILogon then will contact the DataONE Identity service to gather biographical attributes and additional identity attributes such as group memberships and equivalent identities, and produce an X.509 certificate containing these attributes and with a limited duration. This certificate represents a “valid session†via the digitally signed “authentication token†(see below) that is generated by DataONE upon authenticating the user by one of the above mechanisms. The certificate is then returned to the user for subsequent interactions with DataONE, and can be provided to services that need identity information information necessary to perform authorization processing.r˜…r™}rš(h(j•h2j“ubaubhf)r›}rœ(h(X]DataONE web clients will likely use CILogon Portal Delegation (http://www.cilogon.org/portal-delegation) to manage user certificates (rather than the browser). The portal acts as a proxy for the user when interacting with underlying DataONE services that require authentication or authorization. Instead of direct browser-based certificate management, the portal requests and stores user certificates and opaquely presents them to DataONE. This does require development of an extra web application "layer" that provides user session/certificate management in conjunction with the defined DataONE services.h2jlhPh.hQhjh)}r(h+]h/]h-]h,]h0]uhWMÅhXhhY]rž(hbX?DataONE web clients will likely use CILogon Portal Delegation (rŸ…r }r¡(h(X?DataONE web clients will likely use CILogon Portal Delegation (h2j›ubhÈ)r¢}r£(h(X(http://www.cilogon.org/portal-delegationr¤h)}r¥(Urefurij¤h,]h-]h+]h/]h0]uh2j›hY]r¦hbX(http://www.cilogon.org/portal-delegationr§…r¨}r©(h(Uh2j¢ubahQhÌubhbXö) to manage user certificates (rather than the browser). The portal acts as a proxy for the user when interacting with underlying DataONE services that require authentication or authorization. Instead of direct browser-based certificate management, the portal requests and stores user certificates and opaquely presents them to DataONE. This does require development of an extra web application "layer" that provides user session/certificate management in conjunction with the defined DataONE services.rª…r«}r¬(h(Xö) to manage user certificates (rather than the browser). The portal acts as a proxy for the user when interacting with underlying DataONE services that require authentication or authorization. Instead of direct browser-based certificate management, the portal requests and stores user certificates and opaquely presents them to DataONE. This does require development of an extra web application "layer" that provides user session/certificate management in conjunction with the defined DataONE services.h2j›ubeubhf)r­}r®(h(X‘Obtaining a CILogon X.509 certificate requires that the user authenticate through the CILogon InCommon identity services as outlined in Figure 4.r¯h2jlhPh.hQhjh)}r°(h+]h/]h-]h,]h0]uhWMÏhXhhY]r±hbX‘Obtaining a CILogon X.509 certificate requires that the user authenticate through the CILogon InCommon identity services as outlined in Figure 4.r²…r³}r´(h(j¯h2j­ubaubhß)rµ}r¶(h(XSA proposal for mapping existing KNB accounts is included at the bottom of Figure 4.r·h2jlhPh.hQhâh)}r¸(h+]h/]h-]h,]h0]uhWNhXhhY]r¹hf)rº}r»(h(j·h2jµhPh.hQhjh)}r¼(h+]h/]h-]h,]h0]uhWMÔhY]r½hbXSA proposal for mapping existing KNB accounts is included at the bottom of Figure 4.r¾…r¿}rÀ(h(j·h2jºubaubaubj)rÁ}rÂ(h(X.. image:: images/auth_03.png h2jlhPh.hQjh)}rÃ(UuriXdesign/images/auth_03.pngrÄh,]h-]h+]h/]j}rÅU*jÄsh0]uhWM×hXhhY]ubhf)rÆ}rÇ(h(XÎ**Figure 4.** Detailed sequence of events for authentication through CILogon - Client authentication through the CILogon service; CILogon, using Shibboleth, requests a SAML authentication through a registered *Identity Provider* (IdP); the IdP confirms identity and returns SAML response to CILogon; client continues process, the portal delegate requests Certificate from CILogon; CILogon generates X509 certificate and returns it to portal for use with DataONE.h2jlhPh.hQhjh)}rÈ(h+]h/]h-]h,]h0]uhWMØhXhhY]rÉ(j.)rÊ}rË(h(X **Figure 4.**h)}rÌ(h+]h/]h-]h,]h0]uh2jÆhY]rÍhbX Figure 4.rÎ…rÏ}rÐ(h(Uh2jÊubahQj6ubhbXÄ Detailed sequence of events for authentication through CILogon - Client authentication through the CILogon service; CILogon, using Shibboleth, requests a SAML authentication through a registered rÑ…rÒ}rÓ(h(XÄ Detailed sequence of events for authentication through CILogon - Client authentication through the CILogon service; CILogon, using Shibboleth, requests a SAML authentication through a registered h2jÆubcdocutils.nodes emphasis rÔ)rÕ}rÖ(h(X*Identity Provider*h)}r×(h+]h/]h-]h,]h0]uh2jÆhY]rØhbXIdentity ProviderrÙ…rÚ}rÛ(h(Uh2jÕubahQUemphasisrÜubhbXê (IdP); the IdP confirms identity and returns SAML response to CILogon; client continues process, the portal delegate requests Certificate from CILogon; CILogon generates X509 certificate and returns it to portal for use with DataONE.rÝ…rÞ}rß(h(Xê (IdP); the IdP confirms identity and returns SAML response to CILogon; client continues process, the portal delegate requests Certificate from CILogon; CILogon generates X509 certificate and returns it to portal for use with DataONE.h2jÆubeubj')rà}rá(h(XÇ@startuml images/auth_03.png title Detailed CILogon Authentication Sequence participant "IdentityService" as IS << CNode >> participant "Client Browser" as D1 << Application >> participant "Portal" as Portal participant "CILogon" as CI participant "Identity Provider" as IP D1->CI: Select IdP CI-->D1: IdP Redirect note right CIlogon redirect to IdP using "document.forms[0].submit()" posting SAML request to IdP end note D1->IP: Identity Verification IP-->D1: CILogon Redirect note right IdP redirect to CILogon using "document.forms[0].submit()" posting SAML response to CILogon end note create Portal D1 -> Portal Portal->CI: "Download Certificate" CI->IS: getPrincipalInfo(Principal) IS-->CI: PrincipalList CI->CI: Generate and Sign X.509 CI-->Portal: X.509 group For existing KNB identities participant "Metacat API" as Metacat create Metacat D1->Metacat: authenticate with KNB identity/credentials D1<--Metacat: session D1->Portal: get token D1<--Portal: token D1->Metacat: "Map Identites" (token) Metacat->Portal: verify token Portal-->Metacat: valid token Metacat->IS: mapIdentity(MN, CILogon, KNB) note right using trusted MN certificate end note end @endumlh2jlhPh.hQj*h)}râ(jRjSh,]h-]h+]h/]h0]uhWMhXhhY]rãhbXÇ@startuml images/auth_03.png title Detailed CILogon Authentication Sequence participant "IdentityService" as IS << CNode >> participant "Client Browser" as D1 << Application >> participant "Portal" as Portal participant "CILogon" as CI participant "Identity Provider" as IP D1->CI: Select IdP CI-->D1: IdP Redirect note right CIlogon redirect to IdP using "document.forms[0].submit()" posting SAML request to IdP end note D1->IP: Identity Verification IP-->D1: CILogon Redirect note right IdP redirect to CILogon using "document.forms[0].submit()" posting SAML response to CILogon end note create Portal D1 -> Portal Portal->CI: "Download Certificate" CI->IS: getPrincipalInfo(Principal) IS-->CI: PrincipalList CI->CI: Generate and Sign X.509 CI-->Portal: X.509 group For existing KNB identities participant "Metacat API" as Metacat create Metacat D1->Metacat: authenticate with KNB identity/credentials D1<--Metacat: session D1->Portal: get token D1<--Portal: token D1->Metacat: "Map Identites" (token) Metacat->Portal: verify token Portal-->Metacat: valid token Metacat->IS: mapIdentity(MN, CILogon, KNB) note right using trusted MN certificate end note end @endumlrä…rå}ræ(h(Uh2jàubaubhf)rç}rè(h(XÁThe CILogon X.509 certificate provides a portable credential that binds a user’s public key to their distinguished name or another significant identifier (e.g., email) that is stored in the “subject†field of the certificate. Once generated, the CILogon X.509 certificate has a specified span of time in which it is considered valid; this information is stored in the “valid not before†and “valid not after†fields of the certificate.réh2jlhPh.hQhjh)}rê(h+]h/]h-]h,]h0]uhWMhXhhY]rëhbXÁThe CILogon X.509 certificate provides a portable credential that binds a user’s public key to their distinguished name or another significant identifier (e.g., email) that is stored in the “subject†field of the certificate. Once generated, the CILogon X.509 certificate has a specified span of time in which it is considered valid; this information is stored in the “valid not before†and “valid not after†fields of the certificate.rì…rí}rî(h(jéh2jçubaubhf)rï}rð(h(XÖProcessing the CILogon X.509 certificate requires a verification exchange between the service provider (DataONE) and the external user. Upon receiving a service request from the user, the DataONE service provider will first determine that the user’s CILogon X.509 certificate sent with the request is valid (i.e., verify issuer signature and confirm valid date span) and then use the attributes in the certificate to make authorization decisions regarding the request.rñh2jlhPh.hQhjh)}rò(h+]h/]h-]h,]h0]uhWMhXhhY]róhbXÖProcessing the CILogon X.509 certificate requires a verification exchange between the service provider (DataONE) and the external user. Upon receiving a service request from the user, the DataONE service provider will first determine that the user’s CILogon X.509 certificate sent with the request is valid (i.e., verify issuer signature and confirm valid date span) and then use the attributes in the certificate to make authorization decisions regarding the request.rô…rõ}rö(h(jñh2jïubaubj)r÷}rø(h(X.. image:: images/auth_01.png h2jlhPh.hQjh)}rù(UuriXdesign/images/auth_01.pngrúh,]h-]h+]h/]j}rûU*júsh0]uhWM hXhhY]ubhf)rü}rý(h(XÎ**Figure 5.** Authentication and session management assuming that the CN only runs an Identity service, and that the CILogon server runs the session management service as part of the authentication process.h2jlhPh.hQhjh)}rþ(h+]h/]h-]h,]h0]uhWM!hXhhY]rÿ(j.)r}r(h(X **Figure 5.**h)}r(h+]h/]h-]h,]h0]uh2jühY]rhbX Figure 5.r…r}r(h(Uh2jubahQj6ubhbXÁ Authentication and session management assuming that the CN only runs an Identity service, and that the CILogon server runs the session management service as part of the authentication process.r…r}r (h(XÁ Authentication and session management assuming that the CN only runs an Identity service, and that the CILogon server runs the session management service as part of the authentication process.h2jüubeubeubeubhLhK)r }r (h(Uh2hNhPh.hQhRh)}r (h+]h/]h-]h,]r U%authenticating-and-retrieving-a-tokenrah0]rh auhWM›hXhhY]r(h[)r}r(h(X%Authenticating and Retrieving a Tokenrh2j hPh.hQh_h)}r(h+]h/]h-]h,]h0]uhWM›hXhhY]rhbX%Authenticating and Retrieving a Tokenr…r}r(h(jh2jubaubhf)r}r(h(XBecause we wish to support many different identity providers, there is no single "login" method. Different identity providers will inherently utilize different methods for having users prove their identity. Initially, DataONE will target these avenues for authentication:rh2j hPh.hQhjh)}r(h+]h/]h-]h,]h0]uhWMœhXhhY]rhbXBecause we wish to support many different identity providers, there is no single "login" method. Different identity providers will inherently utilize different methods for having users prove their identity. Initially, DataONE will target these avenues for authentication:r…r}r (h(jh2jubaubh7)r!}r"(h(Uh2j hPh.hQhzh)}r#(h;X*h,]h-]h+]h/]h0]uhWM¡hXhhY]r$h3)r%}r&(h(X^CILogon - Users can continue to authenticate using CILogon identities much like they do today.r'h2j!hPh.hQhh)}r((h+]h/]h-]h,]h0]uhWNhXhhY]r)hf)r*}r+(h(j'h2j%hPh.hQhjh)}r,(h+]h/]h-]h,]h0]uhWM¡hY]r-hbX^CILogon - Users can continue to authenticate using CILogon identities much like they do today.r.…r/}r0(h(j'h2j*ubaubaubaubhf)r1}r2(h(XäThe portal keeps track of their successful authnetication from whichever IdP they choose, and will issue an authentication token for that user. To begin the CILogon authorization process in the CN portal, users can navigate to::h2j hPh.hQhjh)}r3(h+]h/]h-]h,]h0]uhWM¢hXhhY]r4hbXãThe portal keeps track of their successful authnetication from whichever IdP they choose, and will issue an authentication token for that user. To begin the CILogon authorization process in the CN portal, users can navigate to:r5…r6}r7(h(XãThe portal keeps track of their successful authnetication from whichever IdP they choose, and will issue an authentication token for that user. To begin the CILogon authorization process in the CN portal, users can navigate to:h2j1ubaubjM)r8}r9(h(X>https:///portal/startRequest[?target=h2j hPh.hQjPh)}r:(jRjSh,]h-]h+]h/]h0]uhWM¦hXhhY]r;hbX>https:///portal/startRequest[?target=r<…r=}r>(h(Uh2j8ubaubh7)r?}r@(h(Uh2j hPh.hQhzh)}rA(h;X*h,]h-]h+]h/]h0]uhWM©hXhhY]rBh3)rC}rD(h(XaORCID - Using a similar workflow as with CILogon, users can opt to authenticate using their ORCIDrEh2j?hPh.hQhh)}rF(h+]h/]h-]h,]h0]uhWNhXhhY]rGhf)rH}rI(h(jEh2jChPh.hQhjh)}rJ(h+]h/]h-]h,]h0]uhWM©hY]rKhbXaORCID - Using a similar workflow as with CILogon, users can opt to authenticate using their ORCIDrL…rM}rN(h(jEh2jHubaubaubaubhf)rO}rP(h(Xêaccounts using OAuth 2.0. After successfully authenticating with the ORCID identity provider, an authentication token can be retrieved from the portal. To begin the ORCID authorization process in the CN portal, users can navigate to::h2j hPh.hQhjh)}rQ(h+]h/]h-]h,]h0]uhWMªhXhhY]rRhbXéaccounts using OAuth 2.0. After successfully authenticating with the ORCID identity provider, an authentication token can be retrieved from the portal. To begin the ORCID authorization process in the CN portal, users can navigate to:rS…rT}rU(h(Xéaccounts using OAuth 2.0. After successfully authenticating with the ORCID identity provider, an authentication token can be retrieved from the portal. To begin the ORCID authorization process in the CN portal, users can navigate to:h2jOubaubjM)rV}rW(h(X+https:///portal/oauth?action=starth2j hPh.hQjPh)}rX(jRjSh,]h-]h+]h/]h0]uhWM®hXhhY]rYhbX+https:///portal/oauth?action=startrZ…r[}r\(h(Uh2jVubaubh7)r]}r^(h(Uh2j hPh.hQhzh)}r_(h;X*h,]h-]h+]h/]h0]uhWM°hXhhY]r`h3)ra}rb(h(XhLDAP - Existing Ecoinformatics account holders can opt to continue using those identites to authenticaterch2j]hPh.hQhh)}rd(h+]h/]h-]h,]h0]uhWNhXhhY]rehf)rf}rg(h(jch2jahPh.hQhjh)}rh(h+]h/]h-]h,]h0]uhWM°hY]rihbXhLDAP - Existing Ecoinformatics account holders can opt to continue using those identites to authenticaterj…rk}rl(h(jch2jfubaubaubaubhf)rm}rn(h(Xßwith the DataONE portal. This is a more direct method of authentication and is meant to bridge the gap between our legacy account system and newer SSO options available above. To authenticate using LDAP, users can post to::h2j hPh.hQhjh)}ro(h+]h/]h-]h,]h0]uhWM±hXhhY]rphbXÞwith the DataONE portal. This is a more direct method of authentication and is meant to bridge the gap between our legacy account system and newer SSO options available above. To authenticate using LDAP, users can post to:rq…rr}rs(h(XÞwith the DataONE portal. This is a more direct method of authentication and is meant to bridge the gap between our legacy account system and newer SSO options available above. To authenticate using LDAP, users can post to:h2jmubaubjM)rt}ru(h(Xhttps:///portal/ldaph2j hPh.hQjPh)}rv(jRjSh,]h-]h+]h/]h0]uhWMµhXhhY]rwhbXhttps:///portal/ldaprx…ry}rz(h(Uh2jtubaubhf)r{}r|(h(X7The following parameters are requred (*) or supported::r}h2j hPh.hQhjh)}r~(h+]h/]h-]h,]h0]uhWM·hXhhY]rhbX6The following parameters are requred (*) or supported:r€…r}r‚(h(X6The following parameters are requred (*) or supported:h2j{ubaubjM)rƒ}r„(h(X„username* - the full LDAP DN password* - the user's LDAP password target - any URI to be redirected to upon successful authentictionh2j hPh.hQjPh)}r…(jRjSh,]h-]h+]h/]h0]uhWM¹hXhhY]r†hbX„username* - the full LDAP DN password* - the user's LDAP password target - any URI to be redirected to upon successful authentictionr‡…rˆ}r‰(h(Uh2jƒubaubhf)rŠ}r‹(h(XØIn all cases, users will retrieve an authentication token from the CN Portal after they have successfully authenticated with their IdP of choice and been redirected back to the CN Portal. The auth token endpoint is::h2j hPh.hQhjh)}rŒ(h+]h/]h-]h,]h0]uhWM½hXhhY]rhbX×In all cases, users will retrieve an authentication token from the CN Portal after they have successfully authenticated with their IdP of choice and been redirected back to the CN Portal. The auth token endpoint is:rŽ…r}r(h(X×In all cases, users will retrieve an authentication token from the CN Portal after they have successfully authenticated with their IdP of choice and been redirected back to the CN Portal. The auth token endpoint is:h2jŠubaubjM)r‘}r’(h(Xhttps:///portal/tokenh2j hPh.hQjPh)}r“(jRjSh,]h-]h+]h/]h0]uhWMÀhXhhY]r”hbXhttps:///portal/tokenr•…r–}r—(h(Uh2j‘ubaubhf)r˜}r™(h(XlNote that the same browser session used to authenticate should be used to retrieve the authentication token.ršh2j hPh.hQhjh)}r›(h+]h/]h-]h,]h0]uhWMÂhXhhY]rœhbXlNote that the same browser session used to authenticate should be used to retrieve the authentication token.r…rž}rŸ(h(jšh2j˜ubaubeubhK)r }r¡(h(Uh2hNhPh.hQhRh)}r¢(h+]h/]h-]h,]r£U authenticated-session-managementr¤ah0]r¥hauhWMÈhXhhY]r¦(h[)r§}r¨(h(X Authenticated Session Managementr©h2j hPh.hQh_h)}rª(h+]h/]h-]h,]h0]uhWMÈhXhhY]r«hbX Authenticated Session Managementr¬…r­}r®(h(j©h2j§ubaubhf)r¯}r°(h(XÇFor DataONE, identity management and verification is only the first step in ensuring system-wide security. Many service calls within DataONE will require authentication of the caller to create an authenticated session with a limited duration for access to DataONE services. The process of authentication for most users will begin with identity verification and downloading of the X.509 certificate from CILogon. This download will often happen from within a local desktop DataONE application, which is acting on behalf of the user and can then use the certificate to represent the authenticated session when it makes requests to DataONE service providers. Both the desktop application and the DataONE service provider can verify (1) that the certificate originated from CILogon and (2) that the owner of the certificate, the user, is the actual party requesting authentication with DataONE (user identity verification is performed as prerequisite of the certificate).r±h2j hPh.hQhjh)}r²(h+]h/]h-]h,]h0]uhWMÊhXhhY]r³hbXÇFor DataONE, identity management and verification is only the first step in ensuring system-wide security. Many service calls within DataONE will require authentication of the caller to create an authenticated session with a limited duration for access to DataONE services. The process of authentication for most users will begin with identity verification and downloading of the X.509 certificate from CILogon. This download will often happen from within a local desktop DataONE application, which is acting on behalf of the user and can then use the certificate to represent the authenticated session when it makes requests to DataONE service providers. Both the desktop application and the DataONE service provider can verify (1) that the certificate originated from CILogon and (2) that the owner of the certificate, the user, is the actual party requesting authentication with DataONE (user identity verification is performed as prerequisite of the certificate).r´…rµ}r¶(h(j±h2j¯ubaubhf)r·}r¸(h(XôPassed from DataONE system to DataONE system, such as making requests from a client application to a Member Node, the certificate is a reference to an authenticated session that contains all the necessary information identifying the user of the original service call and other attributes used to determine authorization in the DataONE system. The certificate itself will have a short "time to live", thereby limiting the duration of malicious activity if a rogue application or user were to intercept the certificate. The certificate will also have limited applicability, in that it will be intended to be used from a particular host location on the internet, and have other restrictions that prevent it from being broadly used as a surrogate for the user.r¹h2j hPh.hQhjh)}rº(h+]h/]h-]h,]h0]uhWMØhXhhY]r»hbXôPassed from DataONE system to DataONE system, such as making requests from a client application to a Member Node, the certificate is a reference to an authenticated session that contains all the necessary information identifying the user of the original service call and other attributes used to determine authorization in the DataONE system. The certificate itself will have a short "time to live", thereby limiting the duration of malicious activity if a rogue application or user were to intercept the certificate. The certificate will also have limited applicability, in that it will be intended to be used from a particular host location on the internet, and have other restrictions that prevent it from being broadly used as a surrogate for the user.r¼…r½}r¾(h(j¹h2j·ubaubhf)r¿}rÀ(h(X Services internal to the DataONE system may operate autonomously to perform maintenance tasks or other asynchronous activities that are not bound to a particular user. In these cases, a certificate will still be generated, but without the prerequisite identity verification. Such certificates will have a special system identity that signifies it is a "trusted" principal of the DataONE system. For most instances, this certificate will serve identically to one generated during the authentication process of normal user.rÁh2j hPh.hQhjh)}rÂ(h+]h/]h-]h,]h0]uhWMãhXhhY]rÃhbX Services internal to the DataONE system may operate autonomously to perform maintenance tasks or other asynchronous activities that are not bound to a particular user. In these cases, a certificate will still be generated, but without the prerequisite identity verification. Such certificates will have a special system identity that signifies it is a "trusted" principal of the DataONE system. For most instances, this certificate will serve identically to one generated during the authentication process of normal user.rÄ…rÅ}rÆ(h(jÁh2j¿ubaubeubhK)rÇ}rÈ(h(Uh2hNhPh.hQhRh)}rÉ(h+]h/]h-]h,]rÊUportal-delegationrËah0]rÌhauhWMìhXhhY]rÍ(h[)rÎ}rÏ(h(XPortal DelegationrÐh2jÇhPh.hQh_h)}rÑ(h+]h/]h-]h,]h0]uhWMìhXhhY]rÒhbXPortal DelegationrÓ…rÔ}rÕ(h(jÐh2jÎubaubhf)rÖ}r×(h(X…For web clients, we can use the CILogon portal delegation approach. Note that the CN and portal are assumed to be on the same server.rØh2jÇhPh.hQhjh)}rÙ(h+]h/]h-]h,]h0]uhWMîhXhhY]rÚhbX…For web clients, we can use the CILogon portal delegation approach. Note that the CN and portal are assumed to be on the same server.rÛ…rÜ}rÝ(h(jØh2jÖubaubj')rÞ}rß(h(XW@startuml images/portal_01.png participant "Browser" as browser participant "CN" as cn participant "Metacat" as metacat participant "Portal" as portal participant "CILogon" as cilogon group login portal -> cilogon: get certificate portal <- cilogon: certificate portal -> browser: cookie end group https://cn-dev.dataone.org/cn/v1/object/blah browser -> cn: get(cookie) cn --> portal: get certificate (cookie) note right same server end note cn <-- portal: certificate cn -> metacat: get(certificate) note right different server end note cn <- metacat: object browser <- cn: object end @endumlh2jÇhPh.hQj*h)}rà(jRjSh,]h-]h+]h/]h0]uhWM hXhhY]ráhbXW@startuml images/portal_01.png participant "Browser" as browser participant "CN" as cn participant "Metacat" as metacat participant "Portal" as portal participant "CILogon" as cilogon group login portal -> cilogon: get certificate portal <- cilogon: certificate portal -> browser: cookie end group https://cn-dev.dataone.org/cn/v1/object/blah browser -> cn: get(cookie) cn --> portal: get certificate (cookie) note right same server end note cn <-- portal: certificate cn -> metacat: get(certificate) note right different server end note cn <- metacat: object browser <- cn: object end @endumlrâ…rã}rä(h(Uh2jÞubaubj)rå}ræ(h(X .. image:: images/portal_01.png h2jÇhPh.hQjh)}rç(UuriXdesign/images/portal_01.pngrèh,]h-]h+]h/]j}réU*jèsh0]uhWMhXhhY]ubhf)rê}rë(h(X{**Figure 7.** Authenticated "read" going through CN. The browser is the client with no certificate. The portal keeps the user's client certificate. The CN looks up the client certificate using the client cookie. The CN includes the client certificate in the request that is sent to Metacat. Object is returned to the client as though it was retrieved directly with a certificate.h2jÇhPh.hQhjh)}rì(h+]h/]h-]h,]h0]uhWMhXhhY]rí(j.)rî}rï(h(X **Figure 7.**h)}rð(h+]h/]h-]h,]h0]uh2jêhY]rñhbX Figure 7.rò…ró}rô(h(Uh2jîubahQj6ubhbXn Authenticated "read" going through CN. The browser is the client with no certificate. The portal keeps the user's client certificate. The CN looks up the client certificate using the client cookie. The CN includes the client certificate in the request that is sent to Metacat. Object is returned to the client as though it was retrieved directly with a certificate.rõ…rö}r÷(h(Xn Authenticated "read" going through CN. The browser is the client with no certificate. The portal keeps the user's client certificate. The CN looks up the client certificate using the client cookie. The CN includes the client certificate in the request that is sent to Metacat. Object is returned to the client as though it was retrieved directly with a certificate.h2jêubeubeubhK)rø}rù(h(Uh2hNhPh.hQhRh)}rú(h+]h/]h-]h,]rûU'session-management-alternative-scenariorüah0]rýhauhWMhXhhY]rþ(h[)rÿ}r(h(X)Session Management (Alternative Scenario)rh2jøhPh.hQh_h)}r(h+]h/]h-]h,]h0]uhWMhXhhY]rhbX)Session Management (Alternative Scenario)r…r}r(h(jh2jÿubaubhf)r}r(h(XSThis is a deprecated scenario that describes the use of a separate Session Service.r h2jøhPh.hQhjh)}r (h+]h/]h-]h,]h0]uhWMhXhhY]r hbXSThis is a deprecated scenario that describes the use of a separate Session Service.r …r }r(h(j h2jubaubhK)r}r(h(Uh2jøhPh.hQhRh)}r(h+]h/]h-]h,]rU0authtoken-references-to-an-authenticated-sessionrah0]rhauhWMhXhhY]r(h[)r}r(h(X0AuthToken references to an Authenticated Sessionrh2jhPh.hQh_h)}r(h+]h/]h-]h,]h0]uhWMhXhhY]rhbX0AuthToken references to an Authenticated Sessionr…r}r(h(jh2jubaubhf)r}r(h(XýEach DataONE :class:`Types.AuthToken` is a unique identifier that is affiliated with and specifies the authentication session associated with a particular request. DataONE AuthToken References are UUID values that are created by the DataONE Session Service when a client requests that a session be established. A client requests that a session be established from a particular Internet Protocol address, and all service requests associated with that session MUST originate from that Internet Protocol address.h2jhPh.hQhjh)}r (h+]h/]h-]h,]h0]uhWMhXhhY]r!(hbX Each DataONE r"…r#}r$(h(X Each DataONE h2jubjy)r%}r&(h(X:class:`Types.AuthToken`r'h2jhPh.hQj}h)}r((UreftypeXclassj‰j€XTypes.AuthTokenU refdomainXpyr)h,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWMhY]r*j‡)r+}r,(h(j'h)}r-(h+]h/]r.(jŒj)Xpy-classr/eh-]h,]h0]uh2j%hY]r0hbXTypes.AuthTokenr1…r2}r3(h(Uh2j+ubahQj’ubaubhbXØ is a unique identifier that is affiliated with and specifies the authentication session associated with a particular request. DataONE AuthToken References are UUID values that are created by the DataONE Session Service when a client requests that a session be established. A client requests that a session be established from a particular Internet Protocol address, and all service requests associated with that session MUST originate from that Internet Protocol address.r4…r5}r6(h(XØ is a unique identifier that is affiliated with and specifies the authentication session associated with a particular request. DataONE AuthToken References are UUID values that are created by the DataONE Session Service when a client requests that a session be established. A client requests that a session be established from a particular Internet Protocol address, and all service requests associated with that session MUST originate from that Internet Protocol address.h2jubeubhf)r7}r8(h(XYThe DataONE AuthToken reference is a unique identifier that references a session that has been established for the purposes of interacting with particular DataONE service providers. DataONE AuthTokens are generally passed in the header of an HTTP request to a service, thereby supporting clients that utilize authentication and those that do not, as well as Member Nodes that support authentication and those that don't. Any Member Nodes or clients that do not support authentication and access control will simply ignore the presence of the AuthToken in the HTTP header information if one is present.r9h2jhPh.hQhjh)}r:(h+]h/]h-]h,]h0]uhWM'hXhhY]r;hbXYThe DataONE AuthToken reference is a unique identifier that references a session that has been established for the purposes of interacting with particular DataONE service providers. DataONE AuthTokens are generally passed in the header of an HTTP request to a service, thereby supporting clients that utilize authentication and those that do not, as well as Member Nodes that support authentication and those that don't. Any Member Nodes or clients that do not support authentication and access control will simply ignore the presence of the AuthToken in the HTTP header information if one is present.r<…r=}r>(h(j9h2j7ubaubhf)r?}r@(h(X©The DataONE HTTP header containing the AuthToken has the name 'x-AuthToken' and contains an identifier value that is a UUID URN; for example, one might send the header::h2jhPh.hQhjh)}rA(h+]h/]h-]h,]h0]uhWM0hXhhY]rBhbX¨The DataONE HTTP header containing the AuthToken has the name 'x-AuthToken' and contains an identifier value that is a UUID URN; for example, one might send the header:rC…rD}rE(h(X¨The DataONE HTTP header containing the AuthToken has the name 'x-AuthToken' and contains an identifier value that is a UUID URN; for example, one might send the header:h2j?ubaubjM)rF}rG(h(X:x-AuthToken: urn:uuid:f689d586-59a6-11e0-8dac-3f586cd046b9h2jhPh.hQjPh)}rH(jRjSh,]h-]h+]h/]h0]uhWM4hXhhY]rIhbX:x-AuthToken: urn:uuid:f689d586-59a6-11e0-8dac-3f586cd046b9rJ…rK}rL(h(Uh2jFubaubhf)rM}rN(h(X@This session reference is used to indicate the session that should be used for requests, and has limited duration based on the session expiration time. AuthToken references refer to sessions that have limited duration and other constraints on their validity, and these constraints MUST be validated by service providers.rOh2jhPh.hQhjh)}rP(h+]h/]h-]h,]h0]uhWM6hXhhY]rQhbX@This session reference is used to indicate the session that should be used for requests, and has limited duration based on the session expiration time. AuthToken references refer to sessions that have limited duration and other constraints on their validity, and these constraints MUST be validated by service providers.rR…rS}rT(h(jOh2jMubaubhf)rU}rV(h(XíIf a Node or other data one service provider receives a service request with the DataONE x-AuthToken header, then the service SHOULD retrieve the associated :class:`SAML.Assertion` data in order to confirm that the client has appropriately authenticated with the DataONE session service. If the service needs to make authorization decisions, the service MUST validate the the associated session data, check validity constraints on the session, and then proceed to make authorization decisions.h2jhPh.hQhjh)}rW(h+]h/]h-]h,]h0]uhWM<hXhhY]rX(hbXIf a Node or other data one service provider receives a service request with the DataONE x-AuthToken header, then the service SHOULD retrieve the associated rY…rZ}r[(h(XIf a Node or other data one service provider receives a service request with the DataONE x-AuthToken header, then the service SHOULD retrieve the associated h2jUubjy)r\}r](h(X:class:`SAML.Assertion`r^h2jUhPh.hQj}h)}r_(UreftypeXclassj‰j€XSAML.AssertionU refdomainXpyr`h,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWM<hY]raj‡)rb}rc(h(j^h)}rd(h+]h/]re(jŒj`Xpy-classrfeh-]h,]h0]uh2j\hY]rghbXSAML.Assertionrh…ri}rj(h(Uh2jbubahQj’ubaubhbX9 data in order to confirm that the client has appropriately authenticated with the DataONE session service. If the service needs to make authorization decisions, the service MUST validate the the associated session data, check validity constraints on the session, and then proceed to make authorization decisions.rk…rl}rm(h(X9 data in order to confirm that the client has appropriately authenticated with the DataONE session service. If the service needs to make authorization decisions, the service MUST validate the the associated session data, check validity constraints on the session, and then proceed to make authorization decisions.h2jUubeubhf)rn}ro(h(XÁWhile making authorization decisions, the service should apply any AccessPolicy rules that reference the identifier for the Principal, any identifier in the 'equivalentIdentity' attributes in the session, any groups that are referenced in an 'isMemberOf' attribute in the session, and any polices that reference the DataONE 'AuthenticatedUser' or 'VerifiedUser' identities. All of these identities are valid identities for the authenticated session.rph2jhPh.hQhjh)}rq(h+]h/]h-]h,]h0]uhWMDhXhhY]rrhbXÁWhile making authorization decisions, the service should apply any AccessPolicy rules that reference the identifier for the Principal, any identifier in the 'equivalentIdentity' attributes in the session, any groups that are referenced in an 'isMemberOf' attribute in the session, and any polices that reference the DataONE 'AuthenticatedUser' or 'VerifiedUser' identities. All of these identities are valid identities for the authenticated session.rs…rt}ru(h(jph2jnubaubhf)rv}rw(h(XBIf a Member Node or Coordinating Node receives an AuthToken that is invalid, can not be found using the :func:`CN_auth.getAuthSession` method, or is determined to not be satisfying the constraints of the session (such as wrong source IP Address), then the service MUST return an :class:`Exceptions.InvalidToken` exception.h2jhPh.hQhjh)}rx(h+]h/]h-]h,]h0]uhWMKhXhhY]ry(hbXhIf a Member Node or Coordinating Node receives an AuthToken that is invalid, can not be found using the rz…r{}r|(h(XhIf a Member Node or Coordinating Node receives an AuthToken that is invalid, can not be found using the h2jvubjy)r}}r~(h(X:func:`CN_auth.getAuthSession`rh2jvhPh.hQj}h)}r€(UreftypeXfuncj‰j€XCN_auth.getAuthSessionU refdomainXpyrh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWMKhY]r‚j‡)rƒ}r„(h(jh)}r…(h+]h/]r†(jŒjXpy-funcr‡eh-]h,]h0]uh2j}hY]rˆhbXCN_auth.getAuthSession()r‰…rŠ}r‹(h(Uh2jƒubahQj’ubaubhbX‘ method, or is determined to not be satisfying the constraints of the session (such as wrong source IP Address), then the service MUST return an rŒ…r}rŽ(h(X‘ method, or is determined to not be satisfying the constraints of the session (such as wrong source IP Address), then the service MUST return an h2jvubjy)r}r(h(X :class:`Exceptions.InvalidToken`r‘h2jvhPh.hQj}h)}r’(UreftypeXclassj‰j€XExceptions.InvalidTokenU refdomainXpyr“h,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWMKhY]r”j‡)r•}r–(h(j‘h)}r—(h+]h/]r˜(jŒj“Xpy-classr™eh-]h,]h0]uh2jhY]ršhbXExceptions.InvalidTokenr›…rœ}r(h(Uh2j•ubahQj’ubaubhbX exception.rž…rŸ}r (h(X exception.h2jvubeubhf)r¡}r¢(h(XÒIf a Member Node or Coordinating Node receives a service request in which there is no x-AuthToken header, or if the header is empty, then the request should be considered to be validated as the DataONE 'Public' user. This user may be denied access to certain services as determined by appropriate access policies, or it may be granted access to services when appropriate (e.g., to perform a :func:`MN_read.get` operation on a data set marked for Public read access).h2jhPh.hQhjh)}r£(h+]h/]h-]h,]h0]uhWMQhXhhY]r¤(hbX‡If a Member Node or Coordinating Node receives a service request in which there is no x-AuthToken header, or if the header is empty, then the request should be considered to be validated as the DataONE 'Public' user. This user may be denied access to certain services as determined by appropriate access policies, or it may be granted access to services when appropriate (e.g., to perform a r¥…r¦}r§(h(X‡If a Member Node or Coordinating Node receives a service request in which there is no x-AuthToken header, or if the header is empty, then the request should be considered to be validated as the DataONE 'Public' user. This user may be denied access to certain services as determined by appropriate access policies, or it may be granted access to services when appropriate (e.g., to perform a h2j¡ubjy)r¨}r©(h(X:func:`MN_read.get`rªh2j¡hPh.hQj}h)}r«(UreftypeXfuncj‰j€X MN_read.getU refdomainXpyr¬h,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWMQhY]r­j‡)r®}r¯(h(jªh)}r°(h+]h/]r±(jŒj¬Xpy-funcr²eh-]h,]h0]uh2j¨hY]r³hbX MN_read.get()r´…rµ}r¶(h(Uh2j®ubahQj’ubaubhbX8 operation on a data set marked for Public read access).r·…r¸}r¹(h(X8 operation on a data set marked for Public read access).h2j¡ubeubh7)rº}r»(h(Uh2jhPh.hQhzh)}r¼(h;X*h,]h-]h+]h/]h0]uhWMXhXhhY]r½(h3)r¾}r¿(h(X7:func:`CN_auth.login` returns :class:`Types.AuthToken` h2jºhPh.hQhh)}rÀ(h+]h/]h-]h,]h0]uhWNhXhhY]rÁhf)rÂ}rÃ(h(X6:func:`CN_auth.login` returns :class:`Types.AuthToken`h2j¾hPh.hQhjh)}rÄ(h+]h/]h-]h,]h0]uhWMXhY]rÅ(jy)rÆ}rÇ(h(X:func:`CN_auth.login`rÈh2jÂhPh.hQj}h)}rÉ(UreftypeXfuncj‰j€X CN_auth.loginU refdomainXpyrÊh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWMXhY]rËj‡)rÌ}rÍ(h(jÈh)}rÎ(h+]h/]rÏ(jŒjÊXpy-funcrÐeh-]h,]h0]uh2jÆhY]rÑhbXCN_auth.login()rÒ…rÓ}rÔ(h(Uh2jÌubahQj’ubaubhbX returns rÕ…rÖ}r×(h(X returns h2jÂubjy)rØ}rÙ(h(X:class:`Types.AuthToken`rÚh2jÂhPh.hQj}h)}rÛ(UreftypeXclassj‰j€XTypes.AuthTokenU refdomainXpyrÜh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWMXhY]rÝj‡)rÞ}rß(h(jÚh)}rà(h+]h/]rá(jŒjÜXpy-classrâeh-]h,]h0]uh2jØhY]rãhbXTypes.AuthTokenrä…rå}ræ(h(Uh2jÞubahQj’ubaubeubaubh3)rç}rè(h(X@:func:`CN_auth.getAuthSession` returns :class:`SAML.Assertion` h2jºhPh.hQhh)}ré(h+]h/]h-]h,]h0]uhWNhXhhY]rêhf)rë}rì(h(X>:func:`CN_auth.getAuthSession` returns :class:`SAML.Assertion`ríh2jçhPh.hQhjh)}rî(h+]h/]h-]h,]h0]uhWMZhY]rï(jy)rð}rñ(h(X:func:`CN_auth.getAuthSession`ròh2jëhPh.hQj}h)}ró(UreftypeXfuncj‰j€XCN_auth.getAuthSessionU refdomainXpyrôh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWMZhY]rõj‡)rö}r÷(h(jòh)}rø(h+]h/]rù(jŒjôXpy-funcrúeh-]h,]h0]uh2jðhY]rûhbXCN_auth.getAuthSession()rü…rý}rþ(h(Uh2jöubahQj’ubaubhbX returns rÿ…r}r(h(X returns h2jëubjy)r}r(h(X:class:`SAML.Assertion`rh2jëhPh.hQj}h)}r(UreftypeXclassj‰j€XSAML.AssertionU refdomainXpyrh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWMZhY]rj‡)r}r (h(jh)}r (h+]h/]r (jŒjXpy-classr eh-]h,]h0]uh2jhY]r hbXSAML.Assertionr…r}r(h(Uh2jubahQj’ubaubeubaubeubeubhK)r}r(h(Uh2jøhPh.hQhRh)}r(h+]h/]h-]h,]rU2structure-of-metadata-about-authenticated-sessionsrah0]rhauhWM^hXhhY]r(h[)r}r(h(X2Structure of metadata about Authenticated Sessionsrh2jhPh.hQh_h)}r(h+]h/]h-]h,]h0]uhWM^hXhhY]rhbX2Structure of metadata about Authenticated Sessionsr…r}r(h(jh2jubaubhf)r }r!(h(X-Metadata about authenticated sessions are represented as a :class:`SAML.Assertion`. Details of the fields to be included in an :class:`SAML.Assertion` include Subject, Address, givenName, sn, mail, equivalentIdentity, and group membership, among other fields. These fields are all mapped to SAML2 Assertion elements, as illustrated in the following example of an authenticated session represented by a SAML Assertion. Note that these SAML Assertion messages are returned when Member Nodes and Coordinating Nodes make calls to :func:`CN_auth.getAuthSession`.h2jhPh.hQhjh)}r"(h+]h/]h-]h,]h0]uhWM`hXhhY]r#(hbX;Metadata about authenticated sessions are represented as a r$…r%}r&(h(X;Metadata about authenticated sessions are represented as a h2j ubjy)r'}r((h(X:class:`SAML.Assertion`r)h2j hPh.hQj}h)}r*(UreftypeXclassj‰j€XSAML.AssertionU refdomainXpyr+h,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWM`hY]r,j‡)r-}r.(h(j)h)}r/(h+]h/]r0(jŒj+Xpy-classr1eh-]h,]h0]uh2j'hY]r2hbXSAML.Assertionr3…r4}r5(h(Uh2j-ubahQj’ubaubhbX-. Details of the fields to be included in an r6…r7}r8(h(X-. Details of the fields to be included in an h2j ubjy)r9}r:(h(X:class:`SAML.Assertion`r;h2j hPh.hQj}h)}r<(UreftypeXclassj‰j€XSAML.AssertionU refdomainXpyr=h,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWM`hY]r>j‡)r?}r@(h(j;h)}rA(h+]h/]rB(jŒj=Xpy-classrCeh-]h,]h0]uh2j9hY]rDhbXSAML.AssertionrE…rF}rG(h(Uh2j?ubahQj’ubaubhbXx include Subject, Address, givenName, sn, mail, equivalentIdentity, and group membership, among other fields. These fields are all mapped to SAML2 Assertion elements, as illustrated in the following example of an authenticated session represented by a SAML Assertion. Note that these SAML Assertion messages are returned when Member Nodes and Coordinating Nodes make calls to rH…rI}rJ(h(Xx include Subject, Address, givenName, sn, mail, equivalentIdentity, and group membership, among other fields. These fields are all mapped to SAML2 Assertion elements, as illustrated in the following example of an authenticated session represented by a SAML Assertion. Note that these SAML Assertion messages are returned when Member Nodes and Coordinating Nodes make calls to h2j ubjy)rK}rL(h(X:func:`CN_auth.getAuthSession`rMh2j hPh.hQj}h)}rN(UreftypeXfuncj‰j€XCN_auth.getAuthSessionU refdomainXpyrOh,]h-]U refexplicit‰h+]h/]h0]j‚jƒj„Nj…NuhWM`hY]rPj‡)rQ}rR(h(jMh)}rS(h+]h/]rT(jŒjOXpy-funcrUeh-]h,]h0]uh2jKhY]rVhbXCN_auth.getAuthSession()rW…rX}rY(h(Uh2jQubahQj’ubaubhbX.…rZ}r[(h(X.h2j ubeubj )r\}r](h(Uh2jhPh.hQjh)}r^(h+]h/]h-]h,]h0]uhWMjhXhhY]r_j)r`}ra(h(X.. figure:: images/auth_02.png h2j\hPh.hQjh)}rb(UuriXdesign/images/auth_02.pngrch,]h-]h+]h/]j}rdU*jcsh0]uhWMjhY]ubaubhf)re}rf(h(XD**Figure 8.** Authentication and session management assuming that the CN runs a seperate SessionService that creates and tracks sessions. This is an alternative scenario based on the idea that CILogon may not be able to make calls to the Identity Service, in which case the separate Session Service would need to be created.h2jhPh.hQhjh)}rg(h+]h/]h-]h,]h0]uhWMkhXhhY]rh(j.)ri}rj(h(X **Figure 8.**h)}rk(h+]h/]h-]h,]h0]uh2jehY]rlhbX Figure 8.rm…rn}ro(h(Uh2jiubahQj6ubhbX7 Authentication and session management assuming that the CN runs a seperate SessionService that creates and tracks sessions. This is an alternative scenario based on the idea that CILogon may not be able to make calls to the Identity Service, in which case the separate Session Service would need to be created.rp…rq}rr(h(X7 Authentication and session management assuming that the CN runs a seperate SessionService that creates and tracks sessions. This is an alternative scenario based on the idea that CILogon may not be able to make calls to the Identity Service, in which case the separate Session Service would need to be created.h2jeubeubjM)rs}rt(h(X1 https://cn.dataone.org/identity ... uid=jones,o=NCEAS,dc=ecoinformatics,dc=org urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport Tom Thumb someone@gmail.com cn=staff,o=NCEAS,dc=dataone,dc=org urn:uuid:f7eca768-59c0-11e0-bf7d-fbbaa0f3405c mbjones@NCEAS /DC=org/DC=cilogon/C=US/O=ProtectNetwork/CN=Matthew Jones A332 h2jhPh.hQjPh)}ru(Ulinenosrv‰Ulanguagerwcdocutils.nodes reprunicode rxXxmlry…rz}r{bh+]jRjSh,]h-]UsourceXt/var/lib/jenkins/jobs/API_Documentation_trunk/workspace/api-documentation/source/design/saml-2-assertion-example.xmlUhighlight_argsr|}r}U linenostartr~Ksh/]h0]uhWMqhXhhY]rhbX1 https://cn.dataone.org/identity ... uid=jones,o=NCEAS,dc=ecoinformatics,dc=org urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport Tom Thumb someone@gmail.com cn=staff,o=NCEAS,dc=dataone,dc=org urn:uuid:f7eca768-59c0-11e0-bf7d-fbbaa0f3405c mbjones@NCEAS /DC=org/DC=cilogon/C=US/O=ProtectNetwork/CN=Matthew Jones A332 r€…r}r‚(h(Uh2jsubaubj')rƒ}r„(h(XÂ@startuml images/auth_01.png participant "MN" as mn << MNode >> participant "Client" as app_client << Application >> participant "CILogon" as cilogon << CNode >> participant "IdentityService" as ident << CNode >> app_client -> cilogon: authenticate() cilogon -> ident: getPrincipalInfo(Principal) cilogon <- ident: PrincipalList app_client <- cilogon: X.509 app_client -> mn: get(X.509, pid) mn -> mn: isAuthorized() app_client <- mn: object @endumlh2jhPh.hQj*h)}r…(jRjSh,]h-]h+]h/]h0]uhWMƒhXhhY]r†hbXÂ@startuml images/auth_01.png participant "MN" as mn << MNode >> participant "Client" as app_client << Application >> participant "CILogon" as cilogon << CNode >> participant "IdentityService" as ident << CNode >> app_client -> cilogon: authenticate() cilogon -> ident: getPrincipalInfo(Principal) cilogon <- ident: PrincipalList app_client <- cilogon: X.509 app_client -> mn: get(X.509, pid) mn -> mn: isAuthorized() app_client <- mn: object @endumlr‡…rˆ}r‰(h(Uh2jƒubaubj')rŠ}r‹(h(X‡@startuml images/auth_02.png participant "CILogon" as cilogon << CNode >> participant "Client" as app_client << Application >> participant "MN" as mn << MNode >> participant "SessionService" as session << CNode >> participant "IdentityService" as ident << CNode >> app_client -> cilogon: authenticate() app_client <- cilogon: X.509 app_client -> session: newSession(X.509) session -> ident: getPrincipalInfo(Principal) session <- ident: PrincipalList app_client <- session: token app_client -> mn: get(token, pid) mn -> session: getAuthSession(token) mn <- session: AuthSession Assertion mn -> mn: isAuthorized() app_client <- mn: object @endumlh2jhPh.hQj*h)}rŒ(jRjSh,]h-]h+]h/]h0]uhWMšhXhhY]rhbX‡@startuml images/auth_02.png participant "CILogon" as cilogon << CNode >> participant "Client" as app_client << Application >> participant "MN" as mn << MNode >> participant "SessionService" as session << CNode >> participant "IdentityService" as ident << CNode >> app_client -> cilogon: authenticate() app_client <- cilogon: X.509 app_client -> session: newSession(X.509) session -> ident: getPrincipalInfo(Principal) session <- ident: PrincipalList app_client <- session: token app_client -> mn: get(token, pid) mn -> session: getAuthSession(token) mn <- session: AuthSession Assertion mn -> mn: isAuthorized() app_client <- mn: object @endumlrŽ…r}r(h(Uh2jŠubaubeubeubeubhPh.hQhRh)}r‘(h+]h/]h-]h,]r’Uusing-access-tokensr“ah0]r”hauhWM&hXhhY]r•(h[)r–}r—(h(XUsing Access Tokensr˜h2hLhPh.hQh_h)}r™(h+]h/]h-]h,]h0]uhWM&hXhhY]ršhbXUsing Access Tokensr›…rœ}r(h(j˜h2j–ubaubhf)rž}rŸ(h(XˆSome clients have difficulty handling X.509 certificates, and so the DataONE V2 API also supports the use of **access tokens** as a mechanism for clients to identifiy themselves for API calls. In this scenario, the user authenticates with the DataONE Portal, and then obtains an access token directly from the DataONE Portal. The client then uses this information to pass access tokens to service providers using an HTTP "Authorization" header. The service provider (e.g., MN), must then validate the access token to ensure that the request is coming from a host with a valid token and that the request is not being repeated via session hijacking.h2hLhPh.hQhjh)}r (h+]h/]h-]h,]h0]uhWM'hXhhY]r¡(hbXmSome clients have difficulty handling X.509 certificates, and so the DataONE V2 API also supports the use of r¢…r£}r¤(h(XmSome clients have difficulty handling X.509 certificates, and so the DataONE V2 API also supports the use of h2jžubj.)r¥}r¦(h(X**access tokens**h)}r§(h+]h/]h-]h,]h0]uh2jžhY]r¨hbX access tokensr©…rª}r«(h(Uh2j¥ubahQj6ubhbX  as a mechanism for clients to identifiy themselves for API calls. In this scenario, the user authenticates with the DataONE Portal, and then obtains an access token directly from the DataONE Portal. The client then uses this information to pass access tokens to service providers using an HTTP "Authorization" header. The service provider (e.g., MN), must then validate the access token to ensure that the request is coming from a host with a valid token and that the request is not being repeated via session hijacking.r¬…r­}r®(h(X  as a mechanism for clients to identifiy themselves for API calls. In this scenario, the user authenticates with the DataONE Portal, and then obtains an access token directly from the DataONE Portal. The client then uses this information to pass access tokens to service providers using an HTTP "Authorization" header. The service provider (e.g., MN), must then validate the access token to ensure that the request is coming from a host with a valid token and that the request is not being repeated via session hijacking.h2jžubeubhf)r¯}r°(h(XîDataONE considered different scenarios for the structure and meaning of these access tokens, largely following the OAuth1.0_ and OAuth2.0_ specifications. These two specification propose related but different mechanisms for generating and utilizing access tokens. Decision making fell along two axes: 1) what does an acces token represent, and 2) how does a service provider validate an access token. The main choices were, in order of both increasing security and increasing complexity, are:h2hLhPh.hQhjh)}r±(h+]h/]h-]h,]h0]uhWM0hXhhY]r²(hbXsDataONE considered different scenarios for the structure and meaning of these access tokens, largely following the r³…r´}rµ(h(XsDataONE considered different scenarios for the structure and meaning of these access tokens, largely following the h2j¯ubhÈ)r¶}r·(h(X OAuth1.0_hËKh2j¯hQhÌh)}r¸(UnameXOAuth1.0hÎX"http://tools.ietf.org/html/rfc5849r¹h,]h-]h+]h/]h0]uhY]rºhbXOAuth1.0r»…r¼}r½(h(Uh2j¶ubaubhbX and r¾…r¿}rÀ(h(X and h2j¯ubhÈ)rÁ}rÂ(h(X OAuth2.0_hËKh2j¯hQhÌh)}rÃ(UnameXOAuth2.0hÎX#https://tools.ietf.org/html/rfc6749rÄh,]h-]h+]h/]h0]uhY]rÅhbXOAuth2.0rÆ…rÇ}rÈ(h(Uh2jÁubaubhbXd specifications. These two specification propose related but different mechanisms for generating and utilizing access tokens. Decision making fell along two axes: 1) what does an acces token represent, and 2) how does a service provider validate an access token. The main choices were, in order of both increasing security and increasing complexity, are:rÉ…rÊ}rË(h(Xd specifications. These two specification propose related but different mechanisms for generating and utilizing access tokens. Decision making fell along two axes: 1) what does an acces token represent, and 2) how does a service provider validate an access token. The main choices were, in order of both increasing security and increasing complexity, are:h2j¯ubeubh7)rÌ}rÍ(h(Uh2hLhPh.hQhzh)}rÎ(h;X*h,]h-]h+]h/]h0]uhWM8hXhhY]rÏ(h3)rÐ}rÑ(h(X Bearer tokensrÒh2jÌhPh.hQhh)}rÓ(h+]h/]h-]h,]h0]uhWNhXhhY]rÔhf)rÕ}rÖ(h(jÒh2jÐhPh.hQhjh)}r×(h+]h/]h-]h,]h0]uhWM8hY]rØhbX Bearer tokensrÙ…rÚ}rÛ(h(jÒh2jÕubaubaubh3)rÜ}rÝ(h(X&HMAC tokens with shared symmetric keysrÞh2jÌhPh.hQhh)}rß(h+]h/]h-]h,]h0]uhWNhXhhY]ràhf)rá}râ(h(jÞh2jÜhPh.hQhjh)}rã(h+]h/]h-]h,]h0]uhWM9hY]rähbX&HMAC tokens with shared symmetric keysrå…ræ}rç(h(jÞh2jáubaubaubh3)rè}ré(h(X2RSA-SHA1 tokens using RSA private/public keypairs h2jÌhPh.hQhh)}rê(h+]h/]h-]h,]h0]uhWNhXhhY]rëhf)rì}rí(h(X1RSA-SHA1 tokens using RSA private/public keypairsrîh2jèhPh.hQhjh)}rï(h+]h/]h-]h,]h0]uhWM:hY]rðhbX1RSA-SHA1 tokens using RSA private/public keypairsrñ…rò}ró(h(jîh2jìubaubaubeubhf)rô}rõ(h(XNWe ultimately decided to use the simpler Bearer Token approach outlined below:röh2hLhPh.hQhjh)}r÷(h+]h/]h-]h,]h0]uhWM<hXhhY]røhbXNWe ultimately decided to use the simpler Bearer Token approach outlined below:rù…rú}rû(h(jöh2jôubaubhIj)rü}rý(h(X0.. _OAuth1.0: http://tools.ietf.org/html/rfc5849jKh2hLhPh.hQjh)}rþ(hÎj¹h,]rÿUoauth1-0rah-]h+]h/]h0]rhauhWMKhXhhY]ubj)r}r(h(X1.. _OAuth2.0: https://tools.ietf.org/html/rfc6749jKh2hLhPh.hQjh)}r(hÎjÄh,]rUoauth2-0rah-]h+]h/]h0]rhauhWMMhXhhY]ubj)r}r (h(X6.. _Bearer tokens: https://tools.ietf.org/html/rfc6750jKh2hLhPh.hQjh)}r (hÎX#https://tools.ietf.org/html/rfc6750r h,]r U bearer-tokensr ah-]h+]h/]h0]rhauhWMOhXhhY]ubj)r}r(h(X?.. _HMAC-SHA1: http://tools.ietf.org/html/rfc5849#section-3.4.2h2hLhPh.hQjh)}r(hÎX0http://tools.ietf.org/html/rfc5849#section-3.4.2h,]rU hmac-sha1rah-]h+]h/]h0]rhauhWMQhXhhY]ubj)r}r(h(X>.. _RSA-SHA1: http://tools.ietf.org/html/rfc5849#section-3.4.3h2hLhPh.hQjh)}r(hÎX0http://tools.ietf.org/html/rfc5849#section-3.4.3h,]rUrsa-sha1rah-]h+]h/]h0]rhauhWMShXhhY]ubj)r}r(h(X.. image:: images/auth_04.png h2hLhPh.hQjh)}r(UuriXdesign/images/auth_04.pngrh,]h-]h+]h/]j}rU*jsh0]uhWMVhXhhY]ubhf)r }r!(h(X¡**Figure 6.** Scenarios for using OAuth access tokens in HTTP Authorization headers as a mechanism to establish client identity and authorization. The user authenticates with the DataONE Portal to establish their identity, and the portal issues a client-specific token. For Bearer Tokens, the Portal issues a signed, reusable access token that is sent to service providers and verified using an asymmetric public key.h2hLhPh.hQhjh)}r"(h+]h/]h-]h,]h0]uhWMWhXhhY]r#(j.)r$}r%(h(X **Figure 6.**h)}r&(h+]h/]h-]h,]h0]uh2j hY]r'hbX Figure 6.r(…r)}r*(h(Uh2j$ubahQj6ubhbX” Scenarios for using OAuth access tokens in HTTP Authorization headers as a mechanism to establish client identity and authorization. The user authenticates with the DataONE Portal to establish their identity, and the portal issues a client-specific token. For Bearer Tokens, the Portal issues a signed, reusable access token that is sent to service providers and verified using an asymmetric public key.r+…r,}r-(h(X” Scenarios for using OAuth access tokens in HTTP Authorization headers as a mechanism to establish client identity and authorization. The user authenticates with the DataONE Portal to establish their identity, and the portal issues a client-specific token. For Bearer Tokens, the Portal issues a signed, reusable access token that is sent to service providers and verified using an asymmetric public key.h2j ubeubj')r.}r/(h(XÓ@startuml images/auth_04.png title Detailed Access Token Authentication Scenarios participant "KNB" as MN << MNode >> participant "R Client" as R << Application >> participant "Portal" as Portal <> participant "Web Client" as Web << Application >> participant "CILogon" as CI participant "Identity Provider" as IP Web->CI: Select IdP CI-->Web: IdP Redirect Web->IP: Identity Verification IP-->Web: CILogon Redirect Web -> Portal: follow redirect to profile page group Bearer Token Scenario Portal->R: copy access_token R->MN: get(access_token, pid) MN-->Portal: getPublicKey() MN<--Portal: public_key MN->MN: validateToken(access_token, public_key) R<-MN: data or NotAuthorized end @endumlh2hLhPh.hQj*h)}r0(jRjSh,]h-]h+]h/]h0]uhWMwhXhhY]r1hbXÓ@startuml images/auth_04.png title Detailed Access Token Authentication Scenarios participant "KNB" as MN << MNode >> participant "R Client" as R << Application >> participant "Portal" as Portal <> participant "Web Client" as Web << Application >> participant "CILogon" as CI participant "Identity Provider" as IP Web->CI: Select IdP CI-->Web: IdP Redirect Web->IP: Identity Verification IP-->Web: CILogon Redirect Web -> Portal: follow redirect to profile page group Bearer Token Scenario Portal->R: copy access_token R->MN: get(access_token, pid) MN-->Portal: getPublicKey() MN<--Portal: public_key MN->MN: validateToken(access_token, public_key) R<-MN: data or NotAuthorized end @endumlr2…r3}r4(h(Uh2j.ubaubhK)r5}r6(h(Uh2hLhPh.hQhRh)}r7(h+]h/]h-]h,]r8U,encoding-session-information-in-http-headersr9ah0]r:hauhWMyhXhhY]r;(h[)r<}r=(h(X,Encoding Session information in HTTP headersr>h2j5hPh.hQh_h)}r?(h+]h/]h-]h,]h0]uhWMyhXhhY]r@hbX,Encoding Session information in HTTP headersrA…rB}rC(h(j>h2j<ubaubhf)rD}rE(h(XyWhen clients wish to use an authentication token, they will include the token value in the Authorization request header::h2j5hPh.hQhjh)}rF(h+]h/]h-]h,]h0]uhWM{hXhhY]rGhbXxWhen clients wish to use an authentication token, they will include the token value in the Authorization request header:rH…rI}rJ(h(XxWhen clients wish to use an authentication token, they will include the token value in the Authorization request header:h2jDubaubjM)rK}rL(h(X#Authorization: Bearer h2j5hPh.hQjPh)}rM(jRjSh,]h-]h+]h/]h0]uhWM~hXhhY]rNhbX#Authorization: Bearer rO…rP}rQ(h(Uh2jKubaubhf)rR}rS(h(XíThis is consistent with the OAuth 2 specification that states how Bearer tokens_ should be transmitted to the service. Service providers should inspect the request for this token and use it when a client x509 certificate is not present.h2j5hPh.hQhjh)}rT(h+]h/]h-]h,]h0]uhWM€hXhhY]rU(hbXIThis is consistent with the OAuth 2 specification that states how Bearer rV…rW}rX(h(XIThis is consistent with the OAuth 2 specification that states how Bearer h2jRubj²)rY}rZ(h(Xtokens_r[h2jRhPNhQj¶h)}r\(h,]r]Uid4r^ah-]h+]h/]h0]UrefidUid3r_uhWNhXhhY]r`hbXtokens_ra…rb}rc(h(Uh2jYubaubhbX should be transmitted to the service. Service providers should inspect the request for this token and use it when a client x509 certificate is not present.rd…re}rf(h(X should be transmitted to the service. Service providers should inspect the request for this token and use it when a client x509 certificate is not present.h2jRubeubhf)rg}rh(h(XïWhen services wish to verify the JSON Web Token (JWT) , they should use the public certificate of the token issuing service (i.e., the CN's public server certificate). A utility is included in the d1_portal project with example code below.rih2j5hPh.hQhjh)}rj(h+]h/]h-]h,]h0]uhWM…hXhhY]rkhbXïWhen services wish to verify the JSON Web Token (JWT) , they should use the public certificate of the token issuing service (i.e., the CN's public server certificate). A utility is included in the d1_portal project with example code below.rl…rm}rn(h(jih2jgubaubj')ro}rp(h(XVerify token:: // get the token String token = request.getHeader("Authorization"); token = token.split(" ")[1]; // parse the JWT SignedJWT signedJWT = SignedJWT.parse(token); // verify the token using server's public key JWSVerifier verifier = new RSASSAVerifier(publicKey); boolean verified = signedJWT.verify(verifier); // check payload for subject ("sub"), expiration ("exp"), etc... String subject = signedJWT.getJWTClaimsSet().getSubject(); Date expDate = signedJWT.getJWTClaimsSet().getExpirationTime();h2j5hPh.hQj*h)}rq(jRjSh,]h-]h+]h/]h0]uhWM™hXhhY]rrhbXVerify token:: // get the token String token = request.getHeader("Authorization"); token = token.split(" ")[1]; // parse the JWT SignedJWT signedJWT = SignedJWT.parse(token); // verify the token using server's public key JWSVerifier verifier = new RSASSAVerifier(publicKey); boolean verified = signedJWT.verify(verifier); // check payload for subject ("sub"), expiration ("exp"), etc... String subject = signedJWT.getJWTClaimsSet().getSubject(); Date expDate = signedJWT.getJWTClaimsSet().getExpirationTime();rs…rt}ru(h(Uh2joubaubeubeubhPh.hQhzh)}rv(h;X*h,]h-]h+]h/]h0]uhWM>hXhhY]rwhGaubhPNhQhh)}rx(h+]h/]h-]h,]h0]uhWNhXhhY]ryhDaubhY]rzhAahQUdefinition_listr{ubhPh.hQUdefinition_list_itemr|h)}r}(h+]h/]h-]h,]h0]uhWMIhY]r~(cdocutils.nodes term r)r€}r(h(X Bearer tokensr‚h2hAhPh.hQUtermrƒh)}r„(h+]h/]h-]h,]h0]uhWMIhY]r…hbX Bearer tokensr†…r‡}rˆ(h(j‚h2j€ubaubh=eubhY]r‰h8ahQU definitionrŠubhY]r‹h4ahQhzubhY]rŒ(hf)r}rŽ(h(X8`Bearer tokens`_ are unique string values issued by an authentication server that show that a client is authorized for access; anyone holding the bearer token can use it to gain access to a service. Service providers validate the token via either a call to the central authorization service or cryptographically using the public key that corresponds to the private key with which the authentication service signed the token. These tokens must be used with TLS, and care must be taken to not leak the tokens via e.g. logs, client storage locations, or via MITM attacks.h2h4hPh.hQhjh)}r(h+]h/]h-]h,]h0]uhWM?hY]r(hÈ)r‘}r’(h(X`Bearer tokens`_hËKh2jhQhÌh)}r“(UnameX Bearer tokenshÎj h,]h-]h+]h/]h0]uhY]r”hbX Bearer tokensr•…r–}r—(h(Uh2j‘ubaubhbX( are unique string values issued by an authentication server that show that a client is authorized for access; anyone holding the bearer token can use it to gain access to a service. Service providers validate the token via either a call to the central authorization service or cryptographically using the public key that corresponds to the private key with which the authentication service signed the token. These tokens must be used with TLS, and care must be taken to not leak the tokens via e.g. logs, client storage locations, or via MITM attacks.r˜…r™}rš(h(X( are unique string values issued by an authentication server that show that a client is authorized for access; anyone holding the bearer token can use it to gain access to a service. Service providers validate the token via either a call to the central authorization service or cryptographically using the public key that corresponds to the private key with which the authentication service signed the token. These tokens must be used with TLS, and care must be taken to not leak the tokens via e.g. logs, client storage locations, or via MITM attacks.h2jubeubj)r›}rœ(h(Uh)}r(h+]h/]h-]h,]h0]uh2h4hY]ržh7)rŸ}r (h(Uh)}r¡(h;X*h,]h-]h+]h/]h0]uh2j›hY]r¢(h3)r£}r¤(h(XLPros: simple to implement on client, passed directly in Authorization headerr¥h)}r¦(h+]h/]h-]h,]h0]uh2jŸhY]r§hf)r¨}r©(h(j¥h2j£hPh.hQhjh)}rª(h+]h/]h-]h,]h0]uhWMFhY]r«hbXLPros: simple to implement on client, passed directly in Authorization headerr¬…r­}r®(h(j¥h2j¨ubaubahQhubh3)r¯}r°(h(XžCons: Passed with every request, simple to capture, can use to steal session via replay attacks, may require centralized validation of tokens, requires TLS. h)}r±(h+]h/]h-]h,]h0]uh2jŸhY]r²hf)r³}r´(h(XœCons: Passed with every request, simple to capture, can use to steal session via replay attacks, may require centralized validation of tokens, requires TLS.rµh2j¯hPh.hQhjh)}r¶(h+]h/]h-]h,]h0]uhWMGhY]r·hbXœCons: Passed with every request, simple to capture, can use to steal session via replay attacks, may require centralized validation of tokens, requires TLS.r¸…r¹}rº(h(jµh2j³ubaubahQhubehQhzubahQj7ubehQhubhY]r»hf)r¼}r½(h(XUnexpected indentation.h)}r¾(h+]h/]h-]h,]h0]uh2h&hY]r¿hbXUnexpected indentation.rÀ…rÁ}rÂ(h(Uh2j¼ubahQhjubahQUsystem_messagerÃubh%)rÄ}rÅ(h(Uh2j hPh.hQjÃh)}rÆ(h+]UlevelKh,]h-]Usourceh.h/]h0]UlineM¢UtypeUWARNINGrÇuhWM¡hXhhY]rÈhf)rÉ}rÊ(h(X;Bullet list ends without a blank line; unexpected unindent.h)}rË(h+]h/]h-]h,]h0]uh2jÄhY]rÌhbX;Bullet list ends without a blank line; unexpected unindent.rÍ…rÎ}rÏ(h(Uh2jÉubahQhjubaubh%)rÐ}rÑ(h(Uh2j hPh.hQjÃh)}rÒ(h+]UlevelKh,]h-]Usourceh.h/]h0]UlineMªUtypejÇuhWM©hXhhY]rÓhf)rÔ}rÕ(h(X;Bullet list ends without a blank line; unexpected unindent.h)}rÖ(h+]h/]h-]h,]h0]uh2jÐhY]r×hbX;Bullet list ends without a blank line; unexpected unindent.rØ…rÙ}rÚ(h(Uh2jÔubahQhjubaubh%)rÛ}rÜ(h(Uh2j hPh.hQjÃh)}rÝ(h+]UlevelKh,]h-]Usourceh.h/]h0]UlineM±UtypejÇuhWM°hXhhY]rÞhf)rß}rà(h(X;Bullet list ends without a blank line; unexpected unindent.h)}rá(h+]h/]h-]h,]h0]uh2jÛhY]râhbX;Bullet list ends without a blank line; unexpected unindent.rã…rä}rå(h(Uh2jßubahQhjubaubeUcurrent_sourceræNU decorationrçNUautofootnote_startrèKUnameidsré}rê(hjhj hh¦h jph jh jËh j h jãhjÅhj“hjhjhjhjÑhjÝhj9hjhjËhjhj hjhj¤hjhj×hjühhUh juhY]rëhNah(UU transformerrìNU footnote_refsrí}rîUrefnamesrï}rð(Xrfc4510rñ]ròhÈ)ró}rô(h(jµh)}rõ(UnameXRFC4510h,]h-]h+]Urefnameröjñh/]h0]uh2j«hY]r÷hbXRFC4510rø…rù}rú(h(Uh2jóubahQhÌubaX bearer tokens]rûj‘aXrfc4514]rü(j–j¡eXgrouper]rýhìaXoauth1.0]rþj¶aXtokensrÿ]r hÈ)r }r (h(j[h)}r (Unamejÿh,]h-]h+]jöjÿh/]h0]uh2jRhY]r hbXtokensr …r }r (h(Uh2j ubahQhÌubaXmace]r h÷aXorcid]r hÉaXoauth2.0]r jÁauUsymbol_footnotesr ]r Uautofootnote_refsr ]r Usymbol_footnote_refsr ]r U citationsr ]r hXhU current_liner NUtransform_messagesr ]r (h%)r }r (h(Uh)}r (h+]UlevelKh,]r jºah-]r j¹aUsourceh.h/]h0]UlineKyUtypeh1uhY]r hf)r }r (h(Uh)}r (h+]h/]h-]h,]h0]uh2j hY]r hbXUnknown target name: "rfc4510".r …r! }r" (h(Uh2j ubahQhjubahQjÃubh%)r# }r$ (h(Uh)}r% (h+]UlevelKh,]r& j_ah-]r' j^aUsourceh.h/]h0]UlineM€Utypeh1uhY]r( hf)r) }r* (h(Uh)}r+ (h+]h/]h-]h,]h0]uh2j# hY]r, hbXUnknown target name: "tokens".r- …r. }r/ (h(Uh2j) ubahQhjubahQjÃubh%)r0 }r1 (h(Uh)}r2 (h+]UlevelKh,]h-]Usourceh.h/]h0]UlineK~UtypeUINFOr3 uhY]r4 hf)r5 }r6 (h(Uh)}r7 (h+]h/]h-]h,]h0]uh2j0 hY]r8 hbX<Hyperlink target "edupersonprincipalname" is not referenced.r9 …r: }r; (h(Uh2j5 ubahQhjubahQjÃubh%)r< }r= (h(Uh)}r> (h+]UlevelKh,]h-]Usourceh.h/]h0]UlineK€Utypej3 uhY]r? hf)r@ }rA (h(Uh)}rB (h+]h/]h-]h,]h0]uh2j< hY]rC hbX<Hyperlink target "teragridprincipalnames" is not referenced.rD …rE }rF (h(Uh2j@ ubahQhjubahQjÃubh%)rG }rH (h(Uh)}rI (h+]UlevelKh,]h-]Usourceh.h/]h0]UlineK‚Utypej3 uhY]rJ hf)rK }rL (h(Uh)}rM (h+]h/]h-]h,]h0]uh2jG hY]rN hbX*Hyperlink target "foaf" is not referenced.rO …rP }rQ (h(Uh2jK ubahQhjubahQjÃubh%)rR }rS (h(Uh)}rT (h+]UlevelKh,]h-]Usourceh.h/]h0]UlineK„Utypej3 uhY]rU hf)rV }rW (h(Uh)}rX (h+]h/]h-]h,]h0]uh2jR hY]rY hbX,Hyperlink target "rc4510" is not referenced.rZ …r[ }r\ (h(Uh2jV ubahQhjubahQjÃubh%)r] }r^ (h(Uh)}r_ (h+]UlevelKh,]h-]Usourceh.h/]h0]UlineMQUtypej3 uhY]r` hf)ra }rb (h(Uh)}rc (h+]h/]h-]h,]h0]uh2j] hY]rd hbX/Hyperlink target "hmac-sha1" is not referenced.re …rf }rg (h(Uh2ja ubahQhjubahQjÃubh%)rh }ri (h(Uh)}rj (h+]UlevelKh,]h-]Usourceh.h/]h0]UlineMSUtypej3 uhY]rk hf)rl }rm (h(Uh)}rn (h+]h/]h-]h,]h0]uh2jh hY]ro hbX.Hyperlink target "rsa-sha1" is not referenced.rp …rq }rr (h(Uh2jl ubahQhjubahQjÃubeUreporterrs NUid_startrt KU autofootnotesru ]rv U citation_refsrw }rx Uindirect_targetsry ]rz Usettingsr{ (cdocutils.frontend Values r| or} }r~ (Ufootnote_backlinksr KUrecord_dependenciesr€ NU rfc_base_urlr Uhttps://tools.ietf.org/html/r‚ U tracebackrƒ ˆUpep_referencesr„ NUstrip_commentsr… NU toc_backlinksr† Uentryr‡ U language_coderˆ Uenr‰ U datestamprŠ NU report_levelr‹ KU _destinationrŒ NU halt_levelr KU strip_classesrŽ Nh_NUerror_encoding_error_handlerr Ubackslashreplacer Udebugr‘ NUembed_stylesheetr’ ‰Uoutput_encoding_error_handlerr“ Ustrictr” U sectnum_xformr• KUdump_transformsr– NU docinfo_xformr— KUwarning_streamr˜ NUpep_file_url_templater™ Upep-%04drš Uexit_status_levelr› KUconfigrœ NUstrict_visitorr NUcloak_email_addressesrž ˆUtrim_footnote_reference_spacerŸ ‰Uenvr  NUdump_pseudo_xmlr¡ NUexpose_internalsr¢ NUsectsubtitle_xformr£ ‰U source_linkr¤ NUrfc_referencesr¥ NUoutput_encodingr¦ Uutf-8r§ U source_urlr¨ NUinput_encodingr© U utf-8-sigrª U_disable_configr« NU id_prefixr¬ UU tab_widthr­ KUerror_encodingr® UUTF-8r¯ U_sourcer° h.Ugettext_compactr± ˆU generatorr² NUdump_internalsr³ NU smart_quotesr´ ‰U pep_base_urlrµ U https://www.python.org/dev/peps/r¶ Usyntax_highlightr· Ulongr¸ Uinput_encoding_error_handlerr¹ j” Uauto_id_prefixrº Uidr» Udoctitle_xformr¼ ‰Ustrip_elements_with_classesr½ NU _config_filesr¾ ]Ufile_insertion_enabledr¿ ˆU raw_enabledrÀ KU dump_settingsrÁ NubUsymbol_footnote_startr KUidsrà }rÄ (jãjßhUhNjjj9j5jºj jj jËjÇj jj^jYj jj¹j³j_j# jjjjjjjÅjÁjÑjÍjüjøjÝjÙjjjËjÇjj j¤j jjüj“hLj jœjpjlj×jÓjjh¦h¢jjuUsubstitution_namesrÅ }rÆ hQhXh)}rÇ (h+]h,]h-]Usourceh.h/]h0]uU footnotesrÈ ]rÉ UrefidsrÊ }rË ub.