API Version: Development

Getting Started

/

Javascript API

/

Authentication

   
  • Authentication
  • Session Authentication
  • Identify desired IPCortex CS
  • Authentication via "pop-up"
  • Authentication options list
  • Using 'External' users
  • Using authentication sub-IDs
  • Logout / Clean-up
  • Logout only
  • Clean-up only
  • Full logout
  • Detecting a logout

    • Authentication

    There are two main authentication mechanisms that you may use to authenticate against an API host.
    1. Session Authentication: allows you to perform a user interactive login (with the option to persistently remember the login state for this client) and then preserve the login state via cookie or session token in order to perform multiple actions over an extended period of time.
    2. API Keys: allow non-interactive applications to present a key which entitles them to perform stateless transactions with the same permissions as a specific user, without needing access to that user's login credentials. API keys are only generally useful for REST calls and are documented with the REST API.
    SEE ALSO: Authentication methods

    Session Authentication

    This consists of two steps: identifying the hostname of the IPCortex Communication System (CS) that you intend to access and then using either the "pop-up" based user authentication mechanism, or legacy username and password that you have collected from the user yourself.

    Identify desired IPCortex CS

    The first thing that any application which isn't hosted from the appliance must do is to set the hostname and method of the target API host.
    NOTE: For many features (e.g. any WebRTC use, use of authentication tokens) it is necessary for the API communication to use an HTTPS URL to a host with a valid certificate installed. Even where you do not intend to use features that require HTTPS, it is strongly recommended that it is always used and HTTP access is provided for the benefit of legacy applications only
    IPCortex.PBX.Auth.setHost('https://pabx.host.name');

    Authentication via "pop-up"

    The recommended mechanism presents a login overlay, served from the API host, on your current web page and prompts the user to supply their credentials directly to the API host if necessary:
    popup screenshot
    If a user is logged-on, or has been authorised to remain logged-on and the authority has not expired, then the Promise resolves immediately without user interaction. Otherwise a login "pop-up" is presented, into which the user may enter credentials. The Promise will then resolve or reject depending on the result of the login.
    NOTE: This mechanism stores and tracks an API Token, allowing the login to persist beyond the lifetime of the session cookie. Token expiry is set based on the application origin and defaults to 1 day.
    IPCortex.PBX.Auth.login(options).then(successFn, failFn)

    Authentication options list

    Note: options may be null or unset.
    Field Type Description
    checkonly BOOL If true, login prompt is not displayed. The login succeeds or fails based on the current login state and any saved tokens that are still valid. All other options will be ignored if this is set.
    username
    password    		 String If username/password are both provided, they will be used to log in and (optionally) generate a token to reconnect an expired session.
    notoken BOOL If true, and combined with a username/password, will log in, but not generate a token.
    nodom BOOL If true, the IFRAME and popup login will not be used, even if a window object exists. Tokens will not be cached and re-used automatically across sessions.
    subid String If set, all subsequent API calls will be qualified with this token so if you need to log in from two browser tabs independently, set a unique value for each tab. NOTE: Only applies to calls made via the API library, so use API rest calls rather than your own REST requests. See also: IPCortex.PBX.Auth.getSubID()
    application String Allows for per-application token permissions to be granted. Not currently user-editable. Has no effect unless using tokens. Valid values:
    • null/blank - causes a token login to be valid for 24 hours, but then forces a logout.
    • refreshable - will keep a token login alive as long as it is used once per day.
    • longLogin - will keep a token login alive as long as it is used once a week.
    tokens String[] If set, try to use provided token(s) to activate or continue an existing login session. Ignored if a username/password are both provided, or if checkonly is true.
    origin String (Optional) Override the origin being logged-in to. Defaults to the parent app's URL. 6.3.10+
    tokenCB function If set, will be called-back with the current live 'tokens' as keys of an object with epiiry times as the data.

    Using 'External' users

    See the REST API documentaion for details of creating and modifying 'external' and/or 'temporary' users.
    Logging in as an 'External' user is essentially the same as any other user with the following adjustments/adaptations:
    • By default a temporary/external user will be deleted 15 minutes after creation if unused.
    • By default a temporary/external user will be deleted shortly after logout (see autodelete: bool setting)
    • An 'External' user is a single-use login. If logged-out or timed-out it must be modified or re-created.
    • An 'External' user's login name is a long auto-generated string.
    • An 'External' user has no password - A 'dummy' password must be provided on login as blank passwords will not be accepted.
    The most significant difference in an 'External' user is that they can play no part in the flow of PABX calls, and can have no user or administrative access to the PABX interface. They may access a limited subset of the API facilities, most notably thay can be used with the Chat, Av and File mechanisms.

    Using authentication sub-IDs

    A common issue with web browsers is that using session cookies, a login session may bleed across between browser tabs causing authentication issues. As long as the API library is used for all calls, this can be resolved with the IPCortex.PBX.Auth.getSubID() call.

    Logout / Clean-up

    There are 3 possible options when logging out, depending on the scenario.
    • Just log out, do not clean up.
    • Just clean up, do not log out.
    • Both logout and clean-up.

    Logout only

    Most useful if it is known that the application is about to exit and only a very lightweight logout is needed.
    IPCortex.PBX.Auth.logout()

    Clean-up only

    Often used in a browser context where the page might be being refreshed. Flushes any enabled feature data down to the PABX (eg. Call History, Settings) that has not already been written, marks Chat as offline, and flushes any data loaded for the currently logged-in user.
    IPCortex.PBX.Auth.exit()

    Full logout

    This is necessary if the application will keep running, but it may be necessary to log in as another user later.
    IPCortex.PBX.Auth.exit({logout: true})

    Detecting a logout

    An application that uses no live data will not be notified of a login expiring. It will be necessary to either call a checkonly login to be sure of the current state, or attempt the API operation and see if it fails. Only operations that communicate to the PABX will fail. The IPCortex.PBX.Auth properties will be updated occasionally (hourly) unless an active login/logout event occurs to update it more quickly.
    An application that uses live data will have called IPCortex.PBX.startFeed() (see here), which takes an optional 2nd parameter to provide an error-callback. If the user is logged-out, then this callback is called with a errno of 2. The IPCortex.PBX.Auth properties will be updated quickly (perhaps 1 minute at worst).