establish_tms_credentials()

establish_tms_credentials()#

establish_tms_credentials(tapis, system_id: str, username: str)

This function is run only the first time you connect to a specific system, such as Stampede3, on TACC.

The functions establish_tms_credentials and remove_tms_credentials help manage your Tapis system user credentials on a given system, like designsafe.storage.default or a specific compute resource.

They’re essential when you need to run jobs, transfer files, or otherwise authenticate to systems registered in Tapis using TMS_KEYS authentication (the typical model on DesignSafe).

This function ensures that the specified user (username) has valid system credentials set up on the specified system_id. It:

  1. Checks if credentials already exist

    • Calls tapis.systems.checkUserCredential.

    • If they exist, prints a message and exits.

  2. If credentials are missing:

    • It catches an UnauthorizedError.

    • Looks up the system definition using getSystem.

    • If the system uses TMS_KEYS as its default authentication, it calls createUserCredential to generate new TMS keys.

  3. Prints confirmation that the credentials are established.

Typical usage scenario#

  • You must have credentials on a system (like SSH keys or TMS managed keys) to submit jobs or move files.

  • This function automates creating those credentials if they’re missing, so your workflows don’t fail.

Smart handling#

  • Only creates new credentials if they don’t already exist.

  • Catches UnauthorizedError specifically, which is what Tapis raises when the user has no credentials on the system.

Managing Tapis system user credentials#

These two helper functions let you easily manage your credentials on a Tapis-registered system (like a storage system or compute resource).

Function

What it does

establish_tms_credentials

Ensures user credentials exist on a Tapis system (creates them if missing). Checks if the user already has credentials on the given system.
If missing, automatically creates new TMS keys (for systems using TMS_KEYS).

remove_tms_credentials

Removes user credentials from a Tapis system. Deletes the user’s credentials from the specified system. Useful for cleanup or resetting keys.

Typical workflow#

# Ensure credentials are set up before running jobs or moving files
establish_tms_credentials(tapis, system_id="designsafe.storage.default", username="jdoe")

# Later, if needed, clean up
remove_tms_credentials(tapis, system_id="designsafe.storage.default", username="jdoe")

This makes it easy to prepare (or reset) your access to Tapis systems from your scripts or notebooks, without having to manually generate or manage SSH/TMS keys.

Files#

You can find these files in Community Data.

establish_tms_credentials.py
def establish_tms_credentials(tapis, system_id: str, username: str):
    """
    Ensure that a user has valid TMS (Tapis Managed System) credentials on a given system.

    This function checks if the specified user already has credentials (such as TMS_KEYS) 
    registered on the specified Tapis system. If the credentials are missing, it 
    automatically establishes them (for systems that use TMS_KEYS authentication).

    This is essential for enabling file operations, data transfers, and job submissions
    that require user-level credentials on systems like DesignSafe storage.

    Parameters
    ----------
    tapis : Tapis
        An authenticated Tapis client (from connect_tapis()).

    system_id : str
        The ID of the Tapis-registered system (e.g. 'designsafe.storage.default').

    username : str
        The Tapis username for which to check or establish credentials.

    Returns
    -------
    None
        Prints status messages indicating whether credentials were found or established.

    Example
    -------
    establish_tms_credentials(
        tapis, 
        system_id='designsafe.storage.default', 
        username='smazzoni'
    )
    """
    # Silvia Mazzoni, 2025
    print(" -- TMS User Credentials --")
    """
    Check if user has system credentials on system.
    If not, it will set them.
    """
    from tapipy.errors import UnauthorizedError
    print('username:',username)
    print('system_id:',system_id)
    try:
        tapis.systems.checkUserCredential(systemId=system_id, userName=username)
        print(f"Found {username}'s system credentials.")
        return
    except UnauthorizedError:
        print(f"User {username} is missing system credentials.")
        print(f"Establishing new credentials")
        system_def = tapis.systems.getSystem(systemId=system_id)
        if system_def.get("defaultAuthnMethod") == "TMS_KEYS":
            tapis.systems.createUserCredential(
                systemId=system_id,
                userName=username,
                createTmsKeys=True,
            )
        print(f"Established {username}'s system credentials.")
    print('-- CREDENTIALS ESTABLISHED SUCCESSFULLY!!! --')
Contents