Support for regions

[sserrata]

• Palo Alto Networks Cloud Python SDK version: v1.5.0
• Python version: 2.7, 3.5+
• Operating System: any

Description

There are two scenarios where the concept of region is relevant:

• The region extracted from the base64 params provided by the Cortex Hub redirect which is used by the get_authorization_url() method, e.g. americas or europe.
• The region specified in the API gateway URL, e.g. api.us.paloaltonetworks.com or api.eu.paloaltonetworks.com (currently defaults to us).

The first is relevant to the identity provider while performing authorization whereas the second determines what regional datacenter to direct API requests to (which should correspond to where the Cortex data lake tenant, et al. reside).

Currently, pancloud is missing a way to set or define a default region that could be used to determine which regional datacenter to direct API requests to. With the current API, you're forced to supply the full API gateway url to direct API requests to a region other than api.us.paloaltonetworks.com, which is the default.

Proposals

1. Add a default_region kwarg to the HTTPClient class. The value provided, e.g. us or eu, could be used to construct the default url used in all API requests made with that HTTPClient() object. Note that default_region would not be applicable to the Credentials class.
2. Add support for a PAN_DEFAULT_REGION environment variable. The behavior would be similar to proposal 1 except that the default_region constructor argument would take precedence over the envar.
3. Add support for a default_region or region to the credentials.json file or credentials store. This one feels a bit out of place, since the region would not necessarily be applicable to Credentials. Again, the region used by get_authorization_url() should normally be extracted from the base64 params passed by the Cortex Hub. It's worth noting that AWS boto3 credentials allow for specifying region. Note that the PAN_DEFAULT_REGION envar would take precedence over this value.

Other considerations

Another interesting approach would be to leverage a custom JWT claim to determine the regional URL, since the IdP would ostensibly have prior knowledge of the region used during authorization. The challenge with such an approach would be sharing the region across multiple instances of HTTPClient() since the value would, ostensibly, be extracted from the access_token in the fetch_tokens() or refresh() response (an operation performed within the scope of a single Credentials() object).

Another thing to note is that it is quite easy for an app to implement its own "region selector," since an application would also have knowledge of what region was used during authorization. This is the current recommended way to handle regional selection of url in the absence of default region support.

[Montana]

Hey @sserrata,

I think this would be good, as I've read this could be a really big change for any applications using the get_authorization_url method to derive the auth_base_url and state, meaning a state parameter is not provided by user, but would give us better populated dynamic groups.