You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by zw...@apache.org on 2014/01/21 00:07:49 UTC
[10/50] git commit: Document the authproxy plugin
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 <jp...@apache.org>
Authored: Wed Jan 8 17:33:58 2014 -0800
Committer: James Peach <jp...@apache.org>
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.