dacs_autologin_ssl

DACS_AUTOLOGIN_SSL(8)       DACS Web Services Manual       DACS_AUTOLOGIN_SSL(8)



NAME
       dacs_autologin_ssl - use an SSL client certificate to automatically
       obtain DACS credentials

SYNOPSIS
       dacs_autologin_ssl [dacsoptions[1]]

DESCRIPTION
       This program is part of the DACS suite.

       The dacs_autologin_ssl CGI program, in conjunction with appropriate DACS
       configuration and a valid SSL client certificate, can be used for
       user-transparent DACS authentication. A user is not prompted for a
       username or password, and no user-visible sign-on procedure takes place.

       At present, the program merely acts as glue to indirectly invoke
       dacs_authenticate(8)[2]. Any valid X.509 certificate can be used for this
       purpose, including a self-signed certificate. Please refer to the
       OpenSSL[3] documentation for additional information about certificates.

       This program can be used to automatically and transparently authenticate
       a user that has been issued an SSL client certificate. When an
       unauthenticated user is denied access to a DACS-wrapped resource, she can
       be automatically authenticated and redirected back to the resource
       without any user input or action. This assumes that the client
       certificate is sent automatically by the browser and that no additional
       user prompting is needed by the authenticating jurisdiction. For
       redirection to the original resource to work properly. the original
       request must have used the GET method.

           Note
           The cert style of authentication must be configured when
           dacs_autologin_ssl is being used as described. See
           dacs_authenticate(8)[4].

OPTIONS
       Only the standard dacsoptions[1] command line arguments are recognized.

   Web Service Arguments
       dasc_autologin_ssl understands the following CGI arguments.

       DACS_ERROR_URL
           When dacs_autologin_ssl is invoked as a result of DACS event
           handling, DACS_ERROR_URL is automatically passed to it by
           dacs_acs(8)[5] and represents the original URL to which access was
           denied. In typical use, dacs_autologin_ssl is configured as the
           handler for a dacs_acs 902 error code (NO_AUTH, "Authentication by
           DACS is required").  dacs_autologin_ssl then invokes
           dacs_authenticate. If DACS authentication is successful,
           dacs_authenticate ordinarily issues a browser redirect to the value
           of DACS_ERROR_URL and a cookie bearing the credentials are set in the
           browser (but see the NOREDIRECT argument). This argument is optional;
           if not provided, the jurisdiction's configured post-authentication
           action will occur.

       NOREDIRECT
           If this optional argument is present (its value is immaterial),
           dacs_autologin_ssl instructs dacs_authenticate to not issue a browser
           redirect to the value of DACS_ERROR_URL.

       AUTH_JURISDICTION
           If this optional argument is present, it gives the name of the
           jurisdiction at which authentication should take place. By default,
           dacs_authenticate is invoked at the same jurisdiction as
           dacs_autologin_ssl.

       CERT_NAME_ATTR
           This optional argument explicitly names the attribute in the
           certificate from which to set USERNAME. The default value is
           SSL_CLIENT_S_DN_CN. It is an error if the specified attribute name
           does not exist. Giving the value of CERT_NAME_ATTR as the empty
           string results in the empty string being passed as the value of
           USERNAME.

EXAMPLE
       A typical use of dacs_autologin_ssl is to transparently authenticate a
       user via his SSL client certificate.

       In the DACS configuration file, dacs.conf, jurisdiction EXAMPLE is
       configured as follows (this excerpt from a configuration file uses
       fictitious domain names):

           <Jurisdiction uri="example.com">

           JURISDICTION_NAME "EXAMPLE"

           ACS_ERROR_HANDLER "NO_AUTH https://example.com/cgi-bin/dacs/dacs_autologin_ssl"

           <!-- Authenticate using an SSL certificate. -->
           <Auth id="cert">
           URL "https://example.com/cgi-bin/dacs/local_cert_authenticate"
           STYLE "cert"
           CONTROL "sufficient"
           CERT_CA_PATH "/usr/local/apache2.2/conf/ssl.crt"
           CERT_NAME_ATTR "SSL_CLIENT_S_DN_CN"
           </Auth>

           </Jurisdiction>

       Assume the following access control rule applies to the request:

           <acl_rule status="enabled">
             <services>
               <service url_pattern='/foo.html'/>
             </services>

             <rule order="allow,deny">
               <allow>
                 user("auth")
               </allow>
             </rule>
           </acl_rule>



       The preceding configuration results in the following behaviour. An
       unauthenticated user accessing foo.html (https://example.com/foo.html) is
       denied access because the rule governing that web page tests for
       authentication and no credentials are sent with the request. As a result,
       the ACS_ERROR_HANDLER[6] directive causes the user to be redirected to
       dacs_autologin_ssl, which redirects the user to dacs_authenticate,
       passing arguments as necessary.

       dacs_authenticate then invokes local_cert_authenticate[4], passing it the
       client's certificate. The certificate is validated and a username is
       extracted from it and mapped to a valid DACS username.

       If authentication succeeds, DACS credentials for the jurisdiction EXAMPLE
       are generated. These credentials are returned to the browser within a
       cookie and the browser is redirected to the value of DACS_ERROR_URL
       (recall that DACS_ERROR_URL was passed to dacs_autologin_ssl by dacs_acs
       when the 902 handler was invoked and was forwarded to dacs_authenticate).
       In this example the user is redirected to https://example.com/foo.html.
       Given the rule above, this time the user's request for foo.html will be
       granted.

       dacs_autologin_ssl may also be used as the target of an explicit
       authentication link. For example:

           <a href="https://example.com/cgi-bin/dacs/dacs_autologin_ssl?\
           AUTH_JURISDICTION=EXAMPLE&\
           DACS_ERROR_URL=https://example.com/cgi-bin/dacs/dacs_current_credentials">Login</a>

       Following the link should result in the user being authenticated and
       redirected to the specified URL.

DIAGNOSTICS
       The program exits 0 if everything was fine, 1 if an error occurred.

SEE ALSO
       dacs_authenticate(8)[2], dacs_acs(8)[5], dacs.conf(5)[7], autologin(8)[8]

AUTHOR
       Distributed Systems Software (www.dss.ca[9])

COPYING
       Copyright © 2003-2012 Distributed Systems Software. See the LICENSE[10]
       file that accompanies the distribution for licensing information.

NOTES
        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html

        3. OpenSSL
           http://www.openssl.org

        4. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_cert_authenticate

        5. dacs_acs(8)
           http://dacs.dss.ca/man/dacs_acs.8.html

        6. ACS_ERROR_HANDLER
           http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ERROR_HANDLER

        7. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html

        8. autologin(8)
           http://dacs.dss.ca/man/autologin.8.html

        9. www.dss.ca
           http://www.dss.ca

       10. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE



DACS 1.4.40                        02/19/2019              DACS_AUTOLOGIN_SSL(8)