Using API key-based authentication with GeoAnalytics Engine

[DerekGourley]

Security and governance for authorized users is important in managing your analytics environment. To help with this, GeoAnalytics Engine 1.5.0 introduced the ability to create (and delete) API keys to provide access to users across your organization. This expands on the GeoAnalytics Engine authorization methods for the connected license, by allowing an API key to be used in place of a username and password. With API keys, a single GeoAnalytics Engine subscription can be used by an administrator to easily control users access by sharing, revoking, and rotating the API keys as needed. In this blog post, we will walk through the steps needed to create and use the new API key authorization method.

Creating an API key

GeoAnalytics Engine API keys are created using the GeoAnalytics Engine dashboard associated with the account. We will describe the steps to create an API key in this section.

Note: We recommend checking with your security/IT teams and following their policies and guidelines for best practices on how to securely store and use API keys generated for use with GeoAnalytics Engine.

1. Select the “Developer credentials” tab and click the “New developer credentials” button.
   
2. The "Create developer credentials" pop-up window will appear. In this window set the expiration date and optionally the referrer URLs, then click the “next” button.
   
3. Give the API key a unique title (e.g., based on the user or group that will be assigned the API key) and optionally fill out the other settings, then click the “next” button.
   
4. Review the API key settings before generating the credentials and then click the "next" button.
5. An option will be provided to generate the API key now or later. Select an option and click the "next" button.
   
   

   Note: Once the API key is generated, it must be copied immediately to a secure location, given that it is not stored for future access. Following the API key security best practices will help keep the API key secure.

   

6. If the option to generate the API key “now” was selected, the API key will appear in a new pop-up window. This API key is used to authorize GeoAnalytics Engine. As noted in step 5 above, following the security best practices will help keep the API key secure.

Authenticating GeoAnalytics Engine using the API key

To authorize GeoAnalytics Engine, first import the “geoanalytics” module. Then use the API key that was generated in the previous step, or use an existing API key, and pass it in as a string value to the “api_key” parameter of the GeoAnalytics Engine authorization function.

import geoanalytics
geoanalytics.auth(api_key="<API key goes here>")

A secret management system can also be used to help keep the API key secure (visibly redacted) and can be used to pass the API key string directly into the API key parameter.

To verify that GeoAnalytics Engine was authorized successfully, use geoanalytics.auth_info().

geoanalytics.auth_info().show()

If the authorization is successful, this will return a table containing the GeoAnalytics Engine authorization information. When using an API key, the "auth" row will have a value of "token/apikey". For demo purposes, the other row values that would normally be returned in the table were left blank.

+---------------+------------+
|           name|       value|
+---------------+------------+
| session_uptime|            |
|           auth|token/apikey|
|          scope|            |
|        offline|            |
|        metered|            |
|     authorized|        true|
|       username|            |
|   billing_type|            |
|available_hours|            |
|  session_usage|            |
+---------------+------------+

If the API key is invalid or deactivated, the GeoAnalytics Engine authorization function will return a “not authorized” error and the "auth_info" table returned will be empty.

To further verify that GeoAnalytics Engine is working successfully, you can run the following sample code below.

# Imports
from geoanalytics.sql import functions as ST, Point

# Create a DataFrame
data = [
    (1, Point(2279074.576461232, 103019.15556246601)),
    (2, Point(2278748.209109826, 103521.65548041835)),
    (3, Point(2279243.741068326, 103250.88697086088))
]
df = spark.createDataFrame(data, ["id", "point"]) \
          .withColumn("point", ST.srid("point", 6558))
df.printSchema()
df.show(truncate=False)

# Plot the DataFrame (Note: `%matplotlib inline` might be needed to make the plot appear)
df_plot = df.st.plot(basemap="light", xmargin=0.15, ymargin=0.3, figsize=(10,10));
df_plot.set_title("Oregon State University points of interest")
df_plot.set_xlabel("X (Meters)")
df_plot.set_ylabel("Y (Meters)");

root
 |-- id: long (nullable = true)
 |-- point: point (nullable = true)

+---+----------------------------------------------+
|id |point                                         |
+---+----------------------------------------------+
|1  |{"x":2279074.576461232,"y":103019.15556246601}|
|2  |{"x":2278748.209109826,"y":103521.65548041835}|
|3  |{"x":2279243.741068326,"y":103250.88697086088}|
+---+----------------------------------------------+

Conclusion

In this blog post we looked at how GeoAnalytics Engine 1.5.0 can be authorized using the new API key method. Hopefully, this post has been helpful with getting started using this new authorization method for your analytics workflows. If you have any questions about this new authorization method or any of the other GeoAnalytics Engine tools or functions, please feel free to provide feedback or ask questions in the comments section below.