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

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

Adjust security info and provide info on current user base.

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/wsse-server.crt
86openid.relyingparty.priKeyFilePath = %(testConfigDir)s/pki/wsse-server.key
87openid.relyingparty.priKeyPwd =
88openid.relyingparty.caCertDirPath = %(testConfigDir)s/ca
89
904) Ensure the crt and key files are available in the config directory:
91
92ndg/security/test/config/pki
93
94and the cacert.pem is in:
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
178NB, the current system contains the following users (user ID, openID url, roles):
179
180cbyrom         https://ndg3beta.badc.rl.ac.uk/openid/Calum.Byrom        urn:badc:security:authz:1.0:attr:oai_editor:admin
181aharwood     https://ndg3beta.badc.rl.ac.uk/openid/Andrew.Harwood  urn:badc:security:authz:1.0:attr:oai_editor:badc
182rlowry          https://ndg3beta.badc.rl.ac.uk/openid/Roy.Lowry            urn:badc:security:authz:1.0:attr:oai_editor:bodc
183
184- their login passwords are available from Phil Kershaw.
185
186
187Using the Editor
188------------------
189A help guide is available from the web app - click on the link, 'help' for detailed
190instructions on how to use.
191
192
193Tests
194------------
195A suite of unit tests is available under oai_info_editor/tests - the file, nostTests.py,
196in this directory, can be used to discover and run all the tests via the python nose module -
197just run it as a python app.
198
199
200 Further Notes
201-----------------
202i) The editor uses the OAIBatch codebase to do the ingest - using the same
203script, oai_document_ingester, that is used by the discovery service
204ii) NB, this work replaces the use of the jOAI harvester web app.  Although the jOAI codebase has
205an exposed java API to complete harvesting (which is used by this editor), in a consistent manner
206to the web app, it doesn't have any public API to curate the data contained by the web app.  Since
207the only additional functionality offered by the jOAI system was increased logging, and since this
208wasn't being used anyway, it was considered simpler just to write a new system to allow
209curation of provider info.
Note: See TracBrowser for help on using the repository browser.