We will provide a brief introduction to the Globus platform-as-a-service for developers, with emphasis on understanding the security model; and will demonstrate how to access Globus services via APIs for integration into custom research applications.
Introduction to the Globus Platform for Developers
1. Introduction to the Globus Platform for
Developers
Greg Nawrocki
greg@globus.org
nawrocki@uchicago.edu
nawrocki@anl.gov
Case Western Reserve University
October 23 – 24, 2023
3. PaaS Security Challenges – Globus Auth
• How to provide:
– Login to apps
o Web apps (Jupyter Notebook / Hub, Portals), Mobile, Desktop, Command line
– Protect all REST API communications
o App ! Globus service (Jupyter Notebook, Portals)
o App ! non-Globus service (Portals)
• While:
– Not introducing even more identities
o Providing a platform to consolidate those identities
– Providing least privileges security model (consents and scopes)
– Being agnostic to programming language and framework
– Being web friendly
– Making it easy for users and developers
3
4. Globus Auth: Foundational IAM service
• Brokers authentication and authorization among…
– End-users
– Identity providers: enterprise, external (federated identities)
– Services: resource servers with REST APIs
– Apps: web, mobile, desktop, command line clients
• Support high assurance service for use with
protected data (e.g. HIPAA protected data)
5
5. Fundamental Concepts
5
• Scopes
– APIs that client is requesting access to
– Resources within that service
o “I want to access the user’s identity information.”
o “I want to ingest information into a search index.”
• Token
– A data structure (JWT - JSON Web Token) returned by the auth
service
o Access Token
– short-lived, signed JWT an app can use with a specific API
» Three key parts: audience (what), subject (who), and scopes
o Refresh Token
– long-lived, signed JWT an app uses to get a new access token
6. Fundamental Concepts
6
• Consent
– A record maintained by the auth service indicating that a person
granted permission to an application to do something on their
behalf
• Credential
– Something used to prove an identity
o Password, client secret, authenticator app code, hardware key,
biometric measurement
o Credentials are only shared with identity providers (for authentication).
o Tokens are not credentials!
7. OAuth 2.0 and OpenID Connect 1.0
OAuth 2.0 is an authorization system.
● Enables an application to securely access remote APIs
● Web-first design: REST API, JSON Web Tokens (JWTs)
● Spec defines grants as ways to obtain access
OpenID Connect 1.0 (OIDC) is a way to use OAuth 2.0 for
authentication.
● Enables applications to obtain user identities and user
tokens
● Leverages the OAuth 2.0 protocol, web browsers for UI
● Signature UX feature: consent
● Spec defines flows as ways to obtain access
8. Securing Apps with Globus Auth – 3 Flows
• Auth Code Grant – Templated App
– Authentication as user identity
– Browser redirect to Globus Auth, auth code returned (no manual copy)
– Tokens stored securely
– CLI / Jupyter Hub secured with Globus Auth
• Native App (with refresh tokens – extend expiration)
– Authentication as user identity
– Authentication URL / come back with an auth code – exchanged for tokens
– Clients can’t keep a secret - tokens in plain text - deployment-key.json
– Jupyter Notebook examples / GCS CLI
• Confidential Client:
– Authentication as application
– ClientID and Secret stored securely
– Custom apps
– developers.globus.org - Client ID / Secret / Client Identity Username
8
9. Obtaining user tokens (so the app can do things
as the user)
A user token has a user identity as its subject. When used with an API,
requests are processed as the user, not as the application.
All apps that use the auth service must register with the service (get a client
ID)
Globus Web App – Settings menu – Developers tab
Apps use the OIDC authorization code flow to obtain user tokens.*
● Web app
○ Use the OIDC authorization code flow “as advertised”
● No browser
○ Use Globus-hosted authorization code redirect (user copy/pastes code) –
Native App Grant
* We don’t generally use the OIDC implicit flow or hybrid flow.
10. CLI
Globus (Resource
Server)
Globus Auth
(Authorization
Server)
5. Authenticate using client id
and secret, send authorization
code
Authorization Code Grant
Browser (User)
1. globus
login
2.
Redirects
user
3. User authenticates and
consents
4. Authorization
code
6. Access token(s)
7. Authenticate with access
token(s) to give the client
the authority invoke the
service
Identity
Provider
11. Browser
Native App Grant
13
Native App
(Client)
1. Run
application
2. URL to
authenticate
3. Authenticate and
consent
4. Auth code
5. Register
auth code
6. Exchange
code
7. Access tokens
8. Authenticate with access
tokens to invoke the
service as user App/Service
(Resource Server)
Globus Auth
(Authorization Server)
12. Native App Grant with Refresh Tokens
14
Native App
(Client)
App/Service
(Resource Server)
Globus Auth
(Authorization Server)
1. Run
application
2. URL to
authenticate
Browser
3. Authenticate and consent
4. Auth code
5. Register
auth code
6. Exchange code,
request refresh tokens
7. Access
tokens and refresh tokens
9. Exchange refresh token
for new access tokens
8. Store refresh tokens
10. Access tokens
11. Authenticate with access
tokens to invoke the service as user
13. Obtain client tokens (so the app can do things as
itself)
All apps that use the auth service must register with the service (get a client
ID).
Apps that have private storage can also get a client secret (credential) and use
the OAuth confidential client credentials grant to obtain access tokens. The
application can request any scope(s), so it can get a token for any API.
Globus Web App – Settings menu – Developers tab
● Simplifies the user experience for obtaining user tokens
● Enables the app to use APIs as itself (not as its human user).
● The app should (must) be able to store secret securely
The subject of these tokens is the application itself, so permissions/ACLs must
be granted to the application’s client ID.
14. Confidential Client Credential Grant
16
1. Authenticate with app
client id and secret
2. Access Tokens
Application,
Science Gateway,
Data Portal
(Client)
3. Authenticate as app
with access tokens to invoke
service (on behalf of authorized
user, within a given scope)
Globus Transfer
(Resource Server)
Globus Auth
(Authorization Server)
15. Cardinal rules of OAuth and OIDC
● All apps are registered with the auth service.
○ Apps don’t have to authenticate to use OIDC, but they must have a
client ID.
○ Access tokens are always issued to a specific app (client ID).
○ An app must never share an access token with another app.
● All Services (APIs) and scopes are registered with the auth
service.
○ APIs must have client secrets (private storage) and must
authenticate with the auth service.*
○ Every distinct logical host+API must be registered separately and
must register distinct scopes.
● Apps should revoke tokens when the user logs out.
○ Call the OAuth 2.0 token revocation method
● Apps should use refresh tokens for long-running sessions.
* This means mobile/desktop apps, CLIs, and JavaScript apps cannot provide OAuth/OIDC-authorized APIs.
16. Globus Transfer - App Access to Collections
• Globus Transfer – Authentication with access tokens
– Individual: Globus login (consents) to get tokens
– Application: Apps are people too!
o developers.globus.org - Client ID / Secret / Client Identity Username
• Collection access
– GCSv5 Mapped Collections (no user certificates, OAUTH tokens and consents)
o https://docs.globus.org/globus-connect-server/v5.4/use-client-credentials/
o Request the data_access scope (per collection) to be able to access the collection.
o The storage gateway must permit identities from the 'clients.auth.globus.org' identity
domain
o Identity Mapping Policy that maps the ‘UUID@clients.auth.globus.org' identity to a valid
local user
– Guest Collections
o Guest Collections auto-activate - need to do this before API calls to endpoints
o Use Guest Collections whenever possible
– Remember to set your ACLs (WebApp)
Automation
18. 20
Custom portals? Science Gateways? Unique workflows? Our open
REST APIs and Python SDK empower you to create an integrated
ecosystem of research data services and applications.
20. Globus APIs
• Auth
• Groups
• Transfer
• Search
• Timer
• Flows
• GCS Manager
• Globus Web App consumes public
Transfer API
• Resource named by URL (standard
REST approach)
• Globus APIs use JSON for documents
docs.globus.org/api/transfer
21. Globus Python SDK
• Python client library for the Globus REST APIs
• Largely direct mapping to REST API
• globus_sdk.TransferClient class handles
connection management, security, framing,
marshaling
globus-sdk-python.readthedocs.io/en/stable/
globus.github.io/globus-sdk-python
23
22. TransferClient low-level calls
• Thin wrapper around REST API
– post(), get(), update(), delete()
get(path, params=None, headers=None, auth=None,
response_class=None)
o path – path for the request, with or without leading slash
o params – dict to be encoded as a query string
o headers – dict of HTTP headers to add to the request
o response_class – class response object, overrides the client’s
default_response_class
o Returns: GlobusHTTPResponse object
24
23. TransferClient higher-level calls
• One method for each API resource
– Direct mapping
– Analogous to CLI commands
endpoint_search(filter_fulltext=None,
filter_scope=None,
num_results=25,
**params)
25
24. Synchronous Tasks
• Endpoint search (with scopes)
• List directory contents (ls)
• Make directory (mkdir)
• Rename
• Note:
– Path encoding & UTF gotchas
– Don’t forget to auto-activate first
26
25. Asynchronous Tasks
• Transfer
– Sync level option
• Delete
• Get submission_id, followed by submit
– Once and only once submission
• Use task id to “follow up”
27
26. The Globus API / SDK with a Jupyter Notebook in a
Jupyter Hub – Auth Code Grant
login
REST APIs
{ “tokens”:…
{“tokens”:…
REST APIs
REST APIs
Bearer a45cd…
27. Walkthrough API with our Jupyter Hub
• https://jupyter.demo.globus.org
– Sign in with Globus
– Verify the consents
– Start My Server (this will take about a minute)
– Open folder: globus-jupyter-notebooks
– Run Platform_Introduction_JupyterHub_Auth.ipynb
• If you mess it up and want to “go back to the beginning”
– Just stop and restart the server
• If you want to use the notebook outside of our hub
– https://github.com/globus/globus-jupyter-notebooks
– Authentication is a manual cut and paste of exchanging the
authorization code for an access token – Native App
29
28. Developer References
• Globus Documentation: docs.globus.org
• Globus API / SDK Documentation
– Transfer API : docs.globus.org/api/transfer/
– SDK: globus-sdk-python.readthedocs.io/en/stable/
• Globus GitHub: github.com/globus/
– Jupyter Notebooks
o Stand alone notebooks and hub integrations that walk through much of the
functionality of our SDK
o https://github.com/globus/globus-jupyter-notebooks
– Automation Examples
o Shell scripted CLI and Python module examples of common research data
management use cases
o https://github.com/globus/automation-examples