We were recently contacted for advice regarding our recommendations for securely accessing content on an enterprise ArcGIS Portal deployment from within QGIS. Fortunately, this setup is fully supported and works seamlessly in QGIS, thanks to the native integration of “OAuth2” authentication in QGIS!
This post details step-by-step instructions in setting up both ArcGIS Portal and QGIS to enable this integration. First, we’ll create a new desktop application on the Portal site in order to obtain the application-specific access keys for OAuth2 authentication. We’ll then create an authentication configuration in QGIS and associate this with a connection to the Portal site. Let’s dive in by doing the Portal configuration first…
Creating an application
Logon to the Portal, and from the “Content” tab, click the “Add Item” option. Select “An application” from the drop down list of options:
Set the type of the application as “Desktop”
You can fill out the rest of this dialog as you see fit. Suggested values are:
- Purpose: Ready to Use
- Platform: Qt
- URL: http://qgis.org
- Tags: QGIS, Desktop, etc
Now – here comes a trick. Portal will force you to attach a file for the application. It doesn’t matter what you attach here, so long as it’s a zip file. While you could attach a zipped copy of the QGIS installer, that’s rather wasteful of server space! We’d generally just opt for a zip file containing a text file with a download link in it.
Click Add Item when you’re all done filling out the form, and the new application should be created on the Portal.
Registering the Application
The next step is to register the application on Portal, so that you can obtain the keys required for the OAuth2 logon using it. From the newly created item’s page, click on the “Settings” tab:
Scroll right to the bottom of this page, and you should see a “Register” button. Press this. Set the “App type” to “Native“.
Add two redirect URIs to the list (don’t forget to click “Add” after entering each!):
- The Portal’s public address, e.g. https://mydomain.com/portal
Finally, press the “Register” button in the dialog. If all goes well then the App Registration section in the item settings should now be populated with details. From here, copy the “App ID” and “Secret” strings, we’ll need these later:
Determine Request URLs
One last configuration setting we’ll need to determine before we fire up QGIS is the Portal’s OAuth Request and Token URLs. These are usually found by appending /sharing/rest/oauth2/authorize and /sharing/rest/oauth2/token to the end of your Portal’s URL.
For instance, if your public Portal URL is http://mydomain.com/portal, then the URLs will be:
Request URL: http://mydomain.com/portal/sharing/rest/oauth2/authorize
Token URL: http://mydomain.com/portal/sharing/rest/oauth2/token
You should be able to open both URLs directly in a browser. The Request URL will likely give a “redirect URL not specified” error, and the Token URL will give a “client_id not specified” error. That’s ok — it’s enough to verify that the URLs are correct.
We’re all done on the Portal side now, so time to fire up QGIS!
Creating an QGIS OAuth2 Authentication Configuration
From your QGIS application, select Options from the Settings menu. Select the Authentication tab. We need to create a new authentication configuration, so press the green + button on the right hand side of the dialog. You’ll get a new dialog prompting you for Authentication details.
There’s a few tricks to this setup. Firstly, it’s important to ensure that you use the exact same settings on all your client machines. This includes the authentication ID field, which defaults to an auto-generated random string. (While it’s possible to automatically deploy the configuration as part of a startup or QGIS setup script, we won’t be covering that here!).
So, from the top of the dialog, we’ll fill in the “Name” field with a descriptive name of the Portal site. You then need to “unlock” the “Id” field by clicking the little padlock icon, and then you’ll be able to enter a standard ID to identify the Portal. The Id field is very strict, and will only accept a 7 letter string!
Drop down the Authentication Type combo box, and select “OAuth2 Authentication” from the list of options. There’s lots of settings we need to fill in here, but here’s what you’ll need:
- Grant flow: set to “Authorization Code”
- Request URL: enter the Request URL we determined in the previous step, e.g. http://mydomain.com/portal/sharing/rest/oauth2/authorize
- Token URL: enter the Token URL from the previous step, e.g. http://mydomain.com/portal/sharing/rest/oauth2/token
- Refresh Token URL: leave empty
- Redirect URL: leave as the default http://127.0.0.1:7070 value
- Client ID: enter the App ID from the Portal item’s App Registration information (see earlier steps)
- Client Secret: enter the App Secret from the Portal item’s App Registration information (see earlier steps)
- Scope: leave empty
- API Key: leave empty
That’s it — leave all the rest of the settings at their default values, and click Save.
You can close down the Options dialog now.
Adding the Portal Connection Details
Lastly, we’ll need to setup the Portal connection as an “ArcGISFeatureServer” and “ArcGISMapServer” connection in QGIS. This is done through the QGIS “Data Source Manager” dialog, accessed through the Layer menu. Click the “ArcGIS Feature Server” tab to start with, and then press “New” in the Server Connections group at the top of this dialog.
Enter a descriptive name for the connection, and then enter the URL for the ArcGIS server REST endpoint associated with your Portal:
Lastly, select the new OAuth2 configuration you just created under the “Authentication” group:
Click OK, and you’re done! When you try to connect to the newly added connection, you’ll automatically be taken to the Portal’s logon screen in order to authenticate with the server. After entering your details, you’ll then be connected securely to the server and will have access to all items which are shared with your user account on the Portal!
You can then repeat this step for and create a similar connection under the “ArcGIS Map Server” tab.
We’ve regularly use this setup for our enterprise clients, and have found it to work flawlessly in recent QGIS versions! If you’ve found this useful and are interested in other “best-practice” recommendations for mixed Open-Source and ESRI workplaces, don’t hesitate to contact us to discuss your requirements… at North Road we specialise in ensuring flawless integration between ESRI based systems and the Open Source geospatial software stack.