In modern web-based software, the need for secure and efficient authorization protocols is critical. Traditional methods of granting access to sensitive data often involve sharing usernames and passwords, which presents several risks to organizations. These risks include potential breaches of personal information, unauthorized access, and difficulties in managing permissions across various applications. These risks have resulted in many data providers choosing to secure their data using OAuth, which is an open standard authorization framework. To support ingesting or disseminating data using HTTP endpoints that are secured with OAuth, ArcGIS Velocity supports configuring the HTTP Poller feed and data source types and HTTP output type with OAuth.
What is OAuth?
Open Authorization (OAuth) is one of the most commonly used authorization frameworks. OAuth allows you to give one application, in this case, ArcGIS Velocity, permission to access your data or use features in another without directly providing your username and password. Instead of accessing your data source directly with a username and password, OAuth allows you to authorize yourself with an access token. An access token provides limited access to data at a secured endpoint for a specific period.
We can think of access tokens like a key card you receive when checking into a hotel. You are authenticated at the front desk using your driver’s license when you arrive at the hotel. Once this is complete, you are provided with a key card. This key card authorizes you to access your hotel room and other amenities like the gym or pool for the duration of your stay. It will only work for the rooms you can access and will not work after your hotel reservation ends. If you lose your key card, anyone else could use it, as it does not retain any information about how you were authenticated when you checked in. If needed, the hotel can also revoke the key card, which will stop working immediately.
Access tokens work very similarly in that we obtain them by authenticating with the authorization server. They specify the resources we can access and the duration of that access. Anyone can use the access token and the token can be revoked at any time.
General OAuth workflow
We have three primary components when using OAuth – our client, in this example, ArcGIS Velocity, an authorization server, and a resource server. The authorization server is a key component of OAuth and is responsible for authenticating users and issuing access tokens with proper access policies. It can do this because of the trust it has established with the resource server. The resource server will hold our secured resource, such as an API providing vehicle data access.
The first step of this workflow is for ArcGIS Velocity to request an access token from the authorization server. If this request is made correctly with the parameters the authorization server expects, the authorization server will return a response as shown in the image below. The response includes an access token, a refresh token, the token’s type, and an expiration value that tells us when the access token will expire. Note that refresh tokens are a central part of OAuth but are not required.
{
"access_token": "08bf97c5r29a77b38eba32455e950f435dxe677",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "2523f32db4aa52nalp906b2984301e4907b37x"
}After ArcGIS Velocity obtains an access token, it can use this access token to request data from the resource server.
ArcGIS Velocity can be configured to utilize the access token’s expiration value and refresh token to send a request to the authorization server’s refresh token endpoint when the access token expires. The refresh token endpoint will provide ArcGIS Velocity with a new access token and refresh token to use in subsequent requests.
Configuring OAuth in ArcGIS Velocity
OAuth 2.0 authorization is currently available for HTTP endpoints that follow the Client Credentials or Password grant types. Refresh token configuration is available for the HTTP Poller feed type and HTTP output type when configured in real-time analytics. The HTTP Poller data source type does not support refresh token configuration, as the source will only need to get an access token at the beginning of every big data analytic run or only once in a real-time analytic the first time the analytic starts. The HTTP output does not support refresh token configuration when used in a big data analytic for the same reason.
In the explanation below, I’ve opted to utilize the HTTP Poller feed type, as this will allow me to demonstrate the optional refresh token configuration step. I start the configuration process by choosing Create Feed > Web and Messaging > HTTP > HTTP Poller.
On the “Configure HTTP Poller” page, I will enter the HTTP endpoint used to access data on my resource server for the URL parameter. I’ve chosen GET as the HTTP Method, as my resource server expects a GET request from clients to pull data. For the custom headers parameter, I’ve set a parameter “Authorization”: “Bearer $accessToken,” as my resource server is configured to only return data if the incoming request includes an “Authorization” header with a valid bearer token as a value. Note that $accessToken is a global variable – ArcGIS Velocity will be able to populate this value and update it as needed based on the configuration we will complete below. Following these changes, I will select “OAuth” under “Authentication” and then select “Configure OAuth”. Your resource server may require URL parameters or additional headers, which should be added before preceding.
Next, I am prompted to configure options for requesting an access token. For the access token endpoint parameter, I will enter the HTTP endpoint to request an access token from my authorization server. Your HTTP Method, POST body, URL parameters, and custom headers will depend on the values expected by your access token endpoint. In this case, my authorization server expects a POST request with the expected values in the POST body for “grant_type”, “username”, “password”, “client_id”, “client_secret”, and “scope.”
When I click “Test”, ArcGIS Velocity will attempt to obtain an access token from the endpoint specified. If this test fails, verifying that you’ve configured the request successfully by attempting the same request outside of ArcGIS Velocity (ex: using Postman or PowerShell) can be helpful. You can also use the Developer Tools in your browser to see if your resource server returned a response or error to this test request.
If this test is successful, ArcGIS Velocity will prompt you to identify which key/value pair will be used to obtain your access token. In the case below, I will click “access_token”. As a note, ArcGIS Velocity expects a key/value pair and does not currently support other formats.
ArcGIS Velocity also provides the option to configure the refresh token and access token expiration from this page, both of which are optional. If a refresh token is specified without an expiration, ArcGIS Velocity will attempt a refresh token request if a data request fails twice in a row. In my case, I’ve chosen “refresh_token” as my refresh token and “expires_in” as my expiration. My access tokens expire after 3600 seconds, so I’ve selected “duration” and “seconds” for my expiration type. With these options selected, ArcGIS Velocity will automatically use the refresh token endpoint to obtain a new access token from the authorization server when the access token expires.
If a refresh token was configured in the previous step, we will need to configure a sample request to the refresh token endpoint, which will allow ArcGIS Velocity to obtain a new access token and refresh token. Similarly to the access token endpoint, I will enter the HTTP endpoint to request a refresh token from my authorization server for the refresh token endpoint parameter. Your Method, POST body, URL parameters, and Custom headers will depend on the values expected by your refresh token endpoint. In my case, my authorization server expects a POST request with the expected values in the POST body for “grant_type”, “refresh_token”, “client_id”, “client_secret”, and “scope.”
My refresh token endpoint requires that I provide my refresh token value in the POST body to obtain a new access token. In the refresh token request, ArcGIS Velocity supports both the $refreshToken and $accessToken global variables in the POST body, URL parameters, and custom headers, as the expected format and location of these global variables will depend on the authorization server configuration.
When I click “Test”, ArcGIS Velocity will attempt to obtain a refresh token from the endpoint specified. Similarly to the access token sample request, Postman, PowerShell, and your browser’s Developer tools can help troubleshoot unsuccessful connections. If this test is successful, ArcGIS Velocity will prompt you to identify which key/value pair will be used to obtain your access token and refresh token, similar to the workflow we followed above for the access token configuration. In my case, I’ve chosen “access_token” and “refresh_token.”
Following this, we are brought back to the “Configure HTTP Poller” page. When we click “Next”, ArcGIS Velocity will attempt a test connection call to your resource server using an access token from your authorization server. We can configure our schema, key fields, and feed polling interval as we would for any other HTTP Poller feed.
As a helpful note, the HTTP Poller feed and HTTP output include the option to “Enable Request Logging”. If a feed or output that uses OAuth is not working as expected, this property can be enabled to assist with troubleshooting. When this parameter is enabled, all access token, refresh token, and data requests will be logged in ArcGIS Velocity’s logs. If data is not being ingested or written as expected, view the responses from the access token, refresh token, and data requests to help identify if changes need to be made to your OAuth workflow. This property should only be enabled for troubleshooting purposes and disabled when troubleshooting is complete.
Conclusion
We can now successfully configure an HTTP Poller feed, data source, or HTTP output using the OAuth authorization, allowing us to utilize HTTP endpoints secured with OAuth 2.0 in our analytics in ArcGIS Velocity. Using the configuration outlined above, ArcGIS Velocity can successfully obtain access tokens and refresh those tokens as necessary, all without any manual user interaction, and utilize these tokens to access secured data. As OAuth is one of the most widely used authorization frameworks, this capability opens the door to utilizing these secured endpoints to support our GIS workflows.
Explore more on real-time GIS, visit the ArcGIS Velocity page here.
Article Discussion: