Server 8.3. PingFederate CORS Support

Transcription

1 Server 8.3 PingFederate CORS Support

2 Copyright Ping Identity Corporation. All rights reserved. PingFederate CORS Support April 18, 2017 Ping Identity Corporation th Street, Suite 100 Denver, CO U.S.A. Trademark Ping Identity, the Ping Identity logo, PingAccess, PingFederate, PingID, and PingOne are registered trademarks of Ping Identity Corporation ( Ping Identity ). All other trademarks or registered trademarks are the property of their respective owners. Disclaimer The information provided in this document is provided as is without warranty of any kind. Ping Identity disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. In no event shall Ping Identity or its suppliers be liable for any damages whatsoever including direct, indirect, incidental, consequential, loss of business profits or special damages, even if Ping Identity or its suppliers have been advised of the possibility of such damages. Some states do not allow the exclusion or limitation of liability for consequential or incidental damages so the foregoing limitation may not apply.

3 2 Contents Enable CORS support in PingFederate 3 Configure a CORS servlet filter 3 Additional notes 4 Enable the OPTIONS HTTP method 5 Enable CORS Logging 6

4 3 Enable CORS support in PingFederate PingFederate uses the Jetty Web Server to listen and respond to HTTP requests. Jetty supports cross-origin resource sharing (CORS), which can be enabled in PingFederate for its OAuth endpoints to participate in cross-origin interaction with applications that run within a web browser. Configuring CORS in PingFederate requires two steps: Configure a servlet filter and enable OPTIONS as a supported HTTP method. Configure a CORS servlet filter 1. Edit the <pf_install>/pingfederate/etc/webdefault.xml file. 2. Locate the session-config element under the Dynamic Servlet Invoker section. 3. Insert the following filter and filter-mapping elements above the session-config element: <filter> <filter-class>org.eclipse.jetty.servlets.crossoriginfilter</filter-class> <param-name>allowedorigins</param-name> <param-value> <param-name>allowedmethods</param-name> <param-value>get,post,head,options</param-value> <param-name>allowedheaders</param-name> <param-value> X-Requested-With,Content-Type,Accept,Origin,Authorization </param-value> </filter> <filter-mapping> <url-pattern>/as/token.oauth2</url-pattern> <url-pattern>/idp/userinfo.openid</url-pattern> <url-pattern>/pf/jwks</url-pattern> </filter-mapping> <session-config> Note: Replace the allowedorigins value of with the actual origin of the JavaScript controller application.

5 4 4. For security reasons, limit the number of origin applications. As needed, you can enable multiple origin applications by using a comma-separated list as the allowedorigins value; for example: <filter> <filter-class>org.eclipse.jetty.servlets.crossoriginfilter</filter-class> <param-name>allowedorigins</param-name> <param-value> <param-name>allowedmethods</param-name> <param-value>get,post,head,options</param-value> <param-name>allowedheaders</param-name> <param-value> X-Requested-With,Content-Type,Accept,Origin,Authorization </param-value> </filter> <filter-mapping> <url-pattern>/as/token.oauth2</url-pattern> <url-pattern>/idp/userinfo.openid</url-pattern> <url-pattern>/pf/jwks</url-pattern> </filter-mapping> Note: For a clustered PingFederate environment, repeat these steps on each engine node. Additional notes Restart of PingFederate is required to activate any changes made in the webdefault.xml file. The sample allowedheaders value ( X-Requested-With,Content-Type,Accept,Origin,Authorization ) is not an exhaustive list. As needed, you can modify the value based on headers expected from your end user browsers, the reverse proxy server, and other networking devices. Modify the url-pattern value to include resources suitable for your use cases. For example, if none of your use cases involve the OpenID Connect User Information endpoint, do not include such url-pattern value. For more information on Jetty and its CORS support, please refer to documentation from Jetty (

6 5 Enable the OPTIONS HTTP method Client-side JavaScript applications make HTTP OPTIONS requests to determine whether actual requests are safe to send for cross-origin interactions. Edit the webdefault.xml file to enable the OPTIONS HTTP method. 1. Edit the <pf_install>/pingfederate/etc/webdefault.xml file. 2. Locate the security-constraint element. 3. Add OPTIONS as a supported http-method value in the second web-resource-collection element; for example: <security-constraint> <web-resource-collection> <web-resource-name> Enable all methods except for HEAD, TRACE, OPTIONS </web-resource-name> <url-pattern>/as/authorization.oauth2</url-pattern> <http-method>get</http-method> <http-method>post</http-method> <http-method>put</http-method> <http-method>delete</http-method> <http-method>connect</http-method> <http-method>patch</http-method> </web-resource-collection> <web-resource-collection> <web-resource-name>enable all methods except for TRACE</web-resource-name> <url-pattern>/*</url-pattern> <http-method>get</http-method> <http-method>post</http-method> <http-method>put</http-method> <http-method>delete</http-method> <http-method>connect</http-method> <http-method>patch</http-method> <http-method>head</http-method> <http-method>options</http-method> </web-resource-collection> </security-constraint> 4. Restart PingFederate. Note: For a clustered PingFederate environment, repeat these steps on each engine node.

7 6 Enable CORS Logging Optionally, you can enable additional logging to troubleshoot CORS requests. 1. Edit the <pf_install>/pingfederate/server/default/conf/log4j2.xml file. 2. Locate the Limit categories section. 3. Add the CrossOriginFilter category as follows: <!-- ================ --> <!-- Limit categories --> <!-- ================ --> <Logger name="org.eclipse.jetty.servlets.crossoriginfilter" level="debug" /> <Logger name="httpclient.wire.content" level="info" /> 4. Restart PingFederate. Tip: For better performance, change the level attribute value to info when debug messages are no longer required. Because the logger has already been added, updating its level attribute value does not require a restart of PingFederate. Note: For a clustered PingFederate environment, repeat these steps on each engine node.