coauth

Usage

NOTE coauth client scripts use JSON object, so provide a polyfill if you need it for old browsers.

• Add coauth resources to your contract (see resources)
• Provide pages for options.authPageUrl and options.resultPageUrl with appropriate scripts (examples can be found in page_examples directory)
• Add coauth client script to your page
• Use script when need to authenticate

Workflow

auth

• Script opens stub window with url options.authPageUrl
• Script obtains auth url from auth_url resource
• Script redirects opened window to auth url
• External system acts, then redirects to stub window with url options.resultPageUrl
• Script performs request to 'result' resource to obtain auth result and calls your callback function providing error or result

If you want to perform last step by yourself (to customise it or whatever), you can set options.customAuthResultRequest = true then instead of the last step the following will happen:

• Script composes data for obtaining auth result and calls your callback function, providing them as 'result' argument
• Your callback function must itself perform request to get auth result
  • You can use auth.authResultHttpRequest() and auth.authResultFrameRequest() helper functions for this if you just want modified headers or data to be sent to standard 'result' resource
• To close any windows or frames created your callback must call authWorker.closeWindow() after all is done

tryAuth

The same as auth, but tries to do all the things within hidden iframe.

Works only if external service can authenticate a user without interaction (redirects back instantly). Otherwise will fail on timeout.

Resources

Resource creation provided by ResourceCreator class.

auth_url

Generates external system auth url.

Use createAuthUrlResource() method.

result

Exchanges data obtained after redirection to auth url with auth result.

Use createAuthResultResource() method.

js

For test purposes only. Exposes coauth client script.

Use createJsResource() method .

Client script

Usage

var auth = new coauth.Auth(url);
 
var options = {
    providerType: 'fb',
    authPageUrl: '/heading/to/external/system/page',
    resultPageUrl: 'http://example.com/comming/back/page'
};
 
var authWorker = auth.auth(options, function(err, result) {
    if(err) {
        console.log('err', err);
    } else {
        console.log('result', result);
 
        // if options.customAuthResultRequest == true
        // call your result resource providing 'result' parameter,
        // on complete call:
        // authWorker.closeWindow();
    }
});

Options

Required options are:

• providerType
• authPageUrl
• resultPageUrl

{
    providerType: '', // provider type
    identity: null, // your identity if need
    hidden: false, // if true, make auth() work exactly as tryAuth(), has no effect for tryAuth()
 
    authPageUrl: '', // stub page to show before redirection to external system, must contain appropriate sript (see page_examples dir)
    resultPageUrl: '', // stub page to show on redirection from external system, must contain appropriate sript (see page_examples dir) and must be full url (because will be used as redirect URI)
 
    customAuthResultRequest: false, // set to true if want to request result resource by yourself
    postMessageWorkaroundFuncName: '', // what function to call on opened window if postMessage() doesn't work
    tryAuthTimeout: 5000, // timeout for tryAuth(), null - use default, 0 - no timeout
 
    window: {
        features: 'dialog=true', // features of popup window
        closeCheckInterval: 200 // how often to check if window is closed by user, ms
    },
 
    auth: { // provider-specific auth step options
        scope: [] // permissions requested
        // other provider-specific options
    },
 
    result: { // provider-specific result obtaining step options
        fields: [] // fields requested
        // other provider-specific options
    }
}

Response

All server response objects have following properties:

• status - HTTP status
• headers - optional headers
• data - data sent by server, contains actual result (see below)
• transport - optional, xhr object in case of xhr request

Result

For standard flow, see Validation.AuthResult

For customAuthResultRequest == true result contains at least following:

• identity
• providerType
• options (options.result subpart only)

Possible errors in callback function

Error is an Error with following possible properties:

• code - error code
• status - optional http status
• message - optional error message
• response - optional response as obtained from server
• optional other attributes

coauth errors:

• WindowClosed - user closed auth window
• Timeout - tryAuth() timeout
• 400 ValidationError - invalid arguments

Noauth/provider errors:

• 400 InputError - data provided to noauth are invalid (possibly error in options)
• 409 UserDenied - user rejected to authenticate
• 500 ProviderConnectionError - cannot connect to provider
• 500 ProviderTechnicalError - provider experiences technical problems (returns 500, 502, "unknown error", etc.)
• 500 ProviderError - other provider-related error (can indicate problems with coauth)

Other errors are unlikely, but still can be raised.

License

MIT