This enhancement will allow authentication to Koha via client side certificates. This can be achieved with apache2 + mod_ssl And the SSLVerifyClient Require directive (Plus a lot more configuration) Configuration for this as part of the install may fall outside the scope of this enhancement, this will be more concerned with dealing with a user that has been authenticated by apache in Koha
Created attachment 4452 [details] [review] Bug 6296: allow users to be authenticated by SSL client certs This adds a new syspref: AllowPKIAuth. It can have one of three states: * None * Common Name * emailAddress If a) this is set to something that's not "None", and b) the webserver is passing SSL client cert details on to Koha, then the relevant field in the user's certificate will be matched up against the field in the database and they will be automatically logged in. This is used as a secure form of single sign-on in some organisations. The "Common Name" field is matched up against the userid, while "emailAddress" is matched against the primary email. This is an example of what might go in the Apache configuration for the virtual host: SSLVerifyClient require SSLVerifyDepth 2 SSLCACertificateFile /etc/apache2/ssl/test/ca.crt SSLOptions +StdEnvVars The last line ensures that the required details are passed to Koha.
Some caveats: * When this is first set up, it pays to clear all session cookies relating to the koha host, especially on the OPAC, or it may look like it's not working. * When using the email address verification, it is still required that users have a username defined, as the login process expects it. Don't know what'll happen if they don't, most likely it'll explode.
Created attachment 4773 [details] [review] Bug 6296: allow users to be authenticated by SSL client certs This adds a new syspref: AllowPKIAuth. It can have one of three states: * None * Common Name * emailAddress If a) this is set to something that's not "None", and b) the webserver is passing SSL client cert details on to Koha, then the relevant field in the user's certificate will be matched up against the field in the database and they will be automatically logged in. This is used as a secure form of single sign-on in some organisations. The "Common Name" field is matched up against the userid, while "emailAddress" is matched against the primary email. This is an example of what might go in the Apache configuration for the virtual host: SSLVerifyClient require SSLVerifyDepth 2 SSLCACertificateFile /etc/apache2/ssl/test/ca.crt SSLOptions +StdEnvVars The last line ensures that the required details are passed to Koha. Signed-off-by: Chris Cormack <chrisc@catalyst.net.nz>
Working in fine in production, signing off
QA comment I won't do anything on this patch, as I don't know how SSL works, I can't have a usefull comment. Ian, hoping you'll do better...
Patch no longer applies after followup to 5995 (return values of checkpw have been altered). Also, system preferences have been condensed from their many language files. Some additional comments: Uses "common name" instead of 'userid' in the system preferences editor; would be much clearer to the library if userid was somehow noted or referenced, so they know how the login works. The sample Apache configs should be added to etc/koha-httpd.conf, as comments. I'm not clear why the return values of checkauth are no longer being captured in many of touched scripts. Could you explain why this is a desirable global change (as it happens in this patch regardless of AllowPKIAuth's settings.
Just addressing the last point, the value was never checked. It was stuck into a variable and that variable was never again referenced. I assume it was copy-paste code, and it was fairly misleading. Because I changed how it behaved, I had to check every instance checkauth was called and make sure it was doing the new right thing. For ones that never used the return value, I cleaned them up.)
Created attachment 5971 [details] [review] Bug 6296: allow users to be authenticated by SSL client certs This adds a new syspref: AllowPKIAuth. It can have one of three states: * None * Common Name * emailAddress If a) this is set to something that's not "None", and b) the webserver is passing SSL client cert details on to Koha, then the relevant field in the user's certificate will be matched up against the field in the database and they will be automatically logged in. This is used as a secure form of single sign-on in some organisations. The "Common Name" field is matched up against the userid, while "emailAddress" is matched against the primary email. This is an example of what might go in the Apache configuration for the virtual host: SSLVerifyClient require SSLVerifyDepth 2 SSLCACertificateFile /etc/apache2/ssl/test/ca.crt SSLOptions +StdEnvVars The last line ensures that the required details are passed to Koha.
New version that applies against master and has the suggested changes applied. I accidentally dropped the sign-off from Chris though, hope that doesn't matter.
Updating version : This ENH could be in Koha 3.8
Bug versionned for master. entries will be made against rel_3_8 once the patch has been applied (see thread about that on koha-devel yesterday)
Please resolve whitespace issues and rebase (syspref and updatedatabase). Applying: Bug 6296: allow users to be authenticated by SSL client certs /usr/share/koha/testclone/.git/rebase-apply/patch:29: space before tab in indent. my $borrower = GetMember(borrowernumber => $user); /usr/share/koha/testclone/.git/rebase-apply/patch:30: space before tab in indent. if ($borrower) { /usr/share/koha/testclone/.git/rebase-apply/patch:31: space before tab in indent. $borrowernumber = $user; /usr/share/koha/testclone/.git/rebase-apply/patch:136: trailing whitespace. SELECT borrowernumber, firstname, surname, flags, borrowers.branchcode, /usr/share/koha/testclone/.git/rebase-apply/patch:137: trailing whitespace. branches.branchname as branchname, warning: C4/Auth.pm has type 100755, expected 100644 error: patch failed: installer/data/mysql/sysprefs.sql:327 error: installer/data/mysql/sysprefs.sql: patch does not apply error: patch failed: installer/data/mysql/updatedatabase.pl:4523 error: installer/data/mysql/updatedatabase.pl: patch does not apply Using index info to reconstruct a base tree... <stdin>:29: space before tab in indent. my $borrower = GetMember(borrowernumber => $user); <stdin>:30: space before tab in indent. if ($borrower) { <stdin>:31: space before tab in indent. $borrowernumber = $user; <stdin>:136: trailing whitespace. SELECT borrowernumber, firstname, surname, flags, borrowers.branchcode, <stdin>:137: trailing whitespace. branches.branchname as branchname, warning: squelched 3 whitespace errors warning: 8 lines add whitespace errors. Falling back to patching base and 3-way merge... Auto-merged C4/Auth.pm Auto-merged C4/Members.pm Auto-merged installer/data/mysql/sysprefs.sql CONFLICT (content): Merge conflict in installer/data/mysql/sysprefs.sql Auto-merged installer/data/mysql/updatedatabase.pl CONFLICT (content): Merge conflict in installer/data/mysql/updatedatabase.pl Failed to merge in the changes.
Created attachment 6386 [details] [review] Bug 6296: allow users to be authenticated by SSL client certs This adds a new syspref: AllowPKIAuth. It can have one of three states: * None * Common Name * emailAddress If a) this is set to something that's not "None", and b) the webserver is passing SSL client cert details on to Koha, then the relevant field in the user's certificate will be matched up against the field in the database and they will be automatically logged in. This is used as a secure form of single sign-on in some organisations. The "Common Name" field is matched up against the userid, while "emailAddress" is matched against the primary email. This is an example of what might go in the Apache configuration for the virtual host: SSLVerifyClient require SSLVerifyDepth 2 SSLCACertificateFile /etc/apache2/ssl/test/ca.crt SSLOptions +StdEnvVars The last line ensures that the required details are passed to Koha. Conflicts: installer/data/mysql/sysprefs.sql installer/data/mysql/updatedatabase.pl
This cleans up the whitespace errors, and fixes the conflicts in updatedatabase and sysprefs.
QA Comment: Code looks good to me (just going through it), but I am inclined to think that this patch needs a new signoff, preferably from someone outside the company.. Changing status to reflect that. Please respond if I am mistaken..
Created attachment 8143 [details] [review] Rebased but not signed off. Bug 6296: allow users to be authenticated by SSL client certs This adds a new syspref: AllowPKIAuth. It can have one of three states: * None * Common Name * emailAddress If a) this is set to something that's not "None", and b) the webserver is passing SSL client cert details on to Koha, then the relevant field in the user's certificate will be matched up against the field in the database and they will be automatically logged in. This is used as a secure form of single sign-on in some organisations. The "Common Name" field is matched up against the userid, while "emailAddress" is matched against the primary email. This is an example of what might go in the Apache configuration for the virtual host: SSLVerifyClient require SSLVerifyDepth 2 SSLCACertificateFile /etc/apache2/ssl/test/ca.crt SSLOptions +StdEnvVars The last line ensures that the required details are passed to Koha. Conflicts: installer/data/mysql/sysprefs.sql installer/data/mysql/updatedatabase.pl
Well, an obscene number of hours worth of testing later, I have determined that this patch doesn't work. I suspect copy-and-paste errors. The AllowPKIAuth syspref is never checked, and even if it were checked where I believe it should be in C4::Auth::checkauth, it doesn't look like the code would ever be reached.
There's definitely a patch missing. Looking at it now.
Created attachment 8248 [details] [review] Bug 6296: allow users to be authenticated by SSL client certs This adds a new syspref: AllowPKIAuth. It can have one of three states: * None * Common Name * emailAddress If a) this is set to something that's not "None", and b) the webserver is passing SSL client cert details on to Koha, then the relevant field in the user's certificate will be matched up against the field in the database and they will be automatically logged in. This is used as a secure form of single sign-on in some organisations. The "Common Name" field is matched up against the userid, while "emailAddress" is matched against the primary email. This is an example of what might go in the Apache configuration for the virtual host: SSLVerifyClient require SSLVerifyDepth 2 SSLCACertificateFile /etc/apache2/ssl/test/ca.crt SSLOptions +StdEnvVars The last line ensures that the required details are passed to Koha.
Hopefully this has everything needed. In particular, it does check the state of the syspref.
Created attachment 8249 [details] [review] Bug 6296: allow users to be authenticated by SSL client certs This adds a new syspref: AllowPKIAuth. It can have one of three states: * None * Common Name * emailAddress If a) this is set to something that's not "None", and b) the webserver is passing SSL client cert details on to Koha, then the relevant field in the user's certificate will be matched up against the field in the database and they will be automatically logged in. This is used as a secure form of single sign-on in some organisations. The "Common Name" field is matched up against the userid, while "emailAddress" is matched against the primary email. This is an example of what might go in the Apache configuration for the virtual host: #SSLVerifyClient require # only allow PKI authentication SSLVerifyClient optional SSLVerifyDepth 2 SSLCACertificateFile /etc/apache2/ssl/test/ca.crt SSLOptions +StdEnvVars The last line ensures that the required details are passed to Koha. To test the PKI authentication, use the following curl command: curl -k --cert client.crt --key client.key https://URL/ (look through the output to find the "Welcome," line to indicate that a user has been authenticated or the "Log in to Your Account" to indicate that a user has not been authenticated) To create the certificates needed for the above command, the following series of commands will work: # Create the CA Key and Certificate for signing Client Certs openssl genrsa -des3 -out ca.key 4096 openssl req -new -x509 -days 365 -key ca.key -out ca.crt # This is the ca.crt file that the Apache config needs to know about, # so put the file at /etc/apache2/ssl/test/ca.crt # Create the Server Key, CSR, and Certificate openssl genrsa -des3 -out server.key 1024 openssl req -new -key server.key -out server.csr # We're self signing our own server cert here. This is a no-no in # production. openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key \ -set_serial 01 -out server.crt # Create the Client Key and CSR openssl genrsa -des3 -out client.key 1024 openssl req -new -key client.key -out client.csr # Sign the client certificate with our CA cert. Unlike signing our own # server cert, this is what we want to do. openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key \ -set_serial 02 -out client.crt openssl pkcs12 -export -in client.crt -inkey client.key -out client.p12 # In theory we can install this client.p12 file in Firefox or Chrome, but # the exact steps for doing so are unclear, and outside the scope of this # patch Signed-off-by: Jared Camins-Esakov <jcamins@cpbibliography.com> Tested with Common Name and E-mail authentication, as well as with PKI authentication disabled. Regular logins continue to work in all cases when SSL authentication is set to optional on the server.
Created attachment 8252 [details] [review] [PASSED QA] Bug 6296: allow users to be authenticated by SSL client certs This adds a new syspref: AllowPKIAuth. It can have one of three states: * None * Common Name * emailAddress If a) this is set to something that's not "None", and b) the webserver is passing SSL client cert details on to Koha, then the relevant field in the user's certificate will be matched up against the field in the database and they will be automatically logged in. This is used as a secure form of single sign-on in some organisations. The "Common Name" field is matched up against the userid, while "emailAddress" is matched against the primary email. This is an example of what might go in the Apache configuration for the virtual host: #SSLVerifyClient require # only allow PKI authentication SSLVerifyClient optional SSLVerifyDepth 2 SSLCACertificateFile /etc/apache2/ssl/test/ca.crt SSLOptions +StdEnvVars The last line ensures that the required details are passed to Koha. To test the PKI authentication, use the following curl command: curl -k --cert client.crt --key client.key https://URL/ (look through the output to find the "Welcome," line to indicate that a user has been authenticated or the "Log in to Your Account" to indicate that a user has not been authenticated) To create the certificates needed for the above command, the following series of commands will work: # Create the CA Key and Certificate for signing Client Certs openssl genrsa -des3 -out ca.key 4096 openssl req -new -x509 -days 365 -key ca.key -out ca.crt # This is the ca.crt file that the Apache config needs to know about, # so put the file at /etc/apache2/ssl/test/ca.crt # Create the Server Key, CSR, and Certificate openssl genrsa -des3 -out server.key 1024 openssl req -new -key server.key -out server.csr # We're self signing our own server cert here. This is a no-no in # production. openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key \ -set_serial 01 -out server.crt # Create the Client Key and CSR openssl genrsa -des3 -out client.key 1024 openssl req -new -key client.key -out client.csr # Sign the client certificate with our CA cert. Unlike signing our own # server cert, this is what we want to do. openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key \ -set_serial 02 -out client.crt openssl pkcs12 -export -in client.crt -inkey client.key -out client.p12 # In theory we can install this client.p12 file in Firefox or Chrome, but # the exact steps for doing so are unclear, and outside the scope of this # patch Signed-off-by: Jared Camins-Esakov <jcamins@cpbibliography.com> Tested with Common Name and E-mail authentication, as well as with PKI authentication disabled. Regular logins continue to work in all cases when SSL authentication is set to optional on the server. Signed-off-by: Ian Walls <koha.sekjal@gmail.com> QA comment: synchronized updatedatabase.pl version of syspref with sysprefs.sql version, to avoid divergent databases between new and upgrading users.
Lots of whitespace cleanup, thank you. Removes the capture of checkauth return values in a lot of scripts... but in all cases, these variables were not used later. This is unnecessary, but not harmful, and does reduce the number of variables stored on those scripts. Implementation of PKI / x.509 certs is safe for other login types, so this will not impact anyone not using the feature. The line added to sysprefs.sql does not match the line in updatedatabase.pl. The sysprefs.sql line is more thorough, giving a proper default value and a controlled list of values, where the updatedatabase version omits these things. I've corrected this. Marking Passed QA
QA comment : it's very hard to see the difference between reindenting & really new code. For the next reindenting time, please provide 2 patches, that will be much more clear. I've tested that it changes nothing when SSL not enabled, not tested SSL work well. Patch pushed