Document the authproxy plugin
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/f199fa7f Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/f199fa7f Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/f199fa7f Branch: refs/heads/5.0.x Commit: f199fa7fc340f2665a2163f98eca30ea74fb57bd Parents: a955b08 Author: James Peach <[email protected]> Authored: Wed Jan 8 17:33:58 2014 -0800 Committer: James Peach <[email protected]> Committed: Fri Jan 10 15:11:44 2014 -0800 ---------------------------------------------------------------------- doc/reference/plugins/authproxy.en.rst | 91 +++++++++++++++++++++++++++++ doc/reference/plugins/index.en.rst | 1 + plugins/experimental/authproxy/README | 56 ------------------ 3 files changed, 92 insertions(+), 56 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/f199fa7f/doc/reference/plugins/authproxy.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/plugins/authproxy.en.rst b/doc/reference/plugins/authproxy.en.rst new file mode 100644 index 0000000..d18165c --- /dev/null +++ b/doc/reference/plugins/authproxy.en.rst @@ -0,0 +1,91 @@ +.. _authproxy_plugin: + +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`. + +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 ``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 + +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 http://git-wip-us.apache.org/repos/asf/trafficserver/blob/f199fa7f/doc/reference/plugins/index.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/plugins/index.en.rst b/doc/reference/plugins/index.en.rst index a435abb..33c0a2c 100644 --- a/doc/reference/plugins/index.en.rst +++ b/doc/reference/plugins/index.en.rst @@ -62,6 +62,7 @@ directory of the Apache Traffic Server source tree. Exmperimental plugins can be .. toctree:: :maxdepth: 1 + authproxy.en balancer.en buffer_upload.en combo_handler.en http://git-wip-us.apache.org/repos/asf/trafficserver/blob/f199fa7f/plugins/experimental/authproxy/README ---------------------------------------------------------------------- diff --git a/plugins/experimental/authproxy/README b/plugins/experimental/authproxy/README deleted file mode 100644 index b0b58cc..0000000 --- a/plugins/experimental/authproxy/README +++ /dev/null @@ -1,56 +0,0 @@ -# AuthProxy - an authorization proxy plugin - -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 delegated the authorization decision to an external -HTTP service. - -This plugin can be used as both a global plugin and a remap plugin. - -Note that modern Traffic Server releases optimize 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 -proxy.config.http.doc_in_cache_skip_dns to 0 on records.config. - -# Plugin Options - -## --auth-transform=redirect|head - -This option specifies how to route the incoming request to the -authorization service. - -If the value 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 value is "redirect" then the incoming request is sent to the -authorization service designated but 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. This -is a contributor opportunity, patches are welcome! - -## --auth-host=HOST - -The name or address of the authorization host. This is only used -by the "redirect" transform. - -## --auth-port=PORT - -The IP 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 proxy.config.http.cache.ignore_authentication=1 -option on the request.
