# new SessionService()
The session service provides access to the current session as well as methods to authenticate it, invalidate it, etc. It is the main interface for the application to Ember Simple Auth's functionality.
// app/components/login-form.js
import Component from '@ember/component';
import { inject as service } from '@ember/service';
export default class LoginFormComponent extends Component {
@service session;
}
Extends
- Service
Members
Transition
# static attemptedTransition
A previously attempted but intercepted transition (e.g. by the SessionService.requireAuthentication If an attempted transition is present it will be retried.
Properties:
| Name | Type | Description |
|---|---|---|
attemptedTransition |
- Default Value:
- null
Object
# static readonly data
The current session data as a plain object. The
authenticated key inside SessionService.data holds the session data that the authenticator resolved
with when the session was authenticated (see BaseAuthenticator.authenticate) and
that will be cleared when the session is invalidated. This data cannot be
written. All other session data is writable and will not be cleared when
the session is invalidated.
Properties:
| Name | Type | Description |
|---|---|---|
data |
- Default Value:
- { authenticated: {} }
Boolean
# static readonly isAuthenticated
Returns whether the session is currently authenticated.
Properties:
| Name | Type | Description |
|---|---|---|
isAuthenticated |
- Default Value:
- false
Methods
# static authenticate(authenticator) → {RSVP.Promise}
Authenticates the session with an authenticator and appropriate
arguments. The authenticator implements the actual steps necessary to
authenticate the session (see
BaseAuthenticator.authenticate and
returns a promise after doing so. The session handles the returned promise
and when it resolves becomes authenticated, otherwise remains
unauthenticated. All data the authenticator resolves with will be
accessible via the
SessionService.data session data's
authenticated property.
This method returns a promise. A resolving promise indicates that the
session was successfully authenticated while a rejecting promise
indicates that authentication failed and the session remains
unauthenticated. The promise does not resolve with a value; instead, the
data returned from the authenticator is available via the
SessionService.data property.
When authentication succeeds this will trigger the
SessionService.authenticationSucceeded event.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
authenticator |
String
|
The authenticator to use to authenticate the session |
|
...args |
Any
|
<optional> |
The arguments to pass to the authenticator; depending on the type of authenticator these might be a set of credentials, a Facebook OAuth Token, etc. |
A promise that resolves when the session was authenticated successfully and rejects otherwise
RSVP.Promise
# static handleAuthentication(routeAfterAuthentication)
This method is called whenever the session goes from being unauthenticated
to being authenticated. If there is a transition that was previously
intercepted by the
SessionService.requireAuthentication,
it will retry it. If there is no such transition, the
ember_simple_auth-redirectTarget cookie will be checked for a url that
represents an attemptedTransition that was aborted in Fastboot mode,
otherwise this action transitions to the specified
routeAfterAuthentication.
Parameters:
| Name | Type | Description |
|---|---|---|
routeAfterAuthentication |
String
|
The route to transition to |
# static handleInvalidation(routeAfterInvalidation)
This method is called whenever the session goes from being authenticated to not being authenticated. It reloads the Ember.js application by redirecting the browser to the specified route so that all in-memory data (such as Ember Data stores etc.) gets cleared.
If the Ember.js application will be used in an environment where the users
don't have direct access to any data stored on the client (e.g.
[cordova](http://cordova.apache.org)) this action can be overridden to e.g.
simply transition to the index route.
Parameters:
| Name | Type | Description |
|---|---|---|
routeAfterInvalidation |
String
|
The route to transition to |
# static invalidate() → {RSVP.Promise}
Invalidates the session with the authenticator it is currently authenticated with (see SessionService.authenticate). This invokes the authenticator's BaseAuthenticator.invalidate method and handles the returned promise accordingly.
This method returns a promise. A resolving promise indicates that the
session was successfully invalidated while a rejecting promise indicates
that invalidation failed and the session remains authenticated. Once the
session is successfully invalidated it clears all of its authenticated data
(see SessionService.data).
When invalidation succeeds this will trigger the
SessionService.invalidationSucceeded
event.
When calling the BaseAuthenticator.invalidate
on an already unauthenticated session, the method will return a resolved Promise
immediately.
Parameters:
| Name | Type | Description |
|---|---|---|
...args |
Array
|
arguments that will be passed to the authenticator |
A promise that resolves when the session was invalidated successfully and rejects otherwise
RSVP.Promise
# static prohibitAuthentication(routeOrCallback) → {Boolean}
Checks whether the session is authenticated and if it is, transitions to the specified route or invokes the specified callback.
Parameters:
| Name | Type | Description |
|---|---|---|
routeOrCallback |
String
|
function
|
The route to transition to in case that the session is authenticated or a callback function to invoke in that case |
true when the session is not authenticated, false otherwise
Boolean
# static requireAuthentication(transition, routeOrCallback) → {Boolean}
Checks whether the session is authenticated and if it is not, transitions to the specified route or invokes the specified callback.
If a transition is in progress and is aborted, this method will save it in the
session service's
SessionService.attemptedTransition
property so that it can be retried after the session is authenticated. If
the transition is aborted in Fastboot mode, the transition's target URL
will be saved in a `ember_simple_auth-redirectTarget` cookie for use by the
browser after authentication is complete.
Parameters:
| Name | Type | Description |
|---|---|---|
transition |
Transition
|
A transition that triggered the authentication requirement or null if the requirement originated independently of a transition |
routeOrCallback |
String
|
function
|
The route to transition to in case that the session is not authenticated or a callback function to invoke in that case |
true when the session is authenticated, false otherwise
Boolean
# static setup()
Sets up the session service.
This method must be called when the application starts up,
usually as the first thing in the `application` route's `beforeModel`
method.
Events
# authenticationSucceeded
Triggered whenever the session is successfully authenticated. This happens when the session gets authenticated via SessionService.authenticate but also when the session is authenticated in another tab or window of the same application and the session state gets synchronized across tabs or windows via the store (see BaseStore.sessionDataUpdated).
# invalidationSucceeded
Triggered whenever the session is successfully invalidated. This happens when the session gets invalidated via SessionService.invalidate but also when the session is invalidated in another tab or window of the same application and the session state gets synchronized across tabs or windows via the store (see BaseStore.sessionDataUpdated.