0
# Authentication Service
1
2
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.
3
4
## Capabilities
5
6
### Core Authentication Clients
7
8
Foundation clients providing general authentication operations and OAuth2 flow management for different application types.
9
10
```python { .api }
11
class AuthClient(BaseClient):
12
"""
13
General Auth API client for identity and authorization operations.
14
15
Provides methods for identity lookup, policy management, scope operations,
16
and general authentication service functionality.
17
"""
18
19
def __init__(
20
self,
21
*,
22
app: GlobusApp | None = None,
23
authorizer: GlobusAuthorizer | None = None,
24
environment: str | None = None,
25
base_url: str | None = None,
26
**kwargs
27
) -> None: ...
28
29
def get_identities(
30
self,
31
*,
32
usernames: list[str] | None = None,
33
ids: list[str] | None = None,
34
**params
35
) -> GetIdentitiesResponse:
36
"""
37
Look up identity information by usernames or identity IDs.
38
39
Parameters:
40
- usernames: List of usernames to resolve
41
- ids: List of identity UUIDs to resolve
42
- **params: Additional query parameters
43
44
Returns:
45
GetIdentitiesResponse with identity information
46
"""
47
48
def get_identity_providers(self, **params) -> GetIdentityProvidersResponse:
49
"""Get list of available identity providers."""
50
51
def get_consents(
52
self,
53
*,
54
identity_id: str | None = None,
55
**params
56
) -> GetConsentsResponse:
57
"""Get consent information for an identity."""
58
59
def get_scopes(
60
self,
61
scope_ids: list[str] | None = None,
62
**params
63
) -> GetScopesResponse:
64
"""Get detailed scope information."""
65
66
def get_projects(self, **params) -> GetProjectsResponse:
67
"""Get project information for the authenticated user."""
68
69
class AuthLoginClient(AuthClient):
70
"""
71
Base class for OAuth2 login clients providing common authentication flow methods.
72
73
Supports both native and confidential application patterns with
74
standardized OAuth2 grant flows.
75
"""
76
77
def __init__(
78
self,
79
client_id: str,
80
*,
81
authorizer: GlobusAuthorizer | None = None,
82
**kwargs
83
) -> None: ...
84
85
@property
86
def client_id(self) -> str:
87
"""The OAuth2 client identifier."""
88
```
89
90
### Native Application Authentication
91
92
OAuth2 client for native applications (public clients) that cannot securely store client secrets. Uses PKCE (Proof Key for Code Exchange) for security.
93
94
```python { .api }
95
class NativeAppAuthClient(AuthLoginClient):
96
"""
97
OAuth client for native applications (public clients).
98
99
Used for client-side applications like desktop apps and mobile apps
100
that cannot securely store client secrets. Uses PKCE for security.
101
"""
102
103
def __init__(
104
self,
105
client_id: str,
106
*,
107
environment: str | None = None,
108
base_url: str | None = None,
109
app_name: str | None = None,
110
transport_params: dict[str, Any] | None = None
111
) -> None: ...
112
113
def oauth2_start_flow(
114
self,
115
requested_scopes: ScopeCollectionType | None = None,
116
*,
117
redirect_uri: str | None = None,
118
state: str = "_default",
119
verifier: str | None = None,
120
refresh_tokens: bool = False,
121
prefill_named_grant: str | None = None
122
) -> GlobusNativeAppFlowManager:
123
"""
124
Start a Native App OAuth2 flow with PKCE.
125
126
Parameters:
127
- requested_scopes: Scopes to request (defaults to basic scopes)
128
- redirect_uri: OAuth redirect URI (defaults to auth.globus.org display page)
129
- state: State parameter for OAuth flow
130
- verifier: PKCE code verifier (auto-generated if not provided)
131
- refresh_tokens: Whether to request refresh tokens
132
- prefill_named_grant: Prefill named grant label on consent page
133
134
Returns:
135
GlobusNativeAppFlowManager for managing the OAuth flow
136
"""
137
138
def oauth2_get_authorize_url(self, **params) -> str:
139
"""
140
Get the authorization URL for the OAuth2 flow.
141
142
Must call oauth2_start_flow() first.
143
144
Returns:
145
Authorization URL string for user authentication
146
"""
147
148
def oauth2_exchange_code_for_tokens(
149
self,
150
auth_code: str
151
) -> OAuthAuthorizationCodeResponse:
152
"""
153
Exchange authorization code for access tokens.
154
155
Parameters:
156
- auth_code: Authorization code from OAuth callback
157
158
Returns:
159
OAuthAuthorizationCodeResponse containing tokens
160
"""
161
162
def oauth2_refresh_token(
163
self,
164
refresh_token: str,
165
*,
166
body_params: dict[str, Any] | None = None
167
) -> OAuthRefreshTokenResponse:
168
"""
169
Use a refresh token to get new access tokens.
170
171
Parameters:
172
- refresh_token: The refresh token
173
- body_params: Additional body parameters
174
175
Returns:
176
OAuthRefreshTokenResponse with new tokens
177
"""
178
179
def oauth2_revoke_token(
180
self,
181
token: str,
182
*,
183
body_params: dict[str, Any] | None = None
184
) -> GlobusHTTPResponse:
185
"""
186
Revoke an access or refresh token.
187
188
Parameters:
189
- token: Token to revoke
190
- body_params: Additional parameters
191
"""
192
```
193
194
### Confidential Application Authentication
195
196
OAuth2 client for confidential applications (server-side apps) that can securely store client secrets. Supports client credentials and authorization code flows.
197
198
```python { .api }
199
class ConfidentialAppAuthClient(AuthLoginClient):
200
"""
201
OAuth client for confidential applications (server-side apps).
202
203
Used for server-side applications that can securely store client secrets.
204
Supports both authorization code and client credentials grant flows.
205
"""
206
207
def __init__(
208
self,
209
client_id: str,
210
client_secret: str,
211
*,
212
environment: str | None = None,
213
base_url: str | None = None,
214
app_name: str | None = None,
215
transport_params: dict[str, Any] | None = None
216
) -> None: ...
217
218
def oauth2_client_credentials_tokens(
219
self,
220
*,
221
requested_scopes: ScopeCollectionType | None = None,
222
body_params: dict[str, Any] | None = None
223
) -> OAuthClientCredentialsResponse:
224
"""
225
Get tokens using OAuth2 Client Credentials grant.
226
227
Used for service-to-service authentication where no user interaction
228
is required. The application acts on its own behalf.
229
230
Parameters:
231
- requested_scopes: Scopes to request for the token
232
- body_params: Additional body parameters
233
234
Returns:
235
OAuthClientCredentialsResponse containing access token
236
"""
237
238
def oauth2_start_flow(
239
self,
240
redirect_uri: str,
241
*,
242
requested_scopes: ScopeCollectionType | None = None,
243
state: str = "_default",
244
refresh_tokens: bool = False,
245
prefill_named_grant: str | None = None
246
) -> None:
247
"""
248
Start an Authorization Code OAuth2 flow.
249
250
Parameters:
251
- redirect_uri: OAuth redirect URI for your application
252
- requested_scopes: Scopes to request
253
- state: State parameter for OAuth flow
254
- refresh_tokens: Whether to request refresh tokens
255
- prefill_named_grant: Prefill named grant label
256
"""
257
258
def oauth2_get_authorize_url(self, **params) -> str:
259
"""Get the authorization URL after starting a flow."""
260
261
def oauth2_exchange_code_for_tokens(
262
self,
263
auth_code: str
264
) -> OAuthAuthorizationCodeResponse:
265
"""Exchange authorization code for tokens."""
266
267
def oauth2_get_dependent_tokens(
268
self,
269
token: str,
270
*,
271
requested_scopes: list[DependentScopeSpec] | None = None
272
) -> OAuthDependentTokenResponse:
273
"""
274
Get dependent tokens for accessing other services.
275
276
Uses an existing token to get tokens for other Globus services
277
that the user has consented to.
278
279
Parameters:
280
- token: Existing access token
281
- requested_scopes: List of dependent scope specifications
282
283
Returns:
284
OAuthDependentTokenResponse with service-specific tokens
285
"""
286
```
287
288
### Authentication Response Objects
289
290
Specialized response classes for different OAuth2 flows and authentication operations.
291
292
```python { .api }
293
class OAuthTokenResponse(GlobusHTTPResponse):
294
"""Base class for OAuth token responses."""
295
296
@property
297
def by_resource_server(self) -> dict[str, dict[str, Any]]:
298
"""Access tokens organized by resource server."""
299
300
def by_scopes(self, scopes: ScopeCollectionType) -> dict[str, dict[str, Any]]:
301
"""Get tokens that match the given scopes."""
302
303
class OAuthAuthorizationCodeResponse(OAuthTokenResponse):
304
"""Response from authorization code exchange."""
305
306
class OAuthClientCredentialsResponse(OAuthTokenResponse):
307
"""Response from client credentials grant."""
308
309
class OAuthRefreshTokenResponse(OAuthTokenResponse):
310
"""Response from refresh token usage."""
311
312
class OAuthDependentTokenResponse(OAuthTokenResponse):
313
"""Response from dependent token request."""
314
315
class GetIdentitiesResponse(GlobusHTTPResponse):
316
"""Response from identity lookup operations."""
317
318
def __iter__(self) -> Iterator[dict[str, Any]]:
319
"""Iterate over identity records."""
320
321
class GetConsentsResponse(GlobusHTTPResponse):
322
"""Response from consent information requests."""
323
324
def __iter__(self) -> Iterator[dict[str, Any]]:
325
"""Iterate over consent records."""
326
```
327
328
### Identity and Token Management
329
330
High-level utilities for identity mapping and token validation.
331
332
```python { .api }
333
class IdentityMap:
334
"""
335
Utility for mapping between different identity representations.
336
337
Provides bidirectional mapping between usernames, identity IDs,
338
and other identity attributes.
339
"""
340
341
def __init__(
342
self,
343
auth_client: AuthClient,
344
id_list: list[str] | None = None
345
) -> None: ...
346
347
def __getitem__(self, identity: str) -> dict[str, Any]:
348
"""Get identity information by username or ID."""
349
350
def get(self, identity: str, default: Any = None) -> dict[str, Any] | Any:
351
"""Get identity information with default fallback."""
352
353
def add(self, identity_document: dict[str, Any]) -> None:
354
"""Add an identity document to the map."""
355
356
class IDTokenDecoder:
357
"""
358
JWT ID token decoder and validator.
359
360
Decodes and validates OpenID Connect ID tokens from Globus Auth
361
with proper signature verification and claims validation.
362
"""
363
364
def __init__(
365
self,
366
auth_client: AuthClient | None = None,
367
*,
368
openid_configuration: dict[str, Any] | None = None,
369
jwks_uri: str | None = None
370
) -> None: ...
371
372
def decode(
373
self,
374
id_token: str,
375
*,
376
verify_signature: bool = True,
377
verify_audience: str | list[str] | None = None,
378
verify_exp: bool = True
379
) -> dict[str, Any]:
380
"""
381
Decode and validate an ID token.
382
383
Parameters:
384
- id_token: JWT ID token string
385
- verify_signature: Whether to verify JWT signature
386
- verify_audience: Expected audience(s) for validation
387
- verify_exp: Whether to verify token expiration
388
389
Returns:
390
Dictionary of decoded claims
391
"""
392
```
393
394
### Dependent Scope Management
395
396
Support for requesting tokens with scopes that depend on other services or resources.
397
398
```python { .api }
399
class DependentScopeSpec:
400
"""
401
Specification for requesting dependent tokens with specific scopes.
402
403
Used when requesting tokens for services that require specific
404
resource-dependent permissions.
405
"""
406
407
def __init__(
408
self,
409
scope: Scope | str,
410
*,
411
optional: bool = False
412
) -> None: ...
413
414
@property
415
def scope(self) -> str:
416
"""The scope string."""
417
418
@property
419
def optional(self) -> bool:
420
"""Whether this scope is optional."""
421
```
422
423
### Error Handling
424
425
Authentication-specific error handling for OAuth flows and API operations.
426
427
```python { .api }
428
class AuthAPIError(GlobusAPIError):
429
"""
430
Error class for Auth service API errors.
431
432
Provides enhanced error handling for authentication-specific
433
error conditions and OAuth2 error responses.
434
"""
435
436
@property
437
def authorization_parameters(self) -> dict[str, Any] | None:
438
"""OAuth2 authorization parameters from error response."""
439
```
440
441
## Common Usage Patterns
442
443
### Native App Authentication Flow
444
445
```python
446
from globus_sdk import NativeAppAuthClient, AccessTokenAuthorizer, TransferClient
447
448
# Initialize native app client
449
auth_client = NativeAppAuthClient("your_client_id")
450
451
# Start OAuth flow
452
auth_client.oauth2_start_flow(refresh_tokens=True)
453
454
# Get authorization URL
455
authorize_url = auth_client.oauth2_get_authorize_url()
456
print(f"Visit: {authorize_url}")
457
458
# Exchange code for tokens
459
auth_code = input("Enter code: ")
460
tokens = auth_client.oauth2_exchange_code_for_tokens(auth_code)
461
462
# Create service clients with tokens
463
transfer_token = tokens.by_resource_server["transfer.api.globus.org"]
464
transfer_client = TransferClient(
465
authorizer=AccessTokenAuthorizer(transfer_token["access_token"])
466
)
467
```
468
469
### Client Credentials Flow
470
471
```python
472
from globus_sdk import ConfidentialAppAuthClient, AccessTokenAuthorizer
473
474
# Service-to-service authentication
475
auth_client = ConfidentialAppAuthClient("client_id", "client_secret")
476
477
# Get tokens for your application
478
tokens = auth_client.oauth2_client_credentials_tokens(
479
requested_scopes=["urn:globus:auth:scope:transfer.api.globus.org:all"]
480
)
481
482
# Use tokens for API access
483
transfer_token = tokens.by_resource_server["transfer.api.globus.org"]
484
authorizer = AccessTokenAuthorizer(transfer_token["access_token"])
485
```
486
487
### Identity Resolution
488
489
```python
490
from globus_sdk import AuthClient, IdentityMap
491
492
auth_client = AuthClient(authorizer=authorizer)
493
494
# Look up identities by username
495
identities = auth_client.get_identities(usernames=["user@example.org"])
496
for identity in identities:
497
print(f"Username: {identity['username']}, ID: {identity['id']}")
498
499
# Use identity map for efficient lookups
500
identity_map = IdentityMap(auth_client, ["user1@example.org", "user2@example.org"])
501
user_info = identity_map["user1@example.org"]
502
```