| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>OpenID Support</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty"><link rel="up" href="configuring-security.html" title="Chapter 7. Configuring Security"><link rel="prev" href="spnego-support.html" title="SPNEGO Support"><link rel="next" href="configuring-jsp.html" title="Chapter 8. Configuring JSP Support"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><link rel="stylesheet" href="css/highlighter/foundation.css"><script src="js/highlight.pack.js"></script><script> |
| hljs.initHighlightingOnLoad(); |
| </script><link type="text/css" rel="stylesheet" href="css/font-awesome/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small"> |
| Version: 9.4.28-SNAPSHOT</span></td><td style="width: 50%"></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">OpenID Support</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="spnego-support.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a> </td><th width="60%" align="center">Chapter 7. Configuring Security<br><a accesskey="p" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></th><td width="20%" align="right"> <a accesskey="n" href="configuring-jsp.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at |
| <span class="website">www.webtide.com</span></a></h5><p> |
| private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... |
| scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development |
| </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="openid-support"></a>OpenID Support</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="openid-support.html#_external_setup">External Setup</a></span></dt><dt><span class="section"><a href="openid-support.html#_distribution_configuration">Distribution Configuration</a></span></dt><dt><span class="section"><a href="openid-support.html#_embedded_configuration">Embedded Configuration</a></span></dt><dt><span class="section"><a href="openid-support.html#_scopes">Scopes</a></span></dt><dt><span class="section"><a href="openid-support.html#_roles">Roles</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_external_setup"></a>External Setup</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_registering_an_app_with_openid_provider"></a>Registering an App with OpenID Provider</h4></div></div></div><p>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 <code class="literal">/j_security_check</code> so that the OpenId Provider will allow redirection back to the webapp.</p><p>These may look like</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">http://localhost:8080/openid-webapp/j_security_check</code></li><li class="listitem"><code class="literal">https://example.com/j_security_check</code></li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_distribution_configuration"></a>Distribution Configuration</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_openid_provider_configuration"></a>OpenID Provider Configuration</h4></div></div></div><p>To enable OpenID support, you first need to activate the <code class="literal">openid</code> module in your implementation.</p><div class="screenexample"><pre class="screen">java -jar {JETTY_HOME}/start.jar --add-to-start=openid</pre></div><p>To configure OpenID Authentication with Jetty you will need to specify the OpenID Provider’s issuer identifier (case sensitive URL using the <code class="literal">https</code> 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 <code class="literal">start.ini</code> or <code class="literal">start.d/openid.ini</code> files.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_webapp_specific_configuration_in_web_xml"></a>WebApp Specific Configuration in web.xml</h4></div></div></div><p>The <code class="literal">web.xml</code> file needs some specific configuration to use OpenID. |
| There must be a <code class="literal">login-config</code> element with an <code class="literal">auth-method</code> value of <code class="literal">OPENID</code>, and a <code class="literal">realm-name</code> value of the exact URL string used to set the OpenID Provider.</p><p>To set the error page, an init param is set at <code class="literal">"org.eclipse.jetty.security.openid.error_page"</code>, its value should be a path relative to the webapp where authentication errors should be redirected.</p><p>Example:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code><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></code></pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_embedded_configuration"></a>Embedded Configuration</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_define_the_literal_openidconfiguration_literal_for_a_specific_openid_provider"></a>Define the <code class="literal">OpenIdConfiguration</code> for a specific OpenID Provider.</h4></div></div></div><p>If the OpenID Provider allows metadata discovery then you can use.</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>OpenIdConfiguration openIdConfig = new OpenIdConfiguration(ISSUER, CLIENT_ID, CLIENT_SECRET);</code></pre><p>Otherwise you can manually enter the necessary information:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>OpenIdConfiguration openIdConfig = new OpenIdConfiguration(ISSUER, TOKEN_ENDPOINT, AUTH_ENDPOINT, CLIENT_ID, CLIENT_SECRET);</code></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_configuring_an_literal_openidloginservice_literal"></a>Configuring an <code class="literal">OpenIdLoginService</code></h4></div></div></div><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>LoginService loginService = new OpenIdLoginService(openIdConfig); |
| securityHandler.setLoginService(loginService);</code></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_configuring_an_literal_openidauthenticator_literal_with_literal_openidconfiguration_literal_and_error_page_redirect"></a>Configuring an <code class="literal">OpenIdAuthenticator</code> with <code class="literal">OpenIdConfiguration</code> and Error Page Redirect</h4></div></div></div><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>Authenticator authenticator = new OpenIdAuthenticator(openIdConfig, "/error"); |
| securityHandler.setAuthenticator(authenticator); |
| servletContextHandler.setSecurityHandler(securityHandler);</code></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_usage"></a>Usage</h4></div></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="_claims_and_access_token"></a>Claims and Access Token</h5></div></div></div><p>Claims about the user can be found using attributes on the session attribute <code class="literal">"org.eclipse.jetty.security.openid.claims"</code>, and the full response containing the OAuth 2.0 Access Token can be found with the session attribute <code class="literal">"org.eclipse.jetty.security.openid.response"</code>.</p><p>Example:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>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");</code></pre></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_scopes"></a>Scopes</h3></div></div></div><p>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 <code class="literal">profile</code> and <code class="literal">email</code> which will give you additional user claims.</p><p>Additional scopes can be requested through the <code class="literal">start.ini</code> or <code class="literal">start.d/openid.ini</code> files, or with <code class="literal">OpenIdConfiguration.addScopes(...);</code> in embedded code.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_roles"></a>Roles</h3></div></div></div><p>If security roles are required they can be configured through a wrapped <code class="literal">LoginService</code> which is deferred to for role information by the <code class="literal">OpenIdLoginService</code>.</p><p>This can be configured in XML through <code class="literal">etc/openid-baseloginservice.xml</code> in the Distribution, or in embedded code using the constructor for the <code class="literal">OpenIdLoginService</code>.</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>LoginService wrappedLoginService = ...; // Optional LoginService for Roles |
| LoginService loginService = new OpenIdLoginService(openIdConfig, wrappedLoginService);</code></pre><p>When using authorization roles, the setting <code class="literal">authenticateNewUsers</code> becomes significant. |
| If set to <code class="literal">true</code> users not found by the wrapped <code class="literal">LoginService</code> will still be authenticated but will have no roles. |
| If set to <code class="literal">false</code> those users will be not be allowed to authenticate and are redirected to the error page. |
| This setting is configured through the property <code class="literal">jetty.openid.authenticateNewUsers</code> in the <code class="literal">start.ini</code> or <code class="literal">start.d/openid.ini</code> file, or with <code class="literal">OpenIdLoginService.setAuthenticateNewUsers(...);</code> in embedded code.</p></div></div><script type="text/javascript"> |
| SyntaxHighlighter.all() |
| </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spnego-support.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a> </td><td width="20%" align="center"><a accesskey="u" href="configuring-security.html"><i class="fa fa-chevron-up" aria-hidden="true"></i> Top</a></td><td width="40%" align="right"> <a accesskey="n" href="configuring-jsp.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr><tr><td width="40%" align="left" valign="top">SPNEGO Support </td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></td><td width="40%" align="right" valign="top"> Chapter 8. Configuring JSP Support</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout"> |
| See an error or something missing? |
| <span class="callout"><a href="http://github.com/eclipse/jetty.project">Contribute to this documentation at |
| <span class="website"><i class="fa fa-github" aria-hidden="true"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2020-03-10)</i></span></div></p></body></html> |
