.. _admin-plugins-authproxy:

AuthProxy Plugin
****************

.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.

There are many ways of authorizing an HTTP request. Often, this
requires making IPC calls to some internal infrastructure. ``AuthProxy``
is a plugin that takes care of the Traffic Server end of authorizing
a request and delegates the authorization decision to an external
HTTP service.

This plugin can be used as either a global plugin or a remap plugin.

Note that Traffic Server optimizes latency by skipping the DNS
lookup state if a document is found in the cache. This will have
the effect of serving the document without consulting the ``AuthProxy``
plugin. you can disable this behavior by setting
:ts:cv:`proxy.config.http.doc_in_cache_skip_dns` to ``0`` in
:file:`records.config`.

Note that the authorization request will need to match a remap rule
(which, as a standalone remap rule, does not need to call the
AuthProxy plugin). If a second remap rule is required, by default,
the authorization request will not have the same Host header as
the request from the client. It could be added using the
``header_rewrite`` plugin (set-header Host "pristine_host.example.com").

Plugin Options
--------------

--auth-transform=TYPE
  This option specifies how to route the incoming request to the
  authorization service. The transform type may be ``head`` or
  ``redirect``.

  If the transform type is ``head``, then the incoming request is
  transformed to a HEAD request and is sent to the same destination.
  If the response is ``200 OK``, the incoming request is allowed
  to proceed.

  If the transform type is ``range``, then the incoming request is
  transformed to a Range request asking for 0 bytes. Other than that,
  the behavior is identical to the ``head`` option above. This type
  of Range request is useful when the upstream destination is a cache,
  and it's not able to cache HEAD requests.

  If the transform type is ``redirect`` then the incoming
  request is sent to the authorization service designated by the
  `--auth-host` and `--auth-port` parameters. If the response is
  200 OK, the incoming request is allowed to proceed.

  When the authorization service responds with a status other than
  200 OK, that response is returned to the client as the response to
  the incoming request. This allows mechanisms such as HTTP basic
  authentication to work correctly. Note that the body of the
  authorization service response is not returned to the client.

--auth-host=HOST
  The name or address of the authorization host. This is only used
  by the ``redirect`` transform.

--auth-port=PORT
  The TCP port of the authorization host. This is only used by the
  ``redirect`` transform.

--force-cacheability
  If this options is set, the plugin will allow Traffic Server to
  cache the result of authorized requests. In the normal case, requests
  with authorization headers are nor cacheable, but this flag allows
  that by setting the :ts:cv:`proxy.config.http.cache.ignore_authentication`
  option on the request.

Examples
--------

In this example, the authentication is performed by converting the incoming
HTTP request to a `HEAD` request and sending that to the origin server
`origin.internal.com`::

  map http://cache.example.com http://origin.internal.com/ \
    @plugin=authproxy.so @pparam=--auth-transform=head

  map http://origin.internal.com http://origin.internal.com/


In this example, the request is directed to a local authentication server
that authorizes the request based on internal policy rules::

  map http://cache.example.com http://origin.internal.com/ \
    @plugin=authproxy.so @pparam=--auth-transform=redirect @pparam=--auth-host=127.0.0.1 @pparam=--auth-port=9000

  map http://origin.internal.com/ http://origin.internal.com/ \
    @plugin=authproxy.so @pparam=--auth-transform=redirect @pparam=--auth-host=127.0.0.1 @pparam=--auth-port=9000