# Modules.WebDialog.AuthenticationSession

Authenticate a user with a web service, even if the web service is run by a third party.

Availability

7.1.0

Extends

# Overview

The AuthenticationSession puts the user in control of whether they want to use their existing logged-in session from Safari. The app provides a URL that points to the authentication webpage. The page will be loaded in a secure view controller. From the webpage, the user can authenticate herself and grant access to the app. On completion, the service will send a callback URL with an authentication token, and this URL will be passed to the app by the callback.

The callback URL usually has a custom URL scheme. For the app to receive the callback URL, it needs to either register the custom URL scheme in its Info.plist, or set the scheme to scheme argument in the initializer.

If the user has already logged into the web service in Safari or other apps via the AuthenticationSession, it is possible to share the existing login information. An alert will be presented to get the user's consent for sharing their existing login information. If the user cancels the alert, the session will be canceled, and the callback will be called.

If the user taps Cancel when showing the login webpage for the web service, the session will be canceled, and the callback will be called as well.

The app can cancel the session by calling cancel(). This will also dismiss the window that is showing the web service's login page.

# Requirements

The AuthenticationSession API is available with the Titanium SDK starting with Release 7.1.0. This module only works with devices running iOS 11.0 and later. Please make sure you have at least Xcode 9 to build to the required sources.

# Getting Started

Create a new authentication session by providing a url and scheme, create an event-listener and start:

var WebDialog = require('ti.webdialog');

var authSession = WebDialog.createAuthenticationSession({
  url: 'https://example.com/oauth?callbackURL=myapp://',
  scheme: 'myapp://'
});

authSession.addEventListener('callback', function(e) {
  if (!e.success) {
      Ti.API.error('Error authenticating: ' + e.error);
      return;
  }
  
  Ti.API.info('Callback URL: ' + e.callbackURL);
});

authSession.start(); // Or cancel() to cancel it manually.

# Properties

# scheme

Availability

7.1.0

scheme :String

The custom URL scheme that the app expects in the callback URL.

# url

Availability

7.1.0

url :String

The initial URL pointing to the authentication webpage. Only supports URLs with http:// or https:// schemes.

# Methods

# cancel

Availability

7.1.0

cancel() → void

Cancel an authentication-session.

If the view controller is already presented to load the webpage for authentication, it will be dismissed. Calling cancel on an already canceled session will have no effect.

Returns

Type: void

# start

Availability

7.1.0

start() → Boolean

Starts the AuthenticationSession instance after it is instantiated.

The start method can only be called once for an AuthenticationSession instance. This also means calling start on a canceled session will fail.

Returns

Returns true if the session starts successfully.

Type: Boolean

# Events

# callback

Availability

7.1.0

The callback which is called when the session is completed successfully or canceled by user.

Properties

Name	Type	Description
error	String	The error-message returned in case something went wrong.
callbackURL	String	The callback-URL returned in case the OAuth-flow succeeded.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.