diff --git a/jetty-documentation/src/main/asciidoc/configuring/security/openid-support.adoc b/jetty-documentation/src/main/asciidoc/configuring/security/openid-support.adoc deleted file mode 100644 index 76e5fd2238ce..000000000000 --- a/jetty-documentation/src/main/asciidoc/configuring/security/openid-support.adoc +++ /dev/null @@ -1,139 +0,0 @@ -// -// ======================================================================== -// 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}"] ----- - - 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.