[jena-site] 01/02: Documentation for bearer auth support

[an...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

andy pushed a commit to branch main-next
in repository https://gitbox.apache.org/repos/asf/jena-site.git

commit 2438a3d3568ae241d99322c994db4f792ec3cc46
Author: Andy Seaborne <an...@apache.org>
AuthorDate: Sat Aug 20 12:04:21 2022 +0100

    Documentation for bearer auth support
---
 source/documentation/sparql-apis/http-auth.md | 38 ++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/source/documentation/sparql-apis/http-auth.md b/source/documentation/sparql-apis/http-auth.md
index a5742bc4f..f742cef98 100644
--- a/source/documentation/sparql-apis/http-auth.md
+++ b/source/documentation/sparql-apis/http-auth.md
@@ -38,9 +38,14 @@ information.  To make this automatic, the first request must not be a streaming
 request (the stream is not repeatable). All HTTP request generated by Jena are
 repeatable.
 
-The URL can contain a `userinfo` part, either the `users@host` form, or the `user:password@host` form.
-If just the user is given, the authentication environment is consulted for registered users-password information. If user and password is given, the details as given are used. This latter form is not recommended and should only be used if necessary because the password is in-clear in the SPARQL
-query.
+The URL can contain a `userinfo` part, either the `users@host` form, or the
+`user:password@host` form.  If just the user is given, the authentication
+environment is consulted for registered users-password information. If user and
+password is given, the details as given are used. This latter form is not
+recommended and should only be used if necessary because the password is
+in-clear in the SPARQL query.
+
+Jena also has [support for bearer authentication](#bearer-authentication).
 
 ### JDK HttpClient.authenticator
 
@@ -137,6 +142,31 @@ used.
     }
 ```
 
-## Examples
+## Authentication Examples
 
 [jena-examples:arq/examples/auth/](https://github.com/apache/jena/tree/main/jena-examples/src/main/java/arq/examples/auth).
+
+## Bearer Authentication
+
+Bearer authentication requires that the application to obtain a token to present
+to the server.
+
+* [RFC 6750](https://tools.ietf.org/html/rfc6750)
+* [RFC 6751](https://tools.ietf.org/html/rfc6751)
+* [JSON Web Tokens (JWT)](https://tools.ietf.org/html/rfc7519)
+* [JSON Web Token Best Current Practices](https://tools.ietf.org/html/rfc8725)
+
+How this token is obtained depends on the deployment environment. 
+
+The application can either register the token to be used:
+
+```
+    AuthEnv.get().addBearerToken(targetURL, jwtString);
+```
+
+or can provide a token provider for 401 challeneges stating bearer authentication.
+
+```
+    AuthEnv.get().setBearerTokenProvider( 
+        (uri, challenge)->{ ... ; return jwtString; });
+```