Add openid and siwe documentation sections.
Signed-off-by: Lachlan Roberts <lachlan@webtide.com>
This commit is contained in:
Lachlan Roberts
parent
70e619208d
commit
614025aed8
|
|
@ -0,0 +1,134 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.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}"]
|
||||
----
|
||||
<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.
|
||||
|
|
@ -0,0 +1,134 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.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}"]
|
||||
----
|
||||
<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.
|
||||
Loading…
Reference in New Issue