Handling profiles and related errors

When using profiles in Zowe Explorer, API calls may sometimes fail with an authentication error. In the event of an authentication error, use the AuthHandler class exposed in Zowe Explorer API (v3.1.0 and above) to lock a profile and prevent further use. Once the profile is re-authenticated, the profile is unlocked and can be used again.

While we recommend using the locking mechanism for profiles, this is an opt-in implementation and profiles can still be used without the locks. However, as the advantages of the locking mechanism outweigh the downsides of not using it, extenders should consider adopting it when necessary. The filesystem currently leverages the locks, so the locking mechanism is not needed when interfacing with Zowe Explorer's FileSystemProvider resources.

Benefits

• Avoids mainframe lockouts by waiting for a profile to be "unlocked" (available) before continuing
• Allows extenders to prompt a user to re-authenticate their profile in event of a 401/authentication error
• Attempts to synchronize profile status between extenders by preventing repeated calls when a profile was used with invalid credentials

Opting in to locks for a profile type

By default, profiles with type zosmf use the locking mechanism. This avoids API calls with invalid credentials, which can occur during asynchronous event/request processing (such as actions fired by VS Code within our filesystem providers).

To opt-in to locks for a specific profile type, call the AuthHandler.enableLocksForType function with the profile type as the parameter:

AuthHandler.enableLocksForType("your-custom-type");

Locking profiles before API calls

We recommend that extenders call the AuthHandler.lockProfile function before making a request with a specific profile. After the operation is completed, call the AuthHandler.unlockProfile function to allow the profile to be used outside of the current context.

await AuthHandler.lockProfile("lpar1.zosmf");
// ... make the API call, then unlock the profile
AuthHandler.unlockProfile("lpar1.zosmf");

Note that AuthHandler.lockProfile is blocking and waits for the lock to be available if it is currently in use. Extenders should ensure that a profile is unlocked after the desired API calls are handled for a profile, so that the profile can be used elsewhere (either by Zowe Explorer or another extender).

Extenders can pass true for the second parameter of AuthHandler.unlockProfile to update "active resources" after unlocking the profile (such as virtual workspaces or active text editors).

Prompt users to authenticate a profile

If an authentication error occurs after locking the profile, call the AuthHandler.promptForAuthentication method with the respective login methods (promptCredentials and ssoLogin) to prompt the user to re-authenticate their profile. Once the profile has been re-authenticated, the profile is unlocked and can be used again.

await AuthHandler.promptForAuthentication(err, profile, {
    // This parameter supports a ProfilesCache instance or individual callbacks
    authMethods: Constants.PROFILES_CACHE
});

Checking whether a profile is locked

Call the AuthHandler.isProfileLocked function with a profile (either an imperative.IProfileLoaded object or the profile name) to determine whether a profile is locked. The function returns true when the profile is locked and returns false otherwise.

Extenders can call this function to check whether the profile is available before trying to acquire the lock. This prevents busy waiting for the lock, which helps when an extender wants to perform an action with a profile without waiting for the profile to be available.

Checking if a profile uses token-based authentication

To determine whether a profile uses token-based authentication, call the AuthHandler.isUsingTokenAuth method with the service profile's secure properties and the base profile's secure properties.

The function returns true if:

• The service profile's secure properties contains a tokenValue and does not contain user and password
• The base profile's secure properties contains a tokenValue

If either of these conditions are not met, the function returns false.

Detecting when a profile has been updated

If a profile was re-authenticated through Zowe Explorer, the ZoweVsCodeExtension.onProfileUpdated event is fired with the updated profile object. This allows extenders to subscribe to profile changes and proceed forward once a specific profile was successfully re-authenticated.

Subscribe to the ZoweVsCodeExtension.onProfileUpdated event to detect changes to profile credentials:

ZoweVsCodeExtension.onProfileUpdated(async (profile) => {
    Gui.showMessage(`Profile updated: ${profile.name}`);
})