API Docs for: 0.0.8
Show:

File: client/auth/base/api.js

  1. /* This Source Code Form is subject to the terms of the Mozilla Public
  2. * License, v. 2.0. If a copy of the MPL was not distributed with this
  3. * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
  4. /*globals define*/
  5. define([
  6. 'p-promise',
  7. 'client/lib/constants',
  8. 'client/lib/options',
  9. 'client/lib/function',
  10. 'client/lib/url'
  11. ], function (p, Constants, Options, FunctionHelpers, Url) {
  12. 'use strict';
  13. var partial = FunctionHelpers.partial;
  14. /**
  15. * The base class for other brokers. Subclasses must override
  16. * `openFxa`. Provides a strategy to authenticate a user.
  17. *
  18. * @class BaseBroker
  19. * @constructor
  20. * @param {string} clientId - the OAuth client ID for the relier
  21. * @param {Object} [options={}] - configuration
  22. * @param {String} [options.oauthHost]
  23. * Firefox Accounts OAuth Server host
  24. * @param {Object} [options.window]
  25. * window override, used for unit tests
  26. * @param {Object} [options.lightbox]
  27. * lightbox override, used for unit tests
  28. * @param {Object} [options.channel]
  29. * channel override, used for unit tests
  30. */
  31. function BaseBroker(clientId, options) {
  32. if (! clientId) {
  33. throw new Error('clientId is required');
  34. }
  35. this._clientId = clientId;
  36. this._oauthHost = options.oauthHost || Constants.DEFAULT_OAUTH_HOST;
  37. this._window = options.window || window;
  38. }
  39. function authenticate(action, config) {
  40. //jshint validthis: true
  41. var self = this;
  42. config = config || {};
  43. return p().then(function () {
  44. var requiredOptions = ['scope', 'state', 'redirectUri'];
  45. Options.checkRequired(requiredOptions, config);
  46. var fxaUrl = getOAuthUrl.call(self, action, config);
  47. return self.openFxa(fxaUrl, config);
  48. });
  49. }
  50. function getOAuthUrl(action, config) {
  51. //jshint validthis: true
  52. var queryParams = {
  53. client_id: this._clientId,
  54. state: config.state,
  55. scope: config.scope,
  56. redirect_uri: config.redirectUri
  57. };
  58. if (action) {
  59. queryParams.action = action;
  60. }
  61. if (config.email) {
  62. queryParams.email = config.email;
  63. }
  64. if (this._context) {
  65. queryParams.context = this._context;
  66. }
  67. return this._oauthHost + '/authorization' + Url.objectToQueryString(queryParams);
  68. }
  69. BaseBroker.prototype = {
  70. _context: null,
  71. /**
  72. * Set the `context` field to be passed to the content server. If not
  73. * set, no context will be sent. Should be called by sub-classes if
  74. * a context is needed.
  75. *
  76. * @method setContext
  77. * @param {String} context
  78. */
  79. setContext: function (context) {
  80. this._context = context;
  81. },
  82. /**
  83. * Open Firefox Accounts to authenticate the user.
  84. * Must be overridden to provide API specific functionality.
  85. *
  86. * @method openFxa
  87. * @param {String} fxaUrl - URL to open for authentication
  88. * @param {options={}} options
  89. *
  90. * @protected
  91. */
  92. openFxa: function (fxaUrl, options) {
  93. throw new Error('openFxa must be overridden');
  94. },
  95. /**
  96. * Sign in an existing user
  97. *
  98. * @method signIn
  99. * @param {Object} config - configuration
  100. * @param {String} config.state
  101. * CSRF/State token
  102. * @param {String} config.redirectUri
  103. * URI to redirect to when complete
  104. * @param {String} config.scope
  105. * OAuth scope
  106. * @param {String} [config.email]
  107. * Email address used to pre-fill into the account form,
  108. * but the user is free to change it. Set to the string literal
  109. * `blank` to ignore any previously signed in email. Default is
  110. * the last email address used to sign in.
  111. */
  112. signIn: partial(authenticate, Constants.SIGNIN_ACTION),
  113. /**
  114. * Force a user to sign in as an existing user.
  115. *
  116. * @method forceAuth
  117. * @param {Object} config - configuration
  118. * @param {String} config.state
  119. * CSRF/State token
  120. * @param {String} config.redirectUri
  121. * URI to redirect to when complete
  122. * @param {String} config.scope
  123. * OAuth scope
  124. * @param {String} config.email
  125. * Email address the user must sign in with. The user
  126. * is unable to modify the email address and is unable
  127. * to sign up if the address is not registered.
  128. * @param {String} [config.ui]
  129. * UI to present - `lightbox` or `redirect` - defaults to `redirect`
  130. */
  131. forceAuth: function (config) {
  132. var self = this;
  133. return p().then(function () {
  134. config = config || {};
  135. var requiredOptions = ['email'];
  136. Options.checkRequired(requiredOptions, config);
  137. return authenticate.call(self, Constants.FORCE_AUTH_ACTION, config);
  138. });
  139. },
  140. /**
  141. * Sign up a new user
  142. *
  143. * @method signUp
  144. * @param {Object} config - configuration
  145. * @param {String} config.state
  146. * CSRF/State token
  147. * @param {String} config.redirectUri
  148. * URI to redirect to when complete
  149. * @param {String} config.scope
  150. * OAuth scope
  151. * @param {String} [config.email]
  152. * Email address used to pre-fill into the account form,
  153. * but the user is free to change it.
  154. */
  155. signUp: partial(authenticate, Constants.SIGNUP_ACTION),
  156. /**
  157. * Best choice auth strategy, has no action set
  158. *
  159. * @method bestChoice
  160. * @param {Object} config - configuration
  161. * @param {String} config.state
  162. * CSRF/State token
  163. * @param {String} config.redirectUri
  164. * URI to redirect to when complete
  165. * @param {String} config.scope
  166. * OAuth scope
  167. * @param {String} [config.email]
  168. * Email address used to pre-fill into the account form,
  169. * but the user is free to change it.
  170. */
  171. bestChoice: partial(authenticate, Constants.BEST_CHOICE_ACTION)
  172. };
  173. return BaseBroker;
  174. });