planet_auth

The Planet Authentication Package : planet_auth

This package contains functionality for authenticating clients to the service and managing authentication material. This package knows nothing about the application services apart from how to interact with authentication layers.

This package understands multiple authentication mechanisms, whose details are encapsulated in implementation subclasses that implement the primary (mostly abstract) base class interfaces.

With many different ways to interact with authentication services and ways to use the resulting authorization material (OAuth tokens, API keys, etc), configuration is important to understand. See the documentation for configuration.

The primary interfaces implemented for users of this package are as follows:

• planet_auth.Auth - A container class for initializing and grouping a working set of authentication objects.
• planet_auth.AuthClient & planet_auth.AuthClientConfig - Responsible for interacting with authentication services to obtain a credential that may be used with other API requests. Different clients have different configuration needs, so a configuration type exists for each client type to keep configuration on rails.
• planet_auth.Credential - Models just a credential. A credential is the unit of authorization material that is obtained from an authorization service, and provided to an applicaiton service so so that the client may make authenticated applicaiton requests. This class is responsible for reading and writing saved credentials to storage and performing basic data validation. This class knows nothing about how to get a credential or how to use a credential.
• planet_auth.RequestAuthenticator - Responsible for decorating application API requests with a credential. Compatible with httpx and requests libraries. Some authentication mechanisms require that the request authenticator also have an AuthClient, others do not. Whether or not this is required is driven by the specifics of the authentication mechanism. It is because of this relationship between credentials, auth clients, and request authenticators that the planet_auth.Auth class exists.

planet_auth.ObjectStorageProvider_KeyType = pathlib.Path module-attribute

Key type for object storage. Paths are currently used in part because of the history of the class. Paths need not be real files on disk. It is up to the implementation to decide if a real file should be used, or another storage mechanism should be used.

planet_auth.Auth

A container class for initializing and managing a working set of authentication objects. See factory methods and the planet_auth_utils.PlanetAuthFactory class for user-friendly initialization.

This container class provides an "auth context" is geared toward client use cases - that is, authenticating ourselves as a client with the goal of making authenticated network API calls to resource servers. Resource servers that have to validate incoming clients' credentials have some different concerns not handled here.

planet_auth.Auth.__init__(auth_client, request_authenticator, token_file_path=None, profile_name=None)

Create a new auth container object with the specified auth components. Users should use one of the more friendly static initializer methods.

planet_auth.Auth.auth_client()

Get the currently configured auth client. Returns: The current AuthClient instance.

planet_auth.Auth.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate(). This call will perform all the same actions as login().

planet_auth.Auth.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

planet_auth.Auth.ensure_request_authenticator_is_ready(allow_open_browser=False, allow_tty_prompt=False)

Do everything necessary to ensure the request authenticator is ready for use, while still biasing towards just-in-time operations and not making unnecessary network requests or prompts for user interaction.

This can be more complex than it sounds given the variations in the capabilities of authentication clients and possible session states. Clients may be initialized with active sessions, initialized with stale but still valid sessions, initialized with invalid or expired sessions, or completely uninitialized. The process taken to ensure client readiness with as little user disruption as possible is as follows:

1. If the client has been logged in and has a non-expired short-term access token, the client will be considered ready without prompting the user or probing the network. This will not require user interaction.
2. If the client has not been logged in and is a type that can do so without prompting the user, the client will be considered ready without prompting the user or probing the network. This will not require user interaction. Login will be delayed until it is required.
3. If the client has been logged in and has an expired short-term access token, the network will be probed to attempt a refresh of the session. This should not require user interaction. If refresh fails, the user will be prompted to perform a fresh login, requiring user interaction.
4. If the client has never been logged in and is a type that requires a user interactive login, a user interactive login will be initiated.

There still may be conditions where we believe we are ready, but requests still ultimately fail. For example, if the auth context holds a static API key or username/password, it is assumed to be ready but the credentials could be bad. Even when ready with valid credentia, requests could fail if the service rejects the request due to its own policy configuration.

Parameters:

Name	Type	Description	Default
allow_open_browser	Optional[bool]	specify whether login is permitted to open a browser window.	False
allow_tty_prompt	Optional[bool]	specify whether login is permitted to request input from the terminal.	False

planet_auth.Auth.initialize_from_client(auth_client, initial_token_data=None, token_file=None, profile_name=None) staticmethod

Construct and initialize a working set of authentication primitives, returning them in a new container object. Parameters: auth_client: An already constructed AuthClient object. initial_token_data: Token data to use for initial state, if not to be read from storage for initialization. token_file: A path to the storage location that should be used for credential storage. Credentials will be read from this location, and this location will be used to save refreshed credentials. Depending on the configuration, this may be ignored or may be None. When this is set to None, tokens will not be persisted to storage. profile_name: A profile name used to identify the Auth configration at runtime.

planet_auth.Auth.initialize_from_config(client_config, initial_token_data=None, token_file=None, profile_name=None) staticmethod

Construct and initialize a working set of authentication primitives, returning them in a new container object. Parameters: client_config: A constructed AuthClientConfig object. initial_token_data: Token data to use for initial state, if not to be read from storage for initialization. token_file: A path to the storage location that should be used for credential storage. Credentials will be read from this location, and this location will be used to save refreshed credentials. Depending on the configuration, this may be ignored or may be None. When this is set to None, tokens will not be persisted to storage. profile_name: A profile name used to identify the Auth configration at runtime.

planet_auth.Auth.initialize_from_config_dict(client_config, initial_token_data=None, token_file=None, profile_name=None, storage_provider=None) staticmethod

Construct and initialize a working set of authentication primitives, returning them in a new container object. Parameters: client_config: A dictionary containing a valid auth client configuration. initial_token_data: Token data to use for initial state, if not to be read from storage for initialization. token_file: A path to a storage location that should be used for credential storage. Credentials will be read from this location, and this location may be used to save refreshed credentials. Depending on the configuration, this may be ignored or may be None. When this is set to None, tokens will not be persisted to storage. profile_name: A profile name used to identify the Auth configration at runtime. storage_provider: A custom storage provider to use.

planet_auth.Auth.login(allow_open_browser=False, allow_tty_prompt=False, **kwargs)

Perform a login with the configured auth client. This higher level function will ensure that the token is saved to storage if Auth context has been configured with a suitable token storage path. Otherwise, the token will be held only in memory. In all cases, the request authenticator will also be updated with the new credentials.

Parameters:

Name	Type	Description	Default
allow_open_browser	Optional[bool]	specify whether login is permitted to open a browser window.	False
allow_tty_prompt	Optional[bool]	specify whether login is permitted to request input from the terminal.	False

planet_auth.Auth.profile_name()

Get the current profile name, if known. May be empty if initialization was performed without using a profile. Returns: Returns the name of the current profile, if known.

planet_auth.Auth.request_authenticator()

Get the current request authenticator. Returns: The current CredentialRequestAuthenticator instance.

planet_auth.Auth.request_authenticator_is_ready()

Check whether the current context's request_authenticator is ready for use.

A context is considered initialized if it can be used to make authenticated client requests without user intervention. What exactly that requires can vary by auth client configured in the context. For example, simple API key clients only need an API key in their configuration. OAuth2 user clients need to have performed a user login and obtained access or refresh tokens.

Note: This will not detect when a credential is expired or otherwise invalid.

planet_auth.Auth.token_file_path()

Get the path to the current credentials file. Returns: The path to the current credentials file.

planet_auth.AuthClient

Bases: ABC

Base class for auth clients. Concrate instances of this base class manage the specific of how to authenticate a user and obtain credentials that may be used for service APIs.

The factory methods in the base class accepts a client specific client configuration type, and will return an instance of an appropriate subclass.

Example

from planet_auth import AuthClientConfig, AuthClient
config_dict = { ... } # See AuthClientConfig
my_auth_config = AuthClientConfig.from_dict(config_dict)
my_auth_client = AuthClient.from_config(my_auth_config)

planet_auth.AuthClient.can_login_unattended() abstractmethod

Check whether the client can perform an unattended login.

Depending on the implementation, some clients may be able to perform unattended logins based on information the client config (e.g. static API key clients can do this). These should return true. Other clients will always require user interactive logins (e.g. a user interactive client using a browser and MFA to login). These should return false. Some clients may be flexible and support either depending on the state of their configuration. These should return a result based on their configuration.

planet_auth.AuthClient.default_request_authenticator(credential) abstractmethod

Return an instance of the default request authenticator to use for the specific AuthClient type and configured to use the provided credential file for persistence.

It's not automatic that the default is always the right choice. Some authenticators may initiate logins, which may be interactive or not depending on the specifics of the AuthClient configuration and implementation type. Whether or not interactivity can be tolerated depends on the specifics of the surrounding application.

In the simplest cases, there really is no relationship between the AuthClient and the request authenticator (see static key implementations). This relationship emerges when the mechanisms of an AuthClient requires frequent refreshing of the Credential. In these cases, it is convenient for the CredentialRequestAuthenticator to also have an AuthClient that is capable of performing this refresh transparently as needed.

AuthClient implementors should favor defaults that do not require user interaction after an initial Credential has been obtained from an initial call to login()

Parameters:

Name	Type	Description	Default
credential	Union[Path, Credential]	A Credential object, or a Path to the credential file that can be used to create an appropriate credential object.	required

Returns: Returns an instance of the default request authenticator class to use for Credentials of the type obtained by the AuthClient.

planet_auth.AuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.AuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.AuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.AuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.AuthClient.login(allow_open_browser=False, allow_tty_prompt=False, **kwargs) abstractmethod

Perform an initial login using the authentication mechanism implemented by the AuthClient instance. The results of a successful login is FileBackedJsonObject Credential containing credentials that may be used for subsequent service API requests. How these credentials are used for this purpose is outside the scope of either the AuthClient or the Credential. This is the job of a RequestAuthenticator.

The login command is permitted to be user interactive. Depending on the implementation, this may include terminal prompts, or may require the use of a web browser.

Authentication parameters are specific to each implementation. Consult subclass documentation for details.

Parameters:

Name	Type	Description	Default
allow_open_browser	Optional[bool]	specify whether login is permitted to open a browser window.	False
allow_tty_prompt	Optional[bool]	specify whether login is permitted to request input from the terminal.	False

Returns: Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type. AuthClient implementations should raise an exception for all login errors.

planet_auth.AuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.AuthClient.refresh(refresh_token, requested_scopes)

Obtain a refreshed credential using the supplied refresh token. This method will be implemented by concrete AuthClients that implement a particular OAuth flow. Parameters: refresh_token: Refresh token requested_scopes: Scopes to request in the access token Returns: Upon success, a fresh Credential will be returned. As with login(), this credential will not have been persisted to storage. This is the responsibility of the application. AuthClient implementations should raise an exception for all login errors.

planet_auth.AuthClient.revoke_access_token(access_token)

Revoke an access token with the authorization server. Parameters: access_token: Access token to revoke.

planet_auth.AuthClient.revoke_refresh_token(refresh_token)

Revoke a refresh token with the authorization server. Parameters: refresh_token: Access token to revoke.

planet_auth.AuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.AuthClient.validate_access_token_local(access_token, required_audience=None, scopes_anyof=None)

Validate an access token locally. While the validation is local, the authorization server may still may contacted to obtain signing keys for validation. Signing keys will be cached for future use.

Auth servers (issuers) may provide service for any number of audiences, so which audience is expected / required is potentially different for each discrete validation check. If the required audience is not provided as an argument, the validate should fall back to the audiences configured in the AuthClientConfig.

If the audience is neither provided as an argument nor present in the AuthClientConfig, an error should be raised.

Note

While tokens may have multiple audiences, and AuthClients may be configured to request multiple audiences, the validation method currently only supports checking for a single audience. This could be considered is a bit of an API mismatch. However, at this time this is considered expected and desirable behavior. Validation is generally considered to be occurring in a context that self identifies as a particular audience, and overlapping claims may mean different things to different audiences. Validation should be done in the context of a single audience at a time.

Parameters:

Name	Type	Description	Default
access_token	str	Access token to validate.	required
required_audience	str	Audience that the token is required to have.	None
scopes_anyof	list	Optional list of OAuth2 scopes to check for in the token. This list is an "any of" list of scopes. As long as one of the scopes in the list is present, validation will pass. If none of the scopes are present, validation will fail.	None

Returns: Returns a dictionary of validated token claims. It should be noted that the returned dictionaries from local and service token validation are not exactly the same. Service validation should return a RFC 7662 dictionary. Local validation returns the token claims.

planet_auth.AuthClient.validate_access_token_remote(access_token)

Validate an access token with the authorization server. Parameters: access_token: Access token to validate Returns: Returns a dictionary of validated token claims. It should be noted that the returned dictionaries from local and service token validation are not exactly the same. Service validation should return a RFC 7662 dictionary. Local validation returns the token claims.

planet_auth.AuthClient.validate_id_token_local(id_token)

Validate an ID token locally. The authorization server may still be called to obtain signing keys for validation. Signing keys will be cached for future use. Parameters: id_token: ID token to validate Returns: Returns a dictionary of validated token claims

planet_auth.AuthClient.validate_id_token_remote(id_token)

Validate an ID token with the authorization server. Parameters: id_token: ID token to validate Returns: Returns a dictionary of validated token claims

planet_auth.AuthClient.validate_refresh_token_remote(refresh_token)

Validate a refresh token with the authorization server. Parameters: refresh_token: Refresh token to validate Returns: Returns the response from the remove validation service.

planet_auth.AuthClientConfig

Bases: FileBackedJsonObject, ABC

Base class for auth client configuration objects. Each concrete auth client type has a dedicated auth client config type to provide client specific validation and guardrails.

The factory methods in the base class accept a dictionary, and will return an instance of an appropriate subclass.

planet_auth.AuthClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.AuthClientConfig.check_data(data)

Check that the provided data is valid. Throws an exception if the data is not valid. This allows the base class to refuse to store or use data, while leaving it to child classes to know what constitutes "valid". Child classes should raise FileBackedJsonObjectException exception.

Child classes should override this method as required to do more application specific data integrity checks. They should also call validation on their base classes so that all layers of validation are performed.

The base assertion is that the data structure has been set. It may be empty, but may not be None. The None data structure is treated as a special case, and means that the class has been constructed, but the data has never been set. Once data has been set, it is only permitted to be set to valid values. The intent of this behavior is to support JIT loading semantics.

planet_auth.AuthClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.AuthClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.AuthClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.AuthClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.AuthClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.AuthClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.AuthClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.AuthClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.AuthClientConfig.meta() abstractmethod classmethod

Return a dictionary of metadata. The meta dictionary provides a place to store information that is primarily for users of AuthClient types rather than for the operation of the Auth Client itself.

Meta Keys

client_type: The literal value used for client_type in configuration dictionaries that indicates the selection of the AuthClient type.

auth_client_class: The concrete AuthClient class that is served by the configuration type.

display_name: Display name for the AuthClient type

description: A description of the AuthClient type

config_hints: A list configuration hints bootstrapping a configuration with a wizard of some sort. This is distinct from a rigid schema for the configuration type.

planet_auth.AuthClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.AuthClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.AuthClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.AuthClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.AuthClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.AuthClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.AuthClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.AuthCodeAuthClient

Bases: AuthCodeAuthClientBase, OidcAuthClientWithNoneClientAuth

AuthClient implementation that implements the OAuth auth code grant with PKCE to obtain user tokens. This implementation is for public clients that cannot maintain client confidentiality.

planet_auth.AuthCodeAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.AuthCodeAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.AuthCodeAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.AuthCodeAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.AuthCodeAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.AuthCodeAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.AuthCodeAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.AuthCodeAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.AuthCodeAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.AuthCodeAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.AuthCodeAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.AuthCodeAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.AuthCodeAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.AuthCodeAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.AuthCodeClientConfig

Bases: OidcAuthClientConfig

Configuration required for planet_auth.AuthCodeAuthClient

planet_auth.AuthCodeClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.AuthCodeClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.AuthCodeClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.AuthCodeClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.AuthCodeClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.AuthCodeClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.AuthCodeClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.AuthCodeClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.AuthCodeClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.AuthCodeClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.AuthCodeClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.AuthCodeClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.AuthCodeClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.AuthCodeClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.AuthCodeClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.AuthCodeClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.AuthCodeWithClientSecretAuthClient

Bases: AuthCodeAuthClientBase, OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment

AuthClient implementation that implements the OAuth auth code grant with PKCE to obtain user tokens. This implementation is for confidential clients that use a client secret to protect the client confidentiality.

planet_auth.AuthCodeWithClientSecretAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.AuthCodeWithClientSecretAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.AuthCodeWithClientSecretAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.AuthCodeWithClientSecretAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.AuthCodeWithClientSecretAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.AuthCodeWithClientSecretAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.AuthCodeWithClientSecretAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.AuthCodeWithClientSecretAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.AuthCodeWithClientSecretAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.AuthCodeWithClientSecretAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.AuthCodeWithClientSecretAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.AuthCodeWithClientSecretAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.AuthCodeWithClientSecretAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.AuthCodeWithClientSecretAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.AuthCodeWithClientSecretClientConfig

Bases: AuthCodeClientConfig, OidcAuthClientWithClientSecretClientConfig

Configuration required for planet_auth.AuthCodeWithClientSecretAuthClient

planet_auth.AuthCodeWithClientSecretClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.AuthCodeWithClientSecretClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.AuthCodeWithClientSecretClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.AuthCodeWithClientSecretClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.AuthCodeWithClientSecretClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.AuthCodeWithClientSecretClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.AuthCodeWithClientSecretClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.AuthCodeWithClientSecretClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.AuthCodeWithClientSecretClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.AuthCodeWithClientSecretClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.AuthCodeWithClientSecretClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.AuthCodeWithClientSecretClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.AuthCodeWithClientSecretClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.AuthCodeWithClientSecretClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.AuthCodeWithClientSecretClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.AuthCodeWithClientSecretClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.AuthCodeWithPubKeyAuthClient

Bases: AuthCodeAuthClientBase, OidcAuthClientWithClientPubkey

AuthClient implementation that implements the OAuth auth code grant with PKCE to obtain user tokens. This implementation is for confidential clients that use a public/private keypair to protect the client confidentiality.

planet_auth.AuthCodeWithPubKeyAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.AuthCodeWithPubKeyAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.AuthCodeWithPubKeyAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.AuthCodeWithPubKeyAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.AuthCodeWithPubKeyAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.AuthCodeWithPubKeyAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.AuthCodeWithPubKeyAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.AuthCodeWithPubKeyAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.AuthCodeWithPubKeyAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.AuthCodeWithPubKeyAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.AuthCodeWithPubKeyAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.AuthCodeWithPubKeyAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.AuthCodeWithPubKeyAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.AuthCodeWithPubKeyAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.AuthCodeWithPubKeyClientConfig

Bases: AuthCodeClientConfig, OidcAuthClientWithPubKeyClientConfig

Configuration required for planet_auth.AuthCodeWithPubKeyAuthClient

planet_auth.AuthCodeWithPubKeyClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.AuthCodeWithPubKeyClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.AuthCodeWithPubKeyClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.AuthCodeWithPubKeyClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.AuthCodeWithPubKeyClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.AuthCodeWithPubKeyClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.AuthCodeWithPubKeyClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.AuthCodeWithPubKeyClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.AuthCodeWithPubKeyClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.AuthCodeWithPubKeyClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.AuthCodeWithPubKeyClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.AuthCodeWithPubKeyClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.AuthCodeWithPubKeyClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.AuthCodeWithPubKeyClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.AuthCodeWithPubKeyClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.AuthCodeWithPubKeyClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.AuthException

Bases: Exception

Base Exception class for all exceptions thrown from the planet_auth library.

planet_auth.AuthException.recast(*exceptions, **params) classmethod

Decorator to recast an exception as the specified exception: Example:

@AuthException.recast(Exception)
@AuthException_SubClass.recast(Some_Specific_Exception)
def raise_my_exception2():
    raise Some_Specific_Exception()

Exercise caution when using multiple re-casts. Recasting as something that is then caught by a decorator further up the stack causes problems: Example:

@AuthException.recast(Exception) # Causes a problem, since it will catch
                                 # the results of the recasts below
@AuthException_SomeSubException.recast(Some_Specific_Exception)
def raise_my_exception2():
    raise Some_Specific_Exception()

planet_auth.ClientCredentialsClientSecretAuthClient

Bases: ClientCredentialsAuthClientBase, OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment

AuthClient implementation that implements the OAuth client credentials grant to obtain tokens for the client itself. This implementation is for confidential clients that use a client secret to protect the client confidentiality.

planet_auth.ClientCredentialsClientSecretAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.ClientCredentialsClientSecretAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.ClientCredentialsClientSecretAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.ClientCredentialsClientSecretAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.ClientCredentialsClientSecretAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.ClientCredentialsClientSecretAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.ClientCredentialsClientSecretAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.ClientCredentialsClientSecretAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.ClientCredentialsClientSecretAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.ClientCredentialsClientSecretAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.ClientCredentialsClientSecretAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.ClientCredentialsClientSecretAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.ClientCredentialsClientSecretAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.ClientCredentialsClientSecretAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.ClientCredentialsClientSecretClientConfig

Bases: OidcAuthClientWithClientSecretClientConfig

Configuration required for planet_auth.ClientCredentialsClientSecretAuthClient

planet_auth.ClientCredentialsClientSecretClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.ClientCredentialsClientSecretClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.ClientCredentialsClientSecretClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.ClientCredentialsClientSecretClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.ClientCredentialsClientSecretClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.ClientCredentialsClientSecretClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.ClientCredentialsClientSecretClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.ClientCredentialsClientSecretClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.ClientCredentialsClientSecretClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.ClientCredentialsClientSecretClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.ClientCredentialsClientSecretClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.ClientCredentialsClientSecretClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.ClientCredentialsClientSecretClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.ClientCredentialsClientSecretClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.ClientCredentialsClientSecretClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.ClientCredentialsClientSecretClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.ClientCredentialsPubKeyAuthClient

Bases: ClientCredentialsAuthClientBase, OidcAuthClientWithClientPubkey

AuthClient implementation that implements the OAuth client credentials grant to obtain tokens for the client itself. This implementation is for confidential clients that use a public/private keypair to protect the client confidentiality.

planet_auth.ClientCredentialsPubKeyAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.ClientCredentialsPubKeyAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.ClientCredentialsPubKeyAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.ClientCredentialsPubKeyAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.ClientCredentialsPubKeyAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.ClientCredentialsPubKeyAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.ClientCredentialsPubKeyAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.ClientCredentialsPubKeyAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.ClientCredentialsPubKeyAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.ClientCredentialsPubKeyAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.ClientCredentialsPubKeyAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.ClientCredentialsPubKeyAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.ClientCredentialsPubKeyAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.ClientCredentialsPubKeyAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.ClientCredentialsPubKeyClientConfig

Bases: OidcAuthClientWithPubKeyClientConfig

Configuration required for planet_auth.ClientCredentialsPubKeyAuthClient

planet_auth.ClientCredentialsPubKeyClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.ClientCredentialsPubKeyClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.ClientCredentialsPubKeyClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.ClientCredentialsPubKeyClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.ClientCredentialsPubKeyClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.ClientCredentialsPubKeyClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.ClientCredentialsPubKeyClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.ClientCredentialsPubKeyClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.ClientCredentialsPubKeyClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.ClientCredentialsPubKeyClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.ClientCredentialsPubKeyClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.ClientCredentialsPubKeyClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.ClientCredentialsPubKeyClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.ClientCredentialsPubKeyClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.ClientCredentialsPubKeyClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.ClientCredentialsPubKeyClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.Credential

Bases: FileBackedJsonObject

A storage backed credential. A credential is expected to be a json dict. Per the base class default storage provider implementation, clear-text .json files or .sops.json files with field level encryption are supported. Custom storage providers may offer different functionality.

Subclass Implementor Notes

The Credential class reserves the data fields _iat and _exp for internal use. These are used to record the time the credential was issued and the time that it expires respectively, expressed as seconds since the epoch. A None or NULL value for _exp indicates that the credential never expires.

This base class does not set these values. It is the responsibility of subclasses to set these values as appropriate. If left unset, the credential will be treated as a non-expiring credential with an indeterminate issued time.

Subclasses that wish to provide values should do so in their constructor and in their set_data() methods.

planet_auth.Credential.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.Credential.check_data(data)

Check that the provided data is valid. Throws an exception if the data is not valid. This allows the base class to refuse to store or use data, while leaving it to child classes to know what constitutes "valid". Child classes should raise FileBackedJsonObjectException exception.

Child classes should override this method as required to do more application specific data integrity checks. They should also call validation on their base classes so that all layers of validation are performed.

The base assertion is that the data structure has been set. It may be empty, but may not be None. The None data structure is treated as a special case, and means that the class has been constructed, but the data has never been set. Once data has been set, it is only permitted to be set to valid values. The intent of this behavior is to support JIT loading semantics.

planet_auth.Credential.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.Credential.expiry_time()

The time that the credential expires, expressed as seconds since the epoch.

planet_auth.Credential.is_expired(at_time=None)

Return true if the credential is expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return false.

planet_auth.Credential.is_expiring()

Return true if the credential has an expiry time.

planet_auth.Credential.is_non_expiring()

Return true if the credential never expires.

planet_auth.Credential.is_not_expired(at_time=None)

Return true if the credential is not expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return true.

planet_auth.Credential.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.Credential.issued_time()

The time that the credential was issued, expressed as seconds since the epoch.

planet_auth.Credential.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.Credential.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.Credential.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.Credential.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.Credential.path()

Retrieve the currently configured path for saved data.

planet_auth.Credential.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.Credential.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.Credential.set_path(file_path)

Update storage path for the object.

planet_auth.Credential.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.Credential.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.Credential.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.CredentialRequestAuthenticator

Bases: RequestAuthenticator, ABC

planet_auth.CredentialRequestAuthenticator.auth_flow(request)

Decorate a "httpx" library based request with authentication

planet_auth.CredentialRequestAuthenticator.credential(refresh_if_needed=False)

Return the current credential.

This may not be the credential the authenticator was constructed with. Request Authenticators are free to refresh credentials depending on the needs of the implementation. This may happen upon this request, or may happen as a side effect of RequestAuthenticator operations.

planet_auth.CredentialRequestAuthenticator.is_initialized()

Return true if the CredentialRequestAuthenticator has a credential that can be used to make requests. If a credential is not in memory, storage is checked for the existence of a credential, but it will not be loaded from storage at this time, preserving JIT loading behavior.

planet_auth.CredentialRequestAuthenticator.pre_request_hook() abstractmethod

Hook that will be called immediately prior to making an HTTP request so that implementing classes may make preparations. Derived classes are expected to populate the member fields _token_prefix, _token_body, and _auth_header with values that are appropriate to the specific implementation. These will then be used during subsequent HTTP request to authenticate the connection using a beater token authorization HTTP header.

Implementers may make external network calls as required to perform necessary tasks such as refreshing access tokens.

Implementations should not require user interaction by default. If an authentication mechanism will require user interaction, this should be an explicit decision that is left to the application using the RequestAuthenticator to control.

planet_auth.CredentialRequestAuthenticator.update_credential(new_credential)

Update the request authenticator with a new credential. It is the job of a derived class to know how to map the contents of a credential into the primitives known to HTTP request auth mechanics. Not all derived classes are expected to understand all credential types.

planet_auth.CredentialRequestAuthenticator.update_credential_data(new_credential_data)

Provide raw data that should be used to update the Credential object used to authenticate requests. This information will be treated as newer than any file back data associated with the credential held by the authenticator, and the file will be overwritten.

planet_auth.DeviceCodeAuthClient

Bases: DeviceCodeAuthClientBase, OidcAuthClientWithNoneClientAuth

AuthClient implementation that implements the OAuth device code grant to obtain user tokens. This implementation is for public clients that cannot maintain client confidentiality.

planet_auth.DeviceCodeAuthClient.device_login_complete(initiated_login_data)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method completes the process initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	dict	The dictionary returned from a successful call to device_login_initiate()	required

Returns: A FileBackedOidcCredential object

planet_auth.DeviceCodeAuthClient.device_login_initiate(requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method initiates the device login process with the auth service. A dictionary that complies to RFC 8628 will be return upon success that can be used by the client application to prompt the user. After prompting the user, device_login_complete() should be called to complete the login process.

Parameters:

Name	Type	Description	Default
requested_scopes	List[str]	a list of strings specifying the scopes to request.	None
requested_audiences	List[str]	a list of strings specifying the audiences to request.	None
extra	Optional[dict]	a dict extra data to pass to the authorization server.	None

Returns: A RFC 8628 compliant dictionary that can be used by the called to prompt the user to complete device authentication. This dictionary should be passed to device_login_complete() to finish the login process.

planet_auth.DeviceCodeAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.DeviceCodeAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.DeviceCodeAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.DeviceCodeAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.DeviceCodeAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.DeviceCodeAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.DeviceCodeAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.DeviceCodeAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.DeviceCodeAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.DeviceCodeAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.DeviceCodeAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.DeviceCodeAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.DeviceCodeClientConfig

Bases: OidcAuthClientConfig

Configuration required for planet_auth.DeviceCodeAuthClient

planet_auth.DeviceCodeClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.DeviceCodeClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.DeviceCodeClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.DeviceCodeClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.DeviceCodeClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.DeviceCodeClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.DeviceCodeClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.DeviceCodeClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.DeviceCodeClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.DeviceCodeClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.DeviceCodeClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.DeviceCodeClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.DeviceCodeClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.DeviceCodeClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.DeviceCodeClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.DeviceCodeClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.DeviceCodeWithClientSecretAuthClient

Bases: DeviceCodeAuthClientBase, OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment

AuthClient implementation that implements the OAuth device code grant to obtain user tokens. This implementation is for confidential clients that use a client secret to protect the client confidentiality.

planet_auth.DeviceCodeWithClientSecretAuthClient.device_login_complete(initiated_login_data)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method completes the process initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	dict	The dictionary returned from a successful call to device_login_initiate()	required

Returns: A FileBackedOidcCredential object

planet_auth.DeviceCodeWithClientSecretAuthClient.device_login_initiate(requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method initiates the device login process with the auth service. A dictionary that complies to RFC 8628 will be return upon success that can be used by the client application to prompt the user. After prompting the user, device_login_complete() should be called to complete the login process.

Parameters:

Name	Type	Description	Default
requested_scopes	List[str]	a list of strings specifying the scopes to request.	None
requested_audiences	List[str]	a list of strings specifying the audiences to request.	None
extra	Optional[dict]	a dict extra data to pass to the authorization server.	None

Returns: A RFC 8628 compliant dictionary that can be used by the called to prompt the user to complete device authentication. This dictionary should be passed to device_login_complete() to finish the login process.

planet_auth.DeviceCodeWithClientSecretAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.DeviceCodeWithClientSecretAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.DeviceCodeWithClientSecretAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.DeviceCodeWithClientSecretAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.DeviceCodeWithClientSecretAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.DeviceCodeWithClientSecretAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.DeviceCodeWithClientSecretAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.DeviceCodeWithClientSecretAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.DeviceCodeWithClientSecretAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.DeviceCodeWithClientSecretAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.DeviceCodeWithClientSecretAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.DeviceCodeWithClientSecretAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.DeviceCodeWithClientSecretClientConfig

Bases: DeviceCodeClientConfig, OidcAuthClientWithClientSecretClientConfig

Configuration required for planet_auth.DeviceCodeWithClientSecretAuthClient

planet_auth.DeviceCodeWithClientSecretClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.DeviceCodeWithClientSecretClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.DeviceCodeWithClientSecretClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.DeviceCodeWithClientSecretClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.DeviceCodeWithClientSecretClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.DeviceCodeWithClientSecretClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.DeviceCodeWithClientSecretClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.DeviceCodeWithClientSecretClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.DeviceCodeWithClientSecretClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.DeviceCodeWithClientSecretClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.DeviceCodeWithClientSecretClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.DeviceCodeWithClientSecretClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.DeviceCodeWithClientSecretClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.DeviceCodeWithClientSecretClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.DeviceCodeWithClientSecretClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.DeviceCodeWithClientSecretClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.DeviceCodeWithPubKeyAuthClient

Bases: DeviceCodeAuthClientBase, OidcAuthClientWithClientPubkey

AuthClient implementation that implements the OAuth device code grant to obtain user tokens. This implementation is for confidential clients that use a public/private keypair to protect the client confidentiality.

planet_auth.DeviceCodeWithPubKeyAuthClient.device_login_complete(initiated_login_data)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method completes the process initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	dict	The dictionary returned from a successful call to device_login_initiate()	required

Returns: A FileBackedOidcCredential object

planet_auth.DeviceCodeWithPubKeyAuthClient.device_login_initiate(requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method initiates the device login process with the auth service. A dictionary that complies to RFC 8628 will be return upon success that can be used by the client application to prompt the user. After prompting the user, device_login_complete() should be called to complete the login process.

Parameters:

Name	Type	Description	Default
requested_scopes	List[str]	a list of strings specifying the scopes to request.	None
requested_audiences	List[str]	a list of strings specifying the audiences to request.	None
extra	Optional[dict]	a dict extra data to pass to the authorization server.	None

Returns: A RFC 8628 compliant dictionary that can be used by the called to prompt the user to complete device authentication. This dictionary should be passed to device_login_complete() to finish the login process.

planet_auth.DeviceCodeWithPubKeyAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.DeviceCodeWithPubKeyAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.DeviceCodeWithPubKeyAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.DeviceCodeWithPubKeyAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.DeviceCodeWithPubKeyAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.DeviceCodeWithPubKeyAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.DeviceCodeWithPubKeyAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.DeviceCodeWithPubKeyAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.DeviceCodeWithPubKeyAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.DeviceCodeWithPubKeyAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.DeviceCodeWithPubKeyAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.DeviceCodeWithPubKeyAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.DeviceCodeWithPubKeyClientConfig

Bases: DeviceCodeClientConfig, OidcAuthClientWithPubKeyClientConfig

Configuration required for planet_auth.DeviceCodeWithPubKeyAuthClient

planet_auth.DeviceCodeWithPubKeyClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.DeviceCodeWithPubKeyClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.DeviceCodeWithPubKeyClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.DeviceCodeWithPubKeyClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.DeviceCodeWithPubKeyClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.DeviceCodeWithPubKeyClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.DeviceCodeWithPubKeyClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.DeviceCodeWithPubKeyClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.DeviceCodeWithPubKeyClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.DeviceCodeWithPubKeyClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.DeviceCodeWithPubKeyClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.DeviceCodeWithPubKeyClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.DeviceCodeWithPubKeyClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.DeviceCodeWithPubKeyClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.DeviceCodeWithPubKeyClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.DeviceCodeWithPubKeyClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.FileBackedApiKey

Bases: Credential

Credential object for storing simple API key bearer tokens.

planet_auth.FileBackedApiKey.api_key()

Get the current API Key.

planet_auth.FileBackedApiKey.bearer_token_prefix()

Get the bearer token prefix that is to be used with the API key.

planet_auth.FileBackedApiKey.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.FileBackedApiKey.check_data(data)

Check that the supplied data represents a valid API key object.

planet_auth.FileBackedApiKey.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.FileBackedApiKey.expiry_time()

The time that the credential expires, expressed as seconds since the epoch.

planet_auth.FileBackedApiKey.is_expired(at_time=None)

Return true if the credential is expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return false.

planet_auth.FileBackedApiKey.is_expiring()

Return true if the credential has an expiry time.

planet_auth.FileBackedApiKey.is_non_expiring()

Return true if the credential never expires.

planet_auth.FileBackedApiKey.is_not_expired(at_time=None)

Return true if the credential is not expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return true.

planet_auth.FileBackedApiKey.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.FileBackedApiKey.issued_time()

The time that the credential was issued, expressed as seconds since the epoch.

planet_auth.FileBackedApiKey.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.FileBackedApiKey.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.FileBackedApiKey.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.FileBackedApiKey.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.FileBackedApiKey.path()

Retrieve the currently configured path for saved data.

planet_auth.FileBackedApiKey.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.FileBackedApiKey.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.FileBackedApiKey.set_path(file_path)

Update storage path for the object.

planet_auth.FileBackedApiKey.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.FileBackedApiKey.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.FileBackedApiKey.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.FileBackedApiKeyRequestAuthenticator

Bases: CredentialRequestAuthenticator

Load a bearer token from a file just in time for the request. Perform local checks on the validity of the token and throw if we think it will fail.

planet_auth.FileBackedApiKeyRequestAuthenticator.auth_flow(request)

Decorate a "httpx" library based request with authentication

planet_auth.FileBackedApiKeyRequestAuthenticator.credential(refresh_if_needed=False)

Return the current credential.

This may not be the credential the authenticator was constructed with. Request Authenticators are free to refresh credentials depending on the needs of the implementation. This may happen upon this request, or may happen as a side effect of RequestAuthenticator operations.

planet_auth.FileBackedApiKeyRequestAuthenticator.is_initialized()

Return true if the CredentialRequestAuthenticator has a credential that can be used to make requests. If a credential is not in memory, storage is checked for the existence of a credential, but it will not be loaded from storage at this time, preserving JIT loading behavior.

planet_auth.FileBackedApiKeyRequestAuthenticator.update_credential(new_credential)

Update the request authenticator with a new credential. It is the job of a derived class to know how to map the contents of a credential into the primitives known to HTTP request auth mechanics. Not all derived classes are expected to understand all credential types.

planet_auth.FileBackedApiKeyRequestAuthenticator.update_credential_data(new_credential_data)

Provide raw data that should be used to update the Credential object used to authenticate requests. This information will be treated as newer than any file back data associated with the credential held by the authenticator, and the file will be overwritten.

planet_auth.FileBackedJsonObject

A storage backed json object for storing information. Base class provides lazy loading and validation before saving or setting the data. Derived classes should provide type specific validation and convenience data accessors. The intent is that this provides a way to have an object backed by storage, and rails are in place to prevent invalid data from being saved or used.

Data is allowed to be initialized as None so that JIT load() use cases can be supported with the data not being read until needed. Care should be taken when constructing from an in-memory data value, as leaf class data validation is not performed during construction.

The None data structure is treated as a special case, and means that the class has been constructed, but the data has never been set. Once data has been set, either by calling set_data() or by loading data from a storage, it is only permitted to be set to valid values.

Saving to the backing is also optional. Uses in this way, this class behaves as a validating in-memory json object holder. To disable saving to storage, construct objects with a None file_path.

The default storage provider will use the file system for storage. When loading from file storage, the file may be SOPS encrypted. When using SOPS encryption, the file should have a ".sops.json" suffix.

planet_auth.FileBackedJsonObject.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.FileBackedJsonObject.check_data(data)

Check that the provided data is valid. Throws an exception if the data is not valid. This allows the base class to refuse to store or use data, while leaving it to child classes to know what constitutes "valid". Child classes should raise FileBackedJsonObjectException exception.

Child classes should override this method as required to do more application specific data integrity checks. They should also call validation on their base classes so that all layers of validation are performed.

The base assertion is that the data structure has been set. It may be empty, but may not be None. The None data structure is treated as a special case, and means that the class has been constructed, but the data has never been set. Once data has been set, it is only permitted to be set to valid values. The intent of this behavior is to support JIT loading semantics.

planet_auth.FileBackedJsonObject.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.FileBackedJsonObject.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.FileBackedJsonObject.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.FileBackedJsonObject.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.FileBackedJsonObject.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.FileBackedJsonObject.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.FileBackedJsonObject.path()

Retrieve the currently configured path for saved data.

planet_auth.FileBackedJsonObject.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.FileBackedJsonObject.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.FileBackedJsonObject.set_path(file_path)

Update storage path for the object.

planet_auth.FileBackedJsonObject.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.FileBackedJsonObject.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.FileBackedJsonObject.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.FileBackedJsonObjectException

Bases: AuthException

Exception indicating a problem with a file backed json object.

planet_auth.FileBackedJsonObjectException.recast(*exceptions, **params) classmethod

Decorator to recast an exception as the specified exception: Example:

@AuthException.recast(Exception)
@AuthException_SubClass.recast(Some_Specific_Exception)
def raise_my_exception2():
    raise Some_Specific_Exception()

Exercise caution when using multiple re-casts. Recasting as something that is then caught by a decorator further up the stack causes problems: Example:

@AuthException.recast(Exception) # Causes a problem, since it will catch
                                 # the results of the recasts below
@AuthException_SomeSubException.recast(Some_Specific_Exception)
def raise_my_exception2():
    raise Some_Specific_Exception()

planet_auth.FileBackedOidcCredential

Bases: Credential

Credential object for storing OAuth/OIDC tokens. Credential should conform to the "token" response defined in RFC 6749 for OAuth access tokens with OIDC extensions for ID tokens.

planet_auth.FileBackedOidcCredential.access_token()

Get the current access token.

planet_auth.FileBackedOidcCredential.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.FileBackedOidcCredential.check_data(data)

Check that the supplied data represents a valid OAuth/OIDC token object.

planet_auth.FileBackedOidcCredential.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.FileBackedOidcCredential.expiry_time()

The time that the credential expires, expressed as seconds since the epoch.

planet_auth.FileBackedOidcCredential.id_token()

Get the current ID token.

planet_auth.FileBackedOidcCredential.is_expired(at_time=None)

Return true if the credential is expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return false.

planet_auth.FileBackedOidcCredential.is_expiring()

Return true if the credential has an expiry time.

planet_auth.FileBackedOidcCredential.is_non_expiring()

Return true if the credential never expires.

planet_auth.FileBackedOidcCredential.is_not_expired(at_time=None)

Return true if the credential is not expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return true.

planet_auth.FileBackedOidcCredential.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.FileBackedOidcCredential.issued_time()

The time that the credential was issued, expressed as seconds since the epoch.

planet_auth.FileBackedOidcCredential.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.FileBackedOidcCredential.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.FileBackedOidcCredential.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.FileBackedOidcCredential.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.FileBackedOidcCredential.path()

Retrieve the currently configured path for saved data.

planet_auth.FileBackedOidcCredential.refresh_token()

Get the current refresh token.

planet_auth.FileBackedOidcCredential.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.FileBackedOidcCredential.set_data(data, copy_data=True)

Set credential data for an OAuth/OIDC credential. The data structure is expected to be an RFC 6749 /token response structure.

planet_auth.FileBackedOidcCredential.set_path(file_path)

Update storage path for the object.

planet_auth.FileBackedOidcCredential.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.FileBackedOidcCredential.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.FileBackedOidcCredential.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.FileBackedPlanetLegacyApiKey

Bases: Credential

Credential object for storing Planet Legacy API Keys

planet_auth.FileBackedPlanetLegacyApiKey.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.FileBackedPlanetLegacyApiKey.check_data(data)

Check that the supplied data represents a valid Planet Legacy API Key object.

planet_auth.FileBackedPlanetLegacyApiKey.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.FileBackedPlanetLegacyApiKey.expiry_time()

The time that the credential expires, expressed as seconds since the epoch.

planet_auth.FileBackedPlanetLegacyApiKey.is_expired(at_time=None)

Return true if the credential is expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return false.

planet_auth.FileBackedPlanetLegacyApiKey.is_expiring()

Return true if the credential has an expiry time.

planet_auth.FileBackedPlanetLegacyApiKey.is_non_expiring()

Return true if the credential never expires.

planet_auth.FileBackedPlanetLegacyApiKey.is_not_expired(at_time=None)

Return true if the credential is not expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return true.

planet_auth.FileBackedPlanetLegacyApiKey.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.FileBackedPlanetLegacyApiKey.issued_time()

The time that the credential was issued, expressed as seconds since the epoch.

planet_auth.FileBackedPlanetLegacyApiKey.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.FileBackedPlanetLegacyApiKey.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.FileBackedPlanetLegacyApiKey.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.FileBackedPlanetLegacyApiKey.legacy_api_key()

Get the current API key.

planet_auth.FileBackedPlanetLegacyApiKey.legacy_jwt()

Get the saved legacy JWT.

planet_auth.FileBackedPlanetLegacyApiKey.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.FileBackedPlanetLegacyApiKey.path()

Retrieve the currently configured path for saved data.

planet_auth.FileBackedPlanetLegacyApiKey.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.FileBackedPlanetLegacyApiKey.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.FileBackedPlanetLegacyApiKey.set_path(file_path)

Update storage path for the object.

planet_auth.FileBackedPlanetLegacyApiKey.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.FileBackedPlanetLegacyApiKey.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.FileBackedPlanetLegacyApiKey.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.InvalidTokenException

Bases: AuthException

Base class for all exceptions that indicate a failure when authenticating a token. Sub-classes may be used to indicate more specific errors.

This exception should not be used to indicate other error conditions that may arise during authentication/authorization.

planet_auth.InvalidTokenException.recast(*exceptions, **params) classmethod

Decorator to recast an exception as the specified exception: Example:

@AuthException.recast(Exception)
@AuthException_SubClass.recast(Some_Specific_Exception)
def raise_my_exception2():
    raise Some_Specific_Exception()

Exercise caution when using multiple re-casts. Recasting as something that is then caught by a decorator further up the stack causes problems: Example:

@AuthException.recast(Exception) # Causes a problem, since it will catch
                                 # the results of the recasts below
@AuthException_SomeSubException.recast(Some_Specific_Exception)
def raise_my_exception2():
    raise Some_Specific_Exception()

planet_auth.NoOpAuthClientConfig

Bases: AuthClientConfig

Auth client that does nothing.

planet_auth.NoOpAuthClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.NoOpAuthClientConfig.check_data(data)

Check that the provided data is valid. Throws an exception if the data is not valid. This allows the base class to refuse to store or use data, while leaving it to child classes to know what constitutes "valid". Child classes should raise FileBackedJsonObjectException exception.

Child classes should override this method as required to do more application specific data integrity checks. They should also call validation on their base classes so that all layers of validation are performed.

The base assertion is that the data structure has been set. It may be empty, but may not be None. The None data structure is treated as a special case, and means that the class has been constructed, but the data has never been set. Once data has been set, it is only permitted to be set to valid values. The intent of this behavior is to support JIT loading semantics.

planet_auth.NoOpAuthClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.NoOpAuthClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.NoOpAuthClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.NoOpAuthClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.NoOpAuthClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.NoOpAuthClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.NoOpAuthClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.NoOpAuthClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.NoOpAuthClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.NoOpAuthClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.NoOpAuthClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.NoOpAuthClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.NoOpAuthClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.NoOpAuthClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.NoOpAuthClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.ObjectStorageProvider

Bases: ABC

Abstract interface used to persist objects to storage.

planet_auth.ObjectStorageProvider.load_obj(key) abstractmethod

Read an object from storage :return:

planet_auth.ObjectStorageProvider.mtime(key) abstractmethod

Return the last modified time in seconds since the epoc for the object. If the object does not exist, an exception should be raised.

planet_auth.ObjectStorageProvider.obj_exists(key) abstractmethod

Check whether a given object exists in storage.

planet_auth.ObjectStorageProvider.obj_rename(src, dst) abstractmethod

Rename/Move an object from the source path to the destination path.

planet_auth.ObjectStorageProvider.save_obj(key, data) abstractmethod

Write an object to storage :return:

planet_auth.OidcAuthClient

Bases: AuthClient, ABC

Base class for AuthClient implementations that implement an OAuth/OIDC authentication flow.

planet_auth.OidcAuthClient.can_login_unattended() abstractmethod

Check whether the client can perform an unattended login.

Depending on the implementation, some clients may be able to perform unattended logins based on information the client config (e.g. static API key clients can do this). These should return true. Other clients will always require user interactive logins (e.g. a user interactive client using a browser and MFA to login). These should return false. Some clients may be flexible and support either depending on the state of their configuration. These should return a result based on their configuration.

planet_auth.OidcAuthClient.default_request_authenticator(credential) abstractmethod

Return an instance of the default request authenticator to use for the specific AuthClient type and configured to use the provided credential file for persistence.

It's not automatic that the default is always the right choice. Some authenticators may initiate logins, which may be interactive or not depending on the specifics of the AuthClient configuration and implementation type. Whether or not interactivity can be tolerated depends on the specifics of the surrounding application.

In the simplest cases, there really is no relationship between the AuthClient and the request authenticator (see static key implementations). This relationship emerges when the mechanisms of an AuthClient requires frequent refreshing of the Credential. In these cases, it is convenient for the CredentialRequestAuthenticator to also have an AuthClient that is capable of performing this refresh transparently as needed.

AuthClient implementors should favor defaults that do not require user interaction after an initial Credential has been obtained from an initial call to login()

Parameters:

Name	Type	Description	Default
credential	Union[Path, Credential]	A Credential object, or a Path to the credential file that can be used to create an appropriate credential object.	required

Returns: Returns an instance of the default request authenticator class to use for Credentials of the type obtained by the AuthClient.

planet_auth.OidcAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.OidcAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.OidcAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.OidcAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.OidcAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.OidcAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.OidcAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.OidcAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.OidcAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.OidcAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.OidcAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.OidcAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.OidcAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.OidcAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.OidcAuthClientConfig

Bases: AuthClientConfig, ABC

Base config class shared by all OAuth/OIDC auth clients.

planet_auth.OidcAuthClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.OidcAuthClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.OidcAuthClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.OidcAuthClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.OidcAuthClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.OidcAuthClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.OidcAuthClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.OidcAuthClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.OidcAuthClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.OidcAuthClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.OidcAuthClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.OidcAuthClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.OidcAuthClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.OidcAuthClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.OidcAuthClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.OidcAuthClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.OidcClientValidatorAuthClient

Bases: OidcAuthClient

The OidcClientValidatorAuthClient is an OAuth2/OIDC client that does not have an identity of its own. It cannot perform a login or obtain access or ID tokens, and it cannot call out to resource servers covered by the issuer's audiences on behalf of users or itself. Instead, this OAuth auth client type exists for programs that need to validate tokens than have been presented to them. This is useful for resource servers themselves when authenticating or authorizing clients.

The implementation is essentially the planet_auth.OidcAuthClient base class with outbound client capabilities disabled.

It should be noted that the other planet_auth.OidcAuthClient derived classes that implement various OAuth flows can also be used to validate clients when inbound and outbound connections fall under the same token issuer realm of trust. But, for use cases where only the validation of incoming requests is required, this class is suitable and does not require the allocation of a client ID.

planet_auth.OidcClientValidatorAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.OidcClientValidatorAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.OidcClientValidatorAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.OidcClientValidatorAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.OidcClientValidatorAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.OidcClientValidatorAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.OidcClientValidatorAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.OidcClientValidatorAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.OidcClientValidatorAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.OidcClientValidatorAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.OidcClientValidatorAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.OidcClientValidatorAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.OidcClientValidatorAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.OidcClientValidatorAuthClientConfig

Bases: OidcAuthClientConfig

Configuration for a planet_auth.OidcClientValidatorAuthClient AuthClient

planet_auth.OidcClientValidatorAuthClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.OidcClientValidatorAuthClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.OidcClientValidatorAuthClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.OidcClientValidatorAuthClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.OidcClientValidatorAuthClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.OidcClientValidatorAuthClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.OidcClientValidatorAuthClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.OidcClientValidatorAuthClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.OidcClientValidatorAuthClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.OidcClientValidatorAuthClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.OidcClientValidatorAuthClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.OidcClientValidatorAuthClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.OidcClientValidatorAuthClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.OidcClientValidatorAuthClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.OidcClientValidatorAuthClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.OidcClientValidatorAuthClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.OidcMultiIssuerValidator

The OidcMultiIssuerValidator is a token validator that can be configured to trust multiple token issuers. This is not expected to be a normal operating mode for most services. This was developed to support migration use cases.

This is a higher level utility class, and is built on top of planet_auth.AuthClient classes. For a lower level utilities, see planet_auth.TokenValidator, or see the validation functionality built into planet_auth.AuthClient.

Warning

Never ever ever EVER use this to bridge between trust environments. For example, do not use this to trust staging and production environment issuing authorities.

planet_auth.OidcMultiIssuerValidator.__init__(trusted, log_result=True)

Create a new multi issuer validator using the provided auth clients. The auth clients are expected to be any Auth that implements OIDC functionality.

Since the expected audience could be different for each issuer, the expectation is that the provided Auth contexts will be configured with an audience, even though that is an optional configuration parameter for most implementing classes.

Parameters:

Name	Type	Description	Default
trusted	List[Auth]		required
log_result	bool		True

planet_auth.OidcMultiIssuerValidator.from_auth_server_configs(trusted_auth_server_configs, log_result=True) staticmethod

Create a new multi issuer validator from the provided auth client config dictionaries.

Parameters:

Name	Type	Description	Default
trusted_auth_server_configs	List[dict]	A list of configuration dictionaries. Unless remote validation is required, the configuration dictionaries may be sparse, containing only the auth_server and audiences properties. auth_server is expected to be a single string, containing the URL of the OAuth issuer. audiences is expected to be an array, and contain a list of supported audiences.	required
log_result	bool	Control whether successful token validations against trusted auth servers should be logged.	True

Example

auth_validator = planet_auth.OidcMultiIssuerValidator.from_auth_server_configs(
    trusted_auth_server_configs=[
        {
            "auth_server": "https://oauth_server.example.com/oauth2/auth_server_id",
            "audiences": ["https://api.example.com/"],
        },
    ],
)

planet_auth.OidcMultiIssuerValidator.from_auth_server_urls(trusted_auth_server_urls, audience=None, log_result=True) staticmethod

Create a new multi issuer validator from the provided OAuth server URLs. This is a convenience method for common cases.

Warning

When mutli validators are initialized from URLs by this method, it is assumed that the auth server URL (used to perform OIDC discovery and locate all the other API endpoints) and the issuer (which is burned into the signed access tokens) are the same. This is normally true, but not universally required. For example, some network proxy configurations may make these different.

This assumption is made in part to avoid the discovery lookup during construction. Since a network lookup could potentially fail, construction of the entire configuration could be rendered non-functional by a network or configuration problem impacting a single auth server.

The multi-validator requires foreknowledge of all the issuers for proper initialization. So, without this assumption it would be unavoidable to introduce network risk into the constructor. This assumption allows us to push all network errors to runtime, and avoids possible initialization time errors.

planet_auth.OidcMultiIssuerValidator.validate_access_token(token, do_remote_revocation_check=False, scopes_anyof=None)

Validate an access token, and return the token's claims if the all validation has succeeded.

Remote revocation checks should be done for high value operations where it is undesirable to allow revoked tokens to be used for the remainder of their lifetime. Token lifetimes should be chosen to be an acceptable trade-off between permitting revoked tokens for the remainder of the token lifespan for performance and scalability, and performing remote validation for extra security.

When an invalid token is presented, an exception is thrown.

Parameters:

Name	Type	Description	Default
token	str	Token to validate	required
do_remote_revocation_check	bool	Control whether the issuer will be consulted for revocation of the access token.	False
scopes_anyof	list	Optional list of OAuth2 scopes to check for in the token. This list is an "any of" list of scopes. As long as one of the scopes in the list is present, validation will pass. If none of the scopes are present, validation will fail.	None

Returns: Returns a tuple of validation results, as returned from planet_auth.AuthClient.validate_access_token_local and planet_auth.AuthClient.validate_access_token_remote

planet_auth.PlanetLegacyAuthClient

Bases: AuthClient

Implementation of the AuthClient that interacts with Planet's API key auth interfaces.

planet_auth.PlanetLegacyAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.PlanetLegacyAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.PlanetLegacyAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.PlanetLegacyAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.PlanetLegacyAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, username=None, password=None, **kwargs)

Perform a login using Planet Legacy authentication endpoints. Parameters: username: Planet account user name. If not specified, the user will be prompted for their user name. password: Planet user password. If not specified, the user will be prompted for their password. allow_tty_prompt: specify whether login is permitted to request input from the terminal. Returns: Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.PlanetLegacyAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.PlanetLegacyAuthClient.refresh(refresh_token, requested_scopes)

Obtain a refreshed credential using the supplied refresh token. This method will be implemented by concrete AuthClients that implement a particular OAuth flow. Parameters: refresh_token: Refresh token requested_scopes: Scopes to request in the access token Returns: Upon success, a fresh Credential will be returned. As with login(), this credential will not have been persisted to storage. This is the responsibility of the application. AuthClient implementations should raise an exception for all login errors.

planet_auth.PlanetLegacyAuthClient.revoke_access_token(access_token)

Revoke an access token with the authorization server. Parameters: access_token: Access token to revoke.

planet_auth.PlanetLegacyAuthClient.revoke_refresh_token(refresh_token)

Revoke a refresh token with the authorization server. Parameters: refresh_token: Access token to revoke.

planet_auth.PlanetLegacyAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.PlanetLegacyAuthClient.validate_access_token_local(access_token, required_audience=None, scopes_anyof=None)

Validate an access token locally. While the validation is local, the authorization server may still may contacted to obtain signing keys for validation. Signing keys will be cached for future use.

Auth servers (issuers) may provide service for any number of audiences, so which audience is expected / required is potentially different for each discrete validation check. If the required audience is not provided as an argument, the validate should fall back to the audiences configured in the AuthClientConfig.

If the audience is neither provided as an argument nor present in the AuthClientConfig, an error should be raised.

Note

While tokens may have multiple audiences, and AuthClients may be configured to request multiple audiences, the validation method currently only supports checking for a single audience. This could be considered is a bit of an API mismatch. However, at this time this is considered expected and desirable behavior. Validation is generally considered to be occurring in a context that self identifies as a particular audience, and overlapping claims may mean different things to different audiences. Validation should be done in the context of a single audience at a time.

Parameters:

Name	Type	Description	Default
access_token	str	Access token to validate.	required
required_audience	str	Audience that the token is required to have.	None
scopes_anyof	list	Optional list of OAuth2 scopes to check for in the token. This list is an "any of" list of scopes. As long as one of the scopes in the list is present, validation will pass. If none of the scopes are present, validation will fail.	None

Returns: Returns a dictionary of validated token claims. It should be noted that the returned dictionaries from local and service token validation are not exactly the same. Service validation should return a RFC 7662 dictionary. Local validation returns the token claims.

planet_auth.PlanetLegacyAuthClient.validate_access_token_remote(access_token)

Validate an access token with the authorization server. Parameters: access_token: Access token to validate Returns: Returns a dictionary of validated token claims. It should be noted that the returned dictionaries from local and service token validation are not exactly the same. Service validation should return a RFC 7662 dictionary. Local validation returns the token claims.

planet_auth.PlanetLegacyAuthClient.validate_id_token_local(id_token)

Validate an ID token locally. The authorization server may still be called to obtain signing keys for validation. Signing keys will be cached for future use. Parameters: id_token: ID token to validate Returns: Returns a dictionary of validated token claims

planet_auth.PlanetLegacyAuthClient.validate_id_token_remote(id_token)

Validate an ID token with the authorization server. Parameters: id_token: ID token to validate Returns: Returns a dictionary of validated token claims

planet_auth.PlanetLegacyAuthClient.validate_refresh_token_remote(refresh_token)

Validate a refresh token with the authorization server. Parameters: refresh_token: Refresh token to validate Returns: Returns the response from the remove validation service.

planet_auth.PlanetLegacyAuthClientConfig

Bases: AuthClientConfig

Configuration required for planet_auth.PlanetLegacyAuthClient

planet_auth.PlanetLegacyAuthClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.PlanetLegacyAuthClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.PlanetLegacyAuthClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.PlanetLegacyAuthClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.PlanetLegacyAuthClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.PlanetLegacyAuthClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.PlanetLegacyAuthClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.PlanetLegacyAuthClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.PlanetLegacyAuthClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.PlanetLegacyAuthClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.PlanetLegacyAuthClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.PlanetLegacyAuthClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.PlanetLegacyAuthClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.PlanetLegacyAuthClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.PlanetLegacyAuthClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.PlanetLegacyAuthClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.PlanetLegacyRequestAuthenticator

Bases: CredentialRequestAuthenticator

Authenticate a request using a legacy Planet API key. Currently, the credential file is now also capable of saving a JWT, but this authenticator makes no use of it.

planet_auth.PlanetLegacyRequestAuthenticator.auth_flow(request)

Decorate a "httpx" library based request with authentication

planet_auth.PlanetLegacyRequestAuthenticator.credential(refresh_if_needed=False)

Return the current credential.

This may not be the credential the authenticator was constructed with. Request Authenticators are free to refresh credentials depending on the needs of the implementation. This may happen upon this request, or may happen as a side effect of RequestAuthenticator operations.

planet_auth.PlanetLegacyRequestAuthenticator.is_initialized()

Return true if the CredentialRequestAuthenticator has a credential that can be used to make requests. If a credential is not in memory, storage is checked for the existence of a credential, but it will not be loaded from storage at this time, preserving JIT loading behavior.

planet_auth.PlanetLegacyRequestAuthenticator.update_credential_data(new_credential_data)

Provide raw data that should be used to update the Credential object used to authenticate requests. This information will be treated as newer than any file back data associated with the credential held by the authenticator, and the file will be overwritten.

planet_auth.RefreshOrReloginOidcTokenRequestAuthenticator

Bases: RefreshingOidcTokenRequestAuthenticator

Decorate a http request with a bearer auth token. Automatically initiate a refresh request using the refresh token if we know the access token to be close to expiration. If we do not have a refresh token, then fall back to re-initiating a login. Sometimes (like with client credential flow), refresh tokens may not be available and we might want to login rather than refresh. It is not an automatic choice to fall back to login when refresh is not available, since for some auth client configurations login is interactive, and would not be appropriate for headless use cases. Refresh should always be silent.

planet_auth.RefreshOrReloginOidcTokenRequestAuthenticator.auth_flow(request)

Decorate a "httpx" library based request with authentication

planet_auth.RefreshOrReloginOidcTokenRequestAuthenticator.is_initialized()

Return true if the CredentialRequestAuthenticator has a credential that can be used to make requests. If a credential is not in memory, storage is checked for the existence of a credential, but it will not be loaded from storage at this time, preserving JIT loading behavior.

planet_auth.RefreshingOidcTokenRequestAuthenticator

Bases: CredentialRequestAuthenticator

Decorate a http request with an OAuth bearer auth token. Automatically initiate a refresh request if we know the access token to be close to expiration.

This class assumes access tokens are JWTs and can be locally inspected, which OIDC and OAuth do not require. JWT access tokens that comply with RFC 9068 can be checked for expiration timing without hitting the network token introspection endpoint.

planet_auth.RefreshingOidcTokenRequestAuthenticator.auth_flow(request)

Decorate a "httpx" library based request with authentication

planet_auth.RefreshingOidcTokenRequestAuthenticator.is_initialized()

Return true if the CredentialRequestAuthenticator has a credential that can be used to make requests. If a credential is not in memory, storage is checked for the existence of a credential, but it will not be loaded from storage at this time, preserving JIT loading behavior.

planet_auth.RequestAuthenticator

Bases: AuthBase, Auth, ABC

Decorate a http request with a bearer auth token.

planet_auth.RequestAuthenticator.auth_flow(request)

Decorate a "httpx" library based request with authentication

planet_auth.RequestAuthenticator.pre_request_hook() abstractmethod

Hook that will be called immediately prior to making an HTTP request so that implementing classes may make preparations. Derived classes are expected to populate the member fields _token_prefix, _token_body, and _auth_header with values that are appropriate to the specific implementation. These will then be used during subsequent HTTP request to authenticate the connection using a beater token authorization HTTP header.

Implementers may make external network calls as required to perform necessary tasks such as refreshing access tokens.

Implementations should not require user interaction by default. If an authentication mechanism will require user interaction, this should be an explicit decision that is left to the application using the RequestAuthenticator to control.

planet_auth.ResourceOwnerAuthClient

Bases: ResourceOwnerAuthClientBase, OidcAuthClientWithNoneClientAuth

AuthClient implementation that implements the OAuth password grant to obtain user tokens. This implementation is for public clients that cannot maintain client confidentiality.

planet_auth.ResourceOwnerAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.ResourceOwnerAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.ResourceOwnerAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.ResourceOwnerAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.ResourceOwnerAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.ResourceOwnerAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.ResourceOwnerAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.ResourceOwnerAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.ResourceOwnerAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.ResourceOwnerAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.ResourceOwnerAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.ResourceOwnerAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.ResourceOwnerAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.ResourceOwnerAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.ResourceOwnerClientConfig

Bases: OidcAuthClientConfig

Configuration required for planet_auth.ResourceOwnerAuthClient

planet_auth.ResourceOwnerClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.ResourceOwnerClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.ResourceOwnerClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.ResourceOwnerClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.ResourceOwnerClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.ResourceOwnerClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.ResourceOwnerClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.ResourceOwnerClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.ResourceOwnerClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.ResourceOwnerClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.ResourceOwnerClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.ResourceOwnerClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.ResourceOwnerClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.ResourceOwnerClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.ResourceOwnerClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.ResourceOwnerClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.ResourceOwnerWithClientSecretAuthClient

Bases: ResourceOwnerAuthClientBase, OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment

AuthClient implementation that implements the OAuth password grant to obtain user tokens. This implementation is for confidential clients that use a client secret to protect the client confidentiality.

planet_auth.ResourceOwnerWithClientSecretAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.ResourceOwnerWithClientSecretAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.ResourceOwnerWithClientSecretAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.ResourceOwnerWithClientSecretAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.ResourceOwnerWithClientSecretAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.ResourceOwnerWithClientSecretAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.ResourceOwnerWithClientSecretAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.ResourceOwnerWithClientSecretAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.ResourceOwnerWithClientSecretAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.ResourceOwnerWithClientSecretAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.ResourceOwnerWithClientSecretAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.ResourceOwnerWithClientSecretAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.ResourceOwnerWithClientSecretAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.ResourceOwnerWithClientSecretAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.ResourceOwnerWithClientSecretClientConfig

Bases: ResourceOwnerClientConfig, OidcAuthClientWithClientSecretClientConfig

Configuration required for planet_auth.ResourceOwnerWithClientSecretAuthClient

planet_auth.ResourceOwnerWithClientSecretClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.ResourceOwnerWithClientSecretClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.ResourceOwnerWithClientSecretClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.ResourceOwnerWithClientSecretClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.ResourceOwnerWithClientSecretClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.ResourceOwnerWithClientSecretClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.ResourceOwnerWithClientSecretClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.ResourceOwnerWithClientSecretClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.ResourceOwnerWithClientSecretClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.ResourceOwnerWithClientSecretClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.ResourceOwnerWithClientSecretClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.ResourceOwnerWithClientSecretClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.ResourceOwnerWithClientSecretClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.ResourceOwnerWithClientSecretClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.ResourceOwnerWithClientSecretClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.ResourceOwnerWithClientSecretClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.ResourceOwnerWithPubKeyAuthClient

Bases: ResourceOwnerAuthClientBase, OidcAuthClientWithClientPubkey

AuthClient implementation that implements the OAuth password grant to obtain user tokens. This implementation is for confidential clients that use a public/private keypair ti protect the client confidentiality.

planet_auth.ResourceOwnerWithPubKeyAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.ResourceOwnerWithPubKeyAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.ResourceOwnerWithPubKeyAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.ResourceOwnerWithPubKeyAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.ResourceOwnerWithPubKeyAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.ResourceOwnerWithPubKeyAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.ResourceOwnerWithPubKeyAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.ResourceOwnerWithPubKeyAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.ResourceOwnerWithPubKeyAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.ResourceOwnerWithPubKeyAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.ResourceOwnerWithPubKeyAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.ResourceOwnerWithPubKeyAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.ResourceOwnerWithPubKeyAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.ResourceOwnerWithPubKeyAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.ResourceOwnerWithPubKeyClientConfig

Bases: ResourceOwnerClientConfig, OidcAuthClientWithPubKeyClientConfig

Configuration required for planet_auth.ResourceOwnerWithPubKeyAuthClient

planet_auth.ResourceOwnerWithPubKeyClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.ResourceOwnerWithPubKeyClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.ResourceOwnerWithPubKeyClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.ResourceOwnerWithPubKeyClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.ResourceOwnerWithPubKeyClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.ResourceOwnerWithPubKeyClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.ResourceOwnerWithPubKeyClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.ResourceOwnerWithPubKeyClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.ResourceOwnerWithPubKeyClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.ResourceOwnerWithPubKeyClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.ResourceOwnerWithPubKeyClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.ResourceOwnerWithPubKeyClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.ResourceOwnerWithPubKeyClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.ResourceOwnerWithPubKeyClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.ResourceOwnerWithPubKeyClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.ResourceOwnerWithPubKeyClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.TokenValidator

Helper class to perform validation of OAuth2 JWT tokens. This class provides the implementation for the locally performed validation in planet_auth.OidcAuthClient classes, but may also be used as a stand-alone validator.

This is a lower level utility class, and has no dependency or knowledge of the higher level planet_auth.AuthClient or planet_auth.Auth classes.

For a higher level application utility, see planet_auth.OidcMultiIssuerValidator

planet_auth.TokenValidator.hazmat_unverified_decode(token_str) staticmethod

Decode a JWT without verifying the signature or any claims.

Warning

Treat unverified token claims with extreme caution. Nothing can be trusted until the token is verified.

Returns:

Type	Description
Tuple[Dict, Dict, Any]	Returns the decoded JWT header, payload, and signature

planet_auth.TokenValidator.validate_id_token(token_str, issuer, client_id, required_claims=None, nonce=None)

Validate a JWT this is a OIDC ID token. Steps over and above basic token validation are performed, as described in https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation

planet_auth.TokenValidator.validate_token(token_str, issuer, audience, required_claims=None, scopes_anyof=None, nonce=None)

Validate the provided token string. Required claims are validated for their presence only. It is up to the application to assert that the claim values meet thr requirements of the caller's use case.

If a nonce is provided, the validator will require that the token have a nonce claim, and that its value matches the supplied value.

Parameters:

Name	Type	Description	Default
token_str	str	Raw encoded JWT string.	required
issuer	str	Required token issuer.	required
audience	str	Required token audience.	required
required_claims	list	Optional list of additional claims that must be present in the token. these claims are only checked for the presence. It is up to the caller to assert that the values are appropriate for the application	None
scopes_anyof	list	Optional list of OAuth2 scopes to check for in the token. This list is an "any of" list of scopes. As long as one of the scopes in the list is present, validation will pass. If none of the scopes are present, validation will fail.	None
nonce	str	Optional nonce value to check for in the token.	None

A note on scope validation.

"Any of" scope enforcement semantics may not make sense for all applications. "All of" is a feature that might be desirable, but has not been implemented. ("Any of" or "all of" for any other arbitrary claim might also have value. But again, this is not implemented here. At some point deriving application meaning from the claims present is a concern of the higher level application, and not a concern of the token validator.)

planet_auth.setPyLoggerForAuthLogger(py_logger)

Set the python logger that should be used by the library. Parameters: py_logger: The python logger that the library should use. Set this to None to completely mute logging.

planet_auth.setStringLogging()

Configure the library to emit simple string log messages. When this mode is set, logs will be emitted with all information in the log message, ahd the logger's extra field will be set to None.

planet_auth.setStructuredLogging(nested_key=DEFAULT_NESTED_KEY)

Configure the library to emit structured log messages. When this mode is set, logs will be emitted specifying information using the logger's extra field.

Parameters:

Name	Type	Description	Default
nested_key	Optional[str]	dict key in which to wrap the library's data logged under the extra field. The default is to include all library logged extra fields encapsulated inside a dictionary with the single key props. This default was chosen to comform to the expectations of the json_logging python module. For example, by default extra data will be submitted to the logger as log(msg="log msg", extra={"props": {library_provided_extra_keys}}). Set this to None to forego wrapping.	DEFAULT_NESTED_KEY

planet_auth.auth

planet_auth.auth.Auth

A container class for initializing and managing a working set of authentication objects. See factory methods and the planet_auth_utils.PlanetAuthFactory class for user-friendly initialization.

This container class provides an "auth context" is geared toward client use cases - that is, authenticating ourselves as a client with the goal of making authenticated network API calls to resource servers. Resource servers that have to validate incoming clients' credentials have some different concerns not handled here.

planet_auth.auth.Auth.__init__(auth_client, request_authenticator, token_file_path=None, profile_name=None)

Create a new auth container object with the specified auth components. Users should use one of the more friendly static initializer methods.

planet_auth.auth.Auth.auth_client()

Get the currently configured auth client. Returns: The current AuthClient instance.

planet_auth.auth.Auth.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate(). This call will perform all the same actions as login().

planet_auth.auth.Auth.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

planet_auth.auth.Auth.ensure_request_authenticator_is_ready(allow_open_browser=False, allow_tty_prompt=False)

Do everything necessary to ensure the request authenticator is ready for use, while still biasing towards just-in-time operations and not making unnecessary network requests or prompts for user interaction.

This can be more complex than it sounds given the variations in the capabilities of authentication clients and possible session states. Clients may be initialized with active sessions, initialized with stale but still valid sessions, initialized with invalid or expired sessions, or completely uninitialized. The process taken to ensure client readiness with as little user disruption as possible is as follows:

1. If the client has been logged in and has a non-expired short-term access token, the client will be considered ready without prompting the user or probing the network. This will not require user interaction.
2. If the client has not been logged in and is a type that can do so without prompting the user, the client will be considered ready without prompting the user or probing the network. This will not require user interaction. Login will be delayed until it is required.
3. If the client has been logged in and has an expired short-term access token, the network will be probed to attempt a refresh of the session. This should not require user interaction. If refresh fails, the user will be prompted to perform a fresh login, requiring user interaction.
4. If the client has never been logged in and is a type that requires a user interactive login, a user interactive login will be initiated.

There still may be conditions where we believe we are ready, but requests still ultimately fail. For example, if the auth context holds a static API key or username/password, it is assumed to be ready but the credentials could be bad. Even when ready with valid credentia, requests could fail if the service rejects the request due to its own policy configuration.

Parameters:

Name	Type	Description	Default
allow_open_browser	Optional[bool]	specify whether login is permitted to open a browser window.	False
allow_tty_prompt	Optional[bool]	specify whether login is permitted to request input from the terminal.	False

planet_auth.auth.Auth.initialize_from_client(auth_client, initial_token_data=None, token_file=None, profile_name=None) staticmethod

Construct and initialize a working set of authentication primitives, returning them in a new container object. Parameters: auth_client: An already constructed AuthClient object. initial_token_data: Token data to use for initial state, if not to be read from storage for initialization. token_file: A path to the storage location that should be used for credential storage. Credentials will be read from this location, and this location will be used to save refreshed credentials. Depending on the configuration, this may be ignored or may be None. When this is set to None, tokens will not be persisted to storage. profile_name: A profile name used to identify the Auth configration at runtime.

planet_auth.auth.Auth.initialize_from_config(client_config, initial_token_data=None, token_file=None, profile_name=None) staticmethod

Construct and initialize a working set of authentication primitives, returning them in a new container object. Parameters: client_config: A constructed AuthClientConfig object. initial_token_data: Token data to use for initial state, if not to be read from storage for initialization. token_file: A path to the storage location that should be used for credential storage. Credentials will be read from this location, and this location will be used to save refreshed credentials. Depending on the configuration, this may be ignored or may be None. When this is set to None, tokens will not be persisted to storage. profile_name: A profile name used to identify the Auth configration at runtime.

planet_auth.auth.Auth.initialize_from_config_dict(client_config, initial_token_data=None, token_file=None, profile_name=None, storage_provider=None) staticmethod

Construct and initialize a working set of authentication primitives, returning them in a new container object. Parameters: client_config: A dictionary containing a valid auth client configuration. initial_token_data: Token data to use for initial state, if not to be read from storage for initialization. token_file: A path to a storage location that should be used for credential storage. Credentials will be read from this location, and this location may be used to save refreshed credentials. Depending on the configuration, this may be ignored or may be None. When this is set to None, tokens will not be persisted to storage. profile_name: A profile name used to identify the Auth configration at runtime. storage_provider: A custom storage provider to use.

planet_auth.auth.Auth.login(allow_open_browser=False, allow_tty_prompt=False, **kwargs)

Perform a login with the configured auth client. This higher level function will ensure that the token is saved to storage if Auth context has been configured with a suitable token storage path. Otherwise, the token will be held only in memory. In all cases, the request authenticator will also be updated with the new credentials.

Parameters:

Name	Type	Description	Default
allow_open_browser	Optional[bool]	specify whether login is permitted to open a browser window.	False
allow_tty_prompt	Optional[bool]	specify whether login is permitted to request input from the terminal.	False

planet_auth.auth.Auth.profile_name()

Get the current profile name, if known. May be empty if initialization was performed without using a profile. Returns: Returns the name of the current profile, if known.

planet_auth.auth.Auth.request_authenticator()

Get the current request authenticator. Returns: The current CredentialRequestAuthenticator instance.

planet_auth.auth.Auth.request_authenticator_is_ready()

Check whether the current context's request_authenticator is ready for use.

A context is considered initialized if it can be used to make authenticated client requests without user intervention. What exactly that requires can vary by auth client configured in the context. For example, simple API key clients only need an API key in their configuration. OAuth2 user clients need to have performed a user login and obtained access or refresh tokens.

Note: This will not detect when a credential is expired or otherwise invalid.

planet_auth.auth.Auth.token_file_path()

Get the path to the current credentials file. Returns: The path to the current credentials file.

planet_auth.auth_client

planet_auth.auth_client.AuthClient

Bases: ABC

Base class for auth clients. Concrate instances of this base class manage the specific of how to authenticate a user and obtain credentials that may be used for service APIs.

The factory methods in the base class accepts a client specific client configuration type, and will return an instance of an appropriate subclass.

Example

from planet_auth import AuthClientConfig, AuthClient
config_dict = { ... } # See AuthClientConfig
my_auth_config = AuthClientConfig.from_dict(config_dict)
my_auth_client = AuthClient.from_config(my_auth_config)

planet_auth.auth_client.AuthClient.can_login_unattended() abstractmethod

Check whether the client can perform an unattended login.

Depending on the implementation, some clients may be able to perform unattended logins based on information the client config (e.g. static API key clients can do this). These should return true. Other clients will always require user interactive logins (e.g. a user interactive client using a browser and MFA to login). These should return false. Some clients may be flexible and support either depending on the state of their configuration. These should return a result based on their configuration.

planet_auth.auth_client.AuthClient.default_request_authenticator(credential) abstractmethod

Return an instance of the default request authenticator to use for the specific AuthClient type and configured to use the provided credential file for persistence.

It's not automatic that the default is always the right choice. Some authenticators may initiate logins, which may be interactive or not depending on the specifics of the AuthClient configuration and implementation type. Whether or not interactivity can be tolerated depends on the specifics of the surrounding application.

In the simplest cases, there really is no relationship between the AuthClient and the request authenticator (see static key implementations). This relationship emerges when the mechanisms of an AuthClient requires frequent refreshing of the Credential. In these cases, it is convenient for the CredentialRequestAuthenticator to also have an AuthClient that is capable of performing this refresh transparently as needed.

AuthClient implementors should favor defaults that do not require user interaction after an initial Credential has been obtained from an initial call to login()

Parameters:

Name	Type	Description	Default
credential	Union[Path, Credential]	A Credential object, or a Path to the credential file that can be used to create an appropriate credential object.	required

Returns: Returns an instance of the default request authenticator class to use for Credentials of the type obtained by the AuthClient.

planet_auth.auth_client.AuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.auth_client.AuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.auth_client.AuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.auth_client.AuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.auth_client.AuthClient.login(allow_open_browser=False, allow_tty_prompt=False, **kwargs) abstractmethod

Perform an initial login using the authentication mechanism implemented by the AuthClient instance. The results of a successful login is FileBackedJsonObject Credential containing credentials that may be used for subsequent service API requests. How these credentials are used for this purpose is outside the scope of either the AuthClient or the Credential. This is the job of a RequestAuthenticator.

The login command is permitted to be user interactive. Depending on the implementation, this may include terminal prompts, or may require the use of a web browser.

Authentication parameters are specific to each implementation. Consult subclass documentation for details.

Parameters:

Name	Type	Description	Default
allow_open_browser	Optional[bool]	specify whether login is permitted to open a browser window.	False
allow_tty_prompt	Optional[bool]	specify whether login is permitted to request input from the terminal.	False

Returns: Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type. AuthClient implementations should raise an exception for all login errors.

planet_auth.auth_client.AuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.auth_client.AuthClient.refresh(refresh_token, requested_scopes)

Obtain a refreshed credential using the supplied refresh token. This method will be implemented by concrete AuthClients that implement a particular OAuth flow. Parameters: refresh_token: Refresh token requested_scopes: Scopes to request in the access token Returns: Upon success, a fresh Credential will be returned. As with login(), this credential will not have been persisted to storage. This is the responsibility of the application. AuthClient implementations should raise an exception for all login errors.

planet_auth.auth_client.AuthClient.revoke_access_token(access_token)

Revoke an access token with the authorization server. Parameters: access_token: Access token to revoke.

planet_auth.auth_client.AuthClient.revoke_refresh_token(refresh_token)

Revoke a refresh token with the authorization server. Parameters: refresh_token: Access token to revoke.

planet_auth.auth_client.AuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.auth_client.AuthClient.validate_access_token_local(access_token, required_audience=None, scopes_anyof=None)

Validate an access token locally. While the validation is local, the authorization server may still may contacted to obtain signing keys for validation. Signing keys will be cached for future use.

Auth servers (issuers) may provide service for any number of audiences, so which audience is expected / required is potentially different for each discrete validation check. If the required audience is not provided as an argument, the validate should fall back to the audiences configured in the AuthClientConfig.

If the audience is neither provided as an argument nor present in the AuthClientConfig, an error should be raised.

Note

While tokens may have multiple audiences, and AuthClients may be configured to request multiple audiences, the validation method currently only supports checking for a single audience. This could be considered is a bit of an API mismatch. However, at this time this is considered expected and desirable behavior. Validation is generally considered to be occurring in a context that self identifies as a particular audience, and overlapping claims may mean different things to different audiences. Validation should be done in the context of a single audience at a time.

Parameters:

Name	Type	Description	Default
access_token	str	Access token to validate.	required
required_audience	str	Audience that the token is required to have.	None
scopes_anyof	list	Optional list of OAuth2 scopes to check for in the token. This list is an "any of" list of scopes. As long as one of the scopes in the list is present, validation will pass. If none of the scopes are present, validation will fail.	None

Returns: Returns a dictionary of validated token claims. It should be noted that the returned dictionaries from local and service token validation are not exactly the same. Service validation should return a RFC 7662 dictionary. Local validation returns the token claims.

planet_auth.auth_client.AuthClient.validate_access_token_remote(access_token)

Validate an access token with the authorization server. Parameters: access_token: Access token to validate Returns: Returns a dictionary of validated token claims. It should be noted that the returned dictionaries from local and service token validation are not exactly the same. Service validation should return a RFC 7662 dictionary. Local validation returns the token claims.

planet_auth.auth_client.AuthClient.validate_id_token_local(id_token)

Validate an ID token locally. The authorization server may still be called to obtain signing keys for validation. Signing keys will be cached for future use. Parameters: id_token: ID token to validate Returns: Returns a dictionary of validated token claims

planet_auth.auth_client.AuthClient.validate_id_token_remote(id_token)

Validate an ID token with the authorization server. Parameters: id_token: ID token to validate Returns: Returns a dictionary of validated token claims

planet_auth.auth_client.AuthClient.validate_refresh_token_remote(refresh_token)

Validate a refresh token with the authorization server. Parameters: refresh_token: Refresh token to validate Returns: Returns the response from the remove validation service.

planet_auth.auth_client.AuthClientConfig

Bases: FileBackedJsonObject, ABC

Base class for auth client configuration objects. Each concrete auth client type has a dedicated auth client config type to provide client specific validation and guardrails.

The factory methods in the base class accept a dictionary, and will return an instance of an appropriate subclass.

planet_auth.auth_client.AuthClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.auth_client.AuthClientConfig.check_data(data)

Check that the provided data is valid. Throws an exception if the data is not valid. This allows the base class to refuse to store or use data, while leaving it to child classes to know what constitutes "valid". Child classes should raise FileBackedJsonObjectException exception.

Child classes should override this method as required to do more application specific data integrity checks. They should also call validation on their base classes so that all layers of validation are performed.

The base assertion is that the data structure has been set. It may be empty, but may not be None. The None data structure is treated as a special case, and means that the class has been constructed, but the data has never been set. Once data has been set, it is only permitted to be set to valid values. The intent of this behavior is to support JIT loading semantics.

planet_auth.auth_client.AuthClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.auth_client.AuthClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.auth_client.AuthClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.auth_client.AuthClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.auth_client.AuthClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.auth_client.AuthClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.auth_client.AuthClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.auth_client.AuthClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.auth_client.AuthClientConfig.meta() abstractmethod classmethod

Return a dictionary of metadata. The meta dictionary provides a place to store information that is primarily for users of AuthClient types rather than for the operation of the Auth Client itself.

Meta Keys

client_type: The literal value used for client_type in configuration dictionaries that indicates the selection of the AuthClient type.

auth_client_class: The concrete AuthClient class that is served by the configuration type.

display_name: Display name for the AuthClient type

description: A description of the AuthClient type

config_hints: A list configuration hints bootstrapping a configuration with a wizard of some sort. This is distinct from a rigid schema for the configuration type.

planet_auth.auth_client.AuthClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.auth_client.AuthClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.auth_client.AuthClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.auth_client.AuthClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.auth_client.AuthClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.auth_client.AuthClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.auth_client.AuthClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.auth_exception

planet_auth.auth_exception.AuthException

Bases: Exception

Base Exception class for all exceptions thrown from the planet_auth library.

planet_auth.auth_exception.AuthException.recast(*exceptions, **params) classmethod

Decorator to recast an exception as the specified exception: Example:

@AuthException.recast(Exception)
@AuthException_SubClass.recast(Some_Specific_Exception)
def raise_my_exception2():
    raise Some_Specific_Exception()

Exercise caution when using multiple re-casts. Recasting as something that is then caught by a decorator further up the stack causes problems: Example:

@AuthException.recast(Exception) # Causes a problem, since it will catch
                                 # the results of the recasts below
@AuthException_SomeSubException.recast(Some_Specific_Exception)
def raise_my_exception2():
    raise Some_Specific_Exception()

planet_auth.auth_exception.InvalidTokenException

Bases: AuthException

Base class for all exceptions that indicate a failure when authenticating a token. Sub-classes may be used to indicate more specific errors.

This exception should not be used to indicate other error conditions that may arise during authentication/authorization.

planet_auth.auth_exception.InvalidTokenException.recast(*exceptions, **params) classmethod

Decorator to recast an exception as the specified exception: Example:

@AuthException.recast(Exception)
@AuthException_SubClass.recast(Some_Specific_Exception)
def raise_my_exception2():
    raise Some_Specific_Exception()

Exercise caution when using multiple re-casts. Recasting as something that is then caught by a decorator further up the stack causes problems: Example:

@AuthException.recast(Exception) # Causes a problem, since it will catch
                                 # the results of the recasts below
@AuthException_SomeSubException.recast(Some_Specific_Exception)
def raise_my_exception2():
    raise Some_Specific_Exception()

planet_auth.credential

planet_auth.credential.Credential

Bases: FileBackedJsonObject

A storage backed credential. A credential is expected to be a json dict. Per the base class default storage provider implementation, clear-text .json files or .sops.json files with field level encryption are supported. Custom storage providers may offer different functionality.

Subclass Implementor Notes

The Credential class reserves the data fields _iat and _exp for internal use. These are used to record the time the credential was issued and the time that it expires respectively, expressed as seconds since the epoch. A None or NULL value for _exp indicates that the credential never expires.

This base class does not set these values. It is the responsibility of subclasses to set these values as appropriate. If left unset, the credential will be treated as a non-expiring credential with an indeterminate issued time.

Subclasses that wish to provide values should do so in their constructor and in their set_data() methods.

planet_auth.credential.Credential.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.credential.Credential.check_data(data)

Check that the provided data is valid. Throws an exception if the data is not valid. This allows the base class to refuse to store or use data, while leaving it to child classes to know what constitutes "valid". Child classes should raise FileBackedJsonObjectException exception.

Child classes should override this method as required to do more application specific data integrity checks. They should also call validation on their base classes so that all layers of validation are performed.

The base assertion is that the data structure has been set. It may be empty, but may not be None. The None data structure is treated as a special case, and means that the class has been constructed, but the data has never been set. Once data has been set, it is only permitted to be set to valid values. The intent of this behavior is to support JIT loading semantics.

planet_auth.credential.Credential.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.credential.Credential.expiry_time()

The time that the credential expires, expressed as seconds since the epoch.

planet_auth.credential.Credential.is_expired(at_time=None)

Return true if the credential is expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return false.

planet_auth.credential.Credential.is_expiring()

Return true if the credential has an expiry time.

planet_auth.credential.Credential.is_non_expiring()

Return true if the credential never expires.

planet_auth.credential.Credential.is_not_expired(at_time=None)

Return true if the credential is not expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return true.

planet_auth.credential.Credential.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.credential.Credential.issued_time()

The time that the credential was issued, expressed as seconds since the epoch.

planet_auth.credential.Credential.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.credential.Credential.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.credential.Credential.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.credential.Credential.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.credential.Credential.path()

Retrieve the currently configured path for saved data.

planet_auth.credential.Credential.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.credential.Credential.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.credential.Credential.set_path(file_path)

Update storage path for the object.

planet_auth.credential.Credential.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.credential.Credential.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.credential.Credential.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.internal

Packages and modules not promising stable interfaces.

planet_auth.logging

planet_auth.logging.auth_logger

planet_auth.logging.auth_logger.AuthLogger

Class that wraps the Python logger so that all logs emitted from this library may be logged with the same consistent JSON format. This is being done so that dashboards may be built using structured data over string reg-ex parsing.

planet_auth.logging.auth_logger.AuthLogger.log_exception(default_event=AuthEvent.TRACE, override_event=None, level=logging.WARNING, exception_cls=Exception, **params)

Decorator to log exceptions. Parameters: default_event : Event to log when the exception does not include a more specific event. override_event : Event to log regardless of whether or not the exception includes another event. level : Log level exception_cls : Exception class to catch and log. Example:

@AuthLogger.log_exception(level=logging.WARNING, event=AuthEvent.INVALID_TOKEN)
def raise_my_exception():
    raise Some_Exception()

planet_auth.logging.auth_logger.setPyLoggerForAuthLogger(py_logger)

Set the python logger that should be used by the library. Parameters: py_logger: The python logger that the library should use. Set this to None to completely mute logging.

planet_auth.logging.auth_logger.setStringLogging()

Configure the library to emit simple string log messages. When this mode is set, logs will be emitted with all information in the log message, ahd the logger's extra field will be set to None.

planet_auth.logging.auth_logger.setStructuredLogging(nested_key=DEFAULT_NESTED_KEY)

Configure the library to emit structured log messages. When this mode is set, logs will be emitted specifying information using the logger's extra field.

Parameters:

Name	Type	Description	Default
nested_key	Optional[str]	dict key in which to wrap the library's data logged under the extra field. The default is to include all library logged extra fields encapsulated inside a dictionary with the single key props. This default was chosen to comform to the expectations of the json_logging python module. For example, by default extra data will be submitted to the logger as log(msg="log msg", extra={"props": {library_provided_extra_keys}}). Set this to None to forego wrapping.	DEFAULT_NESTED_KEY

planet_auth.logging.events

planet_auth.logging.events.AuthEvent

Bases: StrEnum

Auth Events.

Events exist to provide structure to log messages, with the initial use case in mind being building dashboards from log messages. Many events are error conditions, and these will overlap with exceptions, but not events indicate errors.

planet_auth.none

planet_auth.none.noop_auth

planet_auth.none.noop_auth.NoOpAuthClientConfig

Bases: AuthClientConfig

Auth client that does nothing.

planet_auth.none.noop_auth.NoOpAuthClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.none.noop_auth.NoOpAuthClientConfig.check_data(data)

Check that the provided data is valid. Throws an exception if the data is not valid. This allows the base class to refuse to store or use data, while leaving it to child classes to know what constitutes "valid". Child classes should raise FileBackedJsonObjectException exception.

Child classes should override this method as required to do more application specific data integrity checks. They should also call validation on their base classes so that all layers of validation are performed.

The base assertion is that the data structure has been set. It may be empty, but may not be None. The None data structure is treated as a special case, and means that the class has been constructed, but the data has never been set. Once data has been set, it is only permitted to be set to valid values. The intent of this behavior is to support JIT loading semantics.

planet_auth.none.noop_auth.NoOpAuthClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.none.noop_auth.NoOpAuthClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.none.noop_auth.NoOpAuthClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.none.noop_auth.NoOpAuthClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.none.noop_auth.NoOpAuthClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.none.noop_auth.NoOpAuthClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.none.noop_auth.NoOpAuthClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.none.noop_auth.NoOpAuthClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.none.noop_auth.NoOpAuthClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.none.noop_auth.NoOpAuthClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.none.noop_auth.NoOpAuthClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.none.noop_auth.NoOpAuthClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.none.noop_auth.NoOpAuthClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.none.noop_auth.NoOpAuthClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.none.noop_auth.NoOpAuthClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc

Package providing an OAuth2/OIDC implementation of the planet_auth package interfaces. This is a generic OAuth2/OIDC auth client, and knows nothing about Planet APIs.

AuthClients are provided for a number of authentication flows, suitable for user interactive or headless use cases.

Several Request Authenticators are provided that can use the OIDC credentials obtained from an AuthClient. Since frequent credential refresh is a part of using OAuth2/OIDC, these authenticators handle this transparently.

planet_auth.oidc.api_clients

planet_auth.oidc.api_clients.api_client

planet_auth.oidc.api_clients.api_client.OidcApiClient

Bases: ABC

Base class that provides utility functions common to interactions with any of the OIDC endpoints.

planet_auth.oidc.api_clients.authorization_api_client

planet_auth.oidc.api_clients.authorization_api_client.AuthorizationApiClient

Low level API client for the OAuth Authorization endpoint. See RFC 6749 - The OAuth 2.0 Authorization Framework for protocol details.

This is not a child of the OidcApiClient base class since, unlike most low level API clients, this class does not directly call the API. Rather, a web browser or other methods are used to interact with the API in most cases so that IDP redirects, MFA, and user interactive authentication can be performed.

planet_auth.oidc.api_clients.authorization_api_client.AuthorizationApiClient.__init__(authorization_uri, authorization_callback_acknowledgement_response_body=None)

Create a new Authorization API Client.

planet_auth.oidc.api_clients.authorization_api_client.AuthorizationApiClient.authcode_from_pkce_auth_request_with_browser_and_callback_listener(client_id, redirect_uri, requested_scopes, requested_audiences, pkce_code_challenge, extra)

Request an authorization code by launching a web browser directed to the OAuth Authorization endpoint. An HTTP listener will be set up to capture the browser redirect after interaction with the auth server and IDP is complete.

Parameters:

Name	Type	Description	Default
client_id	str	The ID of the OAuth client requesting authorization.	required
redirect_uri	str	The callback URI that should be used to return control to the client program after user authentication and authorization has been completed.	required
requested_scopes	List[str]	A list of strings specifying the scopes to request.	required
requested_audiences	List[str]	A list of strings specifying the audiences to request.	required
pkce_code_challenge	str	PKCE challenge code. The caller should generate this code along with a validation code that can be used to verify responses.	required
extra	Dict	Dict of extra parameters to pass to the authorization endpoint.	required

Returns:

Type	Description
str	Returns an auth code upon success. An exception should be raised upon error.

planet_auth.oidc.api_clients.authorization_api_client.AuthorizationApiClient.authcode_from_pkce_auth_request_with_tty_input(client_id, redirect_uri, requested_scopes, requested_audiences, pkce_code_challenge, extra)

Request an authorization code by prompting the user to visit a specific authorization URI, and then prompt the user for the resulting authorization code via a TTY prompt. The redirect URI should point to an application that is capable of accepting the final callback from the authorization URI, and is ready to parse the response and provide the client with the authorization code so that it may be entered at the prompt.

Parameters:

Name	Type	Description	Default
client_id	str	The ID of the OAuth client requesting authorization.	required
redirect_uri	str	The callback URI that should be used to return control to the client program after user authentication and authorization has been completed.	required
requested_scopes	List[str]	A list of strings specifying the scopes to request.	required
requested_audiences	List[str]	A list of strings specifying the audiences to request.	required
pkce_code_challenge	str	PKCE challenge code. The caller should generate this code along with a validation code that can be used to verify responses.	required
extra	Dict	Dict of extra parameters to pass to the authorization endpoint.	required

Returns:

Type	Description
str	Returns an auth code upon success. An exception should be raised upon error.

planet_auth.oidc.api_clients.authorization_api_client.AuthorizationApiClient.prep_pkce_auth_payload(client_id, redirect_uri, requested_scopes, requested_audiences, pkce_code_challenge, extra) staticmethod

Prepare the payload needed to make an authorization request to an OAuth authorization endpoint. This will usually be used to construct query parameters that are appended to the URL of the authorization endpoint, but some implementations are known to accept a POST rather than a GET with URL parameters.

It should also be noted that this method does not prepare any sort of client authentication. Depending on whether this is used in support of a confidential or non-confidential OAuth client, additional work may be required. The details of what may be required may vary depending on the auth server's demands of a confidential client; The auth server may require HTTP auth headers, or that additional assertions are added to the payload, or may require nothing at all. This all depends on the auth server's configuration for the particular client.

Parameters:

Name	Type	Description	Default
client_id	str	The ID of the OAuth client requesting authorization.	required
redirect_uri	str	The callback URI that should be used to return control to the client program after user authentication and authorization has been completed.	required
requested_scopes	List[str]	A list of strings specifying the scopes to request.	required
requested_audiences	List[str]	A list of strings specifying the audiences to request.	required
pkce_code_challenge	str	PKCE challenge code. The caller should generate this code along with a validation code that can be used to verify responses.	required
extra	Dict	Dict of extra parameters to pass to the authorization endpoint.	required

Returns:

Type	Description
Dict	Returns a dict that is suitable for use in making an authorization request.

Example

auth_url = AUTHORIZATION_ENDPOINT_URL + "?" + urlencode(prep_pkce_auth_payload(...))

planet_auth.oidc.api_clients.device_authorization_api_client

planet_auth.oidc.api_clients.device_authorization_api_client.DeviceAuthorizationApiClient

Bases: OidcApiClient

Low level network client for the "device_authorization_endpoint" OAuth2/OIDC network endpoint. This endpoint is defined by RFC 8628. See https://www.rfc-editor.org/rfc/rfc8628

All invalid responses or error responses will result in an exception.

planet_auth.oidc.api_clients.discovery_api_client

planet_auth.oidc.api_clients.discovery_api_client.DiscoveryApiClient

Bases: OidcApiClient

Low level client for OIDC discovery. See https://openid.net/specs/openid-connect-discovery-1_0.html for details.

planet_auth.oidc.api_clients.discovery_api_client.DiscoveryApiClient.__init__(discovery_uri=None, auth_server=None)

Create a new OIDC discovery API client.

planet_auth.oidc.api_clients.discovery_api_client.DiscoveryApiClient.discovery()

Return the discovery information. If the information was previously fetched, the cached information will be returned, and no network connection will be made.

planet_auth.oidc.api_clients.discovery_api_client.DiscoveryApiClient.do_discovery()

Contact the discovery endpoint, download discovery information, and cache the results inside the client.

planet_auth.oidc.api_clients.discovery_api_client.DiscoveryApiClient.do_discovery_jit()

Contact the discovery endpoint and download and cache the results only if discovery had not previously been performed and cached.

planet_auth.oidc.api_clients.introspect_api_client

planet_auth.oidc.api_clients.introspect_api_client.IntrospectionApiClient

Bases: OidcApiClient

Low level network client for the "introspection" OAuth2/OIDC network endpoint. Responses are defined by RFC 7662.

All invalid responses or responses that indicate that a token is not active will result in an exception.

planet_auth.oidc.api_clients.introspect_api_client.IntrospectionApiClient.__init__(introspect_uri)

Create a new token introspection API client

planet_auth.oidc.api_clients.introspect_api_client.IntrospectionApiClient.validate_access_token(access_token, auth_enricher=None)

Validate an access token against the OAuth introspection endpoint. Invalid tokens will result in an exception.

planet_auth.oidc.api_clients.introspect_api_client.IntrospectionApiClient.validate_id_token(id_token, auth_enricher=None)

Validate an ID token against the OAuth introspection endpoint. Invalid tokens will result in an exception.

planet_auth.oidc.api_clients.introspect_api_client.IntrospectionApiClient.validate_refresh_token(refresh_token, auth_enricher=None)

Validate a refresh token against the OAuth introspection endpoint. Invalid tokens will result in an exception.

planet_auth.oidc.api_clients.jwks_api_client

planet_auth.oidc.api_clients.jwks_api_client.JwksApiClient

Bases: OidcApiClient

Low level API client for the OAuth JWKS endpoint. See RFC 7517 - JSON Web Key (JWK) and RFC 8414 - OAuth 2.0 Authorization Server Metadata for more information.

planet_auth.oidc.api_clients.jwks_api_client.JwksApiClient.__init__(jwks_uri)

Create a JWKS endpoint client

planet_auth.oidc.api_clients.jwks_api_client.JwksApiClient.jwks()

Fetch metadata from the JWKS endpoint.

Returns:

Type	Description
Dict	The full jwks response from the endpoint. An exception will be raised when an error occurs.

planet_auth.oidc.api_clients.jwks_api_client.JwksApiClient.jwks_keys()

Fetch keys from the JWKS endpoint.

Returns:

Type	Description
List	Just the jwks key set from the endpoint. An exception will be raised when an error occurs.

planet_auth.oidc.api_clients.oidc_request_auth

Some OIDC endpoints require client auth, and how auth is done can very depending on how the OIDC provider is configured to handle the particular client. See https://developer.okta.com/docs/reference/api/oidc/#client-authentication-methods

This module provides some helper functions for wrangling the requests for various OIDC client auth methods. It is for the caller to decide the appropriate use of these.

planet_auth.oidc.api_clients.revocation_api_client

planet_auth.oidc.api_clients.revocation_api_client.RevocationApiClient

Bases: OidcApiClient

Low level API client for the OAuth Token Revocation endpoint. See RFC 7009 - OAuth 2.0 Token Revocation for protocol details.

planet_auth.oidc.api_clients.revocation_api_client.RevocationApiClient.__init__(revocation_uri)

Create a new Revocation API Client.

planet_auth.oidc.api_clients.revocation_api_client.RevocationApiClient.revoke_access_token(access_token, auth_enricher=None)

Revoke the specified access token.

planet_auth.oidc.api_clients.revocation_api_client.RevocationApiClient.revoke_refresh_token(refresh_token, auth_enricher=None)

Revoke the specified refresh token.

planet_auth.oidc.api_clients.token_api_client

planet_auth.oidc.api_clients.token_api_client.TokenApiClient

Bases: OidcApiClient

Low level API client for the OAuth Token endpoint. See RFC 6749 - The OAuth 2.0 Authorization Framework for protocol details.

planet_auth.oidc.api_clients.token_api_client.TokenApiClient.__init__(token_uri)

Create a new Token API Client.

planet_auth.oidc.api_clients.token_api_client.TokenApiClient.get_token_from_client_credentials(client_id, requested_scopes=None, requested_audiences=None, auth_enricher=None, extra=None)

Obtain tokens using client credentials and the client credentials grant OAuth flow.

Parameters:

Name	Type	Description	Default
client_id	str	The ID of the OAuth client making the request. (This parameter is not used. This comes from the auth enricher.)	required
requested_audiences	List[str]	A list of strings specifying the audiences to request.	None
requested_scopes	List[str]	A list of scopes to request when obtaining the refreshed tokens. This list may only be a subset of the scopes that were initially granted to the client. A scope increase may not be requested during refresh. A scope increase requires a new authorization (login).	None
auth_enricher	Optional[EnricherFuncType]	Function to layer in the application of client credentials.	None
extra	Dict	Dict of extra parameters to pass to the token endpoint.	None

Returns:

Type	Description
Dict	Returns the token endpoint response payload upon success as a json object. If an error condition is detected, either from the HTTP layer or from a payload that indicates a failure, an exception will be raised.

planet_auth.oidc.api_clients.token_api_client.TokenApiClient.get_token_from_code(redirect_uri, client_id, code, code_verifier, auth_enricher=None)

Obtain tokens using an authorization code.

Returns:

Type	Description
Dict	Returns the token endpoint response payload upon success as a json object. If an error condition is detected, either from the HTTP layer or from a payload that indicates a failure, an exception will be raised.

planet_auth.oidc.api_clients.token_api_client.TokenApiClient.get_token_from_password(client_id, username, password, requested_scopes=None, requested_audiences=None, auth_enricher=None, extra=None)

Obtain tokens using a username and password and the resource owner grant OAuth flow.

Parameters:

Name	Type	Description	Default
client_id	str	The ID of the OAuth client making the request. (This parameter is not used. This comes from the auth enricher.)	required
username	str	The username used for authentication.	required
password	str	The password used for authentication.	required
requested_scopes	List[str]	A list of scopes to request when obtaining the refreshed tokens. This list may only be a subset of the scopes that were initially granted to the client. A scope increase may not be requested during refresh. A scope increase requires a new authorization (login).	None
requested_audiences	List[str]	A list of strings specifying the audiences to request.	None
auth_enricher	Optional[EnricherFuncType]	Function to layer in the application of client credentials.	None
extra	Dict	Dict of extra parameters to pass to the token endpoint.	None

Returns:

Type	Description
Dict	Returns the token endpoint response payload upon success as a json object. If an error condition is detected, either from the HTTP layer or from a payload that indicates a failure, an exception will be raised.

planet_auth.oidc.api_clients.token_api_client.TokenApiClient.get_token_from_refresh(client_id, refresh_token, requested_scopes=None, auth_enricher=None, extra=None)

Obtain tokens using a refresh token.

Parameters:

Name	Type	Description	Default
client_id	str	The ID of the OAuth client making the request.	required
refresh_token	str	The refresh token to use.	required
requested_scopes	List[str]	A list of scopes to request when obtaining the refreshed tokens. This list may only be a subset of the scopes that were initially granted to the client. A scope increase may not be requested during refresh. A scope increase requires a new authorization (login).	None
extra	Dict	Dict of extra parameters to pass to the token endpoint.	None

Returns:

Type	Description
Dict	Returns the token endpoint response payload upon success as a json object. If an error condition is detected, either from the HTTP layer or from a payload that indicates a failure, an exception will be raised.

planet_auth.oidc.api_clients.token_api_client.TokenApiClient.poll_for_token_from_device_code(client_id, device_code, timeout, poll_interval=5, auth_enricher=None)

Poll for the completion of a device code login.

Returns:

Type	Description
Dict	Returns the token endpoint response payload upon success as a json object. If an error condition is detected, either from the HTTP layer or from a payload that indicates a failure, an exception will be raised.

planet_auth.oidc.api_clients.userinfo_api_client

planet_auth.oidc.api_clients.userinfo_api_client.UserinfoApiClient

Bases: OidcApiClient

Low level network client for the "Userinfo" OAuth2/OIDC network endpoint.

planet_auth.oidc.api_clients.userinfo_api_client.UserinfoApiClient.__init__(userinfo_uri)

Create a new token Userinfo API client

planet_auth.oidc.api_clients.userinfo_api_client.UserinfoApiClient.userinfo_from_access_token(access_token)

Obtain user information from the authorization server for the user who owns the presented access token.

Parameters:

Name	Type	Description	Default
access_token	str	User access token.	required

planet_auth.oidc.auth_client

planet_auth.oidc.auth_client.OidcAuthClient

Bases: AuthClient, ABC

Base class for AuthClient implementations that implement an OAuth/OIDC authentication flow.

planet_auth.oidc.auth_client.OidcAuthClient.can_login_unattended() abstractmethod

Check whether the client can perform an unattended login.

Depending on the implementation, some clients may be able to perform unattended logins based on information the client config (e.g. static API key clients can do this). These should return true. Other clients will always require user interactive logins (e.g. a user interactive client using a browser and MFA to login). These should return false. Some clients may be flexible and support either depending on the state of their configuration. These should return a result based on their configuration.

planet_auth.oidc.auth_client.OidcAuthClient.default_request_authenticator(credential) abstractmethod

Return an instance of the default request authenticator to use for the specific AuthClient type and configured to use the provided credential file for persistence.

It's not automatic that the default is always the right choice. Some authenticators may initiate logins, which may be interactive or not depending on the specifics of the AuthClient configuration and implementation type. Whether or not interactivity can be tolerated depends on the specifics of the surrounding application.

In the simplest cases, there really is no relationship between the AuthClient and the request authenticator (see static key implementations). This relationship emerges when the mechanisms of an AuthClient requires frequent refreshing of the Credential. In these cases, it is convenient for the CredentialRequestAuthenticator to also have an AuthClient that is capable of performing this refresh transparently as needed.

AuthClient implementors should favor defaults that do not require user interaction after an initial Credential has been obtained from an initial call to login()

Parameters:

Name	Type	Description	Default
credential	Union[Path, Credential]	A Credential object, or a Path to the credential file that can be used to create an appropriate credential object.	required

Returns: Returns an instance of the default request authenticator class to use for Credentials of the type obtained by the AuthClient.

planet_auth.oidc.auth_client.OidcAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_client.OidcAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_client.OidcAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_client.OidcAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_client.OidcAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_client.OidcAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_client.OidcAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_client.OidcAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_client.OidcAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_client.OidcAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_client.OidcAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_client.OidcAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_client.OidcAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_client.OidcAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_client.OidcAuthClientConfig

Bases: AuthClientConfig, ABC

Base config class shared by all OAuth/OIDC auth clients.

planet_auth.oidc.auth_client.OidcAuthClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_client.OidcAuthClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_client.OidcAuthClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_client.OidcAuthClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_client.OidcAuthClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_client.OidcAuthClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_client.OidcAuthClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_client.OidcAuthClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_client.OidcAuthClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_client.OidcAuthClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_client.OidcAuthClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_client.OidcAuthClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_client.OidcAuthClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_client.OidcAuthClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_client.OidcAuthClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_client.OidcAuthClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth

Bases: OidcAuthClient, ABC

Mix-in base class for "public" (non-confidential) OAuth/OIDC auth clients.

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.can_login_unattended() abstractmethod

Check whether the client can perform an unattended login.

Depending on the implementation, some clients may be able to perform unattended logins based on information the client config (e.g. static API key clients can do this). These should return true. Other clients will always require user interactive logins (e.g. a user interactive client using a browser and MFA to login). These should return false. Some clients may be flexible and support either depending on the state of their configuration. These should return a result based on their configuration.

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.default_request_authenticator(credential) abstractmethod

Return an instance of the default request authenticator to use for the specific AuthClient type and configured to use the provided credential file for persistence.

It's not automatic that the default is always the right choice. Some authenticators may initiate logins, which may be interactive or not depending on the specifics of the AuthClient configuration and implementation type. Whether or not interactivity can be tolerated depends on the specifics of the surrounding application.

In the simplest cases, there really is no relationship between the AuthClient and the request authenticator (see static key implementations). This relationship emerges when the mechanisms of an AuthClient requires frequent refreshing of the Credential. In these cases, it is convenient for the CredentialRequestAuthenticator to also have an AuthClient that is capable of performing this refresh transparently as needed.

AuthClient implementors should favor defaults that do not require user interaction after an initial Credential has been obtained from an initial call to login()

Parameters:

Name	Type	Description	Default
credential	Union[Path, Credential]	A Credential object, or a Path to the credential file that can be used to create an appropriate credential object.	required

Returns: Returns an instance of the default request authenticator class to use for Credentials of the type obtained by the AuthClient.

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_client.OidcAuthClientWithNoneClientAuth.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_client_default_authenticators

planet_auth.oidc.auth_client_default_authenticators.OidcAuthClientWithRefreshOrReloginOidcTokenRequestAuthenticator

Bases: ABC

Mix-in base class for flows that should default to the RefreshOrReloginOidcTokenRequestAuthenticator request authenticator.

planet_auth.oidc.auth_client_default_authenticators.OidcAuthClientWithRefreshingOidcTokenRequestAuthenticator

Bases: ABC

Mix-in base class for flows that should default to the RefreshingOidcTokenRequestAuthenticator request authenticator.

planet_auth.oidc.auth_client_with_client_pubkey

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey

Bases: OidcAuthClient, ABC

Mix-in base class for OIDC auth clients that make use of a client public/private keypair to perform client authentication.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.can_login_unattended() abstractmethod

Check whether the client can perform an unattended login.

Depending on the implementation, some clients may be able to perform unattended logins based on information the client config (e.g. static API key clients can do this). These should return true. Other clients will always require user interactive logins (e.g. a user interactive client using a browser and MFA to login). These should return false. Some clients may be flexible and support either depending on the state of their configuration. These should return a result based on their configuration.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.default_request_authenticator(credential) abstractmethod

Return an instance of the default request authenticator to use for the specific AuthClient type and configured to use the provided credential file for persistence.

It's not automatic that the default is always the right choice. Some authenticators may initiate logins, which may be interactive or not depending on the specifics of the AuthClient configuration and implementation type. Whether or not interactivity can be tolerated depends on the specifics of the surrounding application.

In the simplest cases, there really is no relationship between the AuthClient and the request authenticator (see static key implementations). This relationship emerges when the mechanisms of an AuthClient requires frequent refreshing of the Credential. In these cases, it is convenient for the CredentialRequestAuthenticator to also have an AuthClient that is capable of performing this refresh transparently as needed.

AuthClient implementors should favor defaults that do not require user interaction after an initial Credential has been obtained from an initial call to login()

Parameters:

Name	Type	Description	Default
credential	Union[Path, Credential]	A Credential object, or a Path to the credential file that can be used to create an appropriate credential object.	required

Returns: Returns an instance of the default request authenticator class to use for Credentials of the type obtained by the AuthClient.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithClientPubkey.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig

Bases: OidcAuthClientConfig, ABC

Mix-in base class for OIDC auth clients that make use of a client public/private keypair to perform client authentication.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_client_with_client_pubkey.OidcAuthClientWithPubKeyClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_client_with_client_secret

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig

Bases: OidcAuthClientConfig, ABC

Mix-in base class for OIDC auth clients that make use of a client secret.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecretClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment

Bases: OidcAuthClient, ABC

Mix-in base class for OIDC auth clients that make use of a client secret to perform client authentication.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.can_login_unattended() abstractmethod

Check whether the client can perform an unattended login.

Depending on the implementation, some clients may be able to perform unattended logins based on information the client config (e.g. static API key clients can do this). These should return true. Other clients will always require user interactive logins (e.g. a user interactive client using a browser and MFA to login). These should return false. Some clients may be flexible and support either depending on the state of their configuration. These should return a result based on their configuration.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.default_request_authenticator(credential) abstractmethod

Return an instance of the default request authenticator to use for the specific AuthClient type and configured to use the provided credential file for persistence.

It's not automatic that the default is always the right choice. Some authenticators may initiate logins, which may be interactive or not depending on the specifics of the AuthClient configuration and implementation type. Whether or not interactivity can be tolerated depends on the specifics of the surrounding application.

In the simplest cases, there really is no relationship between the AuthClient and the request authenticator (see static key implementations). This relationship emerges when the mechanisms of an AuthClient requires frequent refreshing of the Credential. In these cases, it is convenient for the CredentialRequestAuthenticator to also have an AuthClient that is capable of performing this refresh transparently as needed.

AuthClient implementors should favor defaults that do not require user interaction after an initial Credential has been obtained from an initial call to login()

Parameters:

Name	Type	Description	Default
credential	Union[Path, Credential]	A Credential object, or a Path to the credential file that can be used to create an appropriate credential object.	required

Returns: Returns an instance of the default request authenticator class to use for Credentials of the type obtained by the AuthClient.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment

Bases: OidcAuthClient, ABC

Mix-in base class for OIDC auth clients that make use of a client secret to perform client authentication.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.can_login_unattended() abstractmethod

Check whether the client can perform an unattended login.

Depending on the implementation, some clients may be able to perform unattended logins based on information the client config (e.g. static API key clients can do this). These should return true. Other clients will always require user interactive logins (e.g. a user interactive client using a browser and MFA to login). These should return false. Some clients may be flexible and support either depending on the state of their configuration. These should return a result based on their configuration.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.default_request_authenticator(credential) abstractmethod

Return an instance of the default request authenticator to use for the specific AuthClient type and configured to use the provided credential file for persistence.

It's not automatic that the default is always the right choice. Some authenticators may initiate logins, which may be interactive or not depending on the specifics of the AuthClient configuration and implementation type. Whether or not interactivity can be tolerated depends on the specifics of the surrounding application.

In the simplest cases, there really is no relationship between the AuthClient and the request authenticator (see static key implementations). This relationship emerges when the mechanisms of an AuthClient requires frequent refreshing of the Credential. In these cases, it is convenient for the CredentialRequestAuthenticator to also have an AuthClient that is capable of performing this refresh transparently as needed.

AuthClient implementors should favor defaults that do not require user interaction after an initial Credential has been obtained from an initial call to login()

Parameters:

Name	Type	Description	Default
credential	Union[Path, Credential]	A Credential object, or a Path to the credential file that can be used to create an appropriate credential object.	required

Returns: Returns an instance of the default request authenticator class to use for Credentials of the type obtained by the AuthClient.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_client_with_client_secret.OidcAuthClientWithClientSecret_PayloadAuthEnrichment.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients

planet_auth.oidc.auth_clients.auth_code_flow

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient

Bases: AuthCodeAuthClientBase, OidcAuthClientWithNoneClientAuth

AuthClient implementation that implements the OAuth auth code grant with PKCE to obtain user tokens. This implementation is for public clients that cannot maintain client confidentiality.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase

Bases: OidcAuthClientWithRefreshingOidcTokenRequestAuthenticator, OidcAuthClient, ABC

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeAuthClientBase.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig

Bases: OidcAuthClientConfig

Configuration required for planet_auth.AuthCodeAuthClient

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient

Bases: AuthCodeAuthClientBase, OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment

AuthClient implementation that implements the OAuth auth code grant with PKCE to obtain user tokens. This implementation is for confidential clients that use a client secret to protect the client confidentiality.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig

Bases: AuthCodeClientConfig, OidcAuthClientWithClientSecretClientConfig

Configuration required for planet_auth.AuthCodeWithClientSecretAuthClient

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithClientSecretClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient

Bases: AuthCodeAuthClientBase, OidcAuthClientWithClientPubkey

AuthClient implementation that implements the OAuth auth code grant with PKCE to obtain user tokens. This implementation is for confidential clients that use a public/private keypair to protect the client confidentiality.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig

Bases: AuthCodeClientConfig, OidcAuthClientWithPubKeyClientConfig

Configuration required for planet_auth.AuthCodeWithPubKeyAuthClient

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_clients.auth_code_flow.AuthCodeWithPubKeyClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_clients.client_credentials_flow

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient

Bases: ClientCredentialsAuthClientBase, OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment

AuthClient implementation that implements the OAuth client credentials grant to obtain tokens for the client itself. This implementation is for confidential clients that use a client secret to protect the client confidentiality.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig

Bases: OidcAuthClientWithClientSecretClientConfig

Configuration required for planet_auth.ClientCredentialsClientSecretAuthClient

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsClientSecretClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient

Bases: ClientCredentialsAuthClientBase, OidcAuthClientWithClientPubkey

AuthClient implementation that implements the OAuth client credentials grant to obtain tokens for the client itself. This implementation is for confidential clients that use a public/private keypair to protect the client confidentiality.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig

Bases: OidcAuthClientWithPubKeyClientConfig

Configuration required for planet_auth.ClientCredentialsPubKeyAuthClient

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_clients.client_credentials_flow.ClientCredentialsPubKeyClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_clients.client_validator

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient

Bases: OidcAuthClient

The OidcClientValidatorAuthClient is an OAuth2/OIDC client that does not have an identity of its own. It cannot perform a login or obtain access or ID tokens, and it cannot call out to resource servers covered by the issuer's audiences on behalf of users or itself. Instead, this OAuth auth client type exists for programs that need to validate tokens than have been presented to them. This is useful for resource servers themselves when authenticating or authorizing clients.

The implementation is essentially the planet_auth.OidcAuthClient base class with outbound client capabilities disabled.

It should be noted that the other planet_auth.OidcAuthClient derived classes that implement various OAuth flows can also be used to validate clients when inbound and outbound connections fall under the same token issuer realm of trust. But, for use cases where only the validation of incoming requests is required, this class is suitable and does not require the allocation of a client ID.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig

Bases: OidcAuthClientConfig

Configuration for a planet_auth.OidcClientValidatorAuthClient AuthClient

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_clients.client_validator.OidcClientValidatorAuthClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_clients.device_code_flow

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient

Bases: DeviceCodeAuthClientBase, OidcAuthClientWithNoneClientAuth

AuthClient implementation that implements the OAuth device code grant to obtain user tokens. This implementation is for public clients that cannot maintain client confidentiality.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.device_login_complete(initiated_login_data)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method completes the process initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	dict	The dictionary returned from a successful call to device_login_initiate()	required

Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.device_login_initiate(requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method initiates the device login process with the auth service. A dictionary that complies to RFC 8628 will be return upon success that can be used by the client application to prompt the user. After prompting the user, device_login_complete() should be called to complete the login process.

Parameters:

Name	Type	Description	Default
requested_scopes	List[str]	a list of strings specifying the scopes to request.	None
requested_audiences	List[str]	a list of strings specifying the audiences to request.	None
extra	Optional[dict]	a dict extra data to pass to the authorization server.	None

Returns: A RFC 8628 compliant dictionary that can be used by the called to prompt the user to complete device authentication. This dictionary should be passed to device_login_complete() to finish the login process.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase

Bases: OidcAuthClientWithRefreshingOidcTokenRequestAuthenticator, OidcAuthClient, ABC

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.device_login_complete(initiated_login_data)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method completes the process initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	dict	The dictionary returned from a successful call to device_login_initiate()	required

Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.device_login_initiate(requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method initiates the device login process with the auth service. A dictionary that complies to RFC 8628 will be return upon success that can be used by the client application to prompt the user. After prompting the user, device_login_complete() should be called to complete the login process.

Parameters:

Name	Type	Description	Default
requested_scopes	List[str]	a list of strings specifying the scopes to request.	None
requested_audiences	List[str]	a list of strings specifying the audiences to request.	None
extra	Optional[dict]	a dict extra data to pass to the authorization server.	None

Returns: A RFC 8628 compliant dictionary that can be used by the called to prompt the user to complete device authentication. This dictionary should be passed to device_login_complete() to finish the login process.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeAuthClientBase.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig

Bases: OidcAuthClientConfig

Configuration required for planet_auth.DeviceCodeAuthClient

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient

Bases: DeviceCodeAuthClientBase, OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment

AuthClient implementation that implements the OAuth device code grant to obtain user tokens. This implementation is for confidential clients that use a client secret to protect the client confidentiality.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.device_login_complete(initiated_login_data)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method completes the process initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	dict	The dictionary returned from a successful call to device_login_initiate()	required

Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.device_login_initiate(requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method initiates the device login process with the auth service. A dictionary that complies to RFC 8628 will be return upon success that can be used by the client application to prompt the user. After prompting the user, device_login_complete() should be called to complete the login process.

Parameters:

Name	Type	Description	Default
requested_scopes	List[str]	a list of strings specifying the scopes to request.	None
requested_audiences	List[str]	a list of strings specifying the audiences to request.	None
extra	Optional[dict]	a dict extra data to pass to the authorization server.	None

Returns: A RFC 8628 compliant dictionary that can be used by the called to prompt the user to complete device authentication. This dictionary should be passed to device_login_complete() to finish the login process.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig

Bases: DeviceCodeClientConfig, OidcAuthClientWithClientSecretClientConfig

Configuration required for planet_auth.DeviceCodeWithClientSecretAuthClient

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithClientSecretClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient

Bases: DeviceCodeAuthClientBase, OidcAuthClientWithClientPubkey

AuthClient implementation that implements the OAuth device code grant to obtain user tokens. This implementation is for confidential clients that use a public/private keypair to protect the client confidentiality.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.device_login_complete(initiated_login_data)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method completes the process initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	dict	The dictionary returned from a successful call to device_login_initiate()	required

Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.device_login_initiate(requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using the Device Code OAuth flow. This method initiates the device login process with the auth service. A dictionary that complies to RFC 8628 will be return upon success that can be used by the client application to prompt the user. After prompting the user, device_login_complete() should be called to complete the login process.

Parameters:

Name	Type	Description	Default
requested_scopes	List[str]	a list of strings specifying the scopes to request.	None
requested_audiences	List[str]	a list of strings specifying the audiences to request.	None
extra	Optional[dict]	a dict extra data to pass to the authorization server.	None

Returns: A RFC 8628 compliant dictionary that can be used by the called to prompt the user to complete device authentication. This dictionary should be passed to device_login_complete() to finish the login process.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig

Bases: DeviceCodeClientConfig, OidcAuthClientWithPubKeyClientConfig

Configuration required for planet_auth.DeviceCodeWithPubKeyAuthClient

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_clients.device_code_flow.DeviceCodeWithPubKeyClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_clients.resource_owner_flow

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient

Bases: ResourceOwnerAuthClientBase, OidcAuthClientWithNoneClientAuth

AuthClient implementation that implements the OAuth password grant to obtain user tokens. This implementation is for public clients that cannot maintain client confidentiality.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig

Bases: OidcAuthClientConfig

Configuration required for planet_auth.ResourceOwnerAuthClient

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient

Bases: ResourceOwnerAuthClientBase, OidcAuthClientWithClientSecret_HttpBasicAuthEnrichment

AuthClient implementation that implements the OAuth password grant to obtain user tokens. This implementation is for confidential clients that use a client secret to protect the client confidentiality.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig

Bases: ResourceOwnerClientConfig, OidcAuthClientWithClientSecretClientConfig

Configuration required for planet_auth.ResourceOwnerWithClientSecretAuthClient

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithClientSecretClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient

Bases: ResourceOwnerAuthClientBase, OidcAuthClientWithClientPubkey

AuthClient implementation that implements the OAuth password grant to obtain user tokens. This implementation is for confidential clients that use a public/private keypair ti protect the client confidentiality.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, requested_scopes=None, requested_audiences=None, extra=None, **kwargs)

Obtain tokens from the OIDC auth server using an appropriate login flow. The base implementation here handles common config fallback behaviors. Concrete subclasses must implement the flow specific logic in a _oidc_flow_login() method. Parameters: allow_open_browser: specify whether login is permitted to open a browser window. allow_tty_prompt: specify whether login is permitted to request input from the terminal. requested_scopes: a list of strings specifying the scopes to request. requested_audiences: a list of strings specifying the audiences to request. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.refresh(refresh_token, requested_scopes=None, extra=None)

Refresh auth tokens using the provided refresh token Parameters: refresh_token: the refresh token to use. requested_scopes: a list of strings specifying the scopes to request during the token refresh. If not specified, server default behavior will apply. extra: a dict extra data to pass to the authorization server. Returns: A FileBackedOidcCredential object

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.revoke_access_token(access_token)

Revoke the access token with the OIDC provider. Parameters: access_token: The access token to revoke

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.revoke_refresh_token(refresh_token)

Revoke the refresh token with the OIDC provider. Parameters: refresh_token: The refresh token to revoke

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.validate_access_token_remote(access_token)

Validate the access token against the OIDC token introspection endpoint Parameters: access_token: The access token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.validate_id_token_local(id_token)

Validate the ID token locally. A remote connection may still be made to obtain signing keys. Parameters: id_token: ID token to validate Returns: Upon success, the validated token claims are returned

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.validate_id_token_remote(id_token)

Validate the ID token against the OIDC token introspection endpoint Parameters: id_token: ID token to validate Returns: The raw validated json payload

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyAuthClient.validate_refresh_token_remote(refresh_token)

Validate the refresh token against the OIDC token introspection endpoint Parameters: refresh_token: Refresh token to validate Returns: The raw validate json payload

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig

Bases: ResourceOwnerClientConfig, OidcAuthClientWithPubKeyClientConfig

Configuration required for planet_auth.ResourceOwnerWithPubKeyAuthClient

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.auth_clients.resource_owner_flow.ResourceOwnerWithPubKeyClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.multi_validator

planet_auth.oidc.multi_validator.OidcMultiIssuerValidator

The OidcMultiIssuerValidator is a token validator that can be configured to trust multiple token issuers. This is not expected to be a normal operating mode for most services. This was developed to support migration use cases.

This is a higher level utility class, and is built on top of planet_auth.AuthClient classes. For a lower level utilities, see planet_auth.TokenValidator, or see the validation functionality built into planet_auth.AuthClient.

Warning

Never ever ever EVER use this to bridge between trust environments. For example, do not use this to trust staging and production environment issuing authorities.

planet_auth.oidc.multi_validator.OidcMultiIssuerValidator.__init__(trusted, log_result=True)

Create a new multi issuer validator using the provided auth clients. The auth clients are expected to be any Auth that implements OIDC functionality.

Since the expected audience could be different for each issuer, the expectation is that the provided Auth contexts will be configured with an audience, even though that is an optional configuration parameter for most implementing classes.

Parameters:

Name	Type	Description	Default
trusted	List[Auth]		required
log_result	bool		True

planet_auth.oidc.multi_validator.OidcMultiIssuerValidator.from_auth_server_configs(trusted_auth_server_configs, log_result=True) staticmethod

Create a new multi issuer validator from the provided auth client config dictionaries.

Parameters:

Name	Type	Description	Default
trusted_auth_server_configs	List[dict]	A list of configuration dictionaries. Unless remote validation is required, the configuration dictionaries may be sparse, containing only the auth_server and audiences properties. auth_server is expected to be a single string, containing the URL of the OAuth issuer. audiences is expected to be an array, and contain a list of supported audiences.	required
log_result	bool	Control whether successful token validations against trusted auth servers should be logged.	True

Example

auth_validator = planet_auth.OidcMultiIssuerValidator.from_auth_server_configs(
    trusted_auth_server_configs=[
        {
            "auth_server": "https://oauth_server.example.com/oauth2/auth_server_id",
            "audiences": ["https://api.example.com/"],
        },
    ],
)

planet_auth.oidc.multi_validator.OidcMultiIssuerValidator.from_auth_server_urls(trusted_auth_server_urls, audience=None, log_result=True) staticmethod

Create a new multi issuer validator from the provided OAuth server URLs. This is a convenience method for common cases.

Warning

When mutli validators are initialized from URLs by this method, it is assumed that the auth server URL (used to perform OIDC discovery and locate all the other API endpoints) and the issuer (which is burned into the signed access tokens) are the same. This is normally true, but not universally required. For example, some network proxy configurations may make these different.

This assumption is made in part to avoid the discovery lookup during construction. Since a network lookup could potentially fail, construction of the entire configuration could be rendered non-functional by a network or configuration problem impacting a single auth server.

The multi-validator requires foreknowledge of all the issuers for proper initialization. So, without this assumption it would be unavoidable to introduce network risk into the constructor. This assumption allows us to push all network errors to runtime, and avoids possible initialization time errors.

planet_auth.oidc.multi_validator.OidcMultiIssuerValidator.validate_access_token(token, do_remote_revocation_check=False, scopes_anyof=None)

Validate an access token, and return the token's claims if the all validation has succeeded.

Remote revocation checks should be done for high value operations where it is undesirable to allow revoked tokens to be used for the remainder of their lifetime. Token lifetimes should be chosen to be an acceptable trade-off between permitting revoked tokens for the remainder of the token lifespan for performance and scalability, and performing remote validation for extra security.

When an invalid token is presented, an exception is thrown.

Parameters:

Name	Type	Description	Default
token	str	Token to validate	required
do_remote_revocation_check	bool	Control whether the issuer will be consulted for revocation of the access token.	False
scopes_anyof	list	Optional list of OAuth2 scopes to check for in the token. This list is an "any of" list of scopes. As long as one of the scopes in the list is present, validation will pass. If none of the scopes are present, validation will fail.	None

Returns: Returns a tuple of validation results, as returned from planet_auth.AuthClient.validate_access_token_local and planet_auth.AuthClient.validate_access_token_remote

planet_auth.oidc.oidc_credential

planet_auth.oidc.oidc_credential.FileBackedOidcCredential

Bases: Credential

Credential object for storing OAuth/OIDC tokens. Credential should conform to the "token" response defined in RFC 6749 for OAuth access tokens with OIDC extensions for ID tokens.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.access_token()

Get the current access token.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.check_data(data)

Check that the supplied data represents a valid OAuth/OIDC token object.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.expiry_time()

The time that the credential expires, expressed as seconds since the epoch.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.id_token()

Get the current ID token.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.is_expired(at_time=None)

Return true if the credential is expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return false.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.is_expiring()

Return true if the credential has an expiry time.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.is_non_expiring()

Return true if the credential never expires.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.is_not_expired(at_time=None)

Return true if the credential is not expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return true.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.issued_time()

The time that the credential was issued, expressed as seconds since the epoch.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.path()

Retrieve the currently configured path for saved data.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.refresh_token()

Get the current refresh token.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.set_data(data, copy_data=True)

Set credential data for an OAuth/OIDC credential. The data structure is expected to be an RFC 6749 /token response structure.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.set_path(file_path)

Update storage path for the object.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.oidc.oidc_credential.FileBackedOidcCredential.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.oidc.request_authenticator

planet_auth.oidc.request_authenticator.RefreshOrReloginOidcTokenRequestAuthenticator

Bases: RefreshingOidcTokenRequestAuthenticator

Decorate a http request with a bearer auth token. Automatically initiate a refresh request using the refresh token if we know the access token to be close to expiration. If we do not have a refresh token, then fall back to re-initiating a login. Sometimes (like with client credential flow), refresh tokens may not be available and we might want to login rather than refresh. It is not an automatic choice to fall back to login when refresh is not available, since for some auth client configurations login is interactive, and would not be appropriate for headless use cases. Refresh should always be silent.

planet_auth.oidc.request_authenticator.RefreshOrReloginOidcTokenRequestAuthenticator.auth_flow(request)

Decorate a "httpx" library based request with authentication

planet_auth.oidc.request_authenticator.RefreshOrReloginOidcTokenRequestAuthenticator.is_initialized()

Return true if the CredentialRequestAuthenticator has a credential that can be used to make requests. If a credential is not in memory, storage is checked for the existence of a credential, but it will not be loaded from storage at this time, preserving JIT loading behavior.

planet_auth.oidc.request_authenticator.RefreshingOidcTokenRequestAuthenticator

Bases: CredentialRequestAuthenticator

Decorate a http request with an OAuth bearer auth token. Automatically initiate a refresh request if we know the access token to be close to expiration.

This class assumes access tokens are JWTs and can be locally inspected, which OIDC and OAuth do not require. JWT access tokens that comply with RFC 9068 can be checked for expiration timing without hitting the network token introspection endpoint.

planet_auth.oidc.request_authenticator.RefreshingOidcTokenRequestAuthenticator.auth_flow(request)

Decorate a "httpx" library based request with authentication

planet_auth.oidc.request_authenticator.RefreshingOidcTokenRequestAuthenticator.is_initialized()

Return true if the CredentialRequestAuthenticator has a credential that can be used to make requests. If a credential is not in memory, storage is checked for the existence of a credential, but it will not be loaded from storage at this time, preserving JIT loading behavior.

planet_auth.oidc.token_validator

planet_auth.oidc.token_validator.TokenValidator

Helper class to perform validation of OAuth2 JWT tokens. This class provides the implementation for the locally performed validation in planet_auth.OidcAuthClient classes, but may also be used as a stand-alone validator.

This is a lower level utility class, and has no dependency or knowledge of the higher level planet_auth.AuthClient or planet_auth.Auth classes.

For a higher level application utility, see planet_auth.OidcMultiIssuerValidator

planet_auth.oidc.token_validator.TokenValidator.hazmat_unverified_decode(token_str) staticmethod

Decode a JWT without verifying the signature or any claims.

Warning

Treat unverified token claims with extreme caution. Nothing can be trusted until the token is verified.

Returns:

Type	Description
Tuple[Dict, Dict, Any]	Returns the decoded JWT header, payload, and signature

planet_auth.oidc.token_validator.TokenValidator.validate_id_token(token_str, issuer, client_id, required_claims=None, nonce=None)

Validate a JWT this is a OIDC ID token. Steps over and above basic token validation are performed, as described in https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation

planet_auth.oidc.token_validator.TokenValidator.validate_token(token_str, issuer, audience, required_claims=None, scopes_anyof=None, nonce=None)

Validate the provided token string. Required claims are validated for their presence only. It is up to the application to assert that the claim values meet thr requirements of the caller's use case.

If a nonce is provided, the validator will require that the token have a nonce claim, and that its value matches the supplied value.

Parameters:

Name	Type	Description	Default
token_str	str	Raw encoded JWT string.	required
issuer	str	Required token issuer.	required
audience	str	Required token audience.	required
required_claims	list	Optional list of additional claims that must be present in the token. these claims are only checked for the presence. It is up to the caller to assert that the values are appropriate for the application	None
scopes_anyof	list	Optional list of OAuth2 scopes to check for in the token. This list is an "any of" list of scopes. As long as one of the scopes in the list is present, validation will pass. If none of the scopes are present, validation will fail.	None
nonce	str	Optional nonce value to check for in the token.	None

A note on scope validation.

"Any of" scope enforcement semantics may not make sense for all applications. "All of" is a feature that might be desirable, but has not been implemented. ("Any of" or "all of" for any other arbitrary claim might also have value. But again, this is not implemented here. At some point deriving application meaning from the claims present is a concern of the higher level application, and not a concern of the token validator.)

planet_auth.planet_legacy

Package providing an implementation of the planet_auth package interfaces that use Planet's legacy authentication end points and API keys. Use of OAuth2/OIDC mechanisms is preferred.

planet_auth.planet_legacy.auth_client

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient

Bases: AuthClient

Implementation of the AuthClient that interacts with Planet's API key auth interfaces.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.device_login_complete(initiated_login_data)

Complete a login process that was initiated by a call to device_login_initiate().

Parameters:

Name	Type	Description	Default
initiated_login_data	Dict	The dictionary that was returned by device_login_initiate()	required

Returns:

Type	Description
Credential	Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.device_login_initiate(**kwargs)

Initiate the process to login a device with limited UI capabilities. The returned dictionary should contain information for the application to present to the user, allowing the user to complete the login process asynchronously.

After prompting the user, device_login_complete() should be called with the same dictionary that was returned by this call.

Returns:

Type	Description
Dict	Upon successful initiation of an asynchronous device login process, a dictionary containing information that must be presented to the user will be returned.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.from_config(config) classmethod

Create an AuthClient of an appropriate subtype from the client config. Returns: An initialized auth client instance.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.get_scopes()

Query the authorization server for a list of scopes. Returns: Returns a list of scopes that may be requested during a call to login or refresh

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.login(allow_open_browser=False, allow_tty_prompt=False, username=None, password=None, **kwargs)

Perform a login using Planet Legacy authentication endpoints. Parameters: username: Planet account user name. If not specified, the user will be prompted for their user name. password: Planet user password. If not specified, the user will be prompted for their password. allow_tty_prompt: specify whether login is permitted to request input from the terminal. Returns: Upon successful login, a Credential will be returned. The returned value will be in memory only. It is the responsibility of the application to save this credential to disk as appropriate using the mechanisms built into the Credential type.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.oidc_discovery()

Query the authorization server's OIDC discovery endpoint for server information. Returns: Returns the OIDC discovery dictionary.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.refresh(refresh_token, requested_scopes)

Obtain a refreshed credential using the supplied refresh token. This method will be implemented by concrete AuthClients that implement a particular OAuth flow. Parameters: refresh_token: Refresh token requested_scopes: Scopes to request in the access token Returns: Upon success, a fresh Credential will be returned. As with login(), this credential will not have been persisted to storage. This is the responsibility of the application. AuthClient implementations should raise an exception for all login errors.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.revoke_access_token(access_token)

Revoke an access token with the authorization server. Parameters: access_token: Access token to revoke.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.revoke_refresh_token(refresh_token)

Revoke a refresh token with the authorization server. Parameters: refresh_token: Access token to revoke.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.userinfo_from_access_token(access_token)

Look up user information from the auth server using the access token. Parameters: access_token: User access token.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.validate_access_token_local(access_token, required_audience=None, scopes_anyof=None)

Validate an access token locally. While the validation is local, the authorization server may still may contacted to obtain signing keys for validation. Signing keys will be cached for future use.

Auth servers (issuers) may provide service for any number of audiences, so which audience is expected / required is potentially different for each discrete validation check. If the required audience is not provided as an argument, the validate should fall back to the audiences configured in the AuthClientConfig.

If the audience is neither provided as an argument nor present in the AuthClientConfig, an error should be raised.

Note

While tokens may have multiple audiences, and AuthClients may be configured to request multiple audiences, the validation method currently only supports checking for a single audience. This could be considered is a bit of an API mismatch. However, at this time this is considered expected and desirable behavior. Validation is generally considered to be occurring in a context that self identifies as a particular audience, and overlapping claims may mean different things to different audiences. Validation should be done in the context of a single audience at a time.

Parameters:

Name	Type	Description	Default
access_token	str	Access token to validate.	required
required_audience	str	Audience that the token is required to have.	None
scopes_anyof	list	Optional list of OAuth2 scopes to check for in the token. This list is an "any of" list of scopes. As long as one of the scopes in the list is present, validation will pass. If none of the scopes are present, validation will fail.	None

Returns: Returns a dictionary of validated token claims. It should be noted that the returned dictionaries from local and service token validation are not exactly the same. Service validation should return a RFC 7662 dictionary. Local validation returns the token claims.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.validate_access_token_remote(access_token)

Validate an access token with the authorization server. Parameters: access_token: Access token to validate Returns: Returns a dictionary of validated token claims. It should be noted that the returned dictionaries from local and service token validation are not exactly the same. Service validation should return a RFC 7662 dictionary. Local validation returns the token claims.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.validate_id_token_local(id_token)

Validate an ID token locally. The authorization server may still be called to obtain signing keys for validation. Signing keys will be cached for future use. Parameters: id_token: ID token to validate Returns: Returns a dictionary of validated token claims

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.validate_id_token_remote(id_token)

Validate an ID token with the authorization server. Parameters: id_token: ID token to validate Returns: Returns a dictionary of validated token claims

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClient.validate_refresh_token_remote(refresh_token)

Validate a refresh token with the authorization server. Parameters: refresh_token: Refresh token to validate Returns: Returns the response from the remove validation service.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig

Bases: AuthClientConfig

Configuration required for planet_auth.PlanetLegacyAuthClient

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.from_dict(config_data) classmethod

Create a AuthClientConfig from a configuration dictionary. Returns: A concrete auth client config object.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.from_file(file_path, storage_provider=None) staticmethod

Create an AuthClientConfig from a json file that contains a config dictionary. Returns: A concrete auth client config object.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.path()

Retrieve the currently configured path for saved data.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.set_path(file_path)

Update storage path for the object.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.planet_legacy.auth_client.PlanetLegacyAuthClientConfig.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.planet_legacy.legacy_api_key

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey

Bases: Credential

Credential object for storing Planet Legacy API Keys

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.check_data(data)

Check that the supplied data represents a valid Planet Legacy API Key object.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.expiry_time()

The time that the credential expires, expressed as seconds since the epoch.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.is_expired(at_time=None)

Return true if the credential is expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return false.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.is_expiring()

Return true if the credential has an expiry time.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.is_non_expiring()

Return true if the credential never expires.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.is_not_expired(at_time=None)

Return true if the credential is not expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return true.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.issued_time()

The time that the credential was issued, expressed as seconds since the epoch.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.legacy_api_key()

Get the current API key.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.legacy_jwt()

Get the saved legacy JWT.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.path()

Retrieve the currently configured path for saved data.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.set_path(file_path)

Update storage path for the object.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.planet_legacy.legacy_api_key.FileBackedPlanetLegacyApiKey.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.planet_legacy.request_authenticator

planet_auth.planet_legacy.request_authenticator.PlanetLegacyRequestAuthenticator

Bases: CredentialRequestAuthenticator

Authenticate a request using a legacy Planet API key. Currently, the credential file is now also capable of saving a JWT, but this authenticator makes no use of it.

planet_auth.planet_legacy.request_authenticator.PlanetLegacyRequestAuthenticator.auth_flow(request)

Decorate a "httpx" library based request with authentication

planet_auth.planet_legacy.request_authenticator.PlanetLegacyRequestAuthenticator.credential(refresh_if_needed=False)

Return the current credential.

This may not be the credential the authenticator was constructed with. Request Authenticators are free to refresh credentials depending on the needs of the implementation. This may happen upon this request, or may happen as a side effect of RequestAuthenticator operations.

planet_auth.planet_legacy.request_authenticator.PlanetLegacyRequestAuthenticator.is_initialized()

Return true if the CredentialRequestAuthenticator has a credential that can be used to make requests. If a credential is not in memory, storage is checked for the existence of a credential, but it will not be loaded from storage at this time, preserving JIT loading behavior.

planet_auth.planet_legacy.request_authenticator.PlanetLegacyRequestAuthenticator.update_credential_data(new_credential_data)

Provide raw data that should be used to update the Credential object used to authenticate requests. This information will be treated as newer than any file back data associated with the credential held by the authenticator, and the file will be overwritten.

planet_auth.request_authenticator

planet_auth.request_authenticator.CredentialRequestAuthenticator

Bases: RequestAuthenticator, ABC

planet_auth.request_authenticator.CredentialRequestAuthenticator.auth_flow(request)

Decorate a "httpx" library based request with authentication

planet_auth.request_authenticator.CredentialRequestAuthenticator.credential(refresh_if_needed=False)

Return the current credential.

This may not be the credential the authenticator was constructed with. Request Authenticators are free to refresh credentials depending on the needs of the implementation. This may happen upon this request, or may happen as a side effect of RequestAuthenticator operations.

planet_auth.request_authenticator.CredentialRequestAuthenticator.is_initialized()

Return true if the CredentialRequestAuthenticator has a credential that can be used to make requests. If a credential is not in memory, storage is checked for the existence of a credential, but it will not be loaded from storage at this time, preserving JIT loading behavior.

planet_auth.request_authenticator.CredentialRequestAuthenticator.pre_request_hook() abstractmethod

Hook that will be called immediately prior to making an HTTP request so that implementing classes may make preparations. Derived classes are expected to populate the member fields _token_prefix, _token_body, and _auth_header with values that are appropriate to the specific implementation. These will then be used during subsequent HTTP request to authenticate the connection using a beater token authorization HTTP header.

Implementers may make external network calls as required to perform necessary tasks such as refreshing access tokens.

Implementations should not require user interaction by default. If an authentication mechanism will require user interaction, this should be an explicit decision that is left to the application using the RequestAuthenticator to control.

planet_auth.request_authenticator.CredentialRequestAuthenticator.update_credential(new_credential)

Update the request authenticator with a new credential. It is the job of a derived class to know how to map the contents of a credential into the primitives known to HTTP request auth mechanics. Not all derived classes are expected to understand all credential types.

planet_auth.request_authenticator.CredentialRequestAuthenticator.update_credential_data(new_credential_data)

Provide raw data that should be used to update the Credential object used to authenticate requests. This information will be treated as newer than any file back data associated with the credential held by the authenticator, and the file will be overwritten.

planet_auth.request_authenticator.RequestAuthenticator

Bases: AuthBase, Auth, ABC

Decorate a http request with a bearer auth token.

planet_auth.request_authenticator.RequestAuthenticator.auth_flow(request)

Decorate a "httpx" library based request with authentication

planet_auth.request_authenticator.RequestAuthenticator.pre_request_hook() abstractmethod

Hook that will be called immediately prior to making an HTTP request so that implementing classes may make preparations. Derived classes are expected to populate the member fields _token_prefix, _token_body, and _auth_header with values that are appropriate to the specific implementation. These will then be used during subsequent HTTP request to authenticate the connection using a beater token authorization HTTP header.

Implementers may make external network calls as required to perform necessary tasks such as refreshing access tokens.

Implementations should not require user interaction by default. If an authentication mechanism will require user interaction, this should be an explicit decision that is left to the application using the RequestAuthenticator to control.

planet_auth.static_api_key

Package providing an implementation of the planet_auth package interfaces that use static data files.

planet_auth.static_api_key.request_authenticator

planet_auth.static_api_key.request_authenticator.FileBackedApiKeyRequestAuthenticator

Bases: CredentialRequestAuthenticator

Load a bearer token from a file just in time for the request. Perform local checks on the validity of the token and throw if we think it will fail.

planet_auth.static_api_key.request_authenticator.FileBackedApiKeyRequestAuthenticator.auth_flow(request)

Decorate a "httpx" library based request with authentication

planet_auth.static_api_key.request_authenticator.FileBackedApiKeyRequestAuthenticator.credential(refresh_if_needed=False)

Return the current credential.

This may not be the credential the authenticator was constructed with. Request Authenticators are free to refresh credentials depending on the needs of the implementation. This may happen upon this request, or may happen as a side effect of RequestAuthenticator operations.

planet_auth.static_api_key.request_authenticator.FileBackedApiKeyRequestAuthenticator.is_initialized()

Return true if the CredentialRequestAuthenticator has a credential that can be used to make requests. If a credential is not in memory, storage is checked for the existence of a credential, but it will not be loaded from storage at this time, preserving JIT loading behavior.

planet_auth.static_api_key.request_authenticator.FileBackedApiKeyRequestAuthenticator.update_credential(new_credential)

Update the request authenticator with a new credential. It is the job of a derived class to know how to map the contents of a credential into the primitives known to HTTP request auth mechanics. Not all derived classes are expected to understand all credential types.

planet_auth.static_api_key.request_authenticator.FileBackedApiKeyRequestAuthenticator.update_credential_data(new_credential_data)

Provide raw data that should be used to update the Credential object used to authenticate requests. This information will be treated as newer than any file back data associated with the credential held by the authenticator, and the file will be overwritten.

planet_auth.static_api_key.static_api_key

planet_auth.static_api_key.static_api_key.FileBackedApiKey

Bases: Credential

Credential object for storing simple API key bearer tokens.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.api_key()

Get the current API Key.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.bearer_token_prefix()

Get the bearer token prefix that is to be used with the API key.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.check_data(data)

Check that the supplied data represents a valid API key object.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.expiry_time()

The time that the credential expires, expressed as seconds since the epoch.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.is_expired(at_time=None)

Return true if the credential is expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return false.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.is_expiring()

Return true if the credential has an expiry time.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.is_non_expiring()

Return true if the credential never expires.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.is_not_expired(at_time=None)

Return true if the credential is not expired at the specified time. If no time is specified, the current time is used. Non-expiring credentials will always return true.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.issued_time()

The time that the credential was issued, expressed as seconds since the epoch.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.static_api_key.static_api_key.FileBackedApiKey.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.path()

Retrieve the currently configured path for saved data.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.set_path(file_path)

Update storage path for the object.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.static_api_key.static_api_key.FileBackedApiKey.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.storage_utils

planet_auth.storage_utils.ObjectStorageProvider_KeyType = pathlib.Path module-attribute

Key type for object storage. Paths are currently used in part because of the history of the class. Paths need not be real files on disk. It is up to the implementation to decide if a real file should be used, or another storage mechanism should be used.

planet_auth.storage_utils.FileBackedJsonObject

A storage backed json object for storing information. Base class provides lazy loading and validation before saving or setting the data. Derived classes should provide type specific validation and convenience data accessors. The intent is that this provides a way to have an object backed by storage, and rails are in place to prevent invalid data from being saved or used.

Data is allowed to be initialized as None so that JIT load() use cases can be supported with the data not being read until needed. Care should be taken when constructing from an in-memory data value, as leaf class data validation is not performed during construction.

The None data structure is treated as a special case, and means that the class has been constructed, but the data has never been set. Once data has been set, either by calling set_data() or by loading data from a storage, it is only permitted to be set to valid values.

Saving to the backing is also optional. Uses in this way, this class behaves as a validating in-memory json object holder. To disable saving to storage, construct objects with a None file_path.

The default storage provider will use the file system for storage. When loading from file storage, the file may be SOPS encrypted. When using SOPS encryption, the file should have a ".sops.json" suffix.

planet_auth.storage_utils.FileBackedJsonObject.check()

Run check_data against our current state. An exception will be thrown if the current data is found to be invalid. Subclasses should not need to override this method, as they are expected to implement check_data(). This method will not perform a load() before checking the data. That is considered an application responsibility.

planet_auth.storage_utils.FileBackedJsonObject.check_data(data)

Check that the provided data is valid. Throws an exception if the data is not valid. This allows the base class to refuse to store or use data, while leaving it to child classes to know what constitutes "valid". Child classes should raise FileBackedJsonObjectException exception.

Child classes should override this method as required to do more application specific data integrity checks. They should also call validation on their base classes so that all layers of validation are performed.

The base assertion is that the data structure has been set. It may be empty, but may not be None. The None data structure is treated as a special case, and means that the class has been constructed, but the data has never been set. Once data has been set, it is only permitted to be set to valid values. The intent of this behavior is to support JIT loading semantics.

planet_auth.storage_utils.FileBackedJsonObject.data()

Retrieve the current data that is in memory. This method will not load the data from storage.

planet_auth.storage_utils.FileBackedJsonObject.is_persisted_to_storage()

Check if the object exists in storage. This does not require or cause the object to be loaded. This does not check that the version in storage is the most up-to-date.

planet_auth.storage_utils.FileBackedJsonObject.lazy_get(field)

Lazy load the data and retrieve the requested field.

planet_auth.storage_utils.FileBackedJsonObject.lazy_load()

Lazy load the data from storage.

If the data has already been set, whether by an the constructor, an explicit set_data(), or a previous load from storage, no attempt is made to refresh the data. Object will behave as an in memory object.

If the data is not set, it will attempt to load the data from storage. An error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

For updating the data from storage even if an in memory copy exists, see lazy_reload().

Users may always force a load at any time by calling load()

planet_auth.storage_utils.FileBackedJsonObject.lazy_reload()

Lazy reload the data from storage.

If the data is set, a reload will be attempted if the data on storage appears to be newer if a path is set. if a path is not set, no attempt will be made to load the data.

If the data is not set, an error will be thrown if the loaded data is invalid, the file has not been set, or the file has been set to a non-existent path.

planet_auth.storage_utils.FileBackedJsonObject.load()

Force a data load from storage. If the file path has not been set, this will be a no-op to allow for in memory operations.

If the data loaded from storage is invalid, an exception will be thrown, and the currently held data will be left unchanged. When in memory data is invalid and no file path has been set, an error IS NOT thrown - there would be nothing to fall back to. In memory users should expect to call check() or check_data() on their own.

planet_auth.storage_utils.FileBackedJsonObject.path()

Retrieve the currently configured path for saved data.

planet_auth.storage_utils.FileBackedJsonObject.save()

Save the data to storage. If the data is invalid according to the child class's check_data() method, the data will not be saved and an error will be thrown. The intent in this design is to never save known bad data.

If the path has not been set, nothing will be saved to storage, and this will silently succeed. This is to allow for transparent in memory only use cases.

planet_auth.storage_utils.FileBackedJsonObject.set_data(data, copy_data=True)

Set the current in memory data. The data will be checked for validity before in memory values are set. Invalid data will result in an exception being thrown and no change being made to the in memory object.

planet_auth.storage_utils.FileBackedJsonObject.set_path(file_path)

Update storage path for the object.

planet_auth.storage_utils.FileBackedJsonObject.set_storage_provider(storage_provider=None)

Update storage provider for the object.

planet_auth.storage_utils.FileBackedJsonObject.storage_provider()

Retrieve the currently configured storage provider for saved data.

planet_auth.storage_utils.FileBackedJsonObject.update_data(sparse_update_data)

Update the data set with the provided sparse update. Updates that result in a data-set that will not pass check_data() will be rejected, and the data will be unchanged.

planet_auth.storage_utils.FileBackedJsonObjectException

Bases: AuthException

Exception indicating a problem with a file backed json object.

planet_auth.storage_utils.FileBackedJsonObjectException.recast(*exceptions, **params) classmethod

Decorator to recast an exception as the specified exception: Example:

@AuthException.recast(Exception)
@AuthException_SubClass.recast(Some_Specific_Exception)
def raise_my_exception2():
    raise Some_Specific_Exception()

Exercise caution when using multiple re-casts. Recasting as something that is then caught by a decorator further up the stack causes problems: Example:

@AuthException.recast(Exception) # Causes a problem, since it will catch
                                 # the results of the recasts below
@AuthException_SomeSubException.recast(Some_Specific_Exception)
def raise_my_exception2():
    raise Some_Specific_Exception()

planet_auth.storage_utils.ObjectStorageProvider

Bases: ABC

Abstract interface used to persist objects to storage.

planet_auth.storage_utils.ObjectStorageProvider.load_obj(key) abstractmethod

Read an object from storage :return:

planet_auth.storage_utils.ObjectStorageProvider.mtime(key) abstractmethod

Return the last modified time in seconds since the epoc for the object. If the object does not exist, an exception should be raised.

planet_auth.storage_utils.ObjectStorageProvider.obj_exists(key) abstractmethod

Check whether a given object exists in storage.

planet_auth.storage_utils.ObjectStorageProvider.obj_rename(src, dst) abstractmethod

Rename/Move an object from the source path to the destination path.

planet_auth.storage_utils.ObjectStorageProvider.save_obj(key, data) abstractmethod

Write an object to storage :return: