From 09997afd000b0a2c001efaba4d0ef4271cad1852 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Mon, 12 Jan 2026 15:28:56 -0600 Subject: [PATCH 1/7] Add documentation on using ClientApp User Guide docs now cover how to register a service account and use it. A new example demonstrates a `ClientApp`-powered `ls`. --- .../client_identities/index.rst | 35 +++++++ .../registering_a_client_identity.rst | 80 ++++++++++++++++ .../using_client_app/client_app_ls.py | 27 ++++++ .../using_client_app/index.rst | 96 +++++++++++++++++++ docs/user_guide/usage_patterns/index.rst | 1 + 5 files changed, 239 insertions(+) create mode 100644 docs/user_guide/usage_patterns/client_identities/index.rst create mode 100644 docs/user_guide/usage_patterns/client_identities/registering_a_client_identity.rst create mode 100644 docs/user_guide/usage_patterns/client_identities/using_client_app/client_app_ls.py create mode 100644 docs/user_guide/usage_patterns/client_identities/using_client_app/index.rst diff --git a/docs/user_guide/usage_patterns/client_identities/index.rst b/docs/user_guide/usage_patterns/client_identities/index.rst new file mode 100644 index 000000000..9b52ff6dc --- /dev/null +++ b/docs/user_guide/usage_patterns/client_identities/index.rst @@ -0,0 +1,35 @@ +.. _userguide_client_identities: + +Using Client Identities +======================= + +Clients registered in Globus can be used as "service accounts", +distinct actors with their own identities. +This is useful for a wide range of automation tasks, in which users want to +leverage Globus APIs, but without handling login flows and user credentials. + +To make use of Client Identities in this way, the client must be registered as a +"service account", capable of performing a *client credentials grant* to get +its tokens. +Once it is so registered, such a client will have an ID and secret, which can be +passed into interfaces in the SDK. +The client credentials (ID and secret) are used to get tokens to power +interactions with Globus APIs, and SDK tools will automatically cache and reload +these tokens appropriately. + +.. note:: + + In order to be used as a Client Identity, a client must have an ID and secret. + However, not every client with an ID and secret supports this usage! Clients + may be registered with various different OAuth2 grant types enabled, and some + clients have an ID and secret but are used to authenticate user logins! + + Put another way: having client credentials is *necessary but not sufficient* + for this kind of usage. + +.. toctree:: + :caption: Using Client Identities with the SDK + :maxdepth: 1 + + registering_a_client_identity + using_client_app/index diff --git a/docs/user_guide/usage_patterns/client_identities/registering_a_client_identity.rst b/docs/user_guide/usage_patterns/client_identities/registering_a_client_identity.rst new file mode 100644 index 000000000..ae641e03b --- /dev/null +++ b/docs/user_guide/usage_patterns/client_identities/registering_a_client_identity.rst @@ -0,0 +1,80 @@ +.. _userguide_register_client_identity: + +Registering a Client Identity +============================= + +In order to be used as a Client Identity or "service account", a client must +be registered in Globus Auth under the correct type. + +This is similar to the +:ref:`getting started documentation on registering an app `, +but using some different settings. + +Creating the Client Identity +---------------------------- + +The following steps will walk you through how to register a client for use as a +service account. +One topic not covered here is how to securely store and manage your secrets -- +the guidance below will simply say "save", and it is the user's responsibility +to decide how to save and secure these credentials. + +1. Navigate to the `Developer Site `_ + +2. Select "Register a service account or application credential for automation" + +3. Create or Select a Project + + * A project is a collection of apps with a shared list of administrators. + * If you don't own any projects, you will automatically be prompted to create one. + * If you do, you will be prompted to either select an existing or create a new one. + +4. Creating or selecting a project will prompt you for another login, sign in with an + account that administers your project. + +5. Give your App a name. This will appear as the identity's "name" where a + user's full name might appear. + +6. Click "Register App". This will create your app and take you to a page + describing it. + +7. Copy the "Client UUID" and save it -- this is your ``client_id`` in the + Python SDK's terms. + +8. Click "Add Client Secret", fill in the label, and save the secret -- this is + your ``client_secret`` in the Python SDK's terms. + + +Saving and Retrieving Client IDs and Secrets +-------------------------------------------- + +The Globus SDK does not offer special capabilities for storage and retrieval of +client IDs and client secrets. + +In examples in SDK documentation, you will see the client ID and secret written +as hardcoded constants, e.g. + +.. code-block:: python + + import globus_sdk + + CLIENT_ID = "YOUR ID HERE" + CLIENT_SECRET = "YOUR SECRET HERE" + + client = globus_sdk.ConfidentialAppAuthClient(CLIENT_ID, CLIENT_SECRET) + +You can replace those variables with sources of your choice. +For example, you could make them environment variables: + +.. code-block:: python + + import os + + CLIENT_ID = os.getenv("CLIENT_ID") + CLIENT_SECRET = os.getenv("CLIENT_SECRET") + + if not (CLIENT_ID and CLIENT_SECRET): + raise RuntimeError("CLIENT_ID and CLIENT_SECRET must both be set.") + +Selecting an appropriate storage and retrieval mechanism for client credentials +is considered a user responsibility by the SDK. diff --git a/docs/user_guide/usage_patterns/client_identities/using_client_app/client_app_ls.py b/docs/user_guide/usage_patterns/client_identities/using_client_app/client_app_ls.py new file mode 100644 index 000000000..a2766d864 --- /dev/null +++ b/docs/user_guide/usage_patterns/client_identities/using_client_app/client_app_ls.py @@ -0,0 +1,27 @@ +import globus_sdk + +# your client credentials +CLIENT_ID = "YOUR ID HERE" +CLIENT_SECRET = "YOUR SECRET HERE" + +# the ID of "tutorial collection 1" +TUTORIAL_COLLECTION = "6c54cade-bde5-45c1-bdea-f4bd71dba2cc" + +# create a ClientApp named "app" +with globus_sdk.ClientApp( + "sample-app", + client_id=CLIENT_ID, + client_secret=CLIENT_SECRET, + config=globus_sdk.GlobusAppConfig(token_storage="memory"), +) as app: + # create a TransferClient named "tc", bound to "app" + with globus_sdk.TransferClient(app=app) as tc: + + # because the tutorial collection is of a type which uses a `data_access` + # scope for fine grained access control, the `data_access` requirement needs + # to be registered with the app + tc.add_app_data_access_scope(TUTORIAL_COLLECTION) + + # iterate over the listing results, printing each filename + for entry in tc.operation_ls(TUTORIAL_COLLECTION, path="/home/share/godata"): + print(entry["name"]) diff --git a/docs/user_guide/usage_patterns/client_identities/using_client_app/index.rst b/docs/user_guide/usage_patterns/client_identities/using_client_app/index.rst new file mode 100644 index 000000000..7a97e529b --- /dev/null +++ b/docs/user_guide/usage_patterns/client_identities/using_client_app/index.rst @@ -0,0 +1,96 @@ +.. _userguide_using_client_app: + +Using a ClientApp with a Service Account +======================================== + +Once you have a client ID and secret from an app registration for a service +account, the SDK has a few tools which can use those credentials to acquire +tokens, to talk to various Globus Services. + +The easiest tool for this job is a ``ClientApp``, a flavor of ``GlobusApp`` +designed to work with service accounts. + +Instantiating a ClientApp +------------------------- + +Constructing an app takes three required parameters, + +- the name of the app for use in the SDK (this does not have to match your registered client name) +- the client ID +- the client secret + +as in: + +.. code-block:: python + + import globus_sdk + + CLIENT_ID = "YOUR ID HERE" + CLIENT_SECRET = "YOUR SECRET HERE" + + app = globus_sdk.ClientApp( + "sample-app", + client_id=CLIENT_ID, + client_secret=CLIENT_SECRET, + ) + +Using the App with a Globus Service +----------------------------------- + +The resulting app can then be passed to any SDK client class to create an API +client object which uses the app for authentication requirements. +For example, to use the ``app`` object to run an ``ls`` on one of the tutorial +collections: + +.. code-block:: python + + TUTORIAL_COLLECTION = "6c54cade-bde5-45c1-bdea-f4bd71dba2cc" + + with globus_sdk.TransferClient(app=app) as tc: + tc.add_app_data_access_scope(TUTORIAL_COLLECTION) + ls_result = tc.operation_ls(TUTORIAL_COLLECTION, path="/home/share/godata") + +.. note:: + + Unfortunately, there are two different meanings of the word "client" in use + in this example! + + A ``TransferClient`` is a "client" in the sense that it is a local object + which provides access to the Globus Transfer Service. + The ``CLIENT_ID``, ``CLIENT_SECRET``, and ``ClientApp`` are all using the + word "client" in reference to the OAuth2 standard's definition of a "client" + as a registered app, a different meaning for the same word. + +Using Memory Storage +-------------------- + +Unlike user logins, client credentials can't be "logged out" vs "logged in" -- +unless they are deleted via the Globus Auth service, they are always active. + +As a result, unlike applications which provide user logins, ``ClientApp``\s will +very often prefer to store any tokens they are using in memory. The tokens will +be cached and reused over the lifetime of the process, but never persisted to +disk. + +To configure an app in this way, simply add a ``config`` to the app +initialization to select the ``"memory"`` storage type: + +.. code-block:: python + + app = globus_sdk.ClientApp( + "sample-app", + client_id=CLIENT_ID, + client_secret=CLIENT_SECRET, + config=globus_sdk.GlobusAppConfig(token_storage="memory"), + ) + +Complete Example +---------------- + +In addition to leveraging all of the elements described above, this example enhances the code sample to +use the ``ClientApp``'s context manager interface to close token storage. +We also add a loop of ``print()`` usages on the ``ls`` result to show some output: + +.. literalinclude:: client_app_ls.py + :caption: ``client_app_ls.py`` [:download:`download `] + :language: python diff --git a/docs/user_guide/usage_patterns/index.rst b/docs/user_guide/usage_patterns/index.rst index 77bf590f4..77efc5bdd 100644 --- a/docs/user_guide/usage_patterns/index.rst +++ b/docs/user_guide/usage_patterns/index.rst @@ -29,3 +29,4 @@ transfers. data_transfer/index sessions_and_consents/index + client_identities/index From 565745816ac7f523585cbbba70199a81893602aa Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Tue, 13 Jan 2026 21:39:38 -0600 Subject: [PATCH 2/7] Apply suggestions from code review Co-authored-by: derek-globus <113056046+derek-globus@users.noreply.github.com> --- docs/user_guide/usage_patterns/client_identities/index.rst | 4 ++-- .../client_identities/using_client_app/index.rst | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/user_guide/usage_patterns/client_identities/index.rst b/docs/user_guide/usage_patterns/client_identities/index.rst index 9b52ff6dc..b087f26b7 100644 --- a/docs/user_guide/usage_patterns/client_identities/index.rst +++ b/docs/user_guide/usage_patterns/client_identities/index.rst @@ -3,7 +3,7 @@ Using Client Identities ======================= -Clients registered in Globus can be used as "service accounts", +Some clients registered in Globus may operate as independent "service accounts", distinct actors with their own identities. This is useful for a wide range of automation tasks, in which users want to leverage Globus APIs, but without handling login flows and user credentials. @@ -14,7 +14,7 @@ its tokens. Once it is so registered, such a client will have an ID and secret, which can be passed into interfaces in the SDK. The client credentials (ID and secret) are used to get tokens to power -interactions with Globus APIs, and SDK tools will automatically cache and reload +interactions with Globus APIs, and SDK's GlobusApp will automatically cache and reload these tokens appropriately. .. note:: diff --git a/docs/user_guide/usage_patterns/client_identities/using_client_app/index.rst b/docs/user_guide/usage_patterns/client_identities/using_client_app/index.rst index 7a97e529b..1d7ef62ab 100644 --- a/docs/user_guide/usage_patterns/client_identities/using_client_app/index.rst +++ b/docs/user_guide/usage_patterns/client_identities/using_client_app/index.rst @@ -15,7 +15,8 @@ Instantiating a ClientApp Constructing an app takes three required parameters, -- the name of the app for use in the SDK (this does not have to match your registered client name) +- a human readable name to identify your app in HTTP requests and token caching (e.g., “My Cool Weathervane”). + - this does not need match the name you supplied during client registration. - the client ID - the client secret From 1d2881fe0be5591d0bbdb69caeb2b2bce180b40a Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Wed, 14 Jan 2026 10:15:11 -0600 Subject: [PATCH 3/7] Rename the 'Service Accounts' user guide section To follow our structure of concept/noun naming for the categories in the usage patterns section. --- docs/user_guide/usage_patterns/index.rst | 2 +- .../index.rst | 26 ++++++++++--------- .../registering_a_service_account.rst} | 10 +++---- .../using_client_app/client_app_ls.py | 0 .../using_client_app/index.rst | 2 +- 5 files changed, 21 insertions(+), 19 deletions(-) rename docs/user_guide/usage_patterns/{client_identities => service_accounts}/index.rst (58%) rename docs/user_guide/usage_patterns/{client_identities/registering_a_client_identity.rst => service_accounts/registering_a_service_account.rst} (93%) rename docs/user_guide/usage_patterns/{client_identities => service_accounts}/using_client_app/client_app_ls.py (100%) rename docs/user_guide/usage_patterns/{client_identities => service_accounts}/using_client_app/index.rst (98%) diff --git a/docs/user_guide/usage_patterns/index.rst b/docs/user_guide/usage_patterns/index.rst index 77efc5bdd..792e1c3fe 100644 --- a/docs/user_guide/usage_patterns/index.rst +++ b/docs/user_guide/usage_patterns/index.rst @@ -29,4 +29,4 @@ transfers. data_transfer/index sessions_and_consents/index - client_identities/index + service_accounts/index diff --git a/docs/user_guide/usage_patterns/client_identities/index.rst b/docs/user_guide/usage_patterns/service_accounts/index.rst similarity index 58% rename from docs/user_guide/usage_patterns/client_identities/index.rst rename to docs/user_guide/usage_patterns/service_accounts/index.rst index b087f26b7..230a9640b 100644 --- a/docs/user_guide/usage_patterns/client_identities/index.rst +++ b/docs/user_guide/usage_patterns/service_accounts/index.rst @@ -1,16 +1,18 @@ -.. _userguide_client_identities: +.. _userguide_service_accounts: -Using Client Identities -======================= +Service Accounts +================ Some clients registered in Globus may operate as independent "service accounts", distinct actors with their own identities. -This is useful for a wide range of automation tasks, in which users want to -leverage Globus APIs, but without handling login flows and user credentials. - -To make use of Client Identities in this way, the client must be registered as a -"service account", capable of performing a *client credentials grant* to get -its tokens. +These are also referred to as "client identities" because the actor in question +is the client itself. +Service accounts useful for a wide range of automation tasks, in which users +want to leverage Globus APIs, but without handling login flows and user +credentials. + +To make use of clients in this way, the client must be registered as a Service +Account, capable of performing a *client credentials grant* to get its tokens. Once it is so registered, such a client will have an ID and secret, which can be passed into interfaces in the SDK. The client credentials (ID and secret) are used to get tokens to power @@ -19,7 +21,7 @@ these tokens appropriately. .. note:: - In order to be used as a Client Identity, a client must have an ID and secret. + In order to be used as a Service Account, a client must have an ID and secret. However, not every client with an ID and secret supports this usage! Clients may be registered with various different OAuth2 grant types enabled, and some clients have an ID and secret but are used to authenticate user logins! @@ -28,8 +30,8 @@ these tokens appropriately. for this kind of usage. .. toctree:: - :caption: Using Client Identities with the SDK + :caption: Using Service Accounts with the SDK :maxdepth: 1 - registering_a_client_identity + registering_a_service_account using_client_app/index diff --git a/docs/user_guide/usage_patterns/client_identities/registering_a_client_identity.rst b/docs/user_guide/usage_patterns/service_accounts/registering_a_service_account.rst similarity index 93% rename from docs/user_guide/usage_patterns/client_identities/registering_a_client_identity.rst rename to docs/user_guide/usage_patterns/service_accounts/registering_a_service_account.rst index ae641e03b..5faf5ae9c 100644 --- a/docs/user_guide/usage_patterns/client_identities/registering_a_client_identity.rst +++ b/docs/user_guide/usage_patterns/service_accounts/registering_a_service_account.rst @@ -1,17 +1,17 @@ -.. _userguide_register_client_identity: +.. _userguide_register_service_account: -Registering a Client Identity +Registering a Service Account ============================= -In order to be used as a Client Identity or "service account", a client must +In order to be used as a Service Account or "Client Identity", a client must be registered in Globus Auth under the correct type. This is similar to the :ref:`getting started documentation on registering an app `, but using some different settings. -Creating the Client Identity ----------------------------- +Creating the Client +------------------- The following steps will walk you through how to register a client for use as a service account. diff --git a/docs/user_guide/usage_patterns/client_identities/using_client_app/client_app_ls.py b/docs/user_guide/usage_patterns/service_accounts/using_client_app/client_app_ls.py similarity index 100% rename from docs/user_guide/usage_patterns/client_identities/using_client_app/client_app_ls.py rename to docs/user_guide/usage_patterns/service_accounts/using_client_app/client_app_ls.py diff --git a/docs/user_guide/usage_patterns/client_identities/using_client_app/index.rst b/docs/user_guide/usage_patterns/service_accounts/using_client_app/index.rst similarity index 98% rename from docs/user_guide/usage_patterns/client_identities/using_client_app/index.rst rename to docs/user_guide/usage_patterns/service_accounts/using_client_app/index.rst index 1d7ef62ab..34f7755fb 100644 --- a/docs/user_guide/usage_patterns/client_identities/using_client_app/index.rst +++ b/docs/user_guide/usage_patterns/service_accounts/using_client_app/index.rst @@ -15,7 +15,7 @@ Instantiating a ClientApp Constructing an app takes three required parameters, -- a human readable name to identify your app in HTTP requests and token caching (e.g., “My Cool Weathervane”). +- a human readable name to identify your app in HTTP requests and token caching (e.g., "My Cool Weathervane"). - this does not need match the name you supplied during client registration. - the client ID - the client secret From a75751cb008b4605cd7fabcfb6c2858b4fdd4c70 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Wed, 14 Jan 2026 11:50:03 -0600 Subject: [PATCH 4/7] Add disambiguation to Service Accounts doc This new section is meant to make it clearer what a Client is, and that the term has two different meanings from two different domains. --- .../usage_patterns/service_accounts/index.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/user_guide/usage_patterns/service_accounts/index.rst b/docs/user_guide/usage_patterns/service_accounts/index.rst index 230a9640b..01e102a84 100644 --- a/docs/user_guide/usage_patterns/service_accounts/index.rst +++ b/docs/user_guide/usage_patterns/service_accounts/index.rst @@ -29,6 +29,25 @@ these tokens appropriately. Put another way: having client credentials is *necessary but not sufficient* for this kind of usage. + +Disambiguation: "Clients" vs "Client Identities" vs "Service Accounts" +---------------------------------------------------------------------- + +There are two different meanings for the word "client", from different domains. + +Conventionally, a library's adapter for a web API is a "client". +In the SDK, we primarily use the word "client" to refer to these API connectors, +as in ``TransferClient``, ``GroupsClient``, etc. + +OAuth2 calls an application registered with the service a "client". +A "Client Identity" is a Globus Auth concept which uses this meaning of +"client". + +As a result of this ambiguity, this documentation will prefer to refer to +"Client Identities" as "Service Accounts", which is the term which is used in +other Globus documentation and the web interface. + + .. toctree:: :caption: Using Service Accounts with the SDK :maxdepth: 1 From 371a20f6e6e4f6cd69869a78de868727327b5f85 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Wed, 14 Jan 2026 17:52:04 -0600 Subject: [PATCH 5/7] Introduce 'Understanding Service Accounts' doc --- .../usage_patterns/service_accounts/index.rst | 49 ++------------ .../understanding_service_accounts.rst | 67 +++++++++++++++++++ 2 files changed, 72 insertions(+), 44 deletions(-) create mode 100644 docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst diff --git a/docs/user_guide/usage_patterns/service_accounts/index.rst b/docs/user_guide/usage_patterns/service_accounts/index.rst index 01e102a84..c82384307 100644 --- a/docs/user_guide/usage_patterns/service_accounts/index.rst +++ b/docs/user_guide/usage_patterns/service_accounts/index.rst @@ -3,54 +3,15 @@ Service Accounts ================ -Some clients registered in Globus may operate as independent "service accounts", -distinct actors with their own identities. -These are also referred to as "client identities" because the actor in question -is the client itself. -Service accounts useful for a wide range of automation tasks, in which users -want to leverage Globus APIs, but without handling login flows and user -credentials. - -To make use of clients in this way, the client must be registered as a Service -Account, capable of performing a *client credentials grant* to get its tokens. -Once it is so registered, such a client will have an ID and secret, which can be -passed into interfaces in the SDK. -The client credentials (ID and secret) are used to get tokens to power -interactions with Globus APIs, and SDK's GlobusApp will automatically cache and reload -these tokens appropriately. - -.. note:: - - In order to be used as a Service Account, a client must have an ID and secret. - However, not every client with an ID and secret supports this usage! Clients - may be registered with various different OAuth2 grant types enabled, and some - clients have an ID and secret but are used to authenticate user logins! - - Put another way: having client credentials is *necessary but not sufficient* - for this kind of usage. - - -Disambiguation: "Clients" vs "Client Identities" vs "Service Accounts" ----------------------------------------------------------------------- - -There are two different meanings for the word "client", from different domains. - -Conventionally, a library's adapter for a web API is a "client". -In the SDK, we primarily use the word "client" to refer to these API connectors, -as in ``TransferClient``, ``GroupsClient``, etc. - -OAuth2 calls an application registered with the service a "client". -A "Client Identity" is a Globus Auth concept which uses this meaning of -"client". - -As a result of this ambiguity, this documentation will prefer to refer to -"Client Identities" as "Service Accounts", which is the term which is used in -other Globus documentation and the web interface. - +"Service Accounts" or "Client Identities" (the terms are synonymous) are +automated users which authenticate with Globus via client credentials. +Using this type of credential allows for automated usage of Globus services +which does not rely on user interaction or login flows. .. toctree:: :caption: Using Service Accounts with the SDK :maxdepth: 1 + understanding_service_accounts registering_a_service_account using_client_app/index diff --git a/docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst b/docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst new file mode 100644 index 000000000..7be3f2a2e --- /dev/null +++ b/docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst @@ -0,0 +1,67 @@ +.. _userguide_understanding_service_accounts: + +Understanding Service Accounts +============================== + +Some clients registered in Globus may operate as independent "service accounts", +distinct actors with their own identities. +These are also referred to as "client identities" because the actor in question +is the client itself. +Service accounts useful for a wide range of automation tasks, in which users +want to leverage Globus APIs, but without handling login flows and user +credentials. + +Service Accounts are Clients +---------------------------- + +To create a service account, users must register a new Globus Auth client as +a Service Account, capable of performing a *client credentials grant* to get +its tokens. +Once it is so registered, such a client will have an ID and secret, which can be +passed into interfaces in the SDK. + +The client credentials (ID and secret) are used to get tokens to power +interactions with Globus APIs, and SDK's :class:`globus_sdk.GlobusApp` and +:class:`globus_sdk.ClientCredentialsAuthorizer` will automatically cache and +reload these tokens appropriately. + +.. note:: + + In order to be used as a Service Account, a client must have an ID and secret. + However, not every client with an ID and secret supports this usage! Clients + may be registered with various different OAuth2 grant types enabled, and some + clients have an ID and secret but are used to authenticate user logins! + + Put another way: having client credentials is *necessary but not sufficient* + for this kind of usage. + + +Disambiguation: "Clients" vs "Client Identities" vs "Service Accounts" +---------------------------------------------------------------------- + +There are two different meanings for the word "client", from different domains. + +Conventionally, a library's adapter for a web API is a "client". +In the SDK, we primarily use the word "client" to refer to these API connectors, +as in ``TransferClient``, ``GroupsClient``, etc. + +OAuth2 calls an application registered with the service a "client". +A "Client Identity" is a Globus Auth concept which uses this meaning of +"client". + +As a result of this ambiguity, this documentation will prefer to refer to +"Client Identities" as "Service Accounts", which is the term which is used in +other Globus documentation and the web interface. + + +Service Account Permissions +--------------------------- + +Service Accounts have their own assigned identities, group memberships, and +permissions within Globus. +They are not implicitly linked in any way to the user who created them, or the +administrators who manage them. +Their permissions are isolated. + +Users of Service Accounts need to separately assign permissions to these +identities, depending on what resources the client is meant to access. From 7f1b9fed0002065b5dd252d01432eaf636f9d69a Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Thu, 22 Jan 2026 11:33:02 -0600 Subject: [PATCH 6/7] Update docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst Co-authored-by: derek-globus <113056046+derek-globus@users.noreply.github.com> --- .../service_accounts/understanding_service_accounts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst b/docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst index 7be3f2a2e..3105168bf 100644 --- a/docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst +++ b/docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst @@ -7,7 +7,7 @@ Some clients registered in Globus may operate as independent "service accounts", distinct actors with their own identities. These are also referred to as "client identities" because the actor in question is the client itself. -Service accounts useful for a wide range of automation tasks, in which users +Service accounts are useful for a wide range of automation tasks, in which users want to leverage Globus APIs, but without handling login flows and user credentials. From 92e0fb94d9e24373cd1e528c3ce155d7c03d7f14 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Thu, 22 Jan 2026 13:54:35 -0600 Subject: [PATCH 7/7] Add 'conflicts' section to Service Accounts doc --- .../understanding_service_accounts.rst | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst b/docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst index 3105168bf..87b4bb08d 100644 --- a/docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst +++ b/docs/user_guide/usage_patterns/service_accounts/understanding_service_accounts.rst @@ -65,3 +65,62 @@ Their permissions are isolated. Users of Service Accounts need to separately assign permissions to these identities, depending on what resources the client is meant to access. + + +Policies Which Conflict With Service Accounts +--------------------------------------------- + +A number of the configurable policies on Globus resources conflict with use of +Service Accounts. +Users often find that they cannot substitute Service Accounts for their own +credentials without also adapting their workflows or configurations to support +this usage. + +In particular, users should be aware of the following classes of issues, and +potential workarounds. + +Identity-specific Permissions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Because clients are not associated with their owners, identity-specific +permissions for users can't be directly "shared" with their clients. + +If your account has permissions to access a resource, but you wish to use a +Service Account to interact with it, add a second permission to give the Service +Account access as well. + +Domain Requirements +~~~~~~~~~~~~~~~~~~~ + +Resources may apply policies which require a specific domain for users. +For example, a University of Chicago Collection may require ``uchicago.edu`` +usernames. + +Service Accounts have a fixed domain of ``clients.auth.globus.org`` and +therefore cannot satisfy these requirements. + +Use user-specific access policies or permissions delegation features, like Guest +Collections, to allow Service Accounts to specifically access resources. + +Session Timeouts +~~~~~~~~~~~~~~~~ + +Globus resources may configure authentication timeouts, forcing users to +reauthenticate within a fixed time window to use a resource. +This is done by checking the Globus Auth session associated with the user's +tokens for last authentication times. + +For example, a Collection may require that users have logged in within the last +hour to access data -- this is part of the suite of features for High Assurance +data access. + +A Service Account authenticates each time it fetches a token, but does not have +a Globus Auth session associated with those authentications. (There is no +browser session interaction in such cases.) +As such, a Service Account cannot satisfy these policies under a naive +interpretation. + +Globus Connect Server implements a special rule to handle this case: session +timeouts are never enforced on Service Accounts. +Other services may implement similar policies or require that access to Service +Accounts be configured separately from regular user permissions.