Login

Login Framework

Login utilities to simplify app development.
By: Shotgun Software
Latest Version: v1.2.2 (alpha)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-framework-login

Table of Contents:

Overview Summary

Documentation

            Class Login API Reference

                  get_instance_for_namespace()

                  Login Constructor

                  login()

                  logout()

            Class ShotgunLogin API Reference

                  get_login()

                  get_connection()

                  set_default_login()

                  set_default_site()

                  set_http_proxy()

Installation, Updates and Development

Configuration Options

Release Notes History

Overview

An interface for managing login information in a secure way along with a standard dialog to collect the information. Also includes an implementation for logging into Shotgun.

Documentation

The Login Framework implements a standard around managing authentication information to log into a service. It consists of an abstract base class (Login) that can be subclassed to manage logging into a specific service and an implementation to manage logins to a Shotgun instance (ShotgunLogin).

It also includes the following Dialog window.

This dialog is shown when the framework needs to collect the authentication information for the service being logged into. By default it is setup for a Shotgun login, but subclasses of Login can modify aspects of its appearance and behavior.

This framework is designed so that it can be used as a standard Toolkit framework or as a stand alone python module (without dependencies on the Toolkit Core). This allows it to be used as part of a bootstrap to locate and initialize a Toolkit environment.

Class Login API Reference

This is an abstract class that provides an abstraction over storing login information for a service. For each service it stores a site specification (for example the url to log into), a login (for example the username to log in with) and a password. The site and password are stored in a non-encrypted settings file, whereas the password is stored in an encrypted keyring, using operating specific implementations.

To use the interface you should simply be able to request the login info from an implementation:

    login_manager = LoginImplementation.get_instance_for_namespace("My Application")
    login_info = login_manager.login()

If the login info has already been collected, it will be returned. If the saved values successfully authenticate, then the resulting login info will be returned. Otherwise a dialog is shown to the user to collect site/login/password.

To subclass, you must at a minimum implement _site_connect, who should validate the connection information.

By default, the public settings are stored by Qt's QSettings, which will use the QApplication's applicationName and organizationName to figure out where to store the settings file. This can be overridden by implementing the _get_settings method in a subclass.

By default, the keyring used on the system will be named after the site (for example if logging into http://www.google.com, it would be "www.google.com.login") and the key would be the login being used. These defaults can be overridden by implementing the _get_keyring_values method in a subclass.

The default dialog that pops up can be overridden by changing the value of _dialog_class. The value of _dialog_kwargs will be passed to the dialog constructor. See the docs from login_dialog.LoginDialog for what the valid arguments are for the default dialog.

get_instance_for_namespace()

Class method that returns a Login instance for the given namespace. If the instance already exists it is returned. This acts as a factory to make it easy to reuse instances of a login manager.

Parameters & Return Value

  • str namespace - A string that acts as a lookup for the login manager.
  • Returns: Returns an instance of a login manager

    login_manager = get_instance_for_namespace("my-app")

Login Constructor

Initialize a login manager.

Login()

login()

Return the login info for the current authenticated login.

This will check saved values to see if there is a valid login cached. If no valid cached login information is found, a login dialog is displayed.

Parameters & Return Value

  • str site - The site to get the login for (None implies the default site)
  • str dialog_message - A message to display in the login dialog
  • bool force_dialog - If True, pop up the dialog even if some valid credentials are retrieved
  • Returns: None on failure and an implementation specific representation on success.

logout()

Log out of the current connection.

This will clear any cached values and the stored password

Parameters & Return Value

  • str site - The site to log out of (None implies the default site)

Class ShotgunLogin API Reference

Convenience wrapper around the Login class which implements managing a login for a Shotgun site. All methods from Login are available in addition to those documented here.

get_login()

Returns the HumanUser for the current login. Acts like login otherwise.

Parameters & Return Value

  • str site - The site to get the login for (None implies the default site)
  • str dialog_message - A message to display in the login dialog
  • bool force_dialog - If True, pop up the dialog even if some valid credentials are retrieved
  • Returns: None on failure and a Shotgun entity style dictionary for the logged in HumanUser on success.

get_connection()

Returns the connection for the current login. Acts like login otherwise

Parameters & Return Value

  • str site - The site to get the login for (None implies the default site)
  • str dialog_message - A message to display in the login dialog
  • bool force_dialog - If True, pop up the dialog even if some valid credentials are retrieved
  • Returns: None on failure and the Shotgun connection on success.

set_default_login()

Set the default value for the login field in the login dialog.

Parameters & Return Value

  • str login - A string to set the field to

set_default_site()

Set the default value for the site field in the login dialog.

Parameters & Return Value

  • str login - A string to set the field to

set_http_proxy()

Set the proxy to use when connecting to Shotgun.

Parameters & Return Value

  • str http_proxy - A string which will be passed to the Shotgun constructor as documented here: https://github.com/shotgunsoftware/python-api/wiki/Reference%3A-Methods#shotgun

Installation and Updates

Updating to the latest version

If you already have this item installed in a project and you want to get the latest version, you can run the update command. You can either navigate to the tank command that comes with that specific project, and run it there:

> cd /my_tank_configs/project_xyz
> ./tank updates

Alternatively, you can run your studio tank command and specify the project name to tell it which project to run the update check for:

> tank Project XYZ updates

Collaboration and Evolution

If you have access to the Shotgun Pipeline Toolkit, you also have access to the source code for all apps, engines and frameworks in Github where we store and manage them. Feel free to evolve these items; use them as a base for further independent development, make changes (and submit pull requests back to us!) or simply tinker with them to see how they have been built and how the toolkit works. You can access this code repository at https://github.com/shotgunsoftware/tk-framework-login.

Special Requirements

  • You need Shotgun Pipeline Toolkit Core API version v0.14.58 or higher to use this.

Configuration

No Configuration Needed!

This item does not have any options to configure!

Release Notes

Welcome to the release notes for this Framework. Below you will find an overview of all the changes we did for each release. We try to be as detailed as possible and include all bugs we have fixed, features we have added and things that may have changed. If you have questions about a particular release, don't hesitate to contact our support team!

v1.2.2

Fixed regressions in the Shotgun login dialog.

Details:

  • A custom message can now be displayed on the Shotgun login dialog.
  • Invoking the dialog a second time won't return immediately anymore.

v1.2.1

Added two factor authentication support for a Shotgun connection.

Details:

In order to use two factor authentication on your site, you need to be running Shotgun 6.1 or later and turn two factor authentication on.

v1.1.1

Full backward compatibility

Details:

In "no site" mode, same keyrings are used as before the "site" mode introduction.

v1.1.0

Ability to specify a target site in login framework

Details:

  • It is now possible to specify a target site when calling Login.login method.
  • If a site is specified, credentials for the given site will be retrieved and used.
  • If a site is not specified, the framework will fall back to previous behavior.
  • Keychain entry names are now set with the full server url, including protocol and port number, allowing to have multiple entries for the same server, but with different protocols or port numbers.

v1.0.6

Store instance cache so that it can be shared by the multiple framework instances that toolkit can create.

v1.0.5

Fix for storing cached values in memory.

v1.0.4

Better handling of retrieving creditials from within the same process if keyring fails.

v1.0.3

Fixes for KDE and when secure store for password is not available.

Details:

Now correctly uses KDE over Gnome in a KDE environment where python can access kwallet. Fixes for passing illegal encodings into the Shotgun API Continue without error when secure store is not allowed, simply do not save password

v1.0.2

More error handling on Windows if password store errors

v1.0.1

Fix for password delete error that can happen on Windows on logout

v1.0.0

Updated UI to fit with newer Shotgun designs

v0.1.4

Fix for error messages for the Shotgun login being shown as tuples

v0.1.3

Added ability to set default login and site for ShotgunLogin. Added support for proxy.

v0.1.2

Dialog layout update. Fix for using gnomekeyring on linux.

v0.1.1

New icon and doc fixes.

v0.1.0

Initial release.

Follow

0 Comments

Please sign in to leave a comment.