Skip to main content
Version: v19 R6 BETA

On Mobile App Authentication

On Mobile App Authentication( mobileInfo : Object ) -> status : Object

ParameterTypeDescription
mobileInfoObject->Information passed by the mobile application
statusObject<-Authentication status

Description

The On Mobile App Authentication 4D database method is in charge of managing mobile app authentication to 4D Server or 4D Developer. It is automatically called by 4D when a user agent sends a login request to 4D Server or 4D Developer for the first time.

note

A user agent is defined by an application ID, a device ID, and a team ID. These ids are passed to the On Mobile App Authentication database method (see below).

The On Mobile App Authentication database method is always called for a first connection, even if the mobile application was built in Guest mode.

The method receives all necessary information from the mobile application in the mobileInfo parameter (object), and must return an authentication status in the status parameter (object). You must declare and initialize these parameters as follows:


//On Mobile App Authentication database method
#DECLARE ($mobileInfo : Object) -> $status : Object

// ...Code for the method
$status:=New object() //do not forget to create the object to return

The following properties are received in the mobileInfo object parameter:

PropertyTypeDescription
emailTextUser email. Not mandatory, can be empty for guest access
applicationObjectInformation about the mobile application
idTextMobile application id
nameTextMobile application name
versionTextMobile application version
deviceObjectInformation about the mobile device (usually, a mobile phone)
idTextGenerated unique device id
versionTextSystem version of the device
descriptionTextDescription of the device
simulatorBooleanTrue if the device is a simulator
teamObjectApple Developer Team information
idTextTeam id (allows developers to use the Xcode project Build and Run functionality)
languageObjectLanguage settings of the user device
idTextUser device current language id, ex: en_US
regionTextUser device current region, ex: US
codeTextUser device current language, ex: en
parametersObjectAny additional information that could be added by the mobile app for custom use
sessionObjectSession information
idTextSession UUID created for this authentication. Could be stored for future use
ipTextClient IP address

After processing information, the database method should return an object with the following properties in status:

PropertyTypeDescription
userInfoObjectUser values to filter queries.
successBooleanTrue if authentication is successful, False otherwise. If success=False, the connection is denied.
statusTextText(Optional) Message to display on the mobile application. If success=true, welcome message; if success=false, can be used to provide user with an explanation.

The connection is automatically rejected if:

  • no value is set to status result or status is not defined,
  • an invalid value is set to status,
  • the On Mobile App Authentication database method is not defined in the application.
info

The connection is automatically accepted if it comes from "localhost" since it is considered a developer testing connection.

Authenticating a mobile request

Basically, authenticating a mobile application connection request is based upon the provided email. For example, if you want to grant access only to connections from emails at 4d.com domain, you can write in the On Mobile App Authentication database method:

 #DECLARE ($mobileInfo : Object) -> $status : Object  

If($mobileInfo.email="@"+Char(At sign)+"4d.com")
$status.success:=True
End if

You can also identify the user agent using the application.id, device.id, and team.id from the $mobileInfo object, and decide to allow or deny access.

Guest access

If the mobile application has been built with the "Requires an email to connect" option unchecked, it is a "guest mode" application. Then, the $mobileInfo.email string will be provided empty. In this case, you can:

  • allow access to guests by returning True in $status.success,
  • identify and evaluate guest access using the user agent information, the decide to allow or deny access.
  • deny access to guests by returning False in $status.success. This can be done for example if the server is in maintenance mode. In this case, an error will be displayed on the mobile app if the user clicks on the Reload button.

Example

Here is a template example for a On Mobile App Authentication database method:

 
//On Mobile App Authentication database method
#DECLARE ($mobileInfo : Object) -> $status : Object


var $Boo_simulator : Boolean
var $Txt_appID;$Txt_appName;$Txt_appVersion;$Txt_device;$Txt_deviceID;$Txt_email : Text
var $Txt_IP;$Txt_languageCode;$Txt_languageId;$Txt_languageRegion;$Txt_osVersion;$Txt_sessionId : Text
var $Txt_teamID : Text

//Get user email
$Txt_email:=String($mobileInfo.email)

If(Length($Txt_email)=0) //no email was provided
// Guest mode - allow or deny connection
$status.success:=True
// $status.success:=False if you want to deny guest access

// Optional welcome message to display on mobile App.
$status.statusText:="Welcome to my application"

Else
// Authenticated mode - Allow or not the connection
If(Is compiled mode) // Deployment version

//Allow, for example, emails from the 4D.com domain
$status.success:=($mobileInfo.email=("@"+Char(At sign)+"4d.com"))

Else //Development version

//Allow all adress for testing purposes
$status.success:=True

End if

If($status.success)


//Optional welcome message to display on mobile App.
$status.statusText:="Authentication successful"

Else

$status.statusText:=$mobileInfo.email+" is not an authorized email address."

End if
End if

// Get App information if identification is needed (optional)
If($mobileInfo.application#Null)
$Txt_appID:=$mobileInfo.application.id // App Id
$Txt_appName:=$mobileInfo.application.name //App Name
$Txt_appVersion:=$mobileInfo.application.version // App Version
End if

//Get Device information if identification is needed (optional)
If($mobileInfo.device#Null)
$Txt_device:=$mobileInfo.device.description //Device Description
$Txt_deviceID:=$mobileInfo.device.id //Device Id
$Txt_osVersion:=$mobileInfo.device.version //System Version
$Boo_simulator:=$mobileInfo.device.simulator //True if device is a Simulator
End if

//Get the Team information if needed (optional)
If($mobileInfo.team#Null)
$Txt_teamID:=$mobileInfo.team.id //Team Id
End if

//Get the User Language information (optional)
If($mobileInfo.language#Null)
$Txt_languageCode:=$mobileInfo.language.Code
$Txt_languageId:=$mobileInfo.language.id
$Txt_languageRegion:=$mobileInfo.language.region
End if

//Get the session information
If($mobileInfo.session#Null)
//Could be stored for future use.
$Txt_sessionId:=$mobileInfo.session.id //UUID created for this authentication
$Txt_IP:=$mobileInfo.session.ip //IP address
End if

//Get the App parameters
If($mobileInfo.parameters#Null)
//Any additional information that could be added by mobile app for custom use (object)
End if