CoT Login

Introduction

This document was written for CoreJs Version: v9.1.0

CoT Login (cot_login.js) is the login module that handles your session and implements helper functions to authenticate a user. The cot_login object can be used to show the login window, after the user logs in successfully you can retrieve user's login information. A successful login returns an SID (session ID) which can be used until it is valid.

Functionalities:

• With CoT Login you can specify which endpoint you want to authenticate against after you have authenticated a SID is returned. Your application can use this SID to make request on API that require authorization. 
• Note: There are three login in APIs
  1. session api
  2. DataAccess
  3. DataAccessV2
• Login UI - Has a default login UI implementation which can be used for user to enter username and password and login.
• CoT Login does other behind the scene work for session management
• CoT Login Uses CoT session (cot_session.js) to manage the session
  1. When you make a successful login request the session object will be set
  2. This session will be valid for 30 minutes by default
  3. When you make the next login request it will update the session on the server side but it doesn't update the session time on the clientside

How To Use

Before you begin:

1. Determine what type of Login configuration you want
2. You need a City Of Toronto login or use one of the test accounts below (for session API only) Here you have few options:
   If you are using the Session API you can use these two accounts:
   testweb1/toronto
   testweb2/toronto
   If you are using the Auth API:
   You can use your own City of Toronto Novel account to login and logout.
   

   AuthAPI v1(https://was-inter-sit.toronto.ca/cc_sr_v1/session) used devldap.toronto.ca
   user ‘testweb1’ is on DEVLDAP
   AuthAPI v2(https://was-intra-sit.toronto.ca/c3api_auth/auth?) used  identldap.toronto.ca
   which use real LDAP account (Novel ID).
   

3. You want to have an API that requires "staff" access. This is one of the reasons why you are implementing login.
4. If you are going to be uploading a file and retrieving files stick with Session API for login. The SID returned from this API will work with other older C3 APIs (aka Upload).

Login Configuration

When you create a cot_login you can pass in configuration options. This is where you can specify which endpoint to use since these are passed in to cot_session to establish your session. Essentially you are making a cot_login object and this object is creating a cot_session object. When you invoke the _login function of cot_login then the cot_session object makes a call to the back end API with your username, password, and if it is successful a cookie is created with your SID. In all other future request this SID can be passed to the back end to allow your application to access (staff/protected) APIs.

Here are the configuration options in cot_login

this.options = $.extend(
    {
      appName: '', //Required, the name of your app, this will be sent to the CC AuthSession API call to login
      ccRoot: '', //Optional, defaults to '' (the current protocol and domain will be used), use this to specify the <protocol>:://<domain> to use for the CC AuthSession API call
      ccPath: '', //Optional, when specified, this overrides the ccApiPath option of CotSession
      ccEndpoint: '', //Optional, when specified, this overrides the ccApiEndpoint option of CotSession
      welcomeSelector: '', //Optional, a jquery selector string for the element where the login/logout information should be displayed
      loginMessage: '', //Optional, an HTML string to display on the login form, this can be used to explain to the user why they are logging in
      onLogin: function(cot_login_instance) {
        //Optional, a function that will be called after the user logs in successfully
      }
    },
    options || {}
  );

Here is an example of login configuration taken from the Intake app. Many different apps and developer might have different approaches to how to use login.

function initLogin() {
    function onLogin() {
      if (config.logoutFlag) {
        document.location.reload();
      }
    }
    // Login options
    const loginOpt = {
      appName: config.APPNAME,
      welcomeSelector: '#loginButton',
      ccRoot: config.CC_ROOT_LOGIN,
      ccPath: '/cc_sr_admin_v1/',
      ccEndpoint: 'session',
      onLogin: onLogin
    };
    // Initialize login
    $('.securesite').after(
      '<div id="loginButton" class="col-xs-12 text-right"></div>'
    );
    return new cot_login(loginOpt);
  }

Once you have a login object you can get the session and sid form there.

headers: {
            'Authorization': 'AuthSession ' + myLoginObject.session.sid
          },