Back to Concepts and HOW TOs

Contents 1 Description 2 Prerequisites 3 Procedure 4 Error Handling 5 Examples 6 Next Steps 7 Tags

[edit] Description

This document describes how to write a Delegated Web Authentication (DWA) Driver.

[edit] Prerequisites

Understanding Delegated Web Authentication
DelegatedWebAuth Class
Using Delegated Web Authentication Drivers

[edit] Procedure

To write a DWA Driver:

1. Create a new class that inherits from Runtime->Utility->DelegatedWebAuth.
2. Add fields to the class to hold the application registration settings required by the authentication provider for which you are adding support. The existing drivers name these fields with a "Settings_" prefix. Consider using this naming convention to maintain consistency with other existing DWA drivers.
3. Add two override functions from DelegatedWebAuth, initialize() and processAuthResults().
4. Implement the initialize() function (which is called by the authenticate() function), and make sure the following happens:
   1. Set the inherited authenticationUrl field to the appropriate URL for the authentication system for which you are implementing support. You have to include some type of session context information for that URL, so you have one of two options, depending on what your authentication system allows:
      1. If the authentication system allows you to specify an entire URL as a context parameter, use the URL returned by the inherited getStandardCallbackUrl() function as a query argument. Then use a UrlBuilder class to build the complete URL for authenticationUrl with that query argument. This does not require any updates to the Bungee DWA datacenter components.
      2. If the authentication system requires you to register a callback URL for your application and allows you to specify context information in its API call, you have to contact Bungee support to create a new web authentication callback URL in the DWA datacenter components. Once that is in place, use a UrlBuilder class to build the URL for authenticationUrl, using the string returned by getContextStr() as the session context information value for the appropriate query argument key.
         1. Note If the authentication system does not provide a way to specify any context information in its API call, it cannot be supported by the Bungee DWA framework.
   2. Initialize any internal state necessary for your authentication. The driver should assume that authenticate() can be called more than once, and each call to authenticate() should start a new session and not save old tokens, etc.
5. Implement the processAuthResults() function.
   1. The authentication results are stored in the inherited resultData map. Analyze that data to determine if the authentication succeeded.
   2. Set the succeeded out parameter to true if a successful authentication occurred, false otherwise.

[edit] Error Handling

The driver should log messages that throw events to help Bungee developers trouble shoot problems. Also, if the driver's required settings are not initialize correctly, the initialize() function should throw an exception to notify the Bungee developer that they forgot to configure the driver correctly.

[edit] Examples

See the Bungee_DWA_Drivers share item for the existing implementations. They are the most useful examples of how to write a Driver.

[edit] Next Steps

The Bungee DWA Drivers project is maintained in the Bungee_DWA_Drivers DesignGroup. Bungee welcomes new Driver implementations. If you are interested in writing a Driver or contributing to new or existing Driver projects, please contact Bungee Support.

[edit] Tags

Log in if you would like to rate this page.