tessl/pypi-globus-sdk
Python SDK for interacting with Globus web APIs including Transfer, Auth, and other research data management services
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
auth-service.mddocs/
Authentication Service
OAuth2 flows, token management, identity resolution, and authorization for native and confidential applications. The Auth service provides comprehensive authentication and authorization capabilities for the Globus ecosystem, supporting multiple OAuth2 grant types, identity providers, and consent management.
Capabilities
Core Authentication Clients
Foundation clients providing general authentication operations and OAuth2 flow management for different application types.
class AuthClient(BaseClient):
"""
General Auth API client for identity and authorization operations.
Provides methods for identity lookup, policy management, scope operations,
and general authentication service functionality.
"""
def __init__(
self,
*,
app: GlobusApp | None = None,
authorizer: GlobusAuthorizer | None = None,
environment: str | None = None,
base_url: str | None = None,
**kwargs
) -> None: ...
def get_identities(
self,
*,
usernames: list[str] | None = None,
ids: list[str] | None = None,
**params
) -> GetIdentitiesResponse:
"""
Look up identity information by usernames or identity IDs.
Parameters:
- usernames: List of usernames to resolve
- ids: List of identity UUIDs to resolve
- **params: Additional query parameters
Returns:
GetIdentitiesResponse with identity information
"""
def get_identity_providers(self, **params) -> GetIdentityProvidersResponse:
"""Get list of available identity providers."""
def get_consents(
self,
*,
identity_id: str | None = None,
**params
) -> GetConsentsResponse:
"""Get consent information for an identity."""
def get_scopes(
self,
scope_ids: list[str] | None = None,
**params
) -> GetScopesResponse:
"""Get detailed scope information."""
def get_projects(self, **params) -> GetProjectsResponse:
"""Get project information for the authenticated user."""
class AuthLoginClient(AuthClient):
"""
Base class for OAuth2 login clients providing common authentication flow methods.
Supports both native and confidential application patterns with
standardized OAuth2 grant flows.
"""
def __init__(
self,
client_id: str,
*,
authorizer: GlobusAuthorizer | None = None,
**kwargs
) -> None: ...
@property
def client_id(self) -> str:
"""The OAuth2 client identifier."""Native Application Authentication
OAuth2 client for native applications (public clients) that cannot securely store client secrets. Uses PKCE (Proof Key for Code Exchange) for security.
class NativeAppAuthClient(AuthLoginClient):
"""
OAuth client for native applications (public clients).
Used for client-side applications like desktop apps and mobile apps
that cannot securely store client secrets. Uses PKCE for security.
"""
def __init__(
self,
client_id: str,
*,
environment: str | None = None,
base_url: str | None = None,
app_name: str | None = None,
transport_params: dict[str, Any] | None = None
) -> None: ...
def oauth2_start_flow(
self,
requested_scopes: ScopeCollectionType | None = None,
*,
redirect_uri: str | None = None,
state: str = "_default",
verifier: str | None = None,
refresh_tokens: bool = False,
prefill_named_grant: str | None = None
) -> GlobusNativeAppFlowManager:
"""
Start a Native App OAuth2 flow with PKCE.
Parameters:
- requested_scopes: Scopes to request (defaults to basic scopes)
- redirect_uri: OAuth redirect URI (defaults to auth.globus.org display page)
- state: State parameter for OAuth flow
- verifier: PKCE code verifier (auto-generated if not provided)
- refresh_tokens: Whether to request refresh tokens
- prefill_named_grant: Prefill named grant label on consent page
Returns:
GlobusNativeAppFlowManager for managing the OAuth flow
"""
def oauth2_get_authorize_url(self, **params) -> str:
"""
Get the authorization URL for the OAuth2 flow.
Must call oauth2_start_flow() first.
Returns:
Authorization URL string for user authentication
"""
def oauth2_exchange_code_for_tokens(
self,
auth_code: str
) -> OAuthAuthorizationCodeResponse:
"""
Exchange authorization code for access tokens.
Parameters:
- auth_code: Authorization code from OAuth callback
Returns:
OAuthAuthorizationCodeResponse containing tokens
"""
def oauth2_refresh_token(
self,
refresh_token: str,
*,
body_params: dict[str, Any] | None = None
) -> OAuthRefreshTokenResponse:
"""
Use a refresh token to get new access tokens.
Parameters:
- refresh_token: The refresh token
- body_params: Additional body parameters
Returns:
OAuthRefreshTokenResponse with new tokens
"""
def oauth2_revoke_token(
self,
token: str,
*,
body_params: dict[str, Any] | None = None
) -> GlobusHTTPResponse:
"""
Revoke an access or refresh token.
Parameters:
- token: Token to revoke
- body_params: Additional parameters
"""Confidential Application Authentication
OAuth2 client for confidential applications (server-side apps) that can securely store client secrets. Supports client credentials and authorization code flows.
class ConfidentialAppAuthClient(AuthLoginClient):
"""
OAuth client for confidential applications (server-side apps).
Used for server-side applications that can securely store client secrets.
Supports both authorization code and client credentials grant flows.
"""
def __init__(
self,
client_id: str,
client_secret: str,
*,
environment: str | None = None,
base_url: str | None = None,
app_name: str | None = None,
transport_params: dict[str, Any] | None = None
) -> None: ...
def oauth2_client_credentials_tokens(
self,
*,
requested_scopes: ScopeCollectionType | None = None,
body_params: dict[str, Any] | None = None
) -> OAuthClientCredentialsResponse:
"""
Get tokens using OAuth2 Client Credentials grant.
Used for service-to-service authentication where no user interaction
is required. The application acts on its own behalf.
Parameters:
- requested_scopes: Scopes to request for the token
- body_params: Additional body parameters
Returns:
OAuthClientCredentialsResponse containing access token
"""
def oauth2_start_flow(
self,
redirect_uri: str,
*,
requested_scopes: ScopeCollectionType | None = None,
state: str = "_default",
refresh_tokens: bool = False,
prefill_named_grant: str | None = None
) -> None:
"""
Start an Authorization Code OAuth2 flow.
Parameters:
- redirect_uri: OAuth redirect URI for your application
- requested_scopes: Scopes to request
- state: State parameter for OAuth flow
- refresh_tokens: Whether to request refresh tokens
- prefill_named_grant: Prefill named grant label
"""
def oauth2_get_authorize_url(self, **params) -> str:
"""Get the authorization URL after starting a flow."""
def oauth2_exchange_code_for_tokens(
self,
auth_code: str
) -> OAuthAuthorizationCodeResponse:
"""Exchange authorization code for tokens."""
def oauth2_get_dependent_tokens(
self,
token: str,
*,
requested_scopes: list[DependentScopeSpec] | None = None
) -> OAuthDependentTokenResponse:
"""
Get dependent tokens for accessing other services.
Uses an existing token to get tokens for other Globus services
that the user has consented to.
Parameters:
- token: Existing access token
- requested_scopes: List of dependent scope specifications
Returns:
OAuthDependentTokenResponse with service-specific tokens
"""Authentication Response Objects
Specialized response classes for different OAuth2 flows and authentication operations.
class OAuthTokenResponse(GlobusHTTPResponse):
"""Base class for OAuth token responses."""
@property
def by_resource_server(self) -> dict[str, dict[str, Any]]:
"""Access tokens organized by resource server."""
def by_scopes(self, scopes: ScopeCollectionType) -> dict[str, dict[str, Any]]:
"""Get tokens that match the given scopes."""
class OAuthAuthorizationCodeResponse(OAuthTokenResponse):
"""Response from authorization code exchange."""
class OAuthClientCredentialsResponse(OAuthTokenResponse):
"""Response from client credentials grant."""
class OAuthRefreshTokenResponse(OAuthTokenResponse):
"""Response from refresh token usage."""
class OAuthDependentTokenResponse(OAuthTokenResponse):
"""Response from dependent token request."""
class GetIdentitiesResponse(GlobusHTTPResponse):
"""Response from identity lookup operations."""
def __iter__(self) -> Iterator[dict[str, Any]]:
"""Iterate over identity records."""
class GetConsentsResponse(GlobusHTTPResponse):
"""Response from consent information requests."""
def __iter__(self) -> Iterator[dict[str, Any]]:
"""Iterate over consent records."""Identity and Token Management
High-level utilities for identity mapping and token validation.
class IdentityMap:
"""
Utility for mapping between different identity representations.
Provides bidirectional mapping between usernames, identity IDs,
and other identity attributes.
"""
def __init__(
self,
auth_client: AuthClient,
id_list: list[str] | None = None
) -> None: ...
def __getitem__(self, identity: str) -> dict[str, Any]:
"""Get identity information by username or ID."""
def get(self, identity: str, default: Any = None) -> dict[str, Any] | Any:
"""Get identity information with default fallback."""
def add(self, identity_document: dict[str, Any]) -> None:
"""Add an identity document to the map."""
class IDTokenDecoder:
"""
JWT ID token decoder and validator.
Decodes and validates OpenID Connect ID tokens from Globus Auth
with proper signature verification and claims validation.
"""
def __init__(
self,
auth_client: AuthClient | None = None,
*,
openid_configuration: dict[str, Any] | None = None,
jwks_uri: str | None = None
) -> None: ...
def decode(
self,
id_token: str,
*,
verify_signature: bool = True,
verify_audience: str | list[str] | None = None,
verify_exp: bool = True
) -> dict[str, Any]:
"""
Decode and validate an ID token.
Parameters:
- id_token: JWT ID token string
- verify_signature: Whether to verify JWT signature
- verify_audience: Expected audience(s) for validation
- verify_exp: Whether to verify token expiration
Returns:
Dictionary of decoded claims
"""Dependent Scope Management
Support for requesting tokens with scopes that depend on other services or resources.
class DependentScopeSpec:
"""
Specification for requesting dependent tokens with specific scopes.
Used when requesting tokens for services that require specific
resource-dependent permissions.
"""
def __init__(
self,
scope: Scope | str,
*,
optional: bool = False
) -> None: ...
@property
def scope(self) -> str:
"""The scope string."""
@property
def optional(self) -> bool:
"""Whether this scope is optional."""Error Handling
Authentication-specific error handling for OAuth flows and API operations.
class AuthAPIError(GlobusAPIError):
"""
Error class for Auth service API errors.
Provides enhanced error handling for authentication-specific
error conditions and OAuth2 error responses.
"""
@property
def authorization_parameters(self) -> dict[str, Any] | None:
"""OAuth2 authorization parameters from error response."""Common Usage Patterns
Native App Authentication Flow
from globus_sdk import NativeAppAuthClient, AccessTokenAuthorizer, TransferClient
# Initialize native app client
auth_client = NativeAppAuthClient("your_client_id")
# Start OAuth flow
auth_client.oauth2_start_flow(refresh_tokens=True)
# Get authorization URL
authorize_url = auth_client.oauth2_get_authorize_url()
print(f"Visit: {authorize_url}")
# Exchange code for tokens
auth_code = input("Enter code: ")
tokens = auth_client.oauth2_exchange_code_for_tokens(auth_code)
# Create service clients with tokens
transfer_token = tokens.by_resource_server["transfer.api.globus.org"]
transfer_client = TransferClient(
authorizer=AccessTokenAuthorizer(transfer_token["access_token"])
)Client Credentials Flow
from globus_sdk import ConfidentialAppAuthClient, AccessTokenAuthorizer
# Service-to-service authentication
auth_client = ConfidentialAppAuthClient("client_id", "client_secret")
# Get tokens for your application
tokens = auth_client.oauth2_client_credentials_tokens(
requested_scopes=["urn:globus:auth:scope:transfer.api.globus.org:all"]
)
# Use tokens for API access
transfer_token = tokens.by_resource_server["transfer.api.globus.org"]
authorizer = AccessTokenAuthorizer(transfer_token["access_token"])Identity Resolution
from globus_sdk import AuthClient, IdentityMap
auth_client = AuthClient(authorizer=authorizer)
# Look up identities by username
identities = auth_client.get_identities(usernames=["user@example.org"])
for identity in identities:
print(f"Username: {identity['username']}, ID: {identity['id']}")
# Use identity map for efficient lookups
identity_map = IdentityMap(auth_client, ["user1@example.org", "user2@example.org"])
user_info = identity_map["user1@example.org"]Install with Tessl CLI
npx tessl i tessl/pypi-globus-sdk