.. Warning: this file is automatically generated. Edits will be lost .. list-table:: Functions defined in :mod:`CNIdentity` :widths: 3 3 10 10 30 :header-rows: 1 * - Tier - Version - REST - Function - Parameters * - Tier 2 - 1.0, (2.0) - ``POST /accounts`` - :func:`registerAccount` - (:class:`session`, :class:`person`) ``->`` :class:`Types.Subject` * - Tier 2 - 1.0, (2.0) - ``PUT /accounts/{subject}`` - :func:`updateAccount` - (:class:`session`, :class:`subject`, :class:`person`) ``->`` :class:`Types.Subject` * - Tier 2 - 1.0, (2.0) - ``PUT /accounts/verification/{subject}`` - :func:`verifyAccount` - (:class:`session`, :class:`subject`) ``->`` boolean * - Tier 2 - 1.0, (2.0) - ``GET /accounts/{subject}`` - :func:`getSubjectInfo` - (:class:`session`, :class:`subject`) ``->`` :class:`Types.SubjectInfo` * - Tier 2 - 1.0, (2.0) - ``GET /accounts?query={query}[&status={status}&start={start}&count={count}]`` - :func:`listSubjects` - (:class:`session`, ``query``, ``status``, ``start``, ``count``) ``->`` :class:`Types.SubjectInfo` * - Tier 2 - 1.0, (2.0) - ``POST /accounts/map`` - :func:`mapIdentity` - (:class:`session`, :class:`primarySubject`, :class:`secondarySubject`) ``->`` boolean * - Tier 2 - 1.0, (2.0) - ``DELETE /accounts/map/{subject}`` - :func:`removeMapIdentity` - (:class:`session`, :class:`subject`) ``->`` boolean * - Tier 2 - 1.0, (2.0) - ``POST /accounts/pendingmap`` - :func:`requestMapIdentity` - (:class:`session`, :class:`subject`) ``->`` boolean * - Tier 2 - 1.0, (2.0) - ``PUT /accounts/pendingmap/{subject}`` - :func:`confirmMapIdentity` - (:class:`session`, :class:`subject`) ``->`` boolean * - Tier 2 - 1.0, (2.0) - ``GET /accounts/pendingmap/{subject}`` - :func:`getPendingMapIdentity` - (:class:`session`, :class:`subject`) ``->`` :class:`Types.SubjectInfo` * - Tier 2 - 1.0, (2.0) - ``DELETE /accounts/pendingmap/{subject}`` - :func:`denyMapIdentity` - (:class:`session`, :class:`subject`) ``->`` boolean * - Tier 2 - 1.0, (2.0) - ``POST /groups`` - :func:`createGroup` - (:class:`session`, :class:`group`) ``->`` :class:`Types.Subject` * - Tier 2 - 1.0, (2.0) - ``PUT /groups`` - :func:`updateGroup` - (:class:`session`, :class:`group`) ``->`` boolean .. function:: registerAccount(session,person) -> Subject Create a new :term:`subject` in the DataONE system. Note that there should probably be a lot more metadata captured about the new user, and there should be a mechanism for specifying the default access control rules for the new account. :Version: 1.0, (2.0) :Use Cases: :doc:`UC16 ` :REST URL: ``POST /accounts`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param person: Information about the Person to be registered with the account, including the real name and email address for the individual. The Subject with the Person must match the subject of the X.509 certificate associated with the authenticated SSL session via client-side authentication, and must not have been registered previously. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a *File part* of the MIME multipart/mixed message. :type person: :class:`Types.Person` :returns: The new subject in the DataONE system. This may be a simple identifier. :rtype: :class:`Types.Subject` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4520)`` :raises Exceptions.IdentifierNotUnique: ``(errorCode=409, detailCode=4521)`` The chosen identity already exists in the system :raises Exceptions.InvalidCredentials: ``(errorCode=401, detailCode=4522)`` Raised if the supplied credentials are invalid, such as an invalid X.509 certificate. :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4523)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=4524)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4525)`` The subject of the session does not match the subject of the person. :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4526)`` .. function:: updateAccount(session,subject,person) -> Subject Update an existing :term:`subject` in the DataONE system. The target subject is determined from subject provided in the URL. The use calling this method must have write access to the account details. Note that there should be a policy for verifying the details that change via this method. :Version: 1.0, (2.0) :Use Cases: :doc:`UC16 ` :REST URL: ``PUT /accounts/{subject}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param subject: The subject of the person being updated. Transmitted as part of the URL path and must be escaped accordingly. :type subject: :class:`Types.Subject` :param person: New information about the Person. The subject of the Person cannot be updated with this method and must match the subject of the X.509 certificate associated with the authenticated SSL session via client-side authentication. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a *File part* of the MIME multipart/mixed message. :type person: :class:`Types.Person` :returns: The Subject in the DataONE system that was updated. :rtype: :class:`Types.Subject` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4530)`` :raises Exceptions.InvalidCredentials: ``(errorCode=401, detailCode=4531)`` Raised if the supplied credentials are invalid, such as an invalid X.509 certificate. :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4532)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=4533)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4534)`` Raised if the subject of the session does not match that of the person. :raises Exceptions.NotFound: ``(errorCode=404, detailCode=4535)`` Raised if the account does not exist. :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4536)`` .. function:: verifyAccount(session,subject) -> boolean Verify that the Person data associated with this Subject is a true representation of the real world person. This service can only be called by users who have an administrative role for the domain of users in question. A successful completion of this operation is indicated by returning a HTTP status of 200. An exeption MUST be returned if the account verification is not successful. :Version: 1.0, (2.0) :REST URL: ``PUT /accounts/verification/{subject}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param subject: The Subject identifier of the Person to be verified. After this service is called for a subject by an authorized user, the account is marked as verified by this user. Transmitted as part of the URL path and must be escaped accordingly. :type subject: :class:`Types.Subject` :returns: True if the account verification succeeds, otherwise false. :rtype: boolean :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4540)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4541)`` This error is raised if the person attempting to validate the account is not authorized to verify accounts. :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4542)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4543)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=4544)`` .. function:: getSubjectInfo(session,subject) -> SubjectInfo Get the information about a Person (their equivalent identities, and the Groups to which they belong) or the Group (including members). :Version: 1.0, (2.0) :Use Cases: :doc:`UC12 ` :REST URL: ``GET /accounts/{subject}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param subject: The Subject identifier of the Person or Group details to be returned. Transmitted as part of the URL path and must be escaped accordingly. :type subject: :class:`Types.Subject` :returns: The Person or Group details are contained in the returned SubjectList for the given Subject :rtype: :class:`Types.SubjectInfo` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4560)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4561)`` :raises Exceptions.NotFound: ``(errorCode=404, detailCode=4564)`` Raised if the requested subject is not registered with the DataONE system :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4563)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4564)`` .. function:: listSubjects(session,query,status,start,count) -> SubjectInfo List the subjects, including users, groups, and systems, that match search criteria. The list can be restricted to subjects whose identifier matches certain substrings, and the size of the resultset can be paged through. :Version: 1.0, (2.0) :REST URL: ``GET /accounts?query={query}[&status={status}&start={start}&count={count}]`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param query: A query string criteria to be matched using a case-insensitive substring match against the identifier for the principal, the givenName or familyName of users, and the groupName of groups. The function returns the union of all successful matches against these fields. Transmitted as a URL query parameter, and so must be escaped accordingly. :type query: string :param status: When provided, the status field can limit the returned list of Subjects to only those with the given status. Currently the 'verified' status is supported. Transmitted as a URL query parameter, and so must be escaped accordingly. :type status: string :param start: The starting record number for the records to be returned (default = 0). Transmitted as a URL query parameter, and so must be escaped accordingly. :type start: integer :param count: The maximum number of entries that should be returned in the response. The Member Node may return fewer and the caller should check the *total* in the response to determine if further pages may be retrieved (default = 100). Transmitted as a URL query parameter, and so must be escaped accordingly. :type count: integer :returns: The list of people and groups that match the query. :rtype: :class:`Types.SubjectInfo` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=2290)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=2270)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=2260)`` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=2261)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=2262)`` .. function:: mapIdentity(session,primarySubject,secondarySubject) -> boolean Create a new mapping between the two identities, asserting that they represent the same subject. Mapping identities with this method requires explicit authorization for the user given in the Session object. The caller must have made sure that the primary and secondary identities represent one and the same individual. Successful completion of the request is indicated by returning a HTTP status of 200. A failed request MUST be indicated by returning an appropriate exception and setting the response HTTP status accordingly. :Version: 1.0, (2.0) :REST URL: ``POST /accounts/map`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param primarySubject: The Subject identifier that will have a mapped identity to the other given subject. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type primarySubject: :class:`Types.Subject` :param secondarySubject: The Subject identifier that will have a mapped identity to the other given subject. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type secondarySubject: :class:`Types.Subject` :returns: True if the mapping was successfully initiated, false otherwise. :rtype: boolean :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=2390)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=2370)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=2360)`` The supplied principal does not have permission to map these two identities :raises Exceptions.NotFound: ``(errorCode=404, detailCode=2340)`` The specified principal does not exist in the DataONE system :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=2361)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=2342)`` :raises Exceptions.IdentifierNotUnique: ``(errorCode=409, detailCode=2343)`` The subject of the session and the provided subject are the same .. function:: removeMapIdentity(session,subject) -> boolean Removes a previously asserted identity mapping from the Subject in the Session to the Subject given by the parameter. The reciprocol mapping entry is also removed. A successful request is indicated by returning a HTTP status of 200. A failed request MUST be indicated by returning an appropriate exception and setting the response HTTP status accordingly. :Version: 1.0, (2.0) :REST URL: ``DELETE /accounts/map/{subject}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param subject: The Subject identifier to be used for equivalentIdentity. This Subject will not match the Subject named in the certificate. Transmitted as part of the URL path and must be escaped accordingly. :type subject: :class:`Types.Subject` :returns: True if the map was successfully created, false otherwise. :rtype: boolean :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=2390)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=2370)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=2360)`` The supplied principal does not have permission to map these two identities :raises Exceptions.NotFound: ``(errorCode=404, detailCode=2340)`` The specified principal does not exist in the DataONE system, or the mapping between the subjects has no yet been initiated. :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=2361)`` .. function:: requestMapIdentity(session,subject) -> boolean Request a new mapping between the authenticated identity in the session and the given identity, asserting that they represent the same subject. Mapping identities is a two-step process wherein a map request is made by a primary Subject and a subsequent (confirmation) map request is made by the secondary Subject. This ensures that mappings are performed only by those that have authority to do so. Successful completion of the request is indicated by returning a HTTP status of 200. A failed request MUST be indicated by returning an appropriate exception and setting the response HTTP status accordingly. :Version: 1.0, (2.0) :REST URL: ``POST /accounts/pendingmap`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param subject: The Subject identifier to be used for equivalentIdentity. This Subject will not match the Subject named in the certificate. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type subject: :class:`Types.Subject` :returns: True if the mapping was successfully initiated, false otherwise. :rtype: boolean :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=2390)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=2370)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=2360)`` The supplied principal does not have permission to map these two identities :raises Exceptions.NotFound: ``(errorCode=404, detailCode=2340)`` The specified principal does not exist in the DataONE system :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=2361)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=2342)`` :raises Exceptions.IdentifierNotUnique: ``(errorCode=409, detailCode=2343)`` The subject of the session and the provided subject are the same .. function:: confirmMapIdentity(session,subject) -> boolean Confirms a previously initiated identity mapping. If subject A asserts that B is the same identity through :func:`CNIdentity.requestMapIdentity`, then this method is called by B to confirm that assertion. A successful request is indicated by returning a HTTP status of 200. A failed request MUST be indicated by returning an appropriate exception and setting the response HTTP status accordingly. :Version: 1.0, (2.0) :REST URL: ``PUT /accounts/pendingmap/{subject}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param subject: The Subject identifier to be used for equivalentIdentity. This Subject will not match the Subject named in the certificate. Transmitted as part of the URL path and must be escaped accordingly. :type subject: :class:`Types.Subject` :returns: True if the map was successfully created, false otherwise. :rtype: boolean :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=2390)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=2370)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=2360)`` The supplied principal does not have permission to map these two identities :raises Exceptions.NotFound: ``(errorCode=404, detailCode=2340)`` The specified principal does not exist in the DataONE system, or the mapping between the subjects has no yet been initiated. :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=2361)`` .. function:: getPendingMapIdentity(session,subject) -> SubjectInfo Gets the SubjectInfo of a previously initiated identity mapping. A successful request is indicated by returning a HTTP status of 200. A failed request MUST be indicated by returning an appropriate exception and setting the response HTTP status accordingly. :Version: 1.0, (2.0) :REST URL: ``GET /accounts/pendingmap/{subject}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param subject: The Subject identifier to be used for equivalentIdentity. This Subject will not match the Subject named in the certificate. Transmitted as part of the URL path and must be escaped accordingly. :type subject: :class:`Types.Subject` :returns: The SubjectInfo :rtype: :class:`Types.SubjectInfo` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=2390)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=2360)`` The supplied principal does not have permission to get the SubjectInfo :raises Exceptions.NotFound: ``(errorCode=404, detailCode=2340)`` The specified principal does not exist in the DataONE system, or the mapping between the subjects has no yet been initiated. :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=2361)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4961)`` .. function:: denyMapIdentity(session,subject) -> boolean Denies a previously initiated identity mapping. If subject A asserts that B is the same identity through :func:`CNIdentity.requestMapIdentity`, then this method is called by B to deny that assertion. A successful request is indicated by returning a HTTP status of 200. A failed request MUST be indicated by returning an appropriate exception and setting the response HTTP status accordingly. :Version: 1.0, (2.0) :REST URL: ``DELETE /accounts/pendingmap/{subject}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param subject: The Subject identifier to be used for equivalentIdentity. This Subject will not match the Subject named in the certificate. Transmitted as part of the URL path and must be escaped accordingly. :type subject: :class:`Types.Subject` :returns: True if the map was successfully created, false otherwise. :rtype: boolean :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=2390)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=2370)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=2360)`` The supplied principal does not have permission to map these two identities :raises Exceptions.NotFound: ``(errorCode=404, detailCode=2340)`` The specified principal does not exist in the DataONE system, or the mapping between the subjects has no yet been initiated. :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=2361)`` .. function:: createGroup(session,group) -> Subject Create a group with the given name. Groups are lists of subjects that allow all members of the group to be referenced by listing solely the subject name of the group. Group names must be unique within the DataONE system. Groups can only be modified by Subjects listed as rightsHolders. :Version: 1.0, (2.0) :REST URL: ``POST /groups`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param group: The Group to be created. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a *File part* of the MIME multipart/mixed message. :type group: :class:`Types.Group` :returns: The Subject of the group that was created. :rtype: :class:`Types.Subject` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=2490)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=2470)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=2460)`` The supplied principal does not have permission to create a group :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=2461)`` :raises Exceptions.IdentifierNotUnique: ``(errorCode=409, detailCode=2400)`` A group by this name already exists .. function:: updateGroup(session,group) -> boolean Add members to the named group. Group members can be modified only by the original creator of the group, otherwise a NotAuthorized exception is thrown. Group members are provided as a list of subjects that replace the group membership. Successful completion of this operation is indicated by a HTTP response status code of 200. Unsuccessful completion of this operation MUST be indicated by returning an appropriate exception. :Version: 1.0, (2.0) :REST URL: ``PUT /groups`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session is used to determine if the request is being made by the creator of the group. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param group: The new Group object that will replace the old Group. The Group.Subject must match the groupName and an update cannot modify this value. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a *File part* of the MIME multipart/mixed message. :type group: :class:`Types.Group` :returns: True if the group that was modified successfully, false otherwise :rtype: boolean :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=2590)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=2570)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=2560)`` The supplied principal does not have permission to add to a group :raises Exceptions.NotFound: ``(errorCode=404, detailCode=2540)`` The specified group does not exist in the DataONE system :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=2561)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=2542)``