# new BaseAuthenticator()
The base class for all authenticators. This serves as a starting point for implementing custom authenticators and must not be used directly.
The authenticator authenticates the session. The actual mechanism used to do this might, e.g., post a set of credentials to a server and in exchange retrieve an access token, initiating authentication against an external provider like Facebook, etc. The details depend on the specific authenticator. Upon successful authentication, any data that the authenticator receives and resolves via the promise returned from the BaseAuthenticator.authenticate method is stored in the session's SessionService.data.
The authenticator also decides whether a set of data that was restored from the session store (see BaseStore.restore) makes up an authenticated session or not.
Authenticators for an application are defined in the app/authenticators
directory, e.g.:
// app/authenticators/oauth2.js
import OAuth2PasswordGrantAuthenticator from 'ember-simple-auth/authenticators/oauth2-password-grant';
export default class OAuth2Authenticator extends OAuth2PasswordGrantAuthenticator {
...
}
and can then be used via the name Ember CLI automatically registers for them within the Ember container.
// app/components/login-form.js
import Component from '@ember/component';
import { inject as service } from '@ember/service';
import { action } from '@ember/object';
export default class LoginFormComponent extends Component {
@service session;
@action
authenticate() {
this.session.authenticate('authenticator:oauth2');
}
}
Extends
- Ember.Object
Members
# static authenticate
Authenticates the session with the specified args. These options vary
depending on the actual authentication mechanism the authenticator
implements (e.g. a set of credentials or a Facebook account id etc.). The
session will invoke this method in order to authenticate itself (see
SessionService.authenticate).
__This method returns a promise. A resolving promise will result in the
session becoming authenticated.__ Any data the promise resolves with will
be saved in and accessible via the session service's `data.authenticated`
property (see SessionService.data).
A rejecting promise indicates that authentication failed and will result in
the session remaining unauthenticated.
The `BaseAuthenticator`'s implementation always returns a rejecting promise
and thus never authenticates the session. __This method must be overridden
in subclasses__.
# static invalidate
This method is invoked as a callback when the session is invalidated. While
the session will invalidate itself and clear all authenticated session data,
it might be necessary for some authenticators to perform additional tasks
(e.g. invalidating an access token on the server side).
This method returns a promise. A resolving promise will result in the
session becoming unauthenticated.__ A rejecting promise will result in
invalidation being intercepted and the session remaining authenticated.
The BaseAuthenticator's implementation always returns a resolving promise
and thus never intercepts session invalidation. __This method doesn't have
to be overridden in custom authenticators if no actions need to be
performed on session invalidation.
# static restore
Restores the session from a session data object. This method is invoked by the session either on application startup if session data is restored from the session store or when properties in the store change due to external events (e.g. in another tab) and the new session data needs to be validated for whether it constitutes an authenticated session.
__This method returns a promise. A resolving promise results in the session
becoming or remaining authenticated.__ Any data the promise resolves with
will be saved in and accessible via the session service's
`data.authenticated` property (see
SessionService.data. A rejecting
promise indicates that `data` does not constitute a valid session and will
result in the session being invalidated or remaining unauthenticated.
The `BaseAuthenticator`'s implementation always returns a rejecting
promise. __This method must be overridden in subclasses.__
Events
# sessionDataInvalidated
Triggered when the authentication data is invalidated by the authenticator due to an external or scheduled event. This might happen, e.g., if a token expires or an event is triggered from an external authentication provider that the authenticator uses. The session handles the event and will invalidate itself when it is triggered.
# sessionDataUpdated
Triggered when the authentication data is updated by the authenticator due to an external or scheduled event. This might happen, e.g., if the authenticator refreshes an expired token or an event is triggered from an external authentication provider that the authenticator uses. The session handles that event, passes the updated data back to the authenticator's BaseAuthenticator.restore method and handles the result of that invocation accordingly.
Parameters:
| Name | Type | Description |
|---|---|---|
data |
Object
|
The updated session data |