Social and OAuth2 Logins

Backendless provides integration with multiple login providers, including social networks and various cloud/enterprise systems. You can see available login providers in the Backendless Console by clicking the Users icon and then the Login Providers section:

For most providers the configuration screen consists of the following elements:

• Reference in code - this is a value that should be used in the Backendless API call(s) documented below. It uniquely identifies the provider in the Backendless system.
• Callback URL - This is a URL that the login provider will use to pass the authentication flow from its system to Backendless. The URL should be copied/pasted into the login provider configuration.
• Client ID (or Web Client ID or App Key) -  a unique value that should be obtained from the login provider side.
• Client Secret (or Web Client Secret or App Secret) - a unique value that should be obtained from the logic provider side.

In order to use a login provider, it must be enabled first. To enable a login provider, select it from the list, fill out the form with the required values and click the toggle that says "This provider is OFF". Make sure to click the SAVE button to save the configuration parameters and the ON/OFF state of the provider.

Once a login provider is enabled, your application can authenticate the users through the provider. Backendless supports two different authentication flows:

Login With Provider's SDK

This approach relies on the login provider's implementation to handle the step of displaying the login screen and collecting the user's credentials. The provider SDK hands of the authentication process by delivering an access token that should be sent to Backendless to exchange it for a Backendless User object.

See the illustrations below demonstrating the flow:

Step 1. Your app initiates the login process using provider's SDK. The result of this step is the login user interface:

Step 2. User enters their credentials and submits the login form. The result of this step is the authentication access token.

Step 3. Your application uses Backendless API to login the user to Backendless using access token. This step results in a user record being created in the Backendless system (if this is a new user). The access token is "exchanged" for Backendless user session. To implement this step use the OAuth2 Login API:

Login Without Provider's SDK

With this approach the provider's SDK is not required. The login form is rendered using HTML/JS. If used in a native mobile environment, it will be necessary to use mobile browser component to render the authentication screen.

Step 1. Your application uses Backendless API to receive a URL for the provider's authentication form. To implement this step use the Get Authorization URL API:

Step 2. Your application opens the login form using the URL from step 1. There is no API for this step, your application needs to use the URL to open it in a web view/browser:

Step 3. User logs in with their credentials and submits the form. If the authentication is successful, the login provider responds with a redirect to the Backendless callback URL (this is the URL you copied/pasted from Backendless Console into provider's configuration):

Step 4. The redirect to the Backendless callback URL in the previous step results in the Backendless User object and Backendless user token sent to the application. A Backendless user record is created in the Users table (if this is a new user). There is no API for this step, your application needs to process the result of the form submission and response from the redirect.

Login Provider Configuration

Configuring a login provider will vary as all providers have their own way for obtaining configuration properties. Below you will find instructions for most commonly used social login providers:

Configuring "Login with Facebook"

1. Navigate to https://developers.facebook.com/
2. Select an application or create one using the My Apps dropdown in the upper right corner.If you are creating a new app, you will see a popup asking "how are you using your app?". Select the For Everything Else answer.
3. Add Facebook Login to your app
   
4. Locate the App ID and App Secret values in the Settings > Basic section and copy the values into the corresponding fields in the Backendless Console ( Users > Login Providers > Facebook ).
5. Click Add Platform and select Website .
6. Enter https://api.backendless.com as the Site URL .
7. Click Save Changes .
8. Click the Settings tab on the Facebook Product section.
9. Scroll down to the Client OAuth Settings block and enter https://api.backendless.com into the Valid OAuth redirect URIs field.
10. In a separate browser window login to Backendless console and navigate to Users > Login Providers > Facebook screen. You will see the Callback URL field. Copy the URL from that field into Valid OAuth redirect URIs (by the time you are done with this step, that field will have two URIs as shown in the screenshot below):
    
11. Scroll down to the bottom of the page and click Save Changes .

Configuring "Login with Google"

1. Navigate to https://console.developers.google.com
2. Choose an existing project or create a new one.
   
3. Use the Search Bar or click the Library menu item and select Google+ API :
   
4. Click Enable to enable the API:
   
5. Once the API is enabled, click the Credentials menu item on the left and then click the CONFIGURE CONSENT SCREEN button. Note, that the consent screen won't show up if a user has created more than 1 Google app.
   
6. Complete all the steps in the OAuth consent screen forms.
7. Return to the APIs  & Services screen for your project and select the Credentials menu on the left and click +Create Credentials > Create OAuth client ID .
   
   
8. Select Web Application .
9. Click the + ADD URI button in the Authorized redirect URIs section and enter the Callback URL value from Backendless Console:
   
10. Click the Credentials menu in the APIs & Services section of your Google project and locate the Web Application client in the OAuth 2.0 Client IDs section:
    
11. Click the edit icon for the Web application client.
12. Copy Client ID and Client secret from the Google API console to the corresponding fields in Backendless Console on the Users > Login Providers > Google screen.
    From here:
    
    
    To Backendless Console:
    

Configuring "Login with Github"

1. Open https://github.com/settings/apps/new
2. Register a new app.
3. In "Application name", type in the name of your app.
4. In Homepage URL use https://api.backendless.com or the homepage URL for your application.
5. For the Authorization callback URL field copy/paste the Callback URL value from Backendless console. You will find the value in the Users > Login Providers > GitHub screen.
6. Click Create Github App .
7. Copy Client ID and Client secret into the corresponding fields in the Users > Login Providers > GitHub screen.
   

Configuring "Login with LinkedIn"

1. Open https://www.linkedin.com/developers/apps
2. Click Create app .
3. In App name type the name of your app.
4. Enter LinkedIn page , Privacy policy and App logo :
   
5. Click Create app .
6. Go to Auth
7. For the Authorization callback URL field copy/paste the Callback URL value from Backendless Console located in Users > Login Providers > LinkedIn
8. Go to Products
9. Enable Sign In with LinkedIn :
   
10. Copy Client ID and Client secret into the corresponding fields in Backendless Console located in the Users > Login Providers > LinkedIn screen.

Get Authorization URL API

This API is used to obtain a URL for the login providers authorization (login) form. The API is used in the OAuth login approach without using login provider's SDK (see Step 1 in Login Without Provider's SDK).

Method

POST

Endpoint URL

https://xxxx.backendless.app/api/users/oauth/<providerCode>/request_url

where:

Argument	Description
<providerCode>	value from Backendless Console on the Users > Login Providers screen.

Important

The xxxx.backendless.app is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.

Request Headers

Content-Type:application/json

where

Argument	Description
Content-Type	must be set to application/json. This header is mandatory.

Request Body

{  
  fieldsMapping: String // Optional. If omitted, default provider fields mappings   
                        // will be used. The value is a string that contains a   
                        // JSON object describing the mappings.   
                        // Consider the following JSON:  
                        // {  
                        //   "my_email":"email",  
                        //   "my_name":"name"  
                        // }  
                        //  
                        // The key identifies the provider's property name and the   
                        // value is the name of the mapped property (column name)   
                        // in Backendless. In the example above, "my_email" and   
                        // "my_name" are the properties returned by the OAuth2   
                        // provider and the corresponding values will be   
                        // respectively stored in the "email" and "name" columns  
                        // in Backendless.  

  permissions: String  // Optional. Applies only to the OAuth2 providers. Contains   
                       // provider scopes for data access. If omitted, default   
                       // provider scopes will be used.  

  redirect: boolean    // Indicates if the server should return authorization URL  
                       // or redirect to it. If the field is omitted, the server   
                       // performs an HTTP redirect.  

  contentType: String  // Optional. Is used to specify the format of the response.   
                       // Can have one of the following values:   
                       // "text/plain" - in this case, the API response is the   
                       //                authorization URL in the plain text  
                       //                format. This is the same behavior when   
                       //                the "contentType" property is not set.  
                       // "application/json" - in this case, the API response is  
                       //                a JSON document with the following   
                       //                structure:  
                       //                {  
                       //                  "url": "authorization URL"  
                       //                }  
                       //  
                       // In order for this property to work, the redirect   
                       // property must be set to false.  
}

Response Body

• If the redirect parameter is set to true, then the server will respond with an HTTP redirect to the authorization URL.
• If the redirect parameter is set to false and the contentType parameter in the request body is not specified, the server returns authorization URL as plain text.
• If the redirect parameter is set to false and the contentType parameter in the request body is set to "application/json", the response is a JSON document with the following structure:

{          
  "url": "authorization URL"  
}

OAuth2 Login API

This API is used to "exchange" login provider's access token to BackendlessUser, it is used in Step 3 of the Login with Provider SDK flow. The API logs in externally authenticated user to Backendless.

Method

POST

Endpoint URL

https://xxxx.backendless.app/api/users/oauth/<providerCode>/login

where:

Argument	Description
<providerCode>	value from Backendless Console on the Users > Login Providers screen.

Important

The xxxx.backendless.app is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.

Request Headers

Content-Type:application/json

where

Argument	Description
Content-Type	must be set to application/json. This header is mandatory.

Request Body

{  
 "accessToken": String,  // Required. This is a value received as a result of authentication   
                         // with the login provider.  
 "fieldsMapping": JSON,  // Optional. Applies only to the OAuth2 providers. Contains provider   
                         // scopes for data access. If omitted default provider scopes will be used.  
                         // The value is a string that contains a JSON object describing the mappings.  
                         // Consider the following JSON:  
                         // {  
                         //   "my_email":"email",  
                         //   "my_name":"name"  
                         // }  
                         // The key identifies the provider's property name and the value is the name of the   
                         // mapped property (column name) in Backendless. In the example above, "my_email"  
                         // and "my_name" are the properties returned by the OAuth2 provider and the   
                         // corresponding values will be respectively stored in the "email" and "name"   
                         // columns in Backendless.  
 "guestUser": JSON       // Optional. If present, should be the result of the Backendless Guest Login API call  
}

Response Body

a JSON structure representing a BackendlessUser.