Skip to content

Configuration and Profiles

Auth Clients

The AuthClient is responsible for all interactions with the authentication services. How a client interacts with the authentication services can vary considerably between implementations.

AuthClient Configuration dictionaries may either be provided directly, or loaded from disk when saved in a Profile (See below).

While it is possible to work directly with the lower level implementation classes, it is generally simpler to organize the working set of objects with an Auth Context instance created from one of the factory methods in planet_auth_utils.PlanetAuthFactory

A number of auth client implementations are provided. Clients should select the one most appropriate for their use case.

OAuth Clients

Auth Code with PKCE

Implemented by planet_auth.AuthCodeAuthClient and planet_auth.AuthCodeClientConfig

Configuration:

~/.planet/_profile_name_/auth_client.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "client_type": "oidc_auth_code",
    "auth_server": "https://login.planet.com/",
    "client_id": "your_client_id",
    "redirect_uri": "client_redirect_url_for_network_hosted_handler__if_needed",
    "local_redirect_uri": "client_redirect_url_for_localhost_handler__if_needed",
    "authorization_callback_acknowledgement": "optional__custom_authorization_callback_acknowledgement",
    "authorization_callback_acknowledgement_file": "optional__custom_authorization_callback_acknowledgement_from_a_file",
    "scopes": [
        "planet",
        "offline_access",
        "openid",
        "profile"
    ]
}

Profile Usage: 

1
2
3
import planet_auth_utils

auth_ctx = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(auth_profile_opt="_profile_name_")

Direct Usage: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import planet_auth_utils

auth_ctx = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context_from_custom_config(
    client_config={
        "client_type": "oidc_auth_code",
        "auth_server": "https://login.example.com/",
        "client_id": "your_client_id",
        "redirect_uri": "client_redirect_url_for_network_hosted_handler__if_needed",
        "authorization_callback_acknowledgement": "optional__custom_authorization_callback_acknowledgement",
        "authorization_callback_acknowledgement_file": "optional__custom_authorization_callback_acknowledgement_from_a_file",
        "scopes": ["planet", "offline_access", "openid", "profile"],
    },
    profile_name="_my_profile_name_",
)

Auth Code with PKCE and Client Public Key

Implemented by planet_auth.AuthCodeWithPubKeyAuthClient and planet_auth.AuthCodeWithPubKeyClientConfig

Configuration:

~/.planet/_profile_name_/auth_client.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    "client_type": "oidc_auth_code_pubkey",
    "auth_server": "https://login.planet.com/",
    "client_id": "your_client_id",
    "client_privkey": "__private_key_literal_PEM__",
    "client_privkey_file": "__path_to_private_key_PEM_file__",
    "client_privkey_password": "__password_protecting_private_key_PEM_data__",
    "redirect_uri": "your_client_redirect_url__if_needed",
    "local_redirect_uri": "client_redirect_url_for_localhost_handler__if_needed",
    "authorization_callback_acknowledgement": "optional__custom_authorization_callback_acknowledgement",
    "authorization_callback_acknowledgement_file": "optional__custom_authorization_callback_acknowledgement_from_a_file",
    "scopes": [
        "planet",
        "offline_access",
        "openid",
        "profile"
    ]
}
Only one of client_privkey or client_privkey_file is required.

Profile Usage and Direct Usage as shown above.

Auth Code with PKCE and Client Secret

Implemented by planet_auth.AuthCodeWithClientSecretAuthClient and planet_auth.AuthCodeWithClientSecretClientConfig

Configuration:

~/.planet/_profile_name_/auth_client.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "client_type": "oidc_auth_code_secret",
    "auth_server": "https://login.planet.com/",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "redirect_uri": "your_client_redirect_url__if_needed",
    "local_redirect_uri": "client_redirect_url_for_localhost_handler__if_needed",
    "authorization_callback_acknowledgement": "optional__custom_authorization_callback_acknowledgement",
    "authorization_callback_acknowledgement_file": "optional__custom_authorization_callback_acknowledgement_from_a_file",
    "scopes": [
        "planet",
        "offline_access",
        "openid",
        "profile"
    ]
}

Profile Usage and Direct Usage as shown above.

Client Credentials with Client Public Key

Implemented by planet_auth.ClientCredentialsPubKeyAuthClient and planet_auth.ClientCredentialsPubKeyClientConfig

Configuration:

~/.planet/_profile_name_/auth_client.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "client_type": "oidc_client_credentials_pubkey",
    "auth_server": "https://login.planet.com/",
    "client_id": "your_client_id",
    "client_privkey": "__private_key_literal_PEM__",
    "client_privkey_file": "__path_to_private_key_PEM_file__",
    "client_privkey_password": "__password_protecting_private_key_PEM_data__",
    "scopes": [
        "planet"
    ]
}
Only one of client_privkey or client_privkey_file is required.

Profile Usage and Direct Usage as shown above.

Client Credentials with Client Secret

Implemented by planet_auth.ClientCredentialsClientSecretAuthClient and planet_auth.ClientCredentialsClientSecretClientConfig

Configuration:

~/.planet/_profile_name_/auth_client.json
1
2
3
4
5
6
7
8
9
{
    "client_type": "oidc_client_credentials_secret",
    "auth_server": "https://login.planet.com/",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "scopes": [
        "planet"
    ]
}

Profile Usage and Direct Usage as shown above.

Resource Owner

Insecure Practice

Use of this OAuth client type is discouraged.

Implemented by planet_auth.ResourceOwnerAuthClient and planet_auth.ResourceOwnerClientConfig

Configuration:

~/.planet/_profile_name_/auth_client.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "client_type": "oidc_resource_owner",
    "auth_server": "https://login.planet.com/",
    "client_id": "your_client_id",
    "username": "_prompted_during_login_if_unset_",
    "password": "_prompted_during_login_if_unset_",
    "scopes": [
        "planet",
        "offline_access",
        "openid",
        "profile"
    ]
}

Profile Usage and Direct Usage as shown above.

Resource Owner with Client Public Key

Insecure Practice

Use of this OAuth client type is discouraged.

Implemented by planet_auth.ResourceOwnerWithPubKeyAuthClient and planet_auth.ResourceOwnerWithPubKeyClientConfig

Configuration:

~/.planet/_profile_name_/auth_client.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "client_type": "oidc_resource_owner_pubkey",
    "auth_server": "https://login.planet.com/",
    "client_id": "your_client_id",
    "client_privkey": "__private_key_literal_PEM__",
    "client_privkey_file": "__path_to_private_key_PEM_file__",
    "client_privkey_password": "__password_protecting_private_key_PEM_data__",
    "username": "_prompted_during_login_if_unset_",
    "password": "_prompted_during_login_if_unset_",
    "scopes": [
        "planet",
        "offline_access",
        "openid",
        "profile"
    ]
}
Only one of client_privkey or client_privkey_file is required.

Profile Usage and Direct Usage as shown above.

Resource Owner with Client Secret

Insecure Practice

Use of this OAuth client type is discouraged.

Implemented by planet_auth.ResourceOwnerWithClientSecretAuthClient and planet_auth.ResourceOwnerWithClientSecretClientConfig

Configuration:

~/.planet/_profile_name_/auth_client.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "client_type": "oidc_resource_owner_secret",
    "auth_server": "https://login.planet.com/",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "username": "_prompted_during_login_if_unset_",
    "password": "_prompted_during_login_if_unset_",
    "scopes": [
        "planet",
        "offline_access",
        "openid",
        "profile"
    ]
}

Profile Usage and Direct Usage as shown above.

OAuth2/OIDC Client Validator

Implemented by planet_auth.OidcClientValidatorAuthClient and planet_auth.OidcClientValidatorAuthClientConfig

Configuration:

~/.planet/_profile_name_/auth_client.json
1
2
3
4
{
  "client_type": "oidc_client_validator",
  "auth_server": "https://login.planet.com/"
}

Usage of this configuration is different from most. This configuration does not prepare an Auth context that is suitable for making authenticated outbound calls, which is one of the primary aims of most auth client types. Instead, this client configuration can only be used to validate incoming tokens.

Planet Legacy Client

Implemented by planet_auth.PlanetLegacyAuthClient and planet_auth.PlanetLegacyAuthClientConfig

Configuration:

~/.planet/_profile_name_/auth_client.json
1
2
3
4
5
{
    "client_type": "planet_legacy",
    "legacy_auth_endpoint": "https://api.planet.com/v0/auth/login",
    "api_key": "_optional_to_eliminate_need_to_do_login_"
}

Profile Usage: 

1
2
3
import planet_auth_utils

auth_ctx = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(auth_profile_opt="_profile_name_")

Direct Usage: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import planet_auth_utils

auth_ctx = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context_from_custom_config(
    client_config={
        "client_type": "planet_legacy",
        "legacy_auth_endpoint": "https://api.planet.com/v0/auth/login",
        "api_key": "_optional_to_eliminate_need_to_do_login_",
    },
    profile_name="_my_legacy_profile_name_",
)

Environment Variables

See planet_auth_utils.EnvironmentVariables for a list of environment variables.

On Disk Configuration Profiles

Central to how the auth client library manages on disk configuration is the concept of an auth profile. The auth profile specifies an AuthClient configuration, controlling how the library interacts with authentication services to obtain service tokens. The AuthClient configuration also controls how those tokens are subsequently used to interact with other services. Auth profiles may be used to manage different user accounts by creating multiple named profiles with otherwise identical AuthClient configurations.

The auth profile also determines where authentication configuration files and authentication tokens are stored on disk. When a given profile is selected, the ~/.planet/<profile> directory will be used in the user’s home directory. Profile names will be down-cased to all lowercase. Within the currently active profile directory, auth credentials will be stored in a token.json file, and auth profile configuration will be stored in an auth_client.json file. The contents and format of these files vary depending on the specific auth mechanism configured for the auth profile. If present, auth_client.sops.json will take priority over auth_client.json, allowing clients that have secrets to securely store this information on disk using SOPS encryption. Similarly, a token.sops.json file will take priority over a token.json file. The configuration of SOPS is outside the scope of this tooling, and left to the user.