Sessions

Elements utilizes Sessions in order for the client application to securely communicate with Elements APIs.

All HTTP requests between the client application and Elements APIs can have a session key. Creating a Session may be completed through several API calls. There are multiple ways to create a session as detailed in this document.

Elements recognizes the following session headers:

• Authorization: [bearer] {secret}

• secret (Required): The Session secret (See Creation Methods below for more information.)

• Elements-SessionSecret: {secret} [u{UserId}] [p{ProfileId}]

• secret (Required): The Session secret (See Creation Methods below for more information.)

• userId (Optional): The id of a User. If the secret matches a Super User then this may be any other non Super User in Elements. This will cause the subsequent request to be executed as the specified User. For all other Users, this must be the identity associated with the session making the request. This will override the User Scoping Rules.

• profileId (Optional): The id of a Profile. If the secret matches a Super User then this may be any Profile in Elements. For all other Users, this must be a Profile associated with the User making the request. Ths will override the Profile Scoping Rules.

Creation Methods

There are several ways to create sessions within Elements. Each section here describes the supported creation methods and how to implement each one of them. In all cases, Elements performs the account verification authoritatively, ensuring that the server has verified the credentials supplied to it.

Username and Password

This the most basic method of creating a session and requires no third-party integration. When creating a User, the client supplies the desired username and password. Elements securely hashes each User's password in the database.

Facebook

Elements supports login using Facebook OAuth tokens. When passing an OAuth token to Elements, Elements will verify the token and create an account for the user based on the information supplied by Facebook. To support Facebook login, Elements requires additional configuration in the admin panel.

The Facebook Sign-In Procedure is as follows:

1. Configure a new Application or select an existing Application.

2. Configure a Facebook Application Configuration

3. Install the appropriate Facebook SDK for your platform of choice.

   • Android

   • iOS

   • JavaScript

   • PHP

   • tvOS

   • Unity

4. Using the Elements RESTful API, submit the following information to Elements:

   • applicationNameOrId: The id or the name of the Application

   • applicationConfigurationNameOrId: The id or the name of the Application

   • facebookOAuthAccessToken: The OAuth Access Token supplied by the Facebook SDK.

   • Note: We recommend using a short-lived token, but any token will work.

5. Elements will respond with information about the User, Session, and other information.

   • Note: This process will also automatically synchronize Facebook friends with Elements Friends

TODO: Add detail on lua code samples to get this running

Apple Sign-In

Per Apple's requirements, Elements supports session creation via Apple Sign-In. This ensures that Apple users may sign in and link their Elements account to their Apple account. This requires additional configuration in the Elements admin panel.

The Apple Sign-In procedure is as follows:

1. Configure a new Application or select an existing Application.
2. Configure an Apple Sign-In Configuration
3. Configure your iOS App for Apple Sign-In
4. Using the Apple SDK obtain an instance of ASAuthorizationAppleIDCredential
5. Using the Elements RESTful API, submit the following to Elements:

   • applicationNameOrId: The id or the name of the Application
   • applicationConfigurationNameOrId: The id or name of the Application
   • identityToken: The identityToken supplied by Apple.
   • authCode: The authorizationCode supplied by Apple.
6. Elements will respond with information about the User, Session, and other information.

TODO: Add detail on lua code samples to get this running

Firebase

Elements supports Firebase Authentication using JWTs (Javascript Web Tokens) generated by the Firebase SDK. Firebase supports a myriad of logins for a variety of platforms. By integrating Firebase, Elements can support all login schemes offered by Firebase without any additional configuration.

1. Configure a new Application or select an existing Application.
2. Configure a Firebase Application Configuration.
3. Integrate the Firebase SDK into your application or site.
4. Using hte Elements RESTful API, submit the JWT generated by the Firebase SDK to Elements.

5. Elements will verify the JWT aginst Firebase's servers as well as create an account within Elements based on the information provided.

   • Note: The claims in the JWT will contain everything necessary to authorize the application.

If using Firebase, we do not recommend mixing other auth strategies other than Username and Password.

Scoping Rules

Within the Elements Security Model, sessions may have two scopes: User or Profile. Some APIs require a session with a current Profile and not just a User. Generally these APIs are for application specific operations, such as Matchmaking.

User

All sessions will have a User associated with them. Once created, they will always be valid for that User until it expires or the user changes their password.

Profile

A Session may, optionally, be scoped by a User and a Profile. The Profile's owner must match the User who created the session. APIs that require Profile scoping rules are as follows:

• Fetching current Profile (eg GET /profile/current)

• Processing IAPs

• Leaderboards and Rankings

• Push Notifications

• Progress and Missions