source: trunk/ndg_oauth/README.txt @ 8030

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg-security/trunk/ndg_oauth/README.txt
Revision 8030, 13.9 KB checked in by rwilkinson, 7 years ago (diff)

Reorganised into ndg.oauth.client and ndg.oauth.server package
structures. Removed development test application and references to
Pylons and other unused packages.

Line 
1Installation of NDG OAuth 2.0 Server Providing MyProxy Certificates as Access Tokens
2====================================================================================
3There are three primary components required:
4o MyProxy server, installed as part of the Globus Toolkit. This acts as a certificate authority for the certificates issued as access tokens.
5o OAuth server - This acts as a MyProxy client to create certificates for authenticated users. It also allows the user to determine whether a given OAuth client should be authorised.
6o OAuth client - This requests MyProxy certificate access tokens from the OAuth server and makes them available to other applications in a Python WSGI stack.
7
8The client contains a test WSGI application that simply displays the retrieved certificate.
9
10These instructions are for OpenSUSE 11.2. Development was with Python 2.6.2.
11
12The NDG OAuth source code is available from the Subversion repository at http://proj.badc.rl.ac.uk/svn/ndg-security/trunk/ndg_oauth.
13
14
15Prerequisites
16=============
17The following should be installed:
18  Apache2 server
19  Apache2 mod_wsgi
20  Python
21  pam-devel
22
23
24Globus Toolkit
25==============
26Install the Globus Toolkit following the instructions at this location (or the equivalent for the current release):
27http://www.globus.org/toolkit/docs/5.0/5.0.4/admin/install/#gtadmin
28
29Configure SimpleCA following:
30http://www.globus.org/toolkit/docs/5.0/5.0.4/admin/install/#gtadmin-simpleca
31
32Following these instructions:
33Create a host certificate.
34Create grid-mapfile with at least one user:
35grid-mapfile-add-entry -dn <DN> -ln <login username>
36in which the DN is the distinguished name to be put in certificates created for the specified username.
37
38Configure MyProxy following:
39http://www.globus.org/toolkit/docs/5.0/5.0.4/security/myproxy/admin/
40
41Configure the $GLOBUS_LOCATION/etc/myproxy-server.config file. The relevant settings are of the following form (modify file locations as necessary):
42
43certificate_issuer_cert /home/globus/.globus/simpleCA/cacert.pem
44certificate_issuer_key /home/globus/.globus/simpleCA/private/cakey.pem
45certificate_issuer_key_passphrase "changeit"
46certificate_serialfile /home/globus/.globus/simpleCA/serial
47certificate_out_dir /home/globus/.globus/simpleCA/newcerts
48certificate_mapfile /etc/grid-security/grid-mapfile
49cert_dir /etc/grid-security/certificates
50pam  "sufficient"
51pam_id "myproxy"
52
53This assumes that initial MyProxy testing will be performed using operating system user accounts and the standard PAM login modules. This can be omitted and pam_credential_translation used instead (see the next section).
54
55Create /etc/pam.d/myproxy
56#%PAM-1.0
57auth     requisite      pam_nologin.so
58auth     include        common-auth
59account  include        common-account
60session  required       pam_loginuid.so
61
62
63In /etc/services add (from $GLOBUS_LOCATION/share/myproxy/etc.services.modifications):
64myproxy-server  7512/tcp    # Myproxy server
65
66Create a xinetd.d myproxy configuration file:
67Copy $GLOBUS_LOCATION/share/myproxy/etc.xinetd.myproxy to /etc/xinetd.d/myproxy
68Check this file - options to set locations include:
69  server       = /usr/local/globus-5.0.4-oauth/sbin/myproxy-server
70  server_args  = -c /usr/local/globus-5.0.4-oauth/etc/myproxy-server.config
71  env          = GLOBUS_LOCATION=/usr/local/globus-5.0.4-oauth LD_LIBRARY_PATH=/usr/local/globus-5.0.4-oauth/lib
72
73Ensure that the files referenced by myproxy-server.config can be read by the user configured to run the MyProxy server.
74
75Update the xinetd configuration using "kill -HUP <xinetd PID>" or "service xinetd restart".
76
77
78At this point it should be possible to use the online CA to via
79myproxyclient logon -b -T -s <host> -p <port> -l <username> -C <trusted certificate dir.> -o <output credential file>
80
81If the -C option is omitted, an appropriate default will be used (e.g., $HOME/.globus/certificates).
82
83
84A host certificate/key pair is needed for the Apache server - this could be created using SimpleCA as follows, if a certificate from another source is not available:
85Create a host credential file with a CN equal to the fully qualified host name following the procedure using grid-cert-request described in the SimpleCA configuration instructions referred to above except use the following options for grid-cert-request (to avoid the certificate CN including the prefix "host/"):
86grid-cert-request -nopw -dir . -cn <fully qualified host name>
87
88Create a single file with the certificate and private key:
89cat usercert.pem userkey.pem > host.pem
90
91
92pam_credential_translation configuration
93========================================
94Ensure that the pam-devel package is installed.
95With Subversion, get http://proj.badc.rl.ac.uk/svn/ndg-security/trunk/MashMyData/pam_credential_translation
96
97On OpenSUSE is was found necessary to add to pam_credential_translation.c the following function:
98
99PAM_EXTERN int pam_sm_acct_mgmt(pam_handle_t *pam_h,
100                                int flags,
101                                int argc,
102                                const char **argv)
103{
104    return PAM_SUCCESS;
105}
106
107Execute make.
108Put the created pam_credential_translation.so in /lib64/security
109Check that file ownership and permissions are the same as for the other SOs in the directory.
110
111Create the file
112/etc/pam.d/myproxy-pam-credential-translation
113The content should be of the form:
114
115#%PAM-1.0
116auth     required       pam_credential_translation.so  sha256passwd=<sha256 hash>
117account  required       pam_credential_translation.so
118
119<sha256 hash> is the SHA256 hash of the global password to be used by the MyProxy client to obtain certificates for the OAuth server. It can be found for a chosen password using:
120echo -n <password> | sha256sum
121
122To configure MyProxy to use this, set in $GLOBUS_LOCATION/etc/myproxy-server.config:
123
124pam_id "myproxy-pam-credential-translation"
125
126
127NDG OAuth Client installation
128=============================
129The NDG OAuth client egg is built by moving to the ndg_oauth/client directory in the source tree and running:
130python setup.py bdist_egg
131
132
133Logged in as a suitable user, install ndgoauthclient as follows:
134
135Create a suitable installation directory and move to it, e.g.:
136mkdir ~/ndgoauthclient
137cd ~/ndgoauthclient
138
139Get the ndgoauthclient egg and the following configuration files:
140  buildout.cfg
141  development.ini
142
143Update in buildout.cfg:
144find-links = <location of ndgoauthclient egg>
145
146Build using the commands:
147easy_install zc.buildout
148buildout init
149wget http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py
150python bootstrap.py
151bin/buildout
152
153This should result in the creation of a file parts/ndgoauthclient_wsgi/wsgi and the referenced eggs being placed in the eggs subdirectory.
154
155Obtain a PEM encoded x509 certificate and key to be used by the client to authenticate itself to the OAuth server. The trusted CA certificate(s) needed to verify this must be present in the location configured for Apache set using the SSLCACertificatePath directive. This is in a virtual host .conf file in /etc/apache2/vhosts.d/ for the default Apache configuration.
156
157Create a ndgoauthclient configuration file based on test_app.ini. The [server:main] section can be ignored when running under Apache. Set values for:
158
159oauth2.client_cert = location of certificate file
160oauth2.client_key = location of key file
161oauth2.ca_dir = path of directory containing trusted CA certificates
162                This should include the certificate(s) needed to verify the host certificate used by the Apache server.
163oauth2.client_id = unique ID of the client (an arbitrary string)
164oauth2.authorization_endpoint=<base URL of OAuth server>/oauth/authorize
165oauth2.access_token_endpoint=<base URL of OAuth server>/oauth/access_token
166
167In a production environment include:
168set debug = false
169
170Note that the directories specified by the following parameters must be writable by the user as which the OAuth client runs:
171  beaker.cache.data_dir
172  beaker.session.data_dir
173
174
175Update the buildout.cfg file to set the .ini file location with the config-file parameter.
176
177
178NDG OAuth Server installation
179=============================
180The NDG OAuth server egg is built by moving to the ndg_oauth/server directory in the source tree and running:
181python setup.py bdist_egg
182
183
184Logged in as a suitable user, install ndgoauthserver as follows:
185
186Create a suitable installation directory and move to it, e.g.:
187mkdir ~/ndgoauthserver
188cd ~/ndgoauthserver
189
190Get the ndgoauthserver egg and the following configuration files:
191  buildout.cfg
192  development.ini
193  client_register.ini
194  repoze_who.ini
195
196Update in buildout.cfg:
197find-links = <location of ndgoauthserver egg>
198
199Build using the commands:
200easy_install zc.buildout
201buildout init
202wget http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py
203python bootstrap.py
204bin/buildout
205
206This should result in the creation of a file parts/ndgoauthserver_wsgi/wsgi and the referenced eggs being placed in the eggs subdirectory.
207
208
209Create a ndgoauthserver configuration file based on development.ini. The [server:main] section can be ignored when running under Apache. Set values for:
210myproxy.client.hostname = host on which MyProxy server is running
211myproxy.client.port = port on which MyProxy server is running if not the default value of 7512
212myproxy.client.caCertDir = full path of directory containing certificates of trusted certificate authorities
213oauth2server.myproxy_global_password = global password set for myproxy-pam-credential-translation PAM module
214
215In a production environment include:
216set debug = false
217
218Note that the directories specified by the following parameters must be writable by the user as which the OAuth client runs:
219  beaker.cache.data_dir
220  beaker.session.data_dir
221  oauth2server.cache.accesstokenregister.data_dir
222  oauth2server.cache.authorizationgrantregister.data_dir
223
224Update the buildout.cfg file to set the .ini file location with the config-file parameter.
225
226
227Copy ndgoauthserver/templates/auth_client_form.html to a suitable location and set
228oauth2authorization.client_authorization_form=<path>/auth_client_form.html
229
230
231Create a password file:
232htpasswd2 -c passwd <username>
233Ensure that its location is as set in repoze_who.ini.
234Add further users using:
235htpasswd2 passwd <username>
236
237
238Each OAuth client needs a x509 certificate with a different distinguished name (DN), since when using certificate authentication of the OAuth client to the server the DN is used to identify the client. (As described above, the client certificates must be issued by CAs trusted by Apache.) The client details are set in the server's client_register.ini file, which is of the following form:
239
240[DEFAULT]
241
242[client_register]
243# Registered clients
244clients=test1,test2
245
246[client:test1]
247name=test1
248id=11
249type=confidential
250redirect_uris=http://host.inst.ac.uk:5001/oauth2/oauth_redirect
251authentication_data=/O=inst/OU=simpleCA-host.inst.ac.uk/OU=inst.ac.uk/CN=test1.client
252
253[client:test2]
254...
255
256The parameters have the following meanings:
257  name = name of client displayed to user when asking for user authorisation for the client
258  id = client ID set as the client configuration file value of oauth2.client_id
259  redirect_uris = <OAuth client application base URL>/oauth2/oauth_redirect
260                - a comma separated list of URLs to which the OAuth server should permit redirection back to the client.
261  authentication_data = Distinguished name contained in the client certificate set as the client configuration file value of oauth2.client_cert
262
263For the test application, create one client entry.
264
265
266Apache
267======
268The OAuth server should be configured within a SSL container.
269
270    <Directory "/home/oauthserver/ndgoauthserver/parts/ndgoauthserver_wsgi">
271        SSLVerifyClient optional_no_ca
272        SSLVerifyDepth  10
273        SSLOptions +StdEnvVars +ExportCertData
274
275        # Pass the Authorization header to the WSGI middleware/application.
276        WSGIPassAuthorization On
277
278        Order allow,deny
279        Allow from all
280    </Directory>
281
282    WSGIDaemonProcess oauth2-server processes=2 threads=15 display-name=%{GROUP} user=oauthserver group=oasgroup
283    WSGIProcessGroup oauth2-server
284
285    # OAuth 2.0 authorization server
286    WSGIScriptAlias /oas /home/oauthserver/ndgoauthserver/parts/ndgoauthserver_wsgi/wsgi
287
288
289The OAuth client may be configured without SSL.
290
291    <Directory "/home/rwilkinson_local/dev/ndgoauthclient_bo/parts/ndgoauthclient_wsgi">
292       Order allow,deny
293       Allow from all
294    </Directory>
295
296    WSGIDaemonProcess oauth2-client processes=2 threads=15 display-name=%{GROUP} user=oauthclient group=oacgroup
297    WSGIProcessGroup oauth2-client
298
299    WSGIScriptAlias /oac /home/oauthclient/ndgoauthclient/parts/ndgoauthclient_wsgi/wsgi
300
301
302Summary of Certificates and Trusted CAs
303=======================================
304There are four sets of certificate and trusted CA relationships, all of which must be configured correctly for the system to work:
305
3061) Apache host certificate / OAuth2 client trusted CAs
307Certificate location:
308Apache parameter: SSLCertificateFile
309Key location:
310Apache parameter: SSLCertificateKeyFile
311
312CA configuration:
313OAuth2 client parameter: oauth2.ca_dir
314
3152) OAuth2 client certificate / Apache trusted CAs
316Certificate location:
317OAuth2 client parameter: oauth2.client_cert
318Key location:
319OAuth2 client parameter: oauth2.client_key
320
321CA configuration:
322Apache parameter: SSLCACertificatePath
323
3243) MyProxy server certificate / MyProxyClient trusted CAs
325Certificate location:
326By default: /etc/grid-security/hostcert.pem
327Overide by setting the environment variable X509_USER_CERT in the /etc/xinetd.d/myproxy
328Key location:
329By default: /etc/grid-security/hostkey.pem
330Overide by setting the environment variable X509_USER_KEY in the /etc/xinetd.d/myproxy
331
332CA configuration:
333myproxy.client.caCertDir
334
3354) MyProxy Server CA certificate / service accepting certificates from MyProxy Online CA
336Certificate and key location:
337The OAuth access token contains the certificate and key
338
339CA configuration:
340Dependent on service. The CA certificate and key are configured with:
341Certificate location:
342myproxy-server.config parameter: certificate_issuer_cert
343Key location:
344myproxy-server.config parameter: certificate_issuer_key
345The certificates downloaded using "myproxyclient logon -T" should include the required trusted certificates.
Note: See TracBrowser for help on using the repository browser.