From da9ec6fd34e5cf60ff248aab1c32a1f4bf3ed859 Mon Sep 17 00:00:00 2001 From: Chris Walker Date: Wed, 26 Feb 2020 21:27:45 -0600 Subject: [PATCH] Docs for OpenID (#4610) Co-authored-by: Lachlan --- .../distribution-guide/security/chapter.adoc | 1 + .../security/openid-support.adoc | 139 ++++++++++++++++++ 2 files changed, 140 insertions(+) create mode 100644 jetty-documentation/src/main/asciidoc/distribution-guide/security/openid-support.adoc diff --git a/jetty-documentation/src/main/asciidoc/distribution-guide/security/chapter.adoc b/jetty-documentation/src/main/asciidoc/distribution-guide/security/chapter.adoc index 9d9be40d323..8f9cdcd34db 100644 --- a/jetty-documentation/src/main/asciidoc/distribution-guide/security/chapter.adoc +++ b/jetty-documentation/src/main/asciidoc/distribution-guide/security/chapter.adoc @@ -26,3 +26,4 @@ include::secure-passwords.adoc[] include::setting-port80-access-for-non-root-user.adoc[] include::jaas-support.adoc[] include::spnego-support.adoc[] +include::openid-support.adoc[] diff --git a/jetty-documentation/src/main/asciidoc/distribution-guide/security/openid-support.adoc b/jetty-documentation/src/main/asciidoc/distribution-guide/security/openid-support.adoc new file mode 100644 index 00000000000..be5133210a3 --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/distribution-guide/security/openid-support.adoc @@ -0,0 +1,139 @@ +// +// ======================================================================== +// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others. +// +// This program and the accompanying materials are made available under +// the terms of the Eclipse Public License 2.0 which is available at +// https://www.eclipse.org/legal/epl-2.0 +// +// This Source Code may also be made available under the following +// Secondary Licenses when the conditions for such availability set +// forth in the Eclipse Public License, v. 2.0 are satisfied: +// the Apache License v2.0 which is available at +// https://www.apache.org/licenses/LICENSE-2.0 +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// ======================================================================== +// + +[[openid-support]] +=== OpenID Support + +==== External Setup + +===== Registering an App with OpenID Provider +You must register the app with an OpenID Provider such as link:https://developers.google.com/identity/protocols/OpenIDConnect#authenticatingtheuser[Google] or link:https://images-na.ssl-images-amazon.com/images/G/01/lwa/dev/docs/website-developer-guide._TTH_.pdf[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}"] +---- + + OPENID + https://accounts.google.com + + + org.eclipse.jetty.security.openid.error_page + /error + +---- + +==== 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 claims = (Map)request.getSession().getAttribute("org.eclipse.jetty.security.openid.claims"); +String userId = claims.get("sub"); + +Map 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.