Merge branch 'jetty-9.4.x' into jetty-10.0.x

jetty-documentation/src/main/asciidoc/configuring/security/openid-support.adoc

@@ -0,0 +1,139 @@
+//
+//  ========================================================================
+//  Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
+//  ========================================================================
+//  All rights reserved. This program and the accompanying materials
+//  are made available under the terms of the Eclipse Public License v1.0
+//  and Apache License v2.0 which accompanies this distribution.
+//
+//      The Eclipse Public License is available at
+//      http://www.eclipse.org/legal/epl-v10.html
+//
+//      The Apache License v2.0 is available at
+//      http://www.opensource.org/licenses/apache2.0.php
+//
+//  You may elect to redistribute this code under either of these licenses.
+//  ========================================================================
+//
+
+[[openid-support]]
+=== OpenID Support
+
+==== External Setup
+
+===== Registering an App with OpenID Provider
+You must register the app with an OpenID Provider such as Google or Amazon.
+This will give you a Client ID and Client Secret.
+Once set up you must also register all the possible URI's for your webapp with the path `/j_security_check` so that the OpenId Provider will allow redirection back to the webapp.
+
+These may look like
+
+ * `http://localhost:8080/openid-webapp/j_security_check`
+
+ *  `https://example.com/j_security_check`
+
+==== Distribution Configuration
+
+===== OpenID Provider Configuration
+To enable OpenID support, you first need to activate the `openid` module in your implementation.
+
+[source, screen, subs="{sub-order}"]
+----
+java -jar {JETTY_HOME}/start.jar --add-to-start=openid
+----
+
+To configure OpenID Authentication with Jetty you will need to specify the OpenID Provider's issuer identifier (case sensitive URL using the `https` scheme) and the OAuth 2.0 Client ID and Client Secret.
+If the OpenID Provider does not allow metadata discovery you will also need to specify the token endpoint and authorization endpoint of the OpenID Provider.
+These can be set as properties in the `start.ini` or `start.d/openid.ini` files.
+
+===== WebApp Specific Configuration in web.xml
+
+The `web.xml` file needs some specific configuration to use OpenID.
+There must be a `login-config` element with an `auth-method` value of `OPENID`, and a `realm-name` value of the exact URL string used to set the OpenID Provider.
+
+To set the error page, an init param is set at `"org.eclipse.jetty.security.openid.error_page"`, its value should be a path relative to the webapp where authentication errors should be redirected.
+
+Example:
+
+[source, xml, subs="{sub-order}"]
+----
+<login-config>
+  <auth-method>OPENID</auth-method>
+  <realm-name>https://accounts.google.com</realm-name>
+</login-config>
+<context-param>
+  <param-name>org.eclipse.jetty.security.openid.error_page</param-name>
+  <param-value>/error</param-value>
+</context-param>
+----
+
+==== Embedded Configuration
+
+===== Define the `OpenIdConfiguration` for a specific OpenID Provider.
+
+If the OpenID Provider allows metadata discovery then you can use.
+
+[source, java, subs="{sub-order}"]
+----
+OpenIdConfiguration openIdConfig = new OpenIdConfiguration(ISSUER, CLIENT_ID, CLIENT_SECRET);
+----
+
+Otherwise you can manually enter the necessary information:
+
+[source, java, subs="{sub-order}"]
+----
+OpenIdConfiguration openIdConfig = new OpenIdConfiguration(ISSUER, TOKEN_ENDPOINT, AUTH_ENDPOINT, CLIENT_ID, CLIENT_SECRET);
+----
+
+===== Configuring an `OpenIdLoginService`
+[source, java, subs="{sub-order}"]
+----
+LoginService loginService = new OpenIdLoginService(openIdConfig);
+securityHandler.setLoginService(loginService);
+----
+
+===== Configuring an `OpenIdAuthenticator` with `OpenIdConfiguration` and Error Page Redirect
+[source, java, subs="{sub-order}"]
+----
+Authenticator authenticator = new OpenIdAuthenticator(openIdConfig, "/error");
+securityHandler.setAuthenticator(authenticator);
+servletContextHandler.setSecurityHandler(securityHandler);
+----
+
+===== Usage
+
+====== Claims and Access Token
+Claims about the user can be found using attributes on the session attribute `"org.eclipse.jetty.security.openid.claims"`, and the full response containing the OAuth 2.0 Access Token can be found with the session attribute `"org.eclipse.jetty.security.openid.response"`.
+
+Example:
+[source, java, subs="{sub-order}"]
+----
+Map<String, Object> claims = (Map)request.getSession().getAttribute("org.eclipse.jetty.security.openid.claims");
+String userId = claims.get("sub");
+
+Map<String, Object> response = (Map)request.getSession().getAttribute("org.eclipse.jetty.security.openid.response");
+String accessToken = response.get("access_token");
+----
+
+==== Scopes
+The OpenID scope is always used but additional scopes can be requested which can give you additional resources or privileges.
+For the Google OpenID Provider it can be useful to request the scopes `profile` and `email` which will give you additional user claims.
+
+Additional scopes can be requested through the `start.ini` or `start.d/openid.ini` files, or with `OpenIdConfiguration.addScopes(...);` in embedded code.
+
+==== Roles
+
+If security roles are required they can be configured through a wrapped `LoginService` which is deferred to for role information by the `OpenIdLoginService`.
+
+This can be configured in XML through `etc/openid-baseloginservice.xml` in the Distribution, or in embedded code using the constructor for the `OpenIdLoginService`.
+
+[source, java, subs="{sub-order}"]
+----
+LoginService wrappedLoginService = ...; // Optional LoginService for Roles
+LoginService loginService = new OpenIdLoginService(openIdConfig, wrappedLoginService);
+----
+
+When using authorization roles, the setting `authenticateNewUsers` becomes significant.
+If set to `true` users not found by the wrapped `LoginService` will still be authenticated but will have no roles.
+If set to `false` those users will be not be allowed to authenticate and are redirected to the error page.
+This setting is configured through the property `jetty.openid.authenticateNewUsers` in the `start.ini` or `start.d/openid.ini` file, or with `OpenIdLoginService.setAuthenticateNewUsers(...);` in embedded code.

jetty-plus/pom.xml

@@ -48,6 +48,16 @@
       <groupId>jakarta.transaction</groupId>
       <artifactId>jakarta.transaction-api</artifactId>
     </dependency>
+    <dependency>
+      <groupId>org.apache.derby</groupId>
+      <artifactId>derby</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.toolchain</groupId>
+      <artifactId>jetty-test-helper</artifactId>
+      <scope>test</scope>
+    </dependency>
     <dependency>
       <groupId>org.eclipse.jetty</groupId>
       <artifactId>jetty-jndi</artifactId>

pom.xml

@@ -1097,6 +1097,16 @@
         <artifactId>jnr-unixsocket</artifactId>
         <version>0.24</version>
       </dependency>
+      <dependency>
+        <groupId>org.apache.derby</groupId>
+        <artifactId>derby</artifactId>
+        <version>10.14.2.0</version>
+      </dependency>
+      <dependency>
+        <groupId>org.apache.derby</groupId>
+        <artifactId>derbytools</artifactId>
+        <version>10.14.2.0</version>
+      </dependency>
       <!-- avoid depending on a range dependency from a transitive dependency -->
       <dependency>
         <groupId>io.grpc</groupId>

tests/test-loginservice/pom.xml

@@ -46,13 +46,11 @@
     <dependency>
       <groupId>org.apache.derby</groupId>
       <artifactId>derby</artifactId>
-      <version>10.4.1.3</version>
       <scope>test</scope>
     </dependency>
     <dependency>
       <groupId>org.apache.derby</groupId>
       <artifactId>derbytools</artifactId>
-      <version>10.4.1.3</version>
       <scope>test</scope>
     </dependency>
     <dependency>

tests/test-sessions/test-jdbc-sessions/pom.xml

@@ -48,13 +48,11 @@
     <dependency>
       <groupId>org.apache.derby</groupId>
       <artifactId>derby</artifactId>
-      <version>10.12.1.1</version>
       <scope>test</scope>
     </dependency>
     <dependency>
       <groupId>org.apache.derby</groupId>
       <artifactId>derbytools</artifactId>
-      <version>10.12.1.1</version>
       <scope>test</scope>
     </dependency>
     <dependency>