source: TI01-discovery/trunk/OAIInfoEditor/README.txt @ 5470

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI01-discovery/trunk/OAIInfoEditor/README.txt@5470
Revision 5470, 7.5 KB checked in by cbyrom, 10 years ago (diff)

Update documentation, adding a section on how to set up the security
+ tidy up the codebase, moving configuration files to the top level
and deleting any app specific data + fix a few links to properly
include the admin parameter + fix an issue with the admin redirection.

Line 
1Prerequisites
2==================
3The following should be installed to run the OAI Info editor:
41. Python2.5 - see http://www.python.org/download/
52. Pylons - see http://docs.pythonweb.org/display/pylonsdocs/Installing+Pylons
63. Genshi - see http://genshi.edgewall.org/wiki/Download
74. OAIBatch - see http://proj.badc.rl.ac.uk/ndg/browser/TI01-discovery/branches/ingestAutomation-upgrade [or main trunk when things have been properly merged]
85. ndgCommon - see http://proj.badc.rl.ac.uk/ndg/browser/ndgCommon
9
10NB, it is easier to setup the prereqs by using easy_install - http://peak.telecommunity.com/DevCenter/EasyInstall
11- then you can just run, easy_install pylons, easy_install genshi, etc.
12
13Installation and Setup
14======================
15Once the prereqs are installed and the codebase is extracted to a local dir:
16
17i) Copy and adjust the content of the following config files, from the base directory to the
18directory to run the app from (taken to be 'oai_info_editor' here), as follows:
19
20development.ini (or secured.ini if using secured version - see security section, below)
21- adjust the host and port settings appropriately
22- turn debug on/off
23- adjust logging level of server output (adjust the logger_root settings)
24
25editor.config
26adjust:
27
28[SERVERS]
29- server - NB, this should match the host and port settings in the development.ini file
30- mailserver - SMTP server for sending mails
31- proxyServer - proxy server to use, if required
32
33[DATA_STORE]
34- appDataFileName - name of the data file used to store the provider info in - NB, this
35is suffixed with '_provider_info_data.xml'
36- appDataFileDir - the directory, relative to the run directory, to store the
37change history data and any parser data files
38- backupFileDir - the directory, relative to the run directory, to store backups of
39the data files in the appDataFileDir
40- harvestDir - the directory to harvest OAI documents to
41
42policy.xml - see the security section for configuring this
43
44
45ii) Add a config file for the postgres DB used by the discovery service; this is required
46when documents are harvested via the editor - since once the harvest is complete, the
47data is automatically ingested into the discovery service.  The file should be in
48the oai_info_editor directory and be called, 'ingest.config'.  The contents should
49be of the format:
50
51databaseName hostName userName password portNumber
52
53(NB, portNumber is optional)
54
55iii) From the oai_info_editor directory, run:
56
57paster serve --reload development.ini
58
59
60Running with security
61----------------------------
62The application is configured to work with the openid based security system available
63with the ndg.security package.  To set it up with this, complete the following:
64
651) Get Phil Kershaw to generate specific security certificate and key for your app
66- these will be refered to, below as app-security.crt and app-security.key, respectively.
67Also get the server encryption certification - we will call this cacert.pem, below.
68 
692) Install the various ndg.security eggs - this can be done, e.g. via:
70
71sudo easy_install -Uf http://ndg.nerc.ac.uk/dist/ ndg_security ndg_security_common ndg_security_server ndg_security_test
72
733) In the installed eggs, go to:
74
75ndg/security/test/integration/authz
76
77and edit the securityservices.ini file as follows:
78
79a) Set the following line (or choose an alternative openid provider):
80
81openid.relyingparty.signinInterface.initialOpenID = https://ndg3beta.badc.rl.ac.uk/openid
82
83b) Set the following:
84
85openid.relyingparty.certFilePath = %(testConfigDir)s/pki/app-security.crt
86openid.relyingparty.priKeyFilePath = %(testConfigDir)s/pki/app-security.key
87openid.relyingparty.priKeyPwd =
88openid.relyingparty.caCertDirPath = %(testConfigDir)s/ca
89
904) Copy the certificate and key from (1) into
91
92ndg/security/test/config/pki
93
94and copy cacert.pem into
95
96ndg/security/test/config/ca
97
98- also, adjust the port number and hostname, if required; this is where this security
99service will be visible from.
100
1015) Start the securityservice app by running:
102
103ndg/security/test/integration/authz/securityservicesapp.py
104
105- this should start the security server - with the logging saying something like:
106
107serving on 0.0.0.0:7443 view at http://127.0.0.1:7443
108
109- if not, diagnose and fix the problems (most likely install issues).
110
1116) Adjust the content of OAIInfoEditor/secured.ini as follows:
112
113a)
114authN.redirectURI = http://localhost:7443/verify
115- this should point to the service set up to run in (5)
116
117b)
118pip.caCertFilePathList=%(here)s/ca/cacert.pem
119- this should point at the local version of cacert.pem - i.e. ensure there is a copy
120of this in the local app ca dir
121
122c)
123pip.wssecurity.signingCertFilePath=%(here)s/pki/app-security.crt
124pip.wssecurity.signingPriKeyFilePath=%(here)s/pki/app-security.key
125pip.wssecurity.caCertFilePathList=%(here)s/ca/cacert.pem
126- again, ensure there are copies of the .crt and .key files in the local pki directory
127
128d)
129pip.wssecurity.addTimestamp=False
130- this avoids a current issue with ntp time synchronisation
131
1327) The app should then be able to be started in secure mode via:
133
134paster serve --reload secured.ini
135
136
137Adding new users + enforcing security
138-------------------------------------------
139Security is enforced by the policy.xml file; this sets what access is required to
140view what URLs.  When a new provider user is added to the system, the template in the
141policy file needs to be updated.  This should look something like:
142
143    <Target>
144        <URIPattern>^/.*badc$</URIPattern>
145        <Attributes>
146            <Attribute>urn:badc:security:authz:1.0:attr:oai_editor:badc</Attribute>
147        </Attributes>
148        <AttributeAuthority>
149            <uri>https://ndg3beta.badc.rl.ac.uk/AttributeAuthority</uri>
150        </AttributeAuthority>
151    </Target>
152
153
154- in this case, any URL which ends in 'badc' requires the user to have the 'badc' role
155in order to view.  Every new provider in the system (e.g. by an admin user) will need
156a new target added to enforce the required security.  Phil Kershaw can then set up
157any required users for this provider.
158
159In the case of admin users, all admin functions are accessed by appending '?admin=1'
160parameter to the URL - and this is handled by the target:
161
162    <Target>
163        <URIPattern>^/.*?admin=1$</URIPattern>
164        <Attributes>
165            <Attribute>urn:badc:security:authz:1.0:attr:oai_editor:admin</Attribute>
166        </Attributes>
167        <AttributeAuthority>
168            <uri>https://ndg3beta.badc.rl.ac.uk/AttributeAuthority</uri>
169        </AttributeAuthority>
170    </Target>
171
172- this keeps things simple.  New admin users just need to have the role,
173
174urn:badc:security:authz:1.0:attr:oai_editor:admin
175
176added.
177
178
179Using the Editor
180------------------
181A help guide is available from the web app - click on the link, 'help' for detailed
182instructions on how to use.
183
184
185Tests
186------------
187A suite of unit tests is available under oai_info_editor/tests - the file, nostTests.py,
188in this directory, can be used to discover and run all the tests via the python nose module -
189just run it as a python app.
190
191
192 Further Notes
193-----------------
194i) The editor uses the OAIBatch codebase to do the ingest - using the same
195script, oai_document_ingester, that is used by the discovery service
196ii) NB, this work replaces the use of the jOAI harvester web app.  Although the jOAI codebase has
197an exposed java API to complete harvesting (which is used by this editor), in a consistent manner
198to the web app, it doesn't have any public API to curate the data contained by the web app.  Since
199the only additional functionality offered by the jOAI system was increased logging, and since this
200wasn't being used anyway, it was considered simpler just to write a new system to allow
201curation of provider info.
Note: See TracBrowser for help on using the repository browser.