*) mod_autht_jwt: New module to handle RFC 7519 JWT tokens within

     bearer tokens, both as part of the aaa framework, and as a way to
     generate tokens and pass them to backend servers and services.

  *) mod_auth_bearer: New module to handle RFC 6750 Bearer tokens, using
     the token_checker hook.

  *) mod_autht_core: New module to handle provider aliases for token
     authentication.



git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1909411 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 480 insertions, 0 deletions

diff --git a/docs/manual/mod/mod_auth_bearer.xml b/docs/manual/mod/mod_auth_bearer.xml
new file mode 100644
index 0000000000..a58fa02aa0
--- /dev/null
+++ b/docs/manual/mod/mod_auth_bearer.xml
@@ -0,0 +1,160 @@
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 1907762 $ -->
+
+<!--
+ 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.
+-->
+
+<modulesynopsis metafile="mod_auth_bearer.xml.meta">
+
+<name>mod_auth_bearer</name>
+<description>Bearer HTTP authentication</description>
+<status>Base</status>
+<sourcefile>mod_auth_bearer.c</sourcefile>
+<identifier>auth_bearer_module</identifier>
+
+<summary>
+    <p>This module allows the use of HTTP Bearer Authentication to
+    restrict access by passing the bearer token to the given providers.
+    This module should be combined with at least one token module
+    such as <module>mod_autht_jwt</module> and one authorization
+    module such as <module>mod_authz_user</module>.</p>
+</summary>
+<seealso><directive module="mod_authn_core">AuthName</directive></seealso>
+<seealso><directive module="mod_authn_core">AuthType</directive></seealso>
+<seealso><directive module="mod_authz_core">Require</directive></seealso>
+<seealso><a href="../howto/auth.html">Authentication howto</a></seealso>
+
+<directivesynopsis>
+<name>AuthBearerProvider</name>
+<description>Sets the authentication provider(s) for this location</description>
+<syntax>AuthBearerProvider <var>provider-name</var>
+[<var>provider-name</var>] ...</syntax>
+<default>AuthBearerProvider file</default>
+<contextlist><context>directory</context><context>.htaccess</context>
+</contextlist>
+<override>AuthConfig</override>
+
+<usage>
+    <p>The <directive>AuthBearerProvider</directive> directive sets
+    which provider is used to verify tokens for this location.
+    The default <code>jwt</code> provider is implemented
+    by the <module>mod_autht_jwt</module> module.  Make sure
+    that the chosen provider module is present in the server.</p>
+    <example><title>Example</title>
+    <highlight language="config">
+&lt;Location "/secure"&gt;
+    AuthType bearer
+    AuthName "private area"
+    AuthBearerProvider jwt
+    AuthtJwtVerify hs256 file "/www/etc/jwt.secret"
+    Require            valid-user
+&lt;/Location&gt;
+    </highlight>
+    </example>
+    <p>Providers are queried in order until a provider finds a match
+    for the requested token. This usually means that the token has been
+    correctly signed, or that the token has not expired.</p>
+
+    <p>The first implemented provider is <module>mod_autht_jwt</module>.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>AuthBearerAuthoritative</name>
+<description>Sets whether token verification is passed to lower level
+modules</description>
+<syntax>AuthBearerAuthoritative On|Off</syntax>
+<default>AuthBearerAuthoritative On</default>
+<contextlist><context>directory</context><context>.htaccess</context>
+</contextlist>
+<override>AuthConfig</override>
+
+<usage>
+    <p>Normally, each token verification module listed in <directive
+    module="mod_auth_bearer">AuthBearerProvider</directive> will attempt
+    to verify the token, and if the token is not found to be valid,
+    access will be denied. Setting the
+    <directive>AuthBearerAuthoritative</directive> directive explicitly
+    to <code>Off</code> allows for token verification to be passed on to
+    other non-provider-based modules if the token is not recognised.
+    This should only be necessary when combining
+    <module>mod_auth_bearer</module> with third-party modules that are not
+    configured with the
+    <directive module="mod_auth_bearer">AuthBearerProvider</directive>
+    directive.  When using such modules, the order of processing
+    is determined in the modules' source code and is not configurable.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>AuthBearerProxy</name>
+<description>Pass a bearer authentication token over a proxy connection
+generated using the given expression</description>
+<syntax>AuthBearerProxy off|<var>expression</var></syntax>
+<default>none</default>
+<contextlist><context>directory</context><context>.htaccess</context>
+</contextlist>
+<override>AuthConfig</override>
+<compatibility>Apache HTTP Server 2.5.1 and later</compatibility>
+<usage>
+    <p>The expression specified is passed as a bearer token in the
+    Authorization header, which is passed to the server or service
+    behind the webserver. The expression is interpreted using the
+    <a href="../expr.html">expression parser</a>, which allows the
+    token to be set based on request parameters.</p>
+
+    <note>
+    The Authorization header added by this directive is <em>not</em>
+    input into any authentication or authorization within the local 
+    server.  It is designed to be passed along to upstream servers.
+    </note>
+
+    <p>In this example, we pass a fixed token to a backend server.</p>
+
+    <example><title>Fixed Example</title>
+    <highlight language="config">
+&lt;Location "/demo"&gt;
+    AuthBearerProxy my-fixed-token
+&lt;/Location&gt;
+    </highlight>
+    </example>
+
+    <p>In this example, we pass the query string as the token to the
+    backend server.</p>
+
+    <example><title>Query String Example</title>
+    <highlight language="config">
+&lt;Location "/secure"&gt;
+    AuthBearerProxy "%{QUERY_STRING}"
+&lt;/Location&gt;
+    </highlight>
+    </example>
+
+    <example><title>Exclusion Example</title>
+    <highlight language="config">
+&lt;Location "/public"&gt;
+    AuthBearerProxy off
+&lt;/Location&gt;
+    </highlight>
+    </example>
+
+</usage>
+</directivesynopsis>
+
+</modulesynopsis>
diff --git a/docs/manual/mod/mod_autht_core.xml b/docs/manual/mod/mod_autht_core.xml
new file mode 100644
index 0000000000..ac0f014a09
--- /dev/null
+++ b/docs/manual/mod/mod_autht_core.xml
@@ -0,0 +1,104 @@
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 1834267 $ -->
+
+<!--
+ 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.
+-->
+
+<modulesynopsis metafile="mod_autht_core.xml.meta">
+
+<name>mod_autht_core</name>
+<description>Core Token Handling</description>
+<status>Base</status>
+<sourcefile>mod_autht_core.c</sourcefile>
+<identifier>autht_core_module</identifier>
+<compatibility>Available in Apache 2.5 and later</compatibility>
+
+<summary>
+    <p>This module provides core token handling capabilities to
+    allow or deny access to portions of the web site.
+    <module>mod_autht_core</module> provides directives that are
+    common to all token providers.</p>
+</summary>
+
+<section id="authtalias"><title>Creating Token Provider Aliases</title>
+
+    <p>Extended token providers can be created within the configuration
+    file and assigned an alias name.  The alias providers can then be
+    referenced through the
+    <directive module="mod_auth_bearer">AuthBearerProvider</directive>
+    directive in the same way as a base token provider.  Besides the
+    ability to create and alias an extended provider, it also allows
+    the same extended token provider to be reference by multiple
+    locations.</p>
+
+    <section id="example"><title>Examples</title>
+
+        <p>This example checks for JWT token signatures in two different
+        secret files.</p>
+
+        <example><title>Checking multiple sources for JWT tokens</title>
+        <highlight language="config">
+# Check here first
+&lt;AuthtProviderAlias jwt jwt1&gt;
+    AuthtJwtVerify hs256 file "/www/conf/realm1.secret"
+&lt;/AuthtProviderAlias&gt;
+
+# Then check here
+&lt;AuthtProviderAlias jwt jwt2&gt;
+    AuthtJwtVerify hs256 file "/www/conf/realm2.secret"
+&lt;/AuthtProviderAlias&gt;
+
+&lt;Directory "/var/web/pages/secure"&gt;
+    AuthBearerProvider jwt1 jwt2
+
+    AuthType Basic
+    AuthName "Protected Area"
+    Require valid-user
+&lt;/Directory&gt;
+        </highlight>
+        </example>
+
+    </section>
+
+</section>
+
+<directivesynopsis type="section">
+<name>AuthtProviderAlias</name>
+<description>Enclose a group of directives that represent an
+extension of a base token provider and referenced by the specified
+alias</description>
+<syntax>&lt;AuthtProviderAlias <var>baseProvider Alias</var>&gt;
+... &lt;/AuthtProviderAlias&gt;</syntax>
+<contextlist><context>server config</context>
+</contextlist>
+
+<usage>
+    <p><code>&lt;AuthtProviderAlias&gt;</code> and
+    <code>&lt;/AuthtProviderAlias&gt;</code> are used to enclose a group of
+    authentication directives that can be referenced by the alias name
+    using the
+    <directive module="mod_auth_bearer">AuthBearerProvider</directive>.</p>
+
+    <note>This directive has no affect on authentication or authorization,
+    even for modules that provide both authentication and authorization
+    in addition to token handling.</note>
+</usage>
+</directivesynopsis>
+
+</modulesynopsis>
diff --git a/docs/manual/mod/mod_autht_jwt.xml b/docs/manual/mod/mod_autht_jwt.xml
new file mode 100644
index 0000000000..08c49ba8bc
--- /dev/null
+++ b/docs/manual/mod/mod_autht_jwt.xml
@@ -0,0 +1,216 @@
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision: 1421821 $ -->
+
+<!--
+ 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.
+-->
+
+<modulesynopsis metafile="mod_autht_jwt.xml.meta">
+
+<name>mod_autht_jwt</name>
+<description>Token authentication using JWT tokens</description>
+<status>Base</status>
+<sourcefile>mod_autht_jwt.c</sourcefile>
+<identifier>autht_jwt_module</identifier>
+
+<summary>
+    <p>This module provides token parsing front-ends such as
+    <module>mod_auth_bearer</module> the ability to authenticate users
+    by verifying a JWT token as described in
+    <a href="http://www.ietf.org/rfc/rfc7519.txt">RFC 7519</a>.</p>
+
+    <p>A JWT token is read from the <var>Authorization</var> header
+    with an <var>auth-scheme</var> of <var>Bearer</var>.</p>
+
+    <p>When using <module>mod_auth_bearer</module> this module is invoked
+    via the
+    <directive module="mod_auth_bearer">AuthBearerProvider</directive>
+    with the <code>jwt</code> value.</p>
+
+    <p>This module can also be used standalone to generate JWT tokens
+    for passing to a backend server or service. Claims are embedded within
+    a token, which is then optionally signed, and passed using the
+    <var>Authorization</var> header as a <var>Bearer</var> token.</p>
+</summary>
+<seealso>
+  <directive module="mod_auth_bearer">AuthBearerProvider</directive>
+</seealso>
+
+<directivesynopsis>
+<name>AuthtJwtDriver</name>
+<description>Sets the name of the underlying crypto driver to
+use</description>
+<syntax>AuthtJwtDriver <var>name</var> <var>[param[=value]]</var></syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+
+<usage>
+    <p>The <directive>AuthtJwtDriver</directive> directive specifies the name of
+    the crypto driver to be used for signing and verification. If not specified,
+    the driver defaults to the recommended driver compiled into APR-util.</p>
+
+    <p>Follow the instructions in the
+    <directive module="mod_session_crypto">SessionCryptoDriver</directive> to
+    set up the driver.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>AuthtJwtVerify</name>
+<description>The JWS signing algorithm and passphrase/key to verify an incoming
+JWT token</description>
+<syntax>AuthtJwtVerify <var>algorithm</var> [<var>type</var> <var>param</var>]</syntax>
+<contextlist><context>directory</context><context>.htaccess</context>
+</contextlist>
+<override>AuthConfig</override>
+
+<usage>
+    <p>The <directive>AuthtJwtVerify</directive> directive specifies the algorithm
+    and secret used to verify incoming bearer tokens.</p>
+
+    <p>If the algorithm type <var>none</var> is selected, the token is not
+    protected, and will be accepted as is. Use only when the client is trusted, and the
+    channel is protected through other means, such as mutually authenticated TLS, or
+    unix domain sockets.</p>
+
+    <p>If present, the <var>sub</var> claim is assigned to REMOTE_USER.</p>
+
+    <example><title>No Verification Example</title>
+    <highlight language="config">
+&lt;Location "/mutual-tls-secured"&gt;
+  AuthType bearer
+  AuthName example-name
+  AuthBearerProvider jwt
+  AuthtJwtVerify none
+  Require valid-user
+&lt;/Location&gt;
+    </highlight>
+    </example>
+
+    <p>If the algorithm type <var>HS256</var> is used, the algorithm is set to
+    <var>HMAC-SHA256</var>, and the secret is set within the <var>file</var> specified
+    as the third parameter. The contents of the bearer token is still visible, and so
+    the channel must still be protected from evesdropping through TLS.</p>
+
+    <p>If the signature is verified, and if present, the <var>sub</var> claim is
+    assigned to REMOTE_USER.</p>
+
+    <example><title>Verification Example</title>
+    <highlight language="config">
+&lt;Location "/secure"&gt;
+  AuthType bearer
+  AuthName example-name
+  AuthBearerProvider jwt
+  AuthtJwtVerify hs256 file "/www/conf/jwt.secret"
+  Require valid-user
+&lt;/Location&gt;
+    </highlight>
+    </example>
+
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>AuthtJwtSign</name>
+<description>The JWS signing algorithm and passphrase/key to sign an outgoing
+JWT token</description>
+<syntax>AuthtJwtSign <var>algorithm</var> [<var>type</var> <var>param</var>]</syntax>
+<contextlist><context>directory</context><context>.htaccess</context>
+</contextlist>
+<override>AuthConfig</override>
+
+<usage>
+    <p>The <directive>AuthtJwtSign</directive> directive specifies the algorithm
+    and secret used to sign outgoing bearer tokens passed to a server or service.</p>
+
+    <p>If the algorithm type <var>none</var> is selected, the token is not
+    protected. Use only when the client is trusted, and the channel is protected
+    through other means, such as mutually authenticated TLS, or unix domain sockets.</p>
+
+    <p>Set the claims to be sent in the token using the
+    <directive module="mod_autht_jwt">AuthtJwtClaim</directive> directive. The
+    <var>sub</var> claim is used to pass the remote user.</p>
+
+    <example><title>No Verification Example</title>
+    <highlight language="config">
+&lt;Location "/mutual-tls-secured"&gt;
+  AuthtJwtClaim set sub %{REMOTE_USER}
+  AuthtJwtSign none
+&lt;/Location&gt;
+    </highlight>
+    </example>
+
+    <p>If the algorithm type <var>HS256</var> is used, the algorithm is set to
+    <var>HMAC-SHA256</var>, and the secret is set within the <var>file</var> specified
+    as the third parameter. The contents of the bearer token is still visible, and so
+    the channel must still be protected from evesdropping through TLS.</p>
+
+    <example><title>Verification Example</title>
+    <highlight language="config">
+&lt;Location "/secure"&gt;
+  AuthtJwtClaim set sub %{REMOTE_USER}
+  AuthtJwtSign hs256 file "/www/conf/jwt.secret"
+&lt;/Location&gt;
+    </highlight>
+    </example>
+
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>AuthtJwtClaim</name>
+<description>Set a claim with the given name and expression, or unset the claim with the given name</description>
+<syntax>AuthtJwtVerify <var>[set|unset]</var> <var>name</var> [<var>value</var>]</syntax>
+<contextlist><context>directory</context><context>.htaccess</context>
+</contextlist>
+<override>AuthConfig</override>
+
+<usage>
+    <p>The <directive>AuthtJwtClaim</directive> directive adds and/or removes
+    claims from token being passed to the backend server or service.</p>
+
+    <p>When a claim is set, the value of the claim is the result of an expression. The
+    expression may include parameters from a digital certificate, or the name of the
+    user that has been authenticated to Apache httpd.</p>
+
+    <example><title>Pass Remote User Example</title>
+    <highlight language="config">
+&lt;Location "/secure"&gt;
+  AuthtJwtClaim set sub %{REMOTE_USER}
+  AuthtJwtSign hs256 file "/www/conf/jwt.secret"
+&lt;/Location&gt;
+    </highlight>
+    </example>
+
+    <p>When a claim is unset, the claim previously set is removed from the token.</p>
+
+    <example><title>Unset Claim Example</title>
+    <highlight language="config">
+AuthtJwtClaim set my-claim present
+&lt;Location "/secure"&gt;
+  AuthtJwtClaim set sub %{REMOTE_USER}
+  AuthtJwtClaim unset my-claim
+  AuthtJwtSign hs256 file "/www/conf/jwt.secret"
+&lt;/Location&gt;
+    </highlight>
+    </example>
+
+</usage>
+</directivesynopsis>
+
+</modulesynopsis>