From d9349e5bc8e7a19774cdf63243f08dd637320658 Mon Sep 17 00:00:00 2001
From: "Stefan E. Funk" <funk@sub.uni-goettingen.de>
Date: Fri, 30 Oct 2015 13:06:44 +0100
Subject: [PATCH] Reformatted.
---
docs/api/tg-authApi.rst | 704 +++++++++++++++++++++++++---------------
docs/conf.py | 2 +-
docs/index.rst | 123 ++++---
3 files changed, 508 insertions(+), 321 deletions(-)
diff --git a/docs/api/tg-authApi.rst b/docs/api/tg-authApi.rst
index 5125540..ce0a819 100644
--- a/docs/api/tg-authApi.rst
+++ b/docs/api/tg-authApi.rst
@@ -1,6 +1,5 @@
-tg-authApi
-==========
-
+TG-auth* API
+============
userExists
@@ -9,13 +8,19 @@ userExists
Checks whether this UserID (eduPersonPrincipalName) exists in RBAC.
* Input Parameters userExistsRequest, with elements
- * auth - String, SessionID of application or user asking
- * log - String for log information, optional
+
+ * auth - String, SessionID of application or user asking
+ * log - String for log information, optional
+
* username - String containing the ID (ePPN) of the user
- * Output Parameters booleanResponse, with element
- * result - boolean, true if user exists, false otherwise
+
+ * Output Parameters booleanResponse, with element
+ * result - boolean, true if user exists, false otherwise
+
* Faults:
- * authenticationFault
+
+ * authenticationFault
+
getNames
--------
@@ -23,9 +28,11 @@ getNames
Returns user records for a list of ePPNs
* Input Parameters getNamesRequest, with elements
- * auth - String, SessionID of user that wants to query for names
- * log - String,
- * ePPN - List of Strings
+
+ * auth - String, SessionID of user that wants to query for names
+ * log - String,
+ * ePPN - List of Strings
+
getIDs
------
@@ -33,460 +40,617 @@ getIDs
Returns user records for a name or mail address.
* Input Parameters getIDsRequest, with elements
- * auth - String, SessionID of user that wants to query for names
- * log - String,
- * name - String with Name
- * mail - String with E-Mail Address
- * organisation - String with Organisation
+
+ * auth - String, SessionID of user that wants to query for names
+ * log - String,
+ * name - String with Name
+ * mail - String with E-Mail Address
+ * organisation - String with Organisation
+
* Output Parameters getIDsResponse. It contains 0...n userDetails, which themselves have elements
- * ePPN - String holding ePPN of user
- * name - String holding Name (cn) of user
- * mail - String holding E-Mail address of user
- * organisation - String holding user' affiliation
- * agreesearch - Boolean, whether user wants his ID to be found be a search for name or mail address
- * usersupplieddata - Boolean, whether user himself or his organisation supplied these data
+
+ * ePPN - String holding ePPN of user
+ * name - String holding Name (cn) of user
+ * mail - String holding E-Mail address of user
+ * organisation - String holding user' affiliation
+ * agreesearch - Boolean, whether user wants his ID to be found be a search for name or mail address
+ * usersupplieddata - Boolean, whether user himself or his organisation supplied these data
+
* Faults none
+
getObjects
----------
Returns URIs of all resources in project. Caller must have some role in the project.
- * Input Parameters getObjectsRequest, with elements
- * auth - String, SessionID of user
- * log - String for log information, optional
- * project - String with projectID
- * Output Parameters resourcesetResponse, with element
- * resource - String with URI of resource in project. Can occur multiple times
+* Input Parameters getObjectsRequest, with elements
+
+ * auth - String, SessionID of user
+ * log - String for log information, optional
+
+ * project - String with projectID
+
+ * Output Parameters resourcesetResponse, with element
+
+ * resource - String with URI of resource in project. Can occur multiple times
+
tgCheckAccess
-------------
Returns access decision for given operation on given resource for session.
- * Input Parameters tgCheckAccessRequest, with elements
- * auth - String, SessionID of user (or service) that wants to intitiate the check
- * log - String for log information, optional
- * sid - String, SessionID of user for whom the check is to be done. Leave empty if check is to be done for user's own session given under auth
- * operation - String, such as "read", "write"
- * resource - String, name of project or role, or URI of TgObject resource
- * Output Parameters booleanResponse, with element
- * result - boolean, true if operation was successful, false otherwise
- * Faults
- * unknownResourceFault
+* Input Parameters tgCheckAccessRequest, with elements
+
+ * auth - String, SessionID of user (or service) that wants to intitiate the check
+ * log - String for log information, optional
+ * sid - String, SessionID of user for whom the check is to be done. Leave empty if check is to be done for user's own session given under auth
+ * operation - String, such as "read", "write"
+ * resource - String, name of project or role, or URI of TgObject resource
+ * Output Parameters booleanResponse, with element
+
+ * result - boolean, true if operation was successful, false otherwise
+
+ * Faults
+
+ * unknownResourceFault
+
tgAssignedRoles
---------------
Returns the roles the requesting user has, in any project. Can be called for another user by project leaders, then roles will be limited to the intersection of those projects where auth is leader AND username has some role in.
- * Input Parameters tgAssignedRolesRequest, with elements
- * auth - String, SessionID of user that wants to query for roles
- * log - String for log information, optional
- * username - String, ePPN of user for whom the query is to be done. Can be empty.
- * Output Parameters rolesetResponse, with element
- * role - String with full-qualified role name of the role. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer". Can occur multiple times.
+* Input Parameters tgAssignedRolesRequest, with elements
+
+ * auth - String, SessionID of user that wants to query for roles
+ * log - String for log information, optional
+ * username - String, ePPN of user for whom the query is to be done. Can be empty.
+
+* Output Parameters rolesetResponse, with element
+
+ * role - String with full-qualified role name of the role. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer". Can occur multiple times.
+
tgAssignedProjects
------------------
Returns projectIDs of all projects the user has some role in.
- * Input Parameters tgAssignedProjectsRequest, with elements
- * auth - String, SessionID of user that wants to query for roles
- * log - String for log information, optional
- * level - Integer. Can be either empty (= level 0) or one of the following:
- * 0 - Returns all projects the user has any role in (default).
- * 1 - Returns only projects where the user has read access, i.e.
+* Input Parameters tgAssignedProjectsRequest, with elements
+
+ * auth - String, SessionID of user that wants to query for roles
+ * log - String for log information, optional
+ * level - Integer. Can be either empty (= level 0) or one of the following:
+
+ * 0 - Returns all projects the user has any role in (default).
+ * 1 - Returns only projects where the user has read access, i.e.
+
* she is Beobachter (observer) or
* she is Bearbeiter (editor) or
+
getAllProjects
--------------
Returns all projects stored in this RBAC instance with ID, name, and description. See also getProjectDescription().
- * Input Parameters getAllProjectsRequest, with elements
- * auth - String, SessionID of user that wants to query for projects. Can be omitted as this information can be reviewed publicly
- * log - String for log information, optional
- * Output Parameters getAllProjectsResponse, with element
- * project - projectInfo, can occur multiple times
- * The type projectInfo consists of the following elements:
- * id - String, project ID, such as "TGPR123"
- * description - String, project description
- * name - String, project name
- * file - String with URI of project file for project-specific settings.
+* Input Parameters getAllProjectsRequest, with elements
+
+ * auth - String, SessionID of user that wants to query for projects. Can be omitted as this information can be reviewed publicly
+ * log - String for log information, optional
+
+* Output Parameters getAllProjectsResponse, with element
+
+ * project - projectInfo, can occur multiple times
+ * The type projectInfo consists of the following elements:
+
+ * id - String, project ID, such as "TGPR123"
+ * description - String, project description
+ * name - String, project name
+ * file - String with URI of project file for project-specific settings.
+
getDeactivatedProjects
----------------------
Returns all projects stored in this RBAC instance with ID, name, and description that are deactivated and can be reactivated by the current user.
- * Input Parameters getAllProjectsRequest, with elements
- * auth - String, SessionID of user that wants to query for projects. Can be omitted as this information can be reviewed publicly
- * log - String for log information, optional
- * Output Parameters getDeactivatedProjectsResponse, with element
- * project - projectInfo, can occur multiple times.
- * The type projectInfo consists of the following elements:
- * id - String, project ID, such as "TGPR123"
- * description - String, project description
- * name - String, project name
- * file - String with URI of project file for project-specific settings.
+* Input Parameters getAllProjectsRequest, with elements
+
+ * auth - String, SessionID of user that wants to query for projects. Can be omitted as this information can be reviewed publicly
+ * log - String for log information, optional
+
+* Output Parameters getDeactivatedProjectsResponse, with element
+
+ * project - projectInfo, can occur multiple times.
+ * The type projectInfo consists of the following elements:
+
+ * id - String, project ID, such as "TGPR123"
+ * description - String, project description
+ * name - String, project name
+ * file - String with URI of project file for project-specific settings.
+
getLeader
---------
Returns Project Leader/s (i.e. who have delegate right on the respective project resource).
- * Input Parameters getLeaderRequest, with elements
- * auth - String, SessionID of user that wants to query for projects. Can be omitted as this information can be reviewed publicly
- * log - String for log information, optional
- * project - String with project ID, such as "TGPR123"
- * Output Parameters usersetResponse, with element
- * username - String holding ePPN of user, can occur multiple times.
+* Input Parameters getLeaderRequest, with elements
+
+ * auth - String, SessionID of user that wants to query for projects. Can be omitted as this information can be reviewed publicly
+ * log - String for log information, optional
+ * project - String with project ID, such as "TGPR123"
+
+* Output Parameters usersetResponse, with element
+
+ * username - String holding ePPN of user, can occur multiple times.
+
filterBySid
-----------
This is tgCheckAccess in batch operation: Returns a list of the resources where a given operation with this SessionID is allowed. The resource parameter must contain a list of resources, and the subset of this list that matches will be returned.
- * Input Parameters filterBySidRequest, with elements
- * auth - String, SessionID of user that wants to do the check
- * log - String for log information, optional
- * resource - String with projectID, or URI of TgObject resource. Can occur multiple times.
- * operation - String, such as "read", "write"
- * Output Parameters filterResponse, with element
- * resource - String with projectID, or URIs that match. Can occur multiple times.
- * Faults
- * authenticationFault
+* Input Parameters filterBySidRequest, with elements
+
+ * auth - String, SessionID of user that wants to do the check
+ * log - String for log information, optional
+ * resource - String with projectID, or URI of TgObject resource. Can occur multiple times.
+ * operation - String, such as "read", "write"
+
+* Output Parameters filterResponse, with element
+
+ * resource - String with projectID, or URIs that match. Can occur multiple times.
+
+* Faults
+
+ * authenticationFault
+
getOwner
--------
Returns ePPN of owner that was set in registerResource. User must have read permission on the resource, or resource must be public.
- * Input Parameters getOwnerRequest, with elements
- * auth - String, SessionID of user that wants to query for the owner
- * log - String for log information, optional
- * resource - String, URI of TgObject
- * Output Parameters getOwnerResponse, with element
- * owner - String, ePPN of owner.
- * Faults
- * authenticationFault
+* Input Parameters getOwnerRequest, with elements
+
+ * auth - String, SessionID of user that wants to query for the owner
+ * log - String for log information, optional
+ * resource - String, URI of TgObject
+
+* Output Parameters getOwnerResponse, with element
+
+ * owner - String, ePPN of owner.
+
+* Faults
+
+ * authenticationFault
+
getMembers
----------
Returns ePPNs of all members in the project, caller must be member herself.
- * Input Parameters getMembersRequest, with elements
- * auth - String, SessionID of user that wants to query for members
- * log - String for log information, optional
- * project - String, ProjectID, such as "TGPR123"
- * Output Parameters usersetResponse, with element
- * username - String holding ePPN of user, can occur multiple times.
- * Faults
- * authenticationFault
+* Input Parameters getMembersRequest, with elements
+
+ * auth - String, SessionID of user that wants to query for members
+ * log - String for log information, optional
+ * project - String, ProjectID, such as "TGPR123"
+
+* Output Parameters usersetResponse, with element
+
+ * username - String holding ePPN of user, can occur multiple times.
+
+* Faults
+
+ * authenticationFault
+
getUserRole
-----------
Returns ePPNs plus Array of Roles of all members in the project, caller must be member herself.
- * Input Parameters getUserRoleRequest, with elements
- * auth - String, SessionID of user that wants to query for roles
- * log - String for log information, optional
- * project - String, ProjectID, such as "TGPR123"
- * Output Parameters getUserRoleResponse. It contains 0...n userRoles, which themselves have elements
- * username - String holding ePPN of user
- * roles - array of Strings with roles the user has (e.g. "Bearbeiter").
- * Faults
- * authenticationFault
- * unknownProjectFault
+* Input Parameters getUserRoleRequest, with elements
+
+ * auth - String, SessionID of user that wants to query for roles
+ * log - String for log information, optional
+ * project - String, ProjectID, such as "TGPR123"
+
+* Output Parameters getUserRoleResponse. It contains 0...n userRoles, which themselves have elements
+
+ * username - String holding ePPN of user
+ * roles - array of Strings with roles the user has (e.g. "Bearbeiter").
+
+* Faults
+
+ * authenticationFault
+ * unknownProjectFault
+
getFriends
----------
Returns ePPNs of the users the authenticated user has relations with, i.e. they are signed into the same project role. Each user name has a score which shows how many roles the requester shares with that user.
- * Input Parameters getFriendsRequest, with element
- * auth - String, SessionID of user that wants to query for friends
- * Output Parameters getFriendsResponse. It contains 0...n friends, which themselves have elements
- * username - String holding ePPN of user
- * score - Integer with the users' number of common roles with the requester
- * Faults none
+* Input Parameters getFriendsRequest, with element
+
+ * auth - String, SessionID of user that wants to query for friends
+
+* Output Parameters getFriendsResponse. It contains 0...n friends, which themselves have elements
+
+ * username - String holding ePPN of user
+ * score - Integer with the users' number of common roles with the requester
+
+* Faults none
+
getRights
---------
Returns permissions for given resource or projectID. Can be used by project leaders to check permissions for another project member.
- * Input Parameters getRightsRequest, with elements
- * auth - String, SessionID of user that wants to query the rights
- * log - String for log information, optional
- * resource - String, URI of TgObject or ProjectID
- * username - ePPN of user whose rights shall be queried. Leave empty to get rights of user authenticated by the auth parameter.
- * Output Parameters operationsetResponse, with element
- * operation - String with a right, such as "read" or "delegate". Can occur multiple times.
- * Faults
- * authenticationFault
+* Input Parameters getRightsRequest, with elements
+
+ * auth - String, SessionID of user that wants to query the rights
+ * log - String for log information, optional
+ * resource - String, URI of TgObject or ProjectID
+ * username - ePPN of user whose rights shall be queried. Leave empty to get rights of user authenticated by the auth parameter.
+
+* Output Parameters operationsetResponse, with element
+
+ * operation - String with a right, such as "read" or "delegate". Can occur multiple times.
+
+* Faults
+
+ * authenticationFault
+
isPublic
--------
Returns status of isPublic flag for a TextGridObject.
- * Input Parameters isPublicRequest, with elements
- * auth - String, SessionID of user that wants to query. Can be empty.
- * log - String for log information, optional
- * resource - String, URI of TgObject
- * Output Parameters booleanResponse, with element
- * result - boolean, true if resource has the isPublic flag set to TRUE, i.e. has been published, false otherwise
+* Input Parameters isPublicRequest, with elements
+
+ * auth - String, SessionID of user that wants to query. Can be empty.
+ * log - String for log information, optional
+ * resource - String, URI of TgObject
+
+* Output Parameters booleanResponse, with element
+
+ * result - boolean, true if resource has the isPublic flag set to TRUE, i.e. has been published, false otherwise
+
getNumberOfResources
--------------------
Returns the total number of resources and the number of public ones in this project. Can be called by anyone.
- * Input Parameters getNumberOfResourcesRequest, with elements
- * auth - String, SessionID of user that wants to query. Can be empty.
- * log - String for log information, optional
- * project - String
- * Output Parameters getNumberOfResourcesResponse, with elements
- * allresources - integer
- * publicresources - integer
+* Input Parameters getNumberOfResourcesRequest, with elements
+
+ * auth - String, SessionID of user that wants to query. Can be empty.
+ * log - String for log information, optional
+ * project - String
+
+* Output Parameters getNumberOfResourcesResponse, with elements
+
+ * allresources - integer
+ * publicresources - integer
+
getProjectDescription
---------------------
Returns name and description of project identified by ID. See also getAllProjects().
- * Input Parameters getProjectDescriptionRequest, with elements
- * auth - String, SessionID of user. Can be empty.
- * log - String for log information, optional
- * project - String, ProjectID
- * Output Parameters getProjectDescriptionResponse, with element
- * project - projectInfo
- * The type projectInfo consists of the following elements:
- * id - String, project ID, such as "TGPR123"
- * description - String, project description
- * name - String, project name
- * file - String with URI of project file for project-specific settings.
+* Input Parameters getProjectDescriptionRequest, with elements
+
+ * auth - String, SessionID of user. Can be empty.
+ * log - String for log information, optional
+ * project - String, ProjectID
+
+* Output Parameters getProjectDescriptionResponse, with element
+
+ * project - projectInfo
+ * The type projectInfo consists of the following elements:
+
+ * id - String, project ID, such as "TGPR123"
+ * description - String, project description
+ * name - String, project name
+ * file - String with URI of project file for project-specific settings.
+
getSid
------
Returns some random SessionID suitable for RBAC.
- * Input Parameters empty
- * Output Parameters getSidResponse, with element
- * sid - String, approximately 60-70 bytes long, consisting of random characters taken from a-zA-Z0-9.
+* Input Parameters empty
+* Output Parameters getSidResponse, with element
+
+ * sid - String, approximately 60-70 bytes long, consisting of random characters taken from a-zA-Z0-9.
+
getSupportedUserAttributes
--------------------------
TODO
+
getMyUserAttributes
-------------------
TODO
+
authenticate
------------
Internal function used by applications to identify themselves (via shared secret between RBAC and WebAuth).
- * Input Parameters authenticateRequest, with elements
- * username - String with name of application
- * password - String with password for this application
- * log - String for log information, optional
- * Output Parameters authenticateResponse, with element
- * auth - String, SessionID of authenticated application (See getSid() for format.)
- * Faults
- * authenticationFault
+* Input Parameters authenticateRequest, with elements
+
+ * username - String with name of application
+ * password - String with password for this application
+ * log - String for log information, optional
+
+* Output Parameters authenticateResponse, with element
+
+ * auth - String, SessionID of authenticated application (See getSid() for format.)
+
+* Faults
+
+ * authenticationFault
+
createProject
-------------
Creates a project. Projects are roles with various sub-roles, i.e Leader, Administrator... Creates default roles with default permissions:
-============================== =============================================================================================================
-Role Right on Project
-============================== =============================================================================================================
+============================== =========
+Role Right on Project
+============================== =========
Projektleiter (project leader) delegate
-Administrator -none-
-Bearbeiter (editor) create
-Beobachter (observer) -none-
-============================== =============================================================================================================
+Administrator -none-
+Bearbeiter (editor) create
+Beobachter (observer) -none-
+============================== =========
These permissions can be adapted afterwards. For the rights on resources, see registerResource().
- * Input Parameters createProjectRequest, with elements
- * auth - String, SessionID of future project leader
- * log - String for log information, optional
- * name - String with name of project
- * description - String with description of project
- * file - String with URI of project file - currently unused, omit or leave empty and use setProjectFile( ) once the file resource has been created
- * Output Parameters createProjectResponse, with element
- * projectId - String with the newly assigned project ID, such as "TGPR123"
+* Input Parameters createProjectRequest, with elements
+
+ * auth - String, SessionID of future project leader
+ * log - String for log information, optional
+ * name - String with name of project
+ * description - String with description of project
+ * file - String with URI of project file - currently unused, omit or leave empty and use setProjectFile( ) once the file resource has been created
+
+* Output Parameters createProjectResponse, with element
+
+ * projectId - String with the newly assigned project ID, such as "TGPR123"
+
setProjectFile
--------------
Registers the URI of a TextGridObject to be the project file for project-specific settings. The URI must be registered at RBAC beforehand.
- * Input Parameters setProjectFileRequest, with elements
- * auth - String, SessionID of Project Leader
- * log - String for log information, optional
- * project - String with projectID
- * file - String with URI of project file
- * Output Parameters booleanResponse, with element
- * result - boolean, true if operation was successful, false otherwise
- * Faults
- * authenticationFault
+* Input Parameters setProjectFileRequest, with elements
+
+ * auth - String, SessionID of Project Leader
+ * log - String for log information, optional
+ * project - String with projectID
+ * file - String with URI of project file
+
+* Output Parameters booleanResponse, with element
+
+ * result - boolean, true if operation was successful, false otherwise
+
+* Faults
+
+ * authenticationFault
+
setName
-------
Supply user-specific information for display instead of the ePPN.
- * Input Parameters setNameRequest, with elements
- * auth - String, SessionID of User who wants to set their name
- * log - String for log information, optional
- * webAuthSecret - String that is known by the Web Authentication which will assure that the data are correct. If the secret is not given, the user entry will be marked as a volunteered one, where the users gave their details themselves.
- * name - String with User Name, preferredly in the form of "givenname surname"
- * mail - String with User's E-Mail address
- * organisation - String with Affiliation of the User
- * agreeSerach - Boolean telling whether the user agrees to be searchable by the getIDs function.
- * Output Parameters booleanResponse, with element
- * result - boolean, true if operation was successful, false otherwise
- * Faults
+* Input Parameters setNameRequest, with elements
+
+ * auth - String, SessionID of User who wants to set their name
+ * log - String for log information, optional
+ * webAuthSecret - String that is known by the Web Authentication which will assure that the data are correct. If the secret is not given, the user entry will be marked as a volunteered one, where the users gave their details themselves.
+ * name - String with User Name, preferredly in the form of "givenname surname"
+ * mail - String with User's E-Mail address
+ * organisation - String with Affiliation of the User
+ * agreeSerach - Boolean telling whether the user agrees to be searchable by the getIDs function.
+
+* Output Parameters booleanResponse, with element
+
+ * result - boolean, true if operation was successful, false otherwise
+
+* Faults
+
addMember
---------
Project leaders can assign users into specific roles. This still does not effect activation of the role in the user(s)' session(s).
- * Input Parameters addMemberRequest, with elements
- * auth - String, SessionID of project leader
- * log - String for log information, optional
- * username - String with ePPN of user to be added
- * role - String with full-qualified role name of the role the user is to be signed into. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer"
- * Output Parameters booleanResponse, with element
- * result - boolean, true if operation was successful, false otherwise
- * Faults
- * rbacFault
+* Input Parameters addMemberRequest, with elements
+
+ * auth - String, SessionID of project leader
+ * log - String for log information, optional
+ * username - String with ePPN of user to be added
+ * role - String with full-qualified role name of the role the user is to be signed into. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer"
+
+* Output Parameters booleanResponse, with element
+
+ * result - boolean, true if operation was successful, false otherwise
+
+* Faults
+
+ * rbacFault
+
deleteMember
------------
Project leaders can delete a role from a user. This still does not effect (de-)activation of the role in the user(s)' session(s).
- * Input Parameters deleteMemberRequest, with elements
- * auth - String, SessionID of project leader
- * log - String for log information, optional
- * username - String with ePPN of user to be signed off
- * role - String with full-qualified role name of the role the user is to be signed off. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer"
- * Output Parameters booleanResponse, with element
- * result - boolean, true if operation was successful, false otherwise
+* Input Parameters deleteMemberRequest, with elements
+
+ * auth - String, SessionID of project leader
+ * log - String for log information, optional
+ * username - String with ePPN of user to be signed off
+ * role - String with full-qualified role name of the role the user is to be signed off. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer"
+
+* Output Parameters booleanResponse, with element
+
+ * result - boolean, true if operation was successful, false otherwise
+
tgAddActiveRole
---------------
Activates a role for a session. NB, currently the login process activates all available roles of the user.
- * Input Parameters tgAddActiveRoleRequest, with elements
- * auth - String, SessionID of user
- * log - String for log information, optional
- * role - String with full-qualified role name of the role the user wants to activate. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer".
- * Output Parameters booleanResponse, with element
- * result - boolean, true if operation was successful, false otherwise
+* Input Parameters tgAddActiveRoleRequest, with elements
+
+ * auth - String, SessionID of user
+ * log - String for log information, optional
+ * role - String with full-qualified role name of the role the user wants to activate. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer".
+
+* Output Parameters booleanResponse, with element
+
+ * result - boolean, true if operation was successful, false otherwise
+
tgDropActiveRole
----------------
De-activates a role for a session.
- * Input Parameters tgDropActiveRoleRequest, with elements
- * auth - String, SessionID of user
- * log - String for log information, optional
- * role - String with full-qualified role name of the role the user wants to de-activate. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer".
- * Output Parameters booleanResponse, with element
- * result - boolean, true if operation was successful, false otherwise
+* Input Parameters tgDropActiveRoleRequest, with elements
+
+ * auth - String, SessionID of user
+ * log - String for log information, optional
+ * role - String with full-qualified role name of the role the user wants to de-activate. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer".
+
+* Output Parameters booleanResponse, with element
+
+ * result - boolean, true if operation was successful, false otherwise
+
tgGrantPermission
-----------------
Enables given operation for given role on given resource. Resource may be an URI of a TgObject, or a projectID. Users need delegate right on resource or project (i.e. be project leader).
- * Input Parameters tgGrantPermissionRequest, with elements
- * auth - String, SessionID of user
- * log - String for log information, optional
- * role - String with full-qualified role name of the role the user wants to grant a right. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer".
- * operation - String, operation to be granted, such as "read", "write".
- * resource - String, URI of TgObject, or projectID
- * Output Parameters booleanResponse, with element
- * result - boolean, true if operation was successful, false otherwise
- * Faults
- * authenticationFault
- * rbacFault
+* Input Parameters tgGrantPermissionRequest, with elements
+
+ * auth - String, SessionID of user
+ * log - String for log information, optional
+ * role - String with full-qualified role name of the role the user wants to grant a right. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer".
+ * operation - String, operation to be granted, such as "read", "write".
+ * resource - String, URI of TgObject, or projectID
+
+* Output Parameters booleanResponse, with element
+
+ * result - boolean, true if operation was successful, false otherwise
+
+* Faults
+
+ * authenticationFault
+ * rbacFault
+
tgRevokePermission
------------------
Disables this permission, see tgGrantPermission for limitations.
- * Input Parameters tgRevokePermissionRequest, with elements
- * auth - String, SessionID of user
- * log - String for log information, optional
- * role - String with full-qualified role name of the role the user wants to revoke a right. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer".
- * operation - String, operation to be granted, such as "read", "write".
- * resource - String, URI of TgObject, or projectID
- * Output Parameters booleanResponse, with element
- * result - boolean, true if operation was successful, false otherwise
- * Faults
- * authenticationFault
+* Input Parameters tgRevokePermissionRequest, with elements
+
+ * auth - String, SessionID of user
+ * log - String for log information, optional
+ * role - String with full-qualified role name of the role the user wants to revoke a right. The full-qualified role name has the form "Administrator,TGPR3,Projekt-Teilnehmer".
+ * operation - String, operation to be granted, such as "read", "write".
+ * resource - String, URI of TgObject, or projectID
+
+* Output Parameters booleanResponse, with element
+
+ * result - boolean, true if operation was successful, false otherwise
+
+* Faults
+
+ * authenticationFault
+
deactivateProject
-----------------
Hides a project. User must be project leader of the project to be deactivated. Hidden projects cannot be modified or read anymore (except published resources). However, information is preserved so that the project can be re-activated by manual modification of the database.
- * Input Parameters deactivateProjectRequest, with elements
- * auth - String, SessionID of user that wants publish
- * log - String for log information, optional
- * project - String, ProjectID
- * Output Parameters booleanResponse, with element
- * result - boolean, true if operation was successful, false otherwise
- * Faults
- * authenticationFault
+* Input Parameters deactivateProjectRequest, with elements
+
+ * auth - String, SessionID of user that wants publish
+ * log - String for log information, optional
+ * project - String, ProjectID
+
+* Output Parameters booleanResponse, with element
+
+ * result - boolean, true if operation was successful, false otherwise
+
+* Faults
+
+ * authenticationFault
+
reactivateProject
-----------------
Reactivate a hidden and deactivated project. The user must be the former project leader of the project to be able to reactivate it. All rights will be restored.
- * Input Parameters reactivateProjectRequest, with elements
- * auth - String, SessionID of user that wants publish
- * log - String for log information, optional
- * project - String, ProjectID
- * Output Parameters booleanResponse, with element
- * result - boolean, true if operation was successful, false otherwise
- * Faults
- * authenticationFault
+* Input Parameters reactivateProjectRequest, with elements
+
+ * auth - String, SessionID of user that wants publish
+ * log - String for log information, optional
+ * project - String, ProjectID
+
+* Output Parameters booleanResponse, with element
+
+ * result - boolean, true if operation was successful, false otherwise
+
+* Faults
+
+ * authenticationFault
+
deleteProject
-------------
Delete a project. User must be project leader of the project that is deleted. Before a project can be deleted there must not be any resources associated with the project. A deleted project cannot be restored.
- * Input Parameters deleteProjectRequest, with elements
- * auth - String, SessionID of user that wants publish
- * log - String for log information, optional
- * project - String, ProjectID
- * Output Parameters booleanResponse, with element
- * result - boolean, true if operation was successful, false otherwise
- * Faults
- * authenticationFault
- * notEmptyFault
+* Input Parameters deleteProjectRequest, with elements
+
+ * auth - String, SessionID of user that wants publish
+ * log - String for log information, optional
+ * project - String, ProjectID
+
+* Output Parameters booleanResponse, with element
+
+ * result - boolean, true if operation was successful, false otherwise
+
+* Faults
+
+ * authenticationFault
+ * notEmptyFault
diff --git a/docs/conf.py b/docs/conf.py
index e5a1220..a193632 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -110,7 +110,7 @@ todo_include_todos = True
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
-html_theme = 'default'
+html_theme = 'classic'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
diff --git a/docs/index.rst b/docs/index.rst
index 5d67896..bcdf756 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,15 +3,16 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
+
TG-auth*
========
-The tg-auth* system consists of two main components:
+The TG-auth* system consists of two main components:
-* openRBAC, a system to maintain, modify, and enforce authorization policies using the Role-Based Access Control framework. See http://www.openrbac.de/, however, the basic software has been heavily customized for use with TextGrid
+* openRBAC, a system to maintain, modify, and enforce authorization policies using the Role-Based Access Control framework. See http://www.openrbac.de/, however, the basic software has been heavily customized for use with TextGrid.
* WebAuthN, a system offering authentication functionalities, both direct using a community-managed user directory and the Shibboleth-based DFN-AAI. WebAuthN is embedded in TextGridLab offering a Login Screen and registers the user in RBAC.
-There are some minor components interacting with tg-auth* (now obsolete since the TextGrid and DARIAH Accounts has been merged… please use the DARIAH Self Service Portal):
+There are some minor components interacting with tg-auth* (now obsolete since the TextGrid and DARIAH Accounts has been merged… please use the `DARIAH Self Service Portal <https://auth.dariah.eu/cgi-bin/selfservice/ldapportal.pl>`_):
* PWchange, a Web application allowing for setting a new password in case the user knows their old one
* PWreset, a Web application that lets users set a new password in case they forgot their old one
@@ -20,8 +21,9 @@ There are some minor components interacting with tg-auth* (now obsolete since th
Technical Information
---------------------
-**Response**
+Response
+^^^^^^^^
* Implementation: PHP, consisting of
* openRBAC core: RBAC implementation backed up by an LDAP directory, e.g. openLDAP
@@ -39,71 +41,85 @@ Technical Information
* ou=sessions for the Session IDs that users have in the TextGridLab and the roles they activated in their sessions
-**WebAuthN**
+WebAuthN
+^^^^^^^^
+* Implementation: PHP
+
+ * Dual Login on the first page:
+
+ * direct authentication in the community LDAP server or via
+ * Shibboleth Login with DFN-AAI-Basic
+
+ * Both Login methods populate the Server variable $REMOTE_USER
+
+* In Login Mode, the following happens:
+
+ 1. authentication
+ 2. registration of a user session with activation of all available roles in RBAC
+ 3. check if user has filled out all required personal information and accepted the Terms of use
+ 4. exposure of the newly assigned Session ID for use in further activities with the TextGridLab and the TG-Utilities
+
+* In User Details mode (no authentication, just see and modify user's attributes), only 3. happens.
+* One WebAuthN installation with one community LDAP server can interact with multiple RBAC instances.
+* HTTP GET or POST arguments for TextGrid-WebAuth.php:
- * Implementation: PHP
- * Dual Login on the first page:
- * direct authentication in the community LDAP server or via
- * Shibboleth Login with DFN-AAI-Basic
- * Both Login methods populate the Server variable $REMOTE_USER
- * In Login Mode, the following happens:
- 1. authentication
- 2. registration of a user session with activation of all available roles in RBAC
- 3. check if user has filled out all required personal information and accepted the Terms of use
- 4. exposure of the newly assigned Session ID for use in further activities with the TextGridLab and the TG-Utilities
- * In User Details mode (no authentication, just see and modify user's attributes), only 3. happens.
- * One WebAuthN installation with one community LDAP server can interact with multiple RBAC instances.
- * HTTP GET or POST arguments for TextGrid-WebAuth.php:
- * authZinstance – string identifying the RBAC instance to be used. Always needed.
- * loginname and password – for authentication at community LDAP. Only in Login mode and with HTTP POST.
- * Sid – Session ID known from some earlier authentication. Necessary for User Details mode.
- * ePPN - User ID of the user. Necessary in User Details mode.
- * TextGrid-WebAuth.php is being called from WebAuthN2.php, which presents both the community login form and the Shibboleth Login Button.
- * For Shibboleth login, the Shibboleth Service Provider (Apache module) guarantees the provision of a correct User ID delivered from some home organisation.
+ * authZinstance – string identifying the RBAC instance to be used. Always needed.
+ * loginname and password – for authentication at community LDAP. Only in Login mode and with HTTP POST.
+ * Sid – Session ID known from some earlier authentication. Necessary for User Details mode.
+ * ePPN - User ID of the user. Necessary in User Details mode.
+* TextGrid-WebAuth.php is being called from WebAuthN2.php, which presents both the community login form and the Shibboleth Login Button.
+* For Shibboleth login, the Shibboleth Service Provider (Apache module) guarantees the provision of a correct User ID delivered from some home organisation.
-**PWchange**
- * PHP Web application
- * Authenticates and changes passwords against an LDAP direcory (community LDAP server)
- * Source currently not in SVN, but available upon request
+PWchange
+^^^^^^^^
+* PHP Web application
+* Authenticates and changes passwords against an LDAP direcory (community LDAP server)
+* Source currently not in SVN, but available upon request
-**PWreset**
- * Perl Web application
- * sends out links for verification of the user's email adress
- * must be used with the system's Web browser, not the TextGridLab-internal one, because of the use of cookies to remember the user
+PWreset
+^^^^^^^
+* Perl Web application
+* sends out links for verification of the user's email adress
+* must be used with the system's Web browser, not the TextGridLab-internal one, because of the use of cookies to remember the user
URLs
----
-**Repository**
- * Current development is is in GIT repository of GWDG Chili, https://projects.gwdg.de/projects/tg-auth
- * Old Subversion repositories as of November 2013 can be found here:
- * openRBAC: https://svn.projects.gwdg.de/svn/textgrid-svn-archive/trunk/middleware/tgauth/info.textgrid.middleware.tgauth.rbac
- * WebAuthN: https://svn.projects.gwdg.de/svn/textgrid-svn-archive/trunk/middleware/tgauth/info.textgrid.middleware.tgauth.webauth
- * PWreset: https://svn.projects.gwdg.de/svn/textgrid-svn-archive/trunk/middleware/tgauth/info.textgrid.middleware.tgauth.passwordReset
+Repository
+^^^^^^^^^^
+* Current development is is in GIT repository of GWDG Chili, https://projects.gwdg.de/projects/tg-auth
+* Old Subversion repositories as of November 2013 can be found here:
-**WSDL**
+ * openRBAC: https://svn.projects.gwdg.de/svn/textgrid-svn-archive/trunk/middleware/tgauth/info.textgrid.middleware.tgauth.rbac
+ * WebAuthN: https://svn.projects.gwdg.de/svn/textgrid-svn-archive/trunk/middleware/tgauth/info.textgrid.middleware.tgauth.webauth
+ * PWreset: https://svn.projects.gwdg.de/svn/textgrid-svn-archive/trunk/middleware/tgauth/info.textgrid.middleware.tgauth.passwordReset
+
+WSDL
+^^^^
OpenRBAC SOAP WSDL locations on the productive TextGridRep TG-auth* server:
- * Most relevant for Lab/User interaction: https://textgridlab.org/1.0/tgauth/wsdl/tgextra.wsdl >> Documentation of TGextra WSDL Methods
- * Relevant for Server access: https://textgridlab.org/1.0/tgauth/wsdl/tgextra-crud.wsdl >> Documentation of TGextra-crud Methods (TODO)
- * Administrative functions:
- * https://textgridlab.org/1.0/tgauth/wsdl/tgadministration.wsdl
- * https://textgridlab.org/1.0/tgauth/wsdl/tgreview.wsdl
- * https://textgridlab.org/1.0/tgauth/wsdl/tgsystem.wsdl
+* Most relevant for Lab/User interaction: https://textgridlab.org/1.0/tgauth/wsdl/tgextra.wsdl >> Documentation of TGextra WSDL Methods
+* Relevant for Server access: https://textgridlab.org/1.0/tgauth/wsdl/tgextra-crud.wsdl >> Documentation of TGextra-crud Methods (TODO)
+* Administrative functions:
+
+ * https://textgridlab.org/1.0/tgauth/wsdl/tgadministration.wsdl
+ * https://textgridlab.org/1.0/tgauth/wsdl/tgreview.wsdl
+ * https://textgridlab.org/1.0/tgauth/wsdl/tgsystem.wsdl
-**Web applications**
+Web applications
+^^^^^^^^^^^^^^^^
Endpoints for the productive TextGridRep:
- * WebAuthN (Login mode): https://textgridlab.org/1.0/WebAuthN/WebAuthN2.php?authZinstance=textgrid-esx1.gwdg.de
- * WebAuthN (User Details mode): https://textgridlab.org/1.0/WebAuthN/TextGrid-WebAuth.php?authZinstance=textgrid-esx1.gwdg.de (append "&Sid=XXXX&ePPN=YYY@ZZZ", see above)
- * PWchange: https://textgridlab.org/1.0/PWchange/index.php
- * PWreset: https://textgridlab.org/1.0/pwReset.pl
+* WebAuthN (Login mode): https://textgridlab.org/1.0/WebAuthN/WebAuthN2.php?authZinstance=textgrid-esx1.gwdg.de
+* WebAuthN (User Details mode): https://textgridlab.org/1.0/WebAuthN/TextGrid-WebAuth.php?authZinstance=textgrid-esx1.gwdg.de (append "&Sid=XXXX&ePPN=YYY@ZZZ", see above)
+* PWchange: https://textgridlab.org/1.0/PWchange/index.php
+* PWreset: https://textgridlab.org/1.0/pwReset.pl
API Documentation
@@ -115,9 +131,16 @@ API Documentation
api/tg-authApi.rst
+Sources
+-------
+
+See tgauth_sources_
+
+
License
-------
See LICENCE_
.. _LICENCE: https://projects.gwdg.de/projects/tg-auth/repository/revisions/master/raw/LICENSE.txt
+.. _tgauth_sources: https://projects.gwdg.de/projects/tg-auth/repository
--
GitLab