Publication Date: 2018-01-11
Approval Date: 2017-12-07
Posted Date: 2017-11-13
Reference number of this document: OGC 17-021
Reference URL for this document: http://www.opengis.net/doc/PER/t13-AB002
Category: Public Engineering Report
Editor: Andreas Matheus
Title: OGC Testbed-13: Security ER
Copyright © 2018 Open Geospatial Consortium. To obtain additional rights of use, visit http://www.opengeospatial.org/
This document is not an OGC Standard. This document is an OGC Public Engineering Report created as a deliverable in an OGC Interoperability Initiative and is not an official position of the OGC membership. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an OGC Standard. Further, any OGC Engineering Report should not be referenced as required or mandatory technology in procurements. However, the discussions in this document could very well lead to the definition of an OGC Standard.
Permission is hereby granted by the Open Geospatial Consortium, ("Licensor"), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement.
If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.
THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD. THE INTELLECTUAL PROPERTY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.
This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.
Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications.
This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.
None of the Intellectual Property or underlying information or technology may be downloaded or otherwise exported or reexported in violation of U.S. export laws and regulations. In addition, you are responsible for complying with any local laws in your jurisdiction which may impact your right to import, export or use the Intellectual Property, and you represent that you have complied with any regulations or registration procedures required by applicable law to make this license enforceable.
- 1. Summary
- 2. References
- 3. Terms and definitions
- 4. Abbreviated terms
- 5. Overview
- 6. Overview to Standards leveraged in this ER
- 7. OAuth2 Plugin
- 7.1. The Trust Principle for OAuth2
- 7.2. OAuth2 Trust for QGIS
- 7.3. Registration of the OAuth2 Plugin
- 7.4. Dynamic Client Registration (RFC 7591)
- 7.5. Registration of the OAuth2 Plugin in TB13
- 7.6. Software Statements for Testbed 13
- 7.7. The QGIS Authentication Framework
- 8. SAML2 Plugin
- 9. OAuth-enabled Web Processing Service
- 10. Security in Workflows
- 11. Technology Integration Experiments
- 12. Conclusions and Future Work
- 12.1. Conclusions
- 12.2. Implications to OGC Standardization Efforts
- 12.3. Future Work
- Appendix A: Technology Integration Tests
- Appendix B: How to use the QGIS Plugin for OAuth2
- Appendix C: How to use the QGIS Plugin for SAML2
- Appendix D: Revision History
- Appendix E: Bibliography
The Security Engineering Report (ER) covers two Testbed 13 topics:
The implementation of authentication and authorization plugins for the QGIS open source desktop GIS client and
the implementation of secured workflow.
The authentication plugins implement the SAML2 ECP with PAOS binding and IdP discovery from the SAML2 federation metadata URL. The access right delegation plugin implements applicable OAuth2 grant types.
Regarding the first topic, this ER discusses the "fit for purpose" aspects for the OAuth2 and SAML2 in the context of an open source desktop application. It also covers the QGIS development as well as building and deployment aspects. Most of the work related to this topic was provided by Secure Dimensions.
Regarding the second topic, this ER outlines the architecture approach and the implications to implementations for security in OGC service workflows as well as the implementation approach itself. Most of the work related to this topic was provided by 52°North.
The requirements addressed by this ER are the implementation of access right delegation (OAuth2) plugin for QGIS as an extension to version 2.18.4. These are able to use OAuth2 protected services WMS and WMTS provided by Dutch Cadaster.
The requirement for workflow security is also to document the following use cases, as implemented by 52°North:
Use Case 1: Dominating Privileges
Use Case 2: Tunneling Proxies
Use Case 3: Identity Mediation
The security state before the Testbed 13 was that the QGIS Open Source desktop GIS was capable to connect to OAuth2 protected OGC Web Services, but a manual registration with Authorization Servers was required.
QGIS was not able to connect to OGC Web Services (OWS) protected with version 2 of the Security Assertion Markup Language (SAML). It was also not possible to construct workflows of protected OGC Web Services.
After Testbed 13, the Open Source desktop GIS QGIS can be used to connect to protected services leveraging OAuth2 and the plugin registration is simplified by the use of digitally signed software statements and Dynamic Client Registration. Now, it is also possible to connect to SAML2 protected OGC Web Services that support the SAML2 Enhanced Client Proxy Protocol (ECP). In workflows, different security recommendations (in addition to those exposed in Testbed 12) will enable the construction and execution of workflows comprised of secured OGC services.
This ER has security applicability (implications) to different OGC working groups, as security is a crosscutting theme across the entire OGC domain.
For the OGC Security Domain Working Group (DWG), this ER provides results towards the use of "modern" security solutions like OAuth2 and SAML2 which expands the generally simple authentication, such as HTTP BASIC authentication. It should thereby stimulate the use of modern security in infrastructures to make protected data sets available via OGC Web Services. Beside the technical merit, this should provide new security based business opportunities.
For the OWS Common Security Standards Working Group (SWG), the implementation of the security extension to QGIS will enable testing the described approach of annotated capabilities regarding aspects like 'fit for purpose'. The feedback will be valuable to the SWG in the process of standardizing the interoperability aspects.
The aspects of workflow security may introduce novel approaches to develop and execute workflows of secured services. It should stimulate discussions in the Workflow DWG and the Security DWG regarding the 'fit for purpose' and interoperability aspects.
All questions regarding this document should be directed to the editor or the contributors:
University of the Bundeswehr
It is expected that this ER stimulates future work regarding the OGC to standardize requirements for client applications to work on modern security aspects and the work being standardized by the OWS Common SWG. More details can be found in section "Conclusions and Future Work".
Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.
The following normative documents are referenced in this document.
For the purposes of this report, the definitions specified in Clause 4 of the OWS Common Implementation Standard OGC 06-121r9 shall apply. In addition, the following terms and definitions apply.
The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.[RFC 6749]
The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.[RFC 6749]
A Free and Open Source Geographic Information System[http://qgis.org]
API Application Programming Interface
AS Authorization Server
ECP Enhanced Client Proxy Profile
RS Resource Server
OIDC OpenID Connect
RFC Request For Comments
OP OpenID Connect Identity Provider
OWS OGC Web Service
SAML Security Assertion Markup Language
This public engineering report is being produced during the OGC Testbed 13, executed from April to December 2017. Even though the title is broad, this document focuses on specific security topics that were worked on during Testbed 13.
This document contains the following information:
Introduction / Overview to the OAuth2 / OpenID Connect and SAML2 standards as they are key to the activities covered by the ER.
Detailed discussion on the use of OAuth2 with Open Source desktop applications, such as QGIS
The use of the QGIS plugin for OAuth2 and the options to register the plugin with OAuth2 Authorization Servers
The use of the QGIS plugin for SAML2
How to compile and install the QGIS plugins for OAuth2 and SAML2
Introduction and details on implementation of security in workflows based on the OGC Web Processing Service (WPS)
Technology Integration tests regarding the QGIS plugin for OAuth2
This document was reviewed and approved by the OGC Security DWG on November xx, 2017
Please note that URL provided in this document will not last forever. It is the responsibility of the participant to keep the URL active until 6 months after the end of Testbed 13; which is 1st July 2018.
This section provides a brief overview to security standards used in the testbed. For any detail not presented, the interested reader should become familiar with the standard itself by downloading a copy from the standardization organization. The URLs can be found in the References section.
The Security Assertion Markup Language (SAML) is a standard of the Organization for the Advancement of Structured Information Standards (OASIS), an alliance partner of the OGC. SAML is concerned with authentication and assertion exchange in trusted distributed systems to support Single-Sign-On and Federated Identity Management.
Many years ago, the OGC Shibboleth Interoperability Experiment conducted a study and prototype implementation of SAML with OGC Web Services. For more information on SAML and how to apply it to OGC Web services, please follow the link to the Public Engineering Report provided in the Bibliography chapter.
First, one should stress what OAuth2 is not about: It is not about authentication and it is also not about authorization.
Instead, the OAuth2 specification describes a framework that enables users to delegate a (controlled) set of rights to an application so that it can access the users' resources. The cool thing about the delegation is that the users must not share their original login credentials with an application. Instead, the users approve the release of a - so called - access token to the application that "carries" the approved set of rights. The application can then present the access token with the actual request to access the user’s resources. The user is the actor in OAuth2 called Resource Owner.
The most dominant use cases concentrate around social platforms like Facebook, Twitter, etc. where the users grant a particular application access to user profile, emails, blogs, etc. It is not relevant who created the application, but it is important that the user trusts the application. As the user cannot establish bi-lateral trust, the OAuth2 specification introduces a 3rd party called Authorization Server.
The Authorization Server is the actor that allows application developers to register and manage their applications. Once registered, the Authorization Server is capable of releasing access tokens to the application once granted by the user. But before the user can approve the release of an access token (which keeps a certain set of rights), the user must authenticate with the Authorization Server. How this authentication takes place is outside the OAuth2 specification. But it is mandatory that the authentication provides the Authorization Server with sufficient information about the user.
The third actor in the OAuth2 framework is the Resource Server. This actor is responsible for authorizing requests from applications to user resources. Basically, the Resource Server must first check if the access token is valid; and if it is, check whether the requested action on the resource was previously approved by the user. OAuth2 manages the associations between different rights and access tokens via scopes. If the request to the resource is involving a scope that is carried by the attached access token, then the resource is returned. In case that the application does ask for an action on the resource which is not covered by the scopes associated with the access token, then the Resource Server returns an error.
From a business perspective, OAuth2 enables a market place where developers can build and register applications that can be run by users to do "cool" things with their resources like pictures, emails, messages etc. Business takes place if a user decides to run an application and either pays money for the use or the application displays advertisements. Either way, it is attractive for developers to register applications with an Authorization Server to make business. The OAuth2 trust model is exactly built for that: Individual developers register applications that can be trusted and run by users to do cool things with their data.
This ER would not be about security if it did not mention the dark side of the things: If the user trusts a malicious application, all kinds of attacks can be thought of that span from remote control to the user’s data to forged (money) transactions in particular in scenarios with one-click-payments enabled.
The Email Alert Application can be used to illustrate the OAuth2 framework in more detail and to show the limitations of OAuth2.
The Email Alert Application shall be an application that runs on a mobile device that processes user emails and generates alerts when certain conditions on emails occur. For example, the user could configure an alert that if receiving emails on the OGC TB13 from the initiative director after business hours (which quite often happens for European users) to initiate an automatic reply stating that it is off-hours. To bring the Email Alert Application to live, we need a developer for the application and an Authorization Server. Say that Secure Dimensions implemented the application and registered it with the Google Play Store. Once the user has installed and started the application, it will ask for setting up trigger conditions. Once the user has done that, the application will ask the user for permission to access the emails stored at GMail: "Please delegate access rights to read your emails stored at GMail and send emails under your name". Once the user has approved this delegation, the application can start fetching emails and check for the alert condition.
This version of the application has one important shortcoming caused by the nature of OAuth2: The application has no information about the user. The access token approved by the user just carries the rights for the application to access the emails of the user but there is no information about the user! Therefore, it is for example not possible for the application - unless it received the information from the user itself - to respond with proper greetings at the end such as "regards Andreas". In other words, with the information from OAuth2, the application could only send a generic message "Your email was received during off-hours. I will start processing my emails tomorrow starting 8 o’clock UTC". Please note that at this point we are stressing the lack of user information, making it difficult to motivate the OAuth2 upgrade to OpenID Connect.
The OpenID Connect specification is an extension to the OAuth2 framework that enables an Authorization Server to also release user information to the application. For the sake of differentiation, an OpenID Connect compliant Authorization Server is called an OpenID Connect Provider or OIDC Provider (OP). The compliance requires that three requirements are implemented: (i) The OP releases the so-called ID Token, which is a JSON Web Token that contains information about the user that delegates access rights to the application; (ii) the ID Token follows the structure defined in the specification; and (iii) the OP operates the UserInfo endpoint. Without going into details, OIDC also introduces additional flows for how the OP can release tokens to the applications. The default is that the OP releases the ID token with the access token or authentication code. This enables the application to establish a user session from the start of the flow, which can be quite handy as we will see with the example Email Alert Service.
Even though OIDC introduces authentication to the OAuth2 flow, one must keep in mind that it is just an extension and therefore is restricted to the OAuth2 framework and the specified flow. However, the introduction of the hybrid flows provides more flexibility and control to the application when requesting tokens.
An OP can basically release three different types of tokens:
id_token: OIDC specific token that contains claims (information) about the current user
access_token: OAuth2 token that carries the delegated rights
refresh_token: An OAuth2 token that technically enables the application to request new (fresh) access tokens from the OP (AS respectfully) once the issued access token is expired.
The Email Alert Application is now split into two parts: The client part installed on the user’s mobile device and a service back-end that can store conditions and process emails to raise alerts. This application is now registered with an OIDC compliant Authorization Server - hence an OP.
With the user’s consent that the application can process the user’s emails, the OP releases an access token (as before) but now as the duty to OIDC, it also releases an ID token. The ID token can then be used by the application to establish a user session with the backend service as well as sending emails with proper greetings (assuming that the ID token contained the user’s name).
In OAuth2, the access (and the refresh) tokens by default are opaque to the application and the Resource Server. That means that it always requires the Authorization Server to validate the access token or to obtain any more information associated with the token.
In that respect, RFC 7662 "OAuth 2.0 Token Introspection" introduces an Authorization Server endpoint that allows the Resource Server to fetch token specific metadata. Some information provided might also be about the user. But it is important to note that this endpoint was not introduced to return user information such as profile information, emails, pictures, messages, etc. The OpenID Connect specification introduces the UserInfo endpoint for exactly that purpose.