dacs_uproxy

DACS_UPROXY(8)              DACS Web Services Manual              DACS_UPROXY(8)



NAME
       dacs_uproxy - minimal HTTP proxying

SYNOPSIS
       dacs_uproxy [dacsoptions[1]]

DESCRIPTION
       This web service is part of the DACS suite.

       The dacs_uproxy web service accepts an incoming HTTP request (the initial
       request), then reissues a nearly identical HTTP request to a different
       URL (the proxied request) and returns its unaltered response. The initial
       request must use either the GET or POST HTTP method; the proxied request
       will use the same method as the initial request. Note that the origin
       server (the web server that receives the proxied request) will see a
       request that originates at the host that runs dacs_uproxy, not the host
       that issues the initial request.

       When run on a firewall host, the program can be useful for forwarding
       incoming requests to interior hosts. An origin server does not need to be
       running DACS. All access control is performed by the jurisdiction that
       runs dacs_uproxy. Similarly, the program can be useful for forwarding
       requests that originate behind the firewall, subject to access control
       permission.

       dacs_uproxy is not a transparent proxy server. A request URL must be
       explicitly addressed to it and include a (partial) name for the target
       resource.

           Security
           The program must be configured with care because it can expose
           otherwise inaccessible hosts to arbitrary HTTP requests from any
           source that can connect to dacs_uproxy.

           Particular care must be taken if a program that is invoked by
           dacs_uproxy generates a redirect that may be handled internally by
           the program's web server. In this event the new request arising from
           the redirection will not automatically be subjected to access control
           because the new request does come through dacs_uproxy. Therefore,
           local redirects must be avoided by proxied web services, resources
           that might be invoked through a local redirect must be publicly
           accessible, or authorization checking must somehow be arranged for
           these resources.

           Access control rules are primarily responsible for expressing
           restrictions on what can be proxied and who can use this service. By
           default, all access to this service is denied. Additionally,
           UPROXY_APPROVED[2] directives must be configured to allow proxying to
           specific origin servers.

           Although in its current form the program has the effect of
           anonymizing the proxied request, this is more of a bug than a
           feature. Future versions may forward an initial request's headers and
           other information.

       With the exception of the Cookie header, most request headers that
       accompany the initial request are sent with the proxied request.
       dacs_uproxy makes no attempt to "impersonate" the user's host, however.
       Therefore, to the origin server it appears as if the request is coming
       from dacs_uproxy and the IP address from which the forwarded request is
       sent. Any cookies sent with the initial request are interpreted by
       dacs_uproxy (e.g., to identify the user making the request for access
       control purposes). At present, it is not possible to forward cookies with
       the proxied request.

       So that the proxied web service can tell that it is being invoked by
       dacs_uproxy, an extension header named DACS-Uproxy-Via is included with
       the forwarded request. Its value is the URL of dacs_uproxy with the
       proxied host appended. With Apache, its value can be accessed from the
       environment variable HTTP_DACS_UPROXY_VIA.

       If dacs_uproxy is passed a DACS_APPROVAL[3] value, that value is
       forwarded with the request through the DACS-Uproxy-Approval header and
       made available by Apache in the HTTP_DACS_UPROXY_APPROVAL environment
       variable. A program invoked indirectly through dacs_uproxy can use this
       information to confirm that DACS authorized the request.

       If the forwarded request generates a redirect (a 3xx class HTTP status
       code is returned), it causes dacs_uproxy to return the redirection
       request.

       The program is a minimal or "micro" HTTP proxy, hence the u in
       dacs_uproxy should really be the Greek letter mu.

   Web Service Arguments
       With some exceptions, all arguments passed to dacs_uproxy are forwarded
       to the proxied request and are not interpreted by dacs_uproxy. The first
       exception is DACS_ACS[4]. Another exception is DACS_UPROXY; if its value
       is DEBUG, debugging output is produced. Neither of these arguments is
       forwarded with the proxied request.

   Operation
       A specification of the proxied request appears as a component of the
       initial request. It is best to explain this with an example. Let us
       assume that the URL for the dacs_uproxy that the client wants to use is
       https://example.com/cgi-bin/dacs/dacs_uproxy. Let us also assume that the
       client wants to access a web service at foo.example.com (the proxied
       host) and that this web service can be invoked from example.com (the
       proxying host) as https://foo.example.com/cgi-bin/some_app. To achieve
       this, the client would invoke this URL:

           https://example.com/cgi-bin/dacs/dacs_uproxy/foo.example.com/cgi-bin/some_app

       Note that no scheme is included with the name of the proxied host. A port
       number may follow it, however, and any path components that follow are
       appended (after the mapping specified by UPROXY_APPROVED) to form the
       final proxied URL.

       For this example to be authorized, an access control rule must grant the
       user access to the initial URL. Whether there is additional access
       control enforced at the proxied host is the responsibility of a web
       administrator. A simple rule that grants access to any authenticated user
       looks like this:

           <acl_rule status="enabled">
             <services>
               <service url_expr='"${Conf::dacs_cgi_bin_prefix}/dacs_uproxy"'/>
               <service url_expr='"${Conf::dacs_cgi_bin_prefix}/dacs_uproxy/*"'/>
             </services>

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

       Most sophisticated rules may of course be used to further constrain how
       dacs_uproxy can be used and by whom.

       The UPROXY_APPROVED[2] directive must be configured before dacs_uproxy
       will do anything, even if otherwise permitted by an access control rule.

       If SSL/TLS is used for the proxied request, the usual DACS configuration
       directives for SSL/TLS apply - see dacs.conf(5)[5]. SSL/TLS can be used
       for the proxied request independently of whether it is used for the
       initial request.

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

BUGS
       The implementation may not yet fully conform to RFC 2616[6].

SEE ALSO
       RFC 2616[6]

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

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

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

        2. UPROXY_APPROVED
           http://dacs.dss.ca/man/dacs.conf.5.html#UPROXY_APPROVED

        3. DACS_APPROVAL
           http://dacs.dss.ca/man/dacs_acs.8.html#dacs_approval

        4. DACS_ACS
           http://dacs.dss.ca/man/dacs_acs.8.html#dacs_acs_argument

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

        6. RFC 2616
           http://www.rfc-editor.org/rfc/rfc2616.txt

        7. www.dss.ca
           http://www.dss.ca

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



DACS 1.4.40                        02/19/2019                     DACS_UPROXY(8)