Skip to content

Commit 063142a

Browse files
sbordetsbordet
committedMar 25, 2025··
Merged branch 'jetty-12.0.x' into 'jetty-12.1.x'.
Signed-off-by: Simone Bordet <[email protected]>
2 parents 6fbfb5f + 3655039 commit 063142a

File tree

15 files changed

+357
-31
lines changed

15 files changed

+357
-31
lines changed
 

‎documentation/jetty/modules/code/examples/pom.xml

+8
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,10 @@
5454
<groupId>org.eclipse.jetty</groupId>
5555
<artifactId>jetty-nosql</artifactId>
5656
</dependency>
57+
<dependency>
58+
<groupId>org.eclipse.jetty</groupId>
59+
<artifactId>jetty-openid</artifactId>
60+
</dependency>
5761
<dependency>
5862
<groupId>org.eclipse.jetty</groupId>
5963
<artifactId>jetty-rewrite</artifactId>
@@ -125,6 +129,10 @@
125129
<groupId>org.eclipse.jetty.memcached</groupId>
126130
<artifactId>jetty-memcached-sessions</artifactId>
127131
</dependency>
132+
<dependency>
133+
<groupId>org.eclipse.jetty.tests</groupId>
134+
<artifactId>jetty-test-common</artifactId>
135+
</dependency>
128136
<dependency>
129137
<groupId>org.eclipse.jetty.websocket</groupId>
130138
<artifactId>jetty-websocket-jetty-client</artifactId>

‎documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/security/OpenIdDocs.java

+134
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
//
2+
// ========================================================================
3+
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
4+
//
5+
// This program and the accompanying materials are made available under the
6+
// terms of the Eclipse Public License v. 2.0 which is available at
7+
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
8+
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
9+
//
10+
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
11+
// ========================================================================
12+
//
13+
14+
package org.eclipse.jetty.docs.programming.security;
15+
16+
import java.io.PrintStream;
17+
import java.security.Principal;
18+
import java.util.Map;
19+
20+
import org.eclipse.jetty.client.HttpClient;
21+
import org.eclipse.jetty.io.Content;
22+
import org.eclipse.jetty.security.AuthenticationState;
23+
import org.eclipse.jetty.security.Constraint;
24+
import org.eclipse.jetty.security.HashLoginService;
25+
import org.eclipse.jetty.security.LoginService;
26+
import org.eclipse.jetty.security.SecurityHandler;
27+
import org.eclipse.jetty.security.UserStore;
28+
import org.eclipse.jetty.security.openid.OpenIdAuthenticator;
29+
import org.eclipse.jetty.security.openid.OpenIdConfiguration;
30+
import org.eclipse.jetty.security.openid.OpenIdLoginService;
31+
import org.eclipse.jetty.server.Handler;
32+
import org.eclipse.jetty.server.Request;
33+
import org.eclipse.jetty.server.Response;
34+
import org.eclipse.jetty.server.Server;
35+
import org.eclipse.jetty.server.Session;
36+
import org.eclipse.jetty.session.SessionHandler;
37+
import org.eclipse.jetty.util.Callback;
38+
import org.eclipse.jetty.util.Fields;
39+
40+
@SuppressWarnings("unused")
41+
public class OpenIdDocs
42+
{
43+
public void combinedExample()
44+
{
45+
Server server = new Server();
46+
// tag::openIdConfigExample[]
47+
// To create an OpenIdConfiguration you can rely on discovery of the OIDC metadata.
48+
OpenIdConfiguration openIdConfig = new OpenIdConfiguration(
49+
"https://example.com/issuer", // ISSUER
50+
"my-client-id", // CLIENT_ID
51+
"my-client-secret" // CLIENT_SECRET
52+
);
53+
54+
// Or you can specify the full OpenID configuration manually.
55+
openIdConfig = new OpenIdConfiguration(
56+
"https://example.com/issuer", // ISSUER
57+
"https://example.com/token", // TOKEN_ENDPOINT
58+
"https://example.com/auth", // AUTH_ENDPOINT
59+
"https://example.com/logout", // END_SESSION_ENDPOINT
60+
"my-client-id", // CLIENT_ID
61+
"my-client-secret", // CLIENT_SECRET
62+
"client_secret_post", // AUTH_METHOD (e.g., client_secret_post, client_secret_basic)
63+
new HttpClient() // HttpClient instance
64+
);
65+
66+
// The specific security handler implementation will change depending on whether you are using EE8/EE9/EE10/EE11 or Jetty Core API.
67+
SecurityHandler.PathMapped securityHandler = new SecurityHandler.PathMapped();
68+
server.insertHandler(securityHandler);
69+
securityHandler.put("/auth/*", Constraint.ANY_USER);
70+
71+
// A nested LoginService is optional and used to specify known users with defined roles.
72+
// This can be any instance of LoginService and is not restricted to be a HashLoginService.
73+
HashLoginService nestedLoginService = new HashLoginService();
74+
UserStore userStore = new UserStore();
75+
userStore.addUser("<admin-user-subject-identifier>", null, new String[]{"admin"});
76+
nestedLoginService.setUserStore(userStore);
77+
78+
// Optional configuration to allow new users not listed in the nested LoginService to be authenticated.
79+
openIdConfig.setAuthenticateNewUsers(true);
80+
81+
// An OpenIdLoginService should be used which can optionally wrap the nestedLoginService to support roles.
82+
LoginService loginService = new OpenIdLoginService(openIdConfig, nestedLoginService);
83+
securityHandler.setLoginService(loginService);
84+
85+
// Configure an OpenIdAuthenticator.
86+
securityHandler.setAuthenticator(new OpenIdAuthenticator(openIdConfig,
87+
"/j_security_check", // The path where the OIDC provider redirects back to Jetty.
88+
"/error", // Optional page where authentication errors are redirected.
89+
"/logoutRedirect" // Optional page where the user is redirected to this page after logout.
90+
));
91+
92+
// Session handler is required for OpenID authentication.
93+
server.insertHandler(new SessionHandler());
94+
// end::openIdConfigExample[]
95+
96+
// tag::openIdUsageExample[]
97+
class OpenIdExampleHandler extends Handler.Abstract
98+
{
99+
@Override
100+
public boolean handle(Request request, Response response, Callback callback) throws Exception
101+
{
102+
PrintStream writer = new PrintStream(Content.Sink.asOutputStream(response));
103+
104+
String pathInContext = Request.getPathInContext(request);
105+
if (pathInContext.startsWith("/error"))
106+
{
107+
// Handle requests to the error page which may have an error description parameter.
108+
Fields parameters = Request.getParameters(request);
109+
writer.println("error_description: " + parameters.get("error_description_jetty") + "<br>");
110+
}
111+
else
112+
{
113+
Principal userPrincipal = AuthenticationState.getUserPrincipal(request);
114+
writer.println("userPrincipal: " + userPrincipal);
115+
if (userPrincipal != null)
116+
{
117+
// You can access the full openid claims for an authenticated session.
118+
Session session = request.getSession(false);
119+
@SuppressWarnings("unchecked")
120+
Map<String, String> claims = (Map<String, String>)session.getAttribute("org.eclipse.jetty.security.openid.claims");
121+
writer.println("claims: " + claims);
122+
writer.println("name: " + claims.get("name"));
123+
writer.println("sub: " + claims.get("sub"));
124+
}
125+
}
126+
127+
writer.close();
128+
callback.succeeded();
129+
return true;
130+
}
131+
}
132+
// end::openIdUsageExample[]
133+
}
134+
}

‎documentation/jetty/modules/operations-guide/nav.adoc

+3-2
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,9 @@
3434
* xref:jndi/index.adoc[]
3535
* Jetty Security
3636
** xref:security/configuring-form-size.adoc[]
37-
* xref:jaas/index.adoc[]
38-
* xref:jaspi/index.adoc[]
37+
** xref:security/jaas-support.adoc[]
38+
** xref:security/jaspi-support.adoc[]
39+
** xref:security/openid-support.adoc[]
3940
* xref:jmx/index.adoc[]
4041
* xref:tools/index.adoc[]
4142
* xref:troubleshooting/index.adoc[]

‎documentation/jetty/modules/operations-guide/pages/features/index.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Protocols::
2323

2424
Technologies::
2525
* xref:annotations/index.adoc[Servlet Annotations]
26-
* xref:jaas/index.adoc[JAAS]
26+
* xref:security/jaas-support.adoc[JAAS]
2727
* xref:jndi/index.adoc[JNDI]
2828
* xref:jsp/index.adoc[JSP]
2929
* xref:jmx/index.adoc[JMX Monitoring & Management]

‎documentation/jetty/modules/operations-guide/pages/modules/standard.adoc

+25-1
Original file line numberDiff line numberDiff line change
@@ -520,10 +520,34 @@ As an example, in a Linux machine named `beryl`, the `/etc/hosts` file may conta
520520
----
521521

522522
If the system property `java.rmi.server.hostname` is not specified, the RMI implementation uses the host name `beryl` to figure out the IP address to store in the RMI stub, in this case `127.0.1.1`.
523-
However, we the RMI server is configured to bind to `localhost`, i.e. `127.0.0.1`.
523+
However, the RMI server is configured to bind to `localhost`, i.e. `127.0.0.1`.
524524

525525
If the system property `java.rmi.server.hostname` is not specified, the RMI client will try to connect to `127.0.1.1` (because that's what in the RMI stub) and fail because nothing is listening on that address.
526526

527+
[[openid]]
528+
== Module `openid`
529+
530+
The `openid` module enables support for OpenID Connect (OIDC) authentication in Jetty, as detailed in xref:security/openid-support.adoc#openid-support[this section].
531+
532+
This module allows Jetty to authenticate users via an OpenID Connect identity provider, making possible to integrate features like "Sign in with Google" or "Sign in with Microsoft", among others.
533+
534+
This simplifies user authentication while leveraging the security and convenience of external identity providers.
535+
536+
The module properties are:
537+
538+
----
539+
include::{jetty-home}/modules/openid.mod[tags=documentation]
540+
----
541+
542+
Among the configurable properties, the only required properties are:
543+
544+
`jetty.openid.provider`::
545+
The issuer identifier of the OpenID Provider, which is the base URL before .well-known/openid-configuration. It must match the issuer field in the provider's configuration and is case-sensitive.
546+
`jetty.openid.clientId`::
547+
The Client Identifier assigned to your application by the OpenID Provider, used to uniquely identify your app during authentication requests.
548+
`jetty.openid.clientSecret`::
549+
The Client Secret issued by the OpenID Provider, used to verify your application's identity during the authentication process. This must be kept confidential.
550+
527551
[[qos]]
528552
== Module `qos`
529553

‎documentation/jetty/modules/operations-guide/pages/security/openid-support.adoc

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
//
2+
// ========================================================================
3+
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
4+
//
5+
// This program and the accompanying materials are made available under the
6+
// terms of the Eclipse Public License v. 2.0 which is available at
7+
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
8+
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
9+
//
10+
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
11+
// ========================================================================
12+
//
13+
14+
[[openid-support]]
15+
= OpenID Support
16+
17+
A more general discussion about OpenID and its support in Jetty is available in the xref:programming-guide:security/openid-support.adoc[programming guide section].
18+
19+
== OpenID Provider Configuration
20+
21+
To enable OpenID support, you need to enable the xref:operations-guide:modules/standard.adoc#openid[`openid` module]:
22+
23+
----
24+
$ java -jar $JETTY_HOME/start.jar --add-modules=openid
25+
----
26+
27+
To configure OpenID Authentication with Jetty you will need to specify the OpenID Provider's issuer identifier (a case-sensitive URL) and the OAuth 2.0 Client ID and Client Secret.
28+
29+
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.
30+
31+
These values can be set as properties in `$JETTY_BASE/start.d/openid.ini` file.
32+
Refer to the xref:modules/standard.adoc#openid[`openid`] Jetty module for the list of configurable properties.
33+
34+
This is an example of an `openid.ini` file which uses discovery of the OpenID endpoints:
35+
36+
----
37+
## The OpenID Identity Provider's issuer ID (the entire URL *before* ".well-known/openid-configuration")
38+
jetty.openid.provider=https://id.example.com/
39+
40+
## The Client Identifier
41+
jetty.openid.clientId=test1234
42+
43+
## The Client Secret
44+
jetty.openid.clientSecret=XT_Mafv_aUCGheuCaKY8P
45+
----
46+
47+
== Web Application Specific Configuration in `web.xml`
48+
49+
The web application's `web.xml` file needs some specific configuration to use OpenID.
50+
51+
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.
52+
53+
To set the error page, you must set an `context-param` named `org.eclipse.jetty.security.openid.error_page` whose value should be a path relative to the web application where authentication errors should be redirected.
54+
55+
For example:
56+
57+
[,xml,subs=attributes+]
58+
----
59+
<?xml version="1.0" encoding="UTF-8"?>
60+
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
61+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
62+
xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
63+
version="6.0">
64+
...
65+
<login-config>
66+
<auth-method>OPENID</auth-method>
67+
<realm-name>https://accounts.google.com</realm-name>
68+
</login-config>
69+
70+
<context-param>
71+
<param-name>org.eclipse.jetty.security.openid.error_page</param-name>
72+
<param-value>/error</param-value>
73+
</context-param>
74+
...
75+
</web-app>
76+
----
77+
78+
== Authorization with Security Roles
79+
80+
If security roles are required, they can be configured through a wrapped `LoginService` which is deferred to for role information by the `OpenIdLoginService`, and assigns security roles to users.
81+
82+
You can configure the wrapped `LoginService` by modifying the `$JETTY_BASE/etc/openid-baseloginservice.xml` file.
83+
84+
You can further configure whether to only authenticate users known to the wrapped `LoginService` by configuring the property `jetty.openid.authenticateNewUsers` in the `$JETTY_BASE/start.d/openid.ini` file.
85+
86+
== Supporting Multiple OpenID Providers
87+
88+
By default, Jetty defines one OpenID Provider that you can configure using the properties defined in the `$JETTY_BASE/start.d/openid.ini` file.
89+
90+
You can support multiple OpenID Providers by creating a custom Jetty module (as described in xref:operations-guide:modules/custom.adoc[this section]).
91+
The custom Jetty module XML file should add an additional `OpenIdConfiguration` as a bean on the `Server` instance, for the additional OpenID Provider.
92+
93+
If there are multiple OpenID configuration instances in the `Server`, then the `OpenIdAuthenticationFactory` will select the one with an `issuer` matching the `<realm-name>` of the `<login-config>` element in the `web.xml` of a given web application.

‎documentation/jetty/modules/programming-guide/nav.adoc

+1
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@
4646
* Jetty Security
4747
** xref:security/siwe-support.adoc[]
4848
** xref:security/configuring-form-size.adoc[]
49+
** xref:security/openid-support.adoc[]
4950
* Migration Guides
5051
** xref:migration/94-to-10.adoc[]
5152
** xref:migration/11-to-12.adoc[]

‎documentation/jetty/modules/programming-guide/pages/security/openid-support.adoc

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
//
2+
// ========================================================================
3+
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
4+
//
5+
// This program and the accompanying materials are made available under the
6+
// terms of the Eclipse Public License v. 2.0 which is available at
7+
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
8+
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
9+
//
10+
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
11+
// ========================================================================
12+
//
13+
14+
[[openid-support]]
15+
= OpenID Support
16+
17+
Jetty supports authentication using the OpenID Connect protocol (see link:https://openid.net/specs/openid-connect-core-1_0-final.html[OpenID Connect Core 1.0]).
18+
19+
This allows users to authenticate with third party OpenID Providers, making possible to integrate features like "Sign in with Google" or "Sign in with Microsoft", among others.
20+
21+
With OpenID Connect, Jetty applications can offload the responsibility of managing user credentials while enabling features like single sign-on (SSO).
22+
23+
== External Configuration
24+
25+
To use OpenID Connect authentication with Jetty you are required to set up an external OpenID Provider for your web application; some examples of OpenID Providers are link:https://developers.google.com/identity/protocols/OpenIDConnect[Google] and link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html[Amazon].
26+
27+
Once you have set up your OpenID Provider you will have access to a Client ID and Client Secret which you can use to configure Jetty.
28+
29+
You must also configure your OpenID Provider to recognize the redirect URIs that your web application will use to handle authentication responses.
30+
By default, the redirect path is `/j_security_check`, but this can be customized through the `OpenIdAuthenticator` configuration if needed.
31+
32+
For example, you may wish to register the following URIs:
33+
34+
* For a deployed application, `+https://example.com/j_security_check+`.
35+
* For local development, `+http://localhost:8080/j_security_check+`.
36+
37+
Ensure that all relevant environments where your web application is deployed have their corresponding URIs registered with the OpenID Provider to avoid authentication errors.
38+
39+
== Jetty Configuration
40+
41+
=== Code Example
42+
43+
This is an example of how you can configure OpenID Connect authentication with an embedded Jetty environment with the Jetty Core API.
44+
45+
[,java,indent=0]
46+
----
47+
include::code:example$src/main/java/org/eclipse/jetty/docs/programming/security/OpenIdDocs.java[tags=openIdConfigExample]
48+
----
49+
50+
=== Application Usage
51+
52+
Here is an example of a Jetty Core `Handler` which handles authenticated requests by accessing the OpenID claims, and also handles authentication errors at `/error`.
53+
54+
[,java,indent=0]
55+
----
56+
include::code:example$src/main/java/org/eclipse/jetty/docs/programming/security/OpenIdDocs.java[tags=openIdUsageExample]
57+
----
58+
59+
==== Claims and Access Token
60+
Claims about the user can be found using attributes in the HTTP session attribute `org.eclipse.jetty.security.openid.claims`, and the full response containing the OAuth 2.0 Access Token can be found in the HTTP session attribute `org.eclipse.jetty.security.openid.response`.
61+
62+
=== Authorization with Security Roles
63+
64+
If security roles are required, they can be configured through a wrapped `LoginService` which is deferred to for role information by the `OpenIdLoginService`.
65+
66+
The wrapped `LoginService` be configured through the constructor arguments of `OpenIdLoginService`, or left `null` if no user roles are required.
67+
68+
When using authorization roles, the property `authenticateNewUsers`, which can be configured through the `OpenIdConfiguration` or directly on the `OpenIdLoginService`, becomes significant.
69+
70+
When `authenticateNewUsers` is set to `true`, users not found by the wrapped `LoginService` will still be authenticated but will have no roles.
71+
72+
When `authenticateNewUsers` is set to `false`, users not found by the wrapped `LoginService` will be not be allowed to authenticate and are redirected to the error page.

0 commit comments

Comments
 (0)
Please sign in to comment.