How To : Using Delegated Web Authentication Drivers
Contents |
[edit] Description
This document describes how to use Delegated Web Authentication (DWA) drivers to authenticate users.
[edit] Prerequisites
Understanding Delegated Web Authentication
DelegatedWebAuth Class
[edit] Procedure
Using any DWA driver follows the same basic pattern.
To use a DWA driver:
- Modify your solution's dependencies to include the Bungee_DWA_Drivers Typelib from the Share. The latest supported release of the supported Bungee DWA drivers is located under the name Bungee_DWA_Drivers. See the Using Import and Include howto for instructions on how to include posted Typelibs from the Bungee Share.
- Note When incorporating a DWA driver from the Share into your code, use the Include option instead of the Import option. Using Include simplifies upgrading to a later release of the DWA driver. See Using Import and Include.
- Create a driver instance and initialize it with your web application registration settings obtained from the appropriate authentication provider.
- Call the driver's authenticate() function inherited from DelegatedWebAuth.
- Check the boolean out parameter of authenticate() to see if the authentication succeeded.
- If the authentication succeeded, get any required session authentication results from a driver-specific function.
[edit] Error Handling
Because the authentication is handled by a non-Bungee web application, there are potential errors that can occur that the DWA API's can't control. For example, if a user is unable to authenticate to the third party, then the DWA code does not receive a response. For this reason, the progress overlay that is automatically shown has a cancel button so that the user can cancel the authentication. The authenticate() function also times out if no response is received after a specified amount of time. In addition, if the application registration information is not specified correctly, the authentication process fails in an unpredictable way. Again, the user can use the cancel button on the progress overlay to get out of this situation.
[edit] Examples
[edit] Google AuthSub
This example describes how to use the DWA driver that provides support for the Google AuthSub API. The name of the Google AuthSub DWA driver is DWA_GAuthSub. The AuthSub API allows you to authenticate users and optionally get a session token that can be used to authenticate to other Google services. These session tokens can be saved to persistent storage by the application and reused later (they do not expire). Developers should be aware that users can disable these session tokens using their Google account page, so applications must be able to handle this situation.
To get a session token, you must set the Settings_GetSessionToken field to true, and specify the URL of the Google service for which you want a session token in the Settings_ServiceUrl field. If you don't set Settings_GetSessionToken to true, then the token that getToken() returns can only be used once.
Below is a sample of a function that would obtain a session token for the Google Calendar feed:
var DWA_GAuthSub auth = new DWA_GAuthSub;
var boolean succeeded;
var string sessionToken;
auth.Settings_ServiceUrl = 'http://www.google.com/calendar/feeds';
auth.Settings_GetSessionToken = true;
auth.authenticate(succeeded);
condition
{
case (!succeeded)
{
return;
}
}
auth.getToken(sessionToken);
At the end, sessionToken contains the token that you can use to access the Google Calendar service. The call to authenticate() opens a new browser window for the Google authentication page, and once a user authenticates, they are prompted to authorize your web application to get a token. After the authorization, the browser window automatically closes and authenticate() returns.
Note Signing requests and secure tokens are not currently supported by the Bungee DWA_GAuthSub driver.
[edit] Facebook
This example shows how to use the DWA_Facebook driver to authenticate against Facebook as described in the Facebook Authentication Guide. Facebook applications must be registered as described in the Facebook Creating Your First Application guide. As part of the registration, you must specify a Callback URL for your application which is where Facebook will load your application and where it will send authentication results back to. This must be set to the Application URL for your Bungee application deployment. The Settings_ApiKey field must be set to your application's API Key, and the Settings_SecretKey field must be set to the Secret. Also, a Bungee powered Facebook application should be set to run in an iframe.
However, simulating your application while developing with the Builder will launch and debug your application using a different URL that what is specified in your deployment settings. For this case you should register another Facebook application for development mode. For this registration, set the Callback URL to https://webauth.bungeeconnect.com. Set the SimulateSettings_ApiKey and the SimulateSettings_SecretKey fields to the API key and the secret key for your development mode registration. The DWA_Facebook driver will automatically detect which settings to use when it runs. The developer only needs to set the Simulate* fields in order for this to work correctly.
The code below shows how to use the DWA_Facebook driver (the Settings values are ficticious and are not actually usable).
var DWA_Facebook auth = new DWA_Facebook;
var boolean succeeded;
var string uid;
var string sessionKey;
var string expires;
auth.Settings_ApiKey = '2323kjlj2342lkj234234';
auth.Settings_SecretKey = 'lkasd090982342jlaksdf9';
auth.SimulateSettings_ApiKey = '2323kjlwerasd42lkj234234';
auth.SimulateSettings_SecretKey = 'lkasd09034235342jlaksdf9';
auth.authenticate(succeeded);
condition
{
case (!succeeded)
{
return;
}
}
auth.getSessionInfo(sessionKey, uid, expires);
At the end, you have access to the sessionKey, user's id, and the expires time for the sessionKey. Now the sessionKey can be used to authenticate subsequent Facebook API calls. See the FacebookUrlBuilder class for a utility that greatly simplifies making Facebook API calls. The authenticate() call opens a new browser window for the Facebook authentication page. If the user is already logged in, then the window automatically disappears and the user does not have to type in their password. Otherwise, they need to authenticate to Facebook. Once they have authenticated, the new browser window automatically closes and control is returned back to the Bungee application.
Important Creating non-expiring session keys is not supported yet. Also, be sure not to configure the IP Addresses of Servers Making Requests Facebook application setting when running Bungee applications out of the Bungee cloud, as the IP addresses for your application sessions may change.
[edit] MS Live ID
This example shows how to use the DWA_LiveID driver to authenticate users through the Microsoft Live ID service. Applications using the Live ID authentication API's must register as described on MSDN. When registering, you must set the Return URL setting to your deployment's Application URL with '/blwebauth/MSLiveID' appended in order for the DWA_LiveID driver to work correctly. The Secret Key is set by you, and you must initialize your DWA_LiveID instance's Settings_SecretKey field with that value. After you have registered, you are given an application ID with which the Settings_AppID field must be initialized.
When using the Builder to simulate/debug your code that uses DWA_LiveID, a different URL will be used when launching your application than what you have registered with the Live services. In order for DWA_LiveID to function correctly during Builder development, you must have an additional application registration with Live services. This registration for development mode must set the Return URL to https://webauth.bungeeconnect.com/blwebauth/MSLiveID. Set the SimulateSettings_AppID and SimulateSettings_SecretKey fields to the values from this second application registration. The DWA_LiveID driver will automatically detect what settings to use when executed.
The sample code below demonstrates how to authenticate with Live ID (the Settings values are ficticious and cannot be reused).
var DWA_LiveID auth = new DWA_LiveID;
var boolean succeeded;
var string uid;
auth.Settings_AppID = '09872983423LKS09';
auth.Settings_SecretKey = 'My Application's Secret Key';
auth.SimulateSettings_AppID = '987234000LKJ22';
auth.SimulateSettings_SecretKey = 'My Application's Secret Key for development';
auth.authenticate(succeeded);
condition
{
case (!succeeded)
{
return;
}
}
auth.getUid(uid);
After the authentication, you have access to the user's uid, which is unique to your application. The authenticate() call opens a new browser window for the Live authentication page. If the user is already logged in, then the window automatically disappears and the user does not have to type in their password. Otherwise, they need to authenticate to Live. Once they have authenticated, the new browser window automatically closes and control is returned back to the Bungee application.