User-password application scripting guide

Chapter 2 User-password application scripting guide You can use the generic user-password application template (described in Creating a generic user-password application profile) to add a user-password web application to the Samsung SDS CellWe EMM application catalog. This template creates a user-password application profile for a web application that defines how the cloud service logs an authenticated user on to the web application via an HTML reply form containing user and password information. Each user-password application profile requires a custom user-password script. The script defines how the cloud service creates an HTML response to log on for each user s session with the web application. Each application profile may also provide an optional user map script that determines the user s application log-on name and password for use in the HTML response. Both scripts are written in JavaScript. This guide provides these sections: User-password authentication overview is an overview of the user-password authentication process for a user session with a web application. It shows how the cloud service works with a set of JavaScript objects during the process. Writing a user map script describes how you can write an optional user map script to specify an application user log-on name and password for a user session. Writing a custom user-password script describes how to write the required custom user-password script to define an HTML response that authenticates the user for a user session. Scripting environment reference is a reference section for the objects, methods, and variables in the user map and user-password scripting environment. To write a custom user-password script, you need to know how to write code in JavaScript. For the vast majority of user-password web applications, the script is simple and you won t need to do anything more than what s described in Creating a generic user-password application profile. This guide is for the unusual application that might require more. User-password authentication overview When the cloud service authenticates a user to a user-password web application, the cloud service creates an HTML response for the user session that satisfies the requirements of the 1157

User-password authentication overview web application and presents necessary information about the current user. The following figure shows user-password authentication steps. Step descriptions follow. 1 The user clicks the web application in the user portal. 2 The user portal notifies the cloud service that the user wants a session with the web application. 3 The cloud service creates a set of JavaScript objects for this user-password user session: An Application object that contains the properties of the web application as they re defined in the web application profile. Those properties are defined using the generic user-password application template and include the application name, the URL, the icon, and others that appear in the template in the Admin Portal. The Application object is a read-only object. A script reads its properties through the object s Get() method. A LoginUser object that contains information about the user identity used to log onto the service provider: the web application log-on user name (which is not necessarily the user portal login user name) and so on. This is a read-write object that may be altered before it s used later in the custom user-password script to set the user name and password in the HTML response. A response object that defines the elements of the HTML response that the cloud service builds to send to the web application. The response object is a read/write object that the custom user-password script sets using the object s AddFormField() method. 4 The cloud service determines the web application log-on user name and password as specified in the generic user-password application template.the template specifies any one of these four methods: Cloud Manager user s guide 1158

User-password authentication overview The cloud service checks the user s Active Directory user record through the cloud connector and retrieves the specified attribute as the application user name. It prompts the user for the password. The cloud service then assigns the user name to the LoginUser.Username property and the password to the LoginUser.Password property. The cloud service caches the returned user-name attribute so that it doesn t have to retrieve it again from Active Directory for later identical queries. The cloud service also stores the password locally so the user need not enter it again for future user sessions with this application. The cloud service reads the shared single user name and password specified in the template and assigns them to LoginUser.Username and LoginUser.Password. The cloud service prompts the user for the web application log-on user name and password and assigns them to LoginUser.Username and LoginUser.Password. The cloud service stores the user name and password locally so the user need not enter them again for future sessions with this application. The cloud service executes the user map script set in the template, which creates a user name and assigns it to LoginUser.Username. The script may also create an optional password and assign it to LoginUser.Password. The cloud service prompts the user for a password in any case. If the script doesn t create its own password, the cloud service writes the entered password to LoginUser.Password and also stores the password locally so that the user need not enter it again for future sessions with this application. If the script creates its own password, the cloud service ignores the user s entered password. 5 The cloud service executes the custom user-password script to specify an HTML response for the user session. The script must include all the HTML response fields required by the web application and must provide appropriate values for those fields. Most applications require only a user field and a password field, but a few may require additional fields. The script uses response.addformfield() to define the elements in the private assertion object. 6 The cloud service creates an HTML response based on the properties of the response object. 7 The cloud service sends the HTML response to the user portal (or the browser running it). The HTML response includes a redirection that instructs the user portal to send the response to the web application at the URL specified in the web application s profile. The profile must contain a standard URL (set in the URL field of the generic userpassword application template) and may also contain a mobile URL (set in the Mobile URL field). If the request for connection comes from a mobile device, the cloud service redirects the HTML response to the mobile URL if one exists, otherwise the cloud service redirects the response to the standard URL. If the request for connection is not from a mobile device, the cloud service redirects the response to the standard URL. Chapter 2 User-password application scripting guide 1159

Writing a user map script 8 The user portal sends the HTML response to the specified URL. 9 The web application reads the HTML response and then (if the response checks out) logs the user onto the web application. Writing a user map script The user map script is JavaScript that you may create as an optional way to determine the user name and password used to log onto a web application. Entering a user map script To enter the user map script in the Application Settings tab of the generic user-password application template: 1 Under Account Mapping, select Use Account Mapping Script to open the user map script text panel. 2 Enter the script in the text panel. Incorrect JavaScript syntax in a line triggers a yellow symbol before the line number. 3 (Optional) Click Test. The Test Results window opens showing Account Mapping Details and the results of a Trace of the script. The Account Mapping Details list displays the attributes of the mapped LoginUser. 4 Click Save Changes. Read Creating a generic user-password application profile for more information about using the generic user-password application template. User map script elements The user map script is an optional way to determine the user name and password to present to a web application. Use it if the other user-mapping options won t provide what s required. Your script can examine current application and user properties for this user session and can use that information and any other factors to create a user name and password. The user map script must, at some point, assign a user name to the LoginUser.Username property. It may also assign a password to the LoginUser.Password property, but it s not required. If the script doesn t create and assign a password, the cloud service gets the password by requesting it from the user. It then assigns the password to the LoginUser.Password property. Cloud Manager user s guide 1160

Writing a user map script Retrieving application information If the user map script requires information about the current web application, it can retrieve properties from the Application object created for this user session. The method Application.Get() retrieves those properties. It takes as its argument a string that specifies the property whose value to retrieve. Application( Name ), for example, retrieves the name of the application. The Application object describes all of the Application object s properties that you may retrieve. These properties aren t typically used for determining a user name and password, although the application name may sometimes be useful. Retrieving LoginUser properties If the user map script requires information about the current user settings, it can examine the properties of the LoginUser object created for this user session. The LoginUser object describes the LoginUser properties. Several of these properties (LoginUser.GroupNames, for example) contain an array of group names of which the user is a member. These might be useful, depending on your requirements, for determining a user name. You might, for example, specify a single user name and password for anyone belonging to the admin group, and specify another single user name and password for anyone belonging to the sales group. Retrieving the user s Active Directory attributes The LoginUser object offers a single method, Get(), that can retrieve any one of the current user s Active Directory attributes. It takes as its argument a string that specifies the key of the attribute to retrieve. LoginUser.Get( mail ), for example, returns the user s email address as stored in Active Directory. When LoginUser.Get() executes, the cloud service contacts Active Directory through the cloud connector for the user s organization and retrieves the attribute. If, for example, a user has logged into the user portal as a member of the Acme organization, executing LoginUser.Get() during one of that user s log-on sessions contacts the Acme Active Directory service through the cloud connector set up in Acme s internal network. Specifying the user log-on name Once your script has created a web application log-on name as a string value, it must assign the name to the LoginUser.Username property. The script can assign the user name string directly to the property. Specifying the password The script is not required to create a password, and often does not. If it does create a password as a string value, it must assign the password to the LoginUser.Password property so the custom user-password script can read the password later. Chapter 2 User-password application scripting guide 1161

Writing a custom user-password script If the script doesn t assign a password value to LoginUser.Password, the cloud service determines the password value by asking the user for the password. The cloud service then assigns the user-provided password to LoginUser.Password. The cloud service also saves the password so that the user doesn t need to re-enter the password for later user sessions with the application. An example script This sample user map script creates a user name by adding the application name to the current user name in Active Directory. The script assigns the result to LoginUser.Username. LoginUser.Username = LoginUser.Get( user ) + # + Application.Get( Name ); When the user whose AD account is barney.blanton wants to log into the web application named Busfare, the script creates the user name barney.blanton#busfare. The script assigns the user name to LoginUser.Username, where the custom user-password script will find the user name later and use it for the HTML response. Because the script does not create and assign a password to LoginUser.Password, the cloud service uses the password it receives when it prompts the user. The cloud service assigns the password to LoginUser.Password and then stores the password locally for later user sessions. Writing a custom user-password script The custom user-password script specifies elements that must be present in the HTML response that starts the current user session with a web application. To write the script, you must know what HTML response fields the web application requires. The script must retrieve required information from the web application s profile and the user object, and must then specify the response fields and their values using the response.addformfield() method. After the script executes, the cloud service follows the script s specifications to create an HTML response. The custom user-password script is JavaScript. Each generic user-password application profile requires a custom user-password script. Entering a custom user-password script To enter the custom user-password script in the Advanced tab of the generic user-password application template: 1 Click Edit. 2 Enter the advanced script in the text panel, replacing the existing script or using it as a template script. Cloud Manager user s guide 1162

Writing a custom user-password script Incorrect JavaScript syntax in a line triggers a yellow symbol before the line number. Although the text panel offers this simple JavaScript support, if you re writing a script of any length you may want to use a specialized JavaScript editor and paste the results into the text panel. Note The template script present in the text panel by default will in almost all cases not work as a custom user-password script for a web application. You must modify or replace the script to meet the specific response field requirements of the web application. 3 (Optional) Click Test. The Advanced Script Results window opens showing SSO Token details and the results of a trace of the script. The SSO token is generated by the Admin Portal for the user to log in to the web application. 4 Click Save Changes. Read Creating a generic user-password application profile for more information about using the generic user-password application template. Determining HTML response requirements for the web application Each user-password web application typically requires its own set of fields in an HTML response. The help text for the generic user-password application template describes how to use a browser to discover these fields in Discovering the login URL and form data fields. You may also use other HTML POST analysis tools to discover required fields. Most user-password applications require only a user name field and a password field. Each application typically uses its own pair of field names for these fields, though, so it takes some customization to correctly set up the custom user-password script. The POST analysis may reveal extra required fields for a very few user-password applications. You may be able to guess what these fields must contain by their names and supply the proper values, but if not you ll need to contact the web application service provider s technical support or development team to ask for details. Retrieving information To retrieve information, the custom user-password script has access to the same JavaScript objects and global variables used in the user map script. Retrieving application information The read-only Application object created by the cloud service for a user session contains the properties defined in the application profile. Create a web application s profile using the generic user-password application template in the Admin Portal (described in Creating a generic user-password application profile). You must set appropriate application properties Chapter 2 User-password application scripting guide 1163

Writing a custom user-password script in the application profile before the custom user-password script can retrieve application properties successfully. The method Application.Get() retrieves application properties. It takes as its argument a string that specifies the property whose value to retrieve. Application.Get( Name ), for example, retrieves the name of the application. The Application object describes all the Application object s properties that you can retrieve. The following table shows two of the most useful application properties for userpassword information. Note that these property names are case-sensitive. Note also that one of the properties has a synonymous global variable that you can use in place of using Application.Get(). Property name Name Url The name of the application as entered in the Application Settings tab. The contact URL for the HTML response as specified in the URL field in the Application Settings tab. Synonymous with the global variable ServiceUrl. Retrieving LoginUser properties The properties of this user session s LoginUser object provide information about the user being authenticated for this user session. The following table describes the properties. Property name LoginUser.Username LoginUser.Password LoginUser.GroupNames LoginUser.EffectiveGroupN ames LoginUser.GroupDNs LoginUser.EffectiveGroupD Ns The username used to log the current user on to the web application. The cloud service determines the username for this user session depending on the Map to user Accounts setting in the Application Settings tab. This property is synonymous with the global variable UserIdentifier. The password used to log the current user on to the web application. The cloud service determines the password for this user session depending on the Map to user Accounts setting in the Application Settings tab. An array of group names for groups in which the user is a direct member (according to the user s Active Directory account). An array of group names for groups in which the user is an effective member (according to the user s Active Directory account). A user is an effective member of a group if he is either a direct member of the group or is a direct member of a group that is in turn a member of the group. An array of distinguished names for groups in which the user is a direct member. An array of distinguished names of groups in which the user is an effective member. Retrieving the user s Active Directory attributes The LoginUser object offers a single method, Get(), that can retrieve any one of the current user s Active Directory attributes. It takes as its argument a string that specifies the Cloud Manager user s guide 1164

Writing a custom user-password script name of the attribute to retrieve. LoginUser.Get( mail ), for example, returns the user s email address as stored in Active Directory. When LoginUser.Get() executes, the cloud service contacts Active Directory through the cloud connector for the user s organization and retrieves the attribute. If, for example, a user has logged into the user portal as a member of the Acme organization, executing LoginUser.Get() during one of that user s log-on sessions contacts the Acme Active Directory service through the cloud connector set up in Acme s internal network. Defining HTML response fields To define HTML response fields and set their values, use the response.addformfield() method. It s a simple method that takes two arguments: fieldname, a string that defines the name of a field to add to the HTML response. fieldvalue, a string that defines the value presented in this HTML response field. When executed, response.addformfield() adds the defined field and its value to the response object. The cloud service reads the response object s field definitions when it s time to connect to the web application and creates an HTML response with those fields and their values. It s best to supply the fieldvalue string by processing it through the global method encode(). This method ensures that the string is HTML-safe by properly encoding any special symbols such as @. The following example adds a field named username-field and sets its value to the current value of LoginUser.Username. The example uses encode() to ensure that whatever value is supplied is HTML safe: response.addformfield("username-field", encode(loginuser.username)); The custom user-password script should at least define a user-name field and a password field using whatever field names the web application requires. If the application requires additional fields, use response.addformfield() to name those fields and set their values. You ll find the response object and encode() method both described in Scripting environment reference. Using the custom user-password script template You can use the sample user-password script in the Advanced tab as a template for your own custom user-password script. The first two lines set values for the fields username-field and password-field, which are probably not the field names required by a specific userpassword web application. Simply replacing those field names with the field names an application requires will satisfy most applications. The third and forth lines add a third and fourth field to the response, which probably aren t necessary. You can delete them if they aren t. If an application requires additional fields, modify these lines with the required field names and values. Chapter 2 User-password application scripting guide 1165

Scripting environment reference To see further examples of custom user-password scripts, select any already-defined userpassword application profile in the Apps panel of the Admin Portal, then view its Advanced tab. The tab displays the custom script used to connect to that application. Scripting environment reference The cloud service creates a set of JavaScript objects, global variables, and global methods for each user-password user session. These objects provide information that a user map script or a custom user-password script can read and act on. Some of the objects also accept values that specify elements with the HTML response that the cloud service presents to a web application. This section describes the user-session JavaScript environment in which the user map script and the custom user-password script execute. The section describes each available object and its public properties and methods. It also describes available global variables and global methods. The LoginUser object The cloud service creates a single LoginUser object for each user session for a userpassword web application. The object is an instance of the LoginUser class, and is a read/ write object. The LoginUser object s properties describe the user as he or she is presented to the web application. The following table describes those properties. Property name LoginUser.Username LoginUser.Password LoginUser.GroupNames LoginUser.EffectiveGroupN ames LoginUser.GroupDNs LoginUser.EffectiveGroupD Ns The username used to log the current user on to the web application. The cloud service determines the username for this user session depending on the Map to User Accounts setting in the Application Settings tab. The password used to log the current user on to the web application. The cloud service determines the password for this user session depending on the Map to User Accounts setting in the Application Settings tab. This property is synonymous with the global variable LoginPassword. An array of group names for groups in which the user is a direct member (according to the user s Active Directory account). An array of group names for groups in which the user is an effective member (according to the user s Active Directory account). A user is an effective member of a group if he is either a direct member of the group or is a direct member of a group that is in turn a member of the group. An array of distinguished names for groups in which the user is a direct member. An array of distinguished names of groups in which the user is an effective member. Cloud Manager user s guide 1166

Scripting environment reference The LoginUser object has a single method that a script may call: Method name LoginUser.Get(ADkey) This method returns any one of the current user s Active Directory attributes. It takes as its argument a string that specifies the key of the attribute to retrieve. An example: LoginUser.Get( mail ) returns the user s email address as stored in the user s Active Directory account. The Application object The cloud service creates a single Application object for each user session for a userpassword web application. The object is an instance of the ReadOnlyDataEntity class, and is a read-only object. The Application object s properties describe the web application as it s defined in the application profile. You create a web application s profile in the Admin Portal using the generic user-password application template (described in Creating a generic user-password application profile). The Application object does not have any publicly accessible properties. The script accesses the object s properties using the object s single public method, Application.Get(). Method Name Application.Get(property) The following section describes the property arguments this method can take. Application properties This method returns an Application object property. It takes as its argument a string that specifies the property to return. An example: Application.Get( Name ) returns the name of the application as entered in the Application Settings tab. The Application.Get() method may take the following property names as an argument. Each argument returns a different application property. The property names are casesensitive. Property Name _PartitionKey _RowKey Icon Name The customer ID used to establish the user session. An example: BZ284. The UUID (universally unique identifier) of the application. The text description of the web application entered in the description field of the Application Settings tab. The graphic file used as the icon for this application as set in the Application Settings tab. The name of the application as entered in the Application Settings tab. Chapter 2 User-password application scripting guide 1167

Scripting environment reference Property Name TemplateName Url UserName Strategy UserPassScript WebAppType The type of generic application template used to define this web application s profile. Possible return values: Generic SAML Generic User-Password The contact URL specified in the URL field in the Application Settings tab. Synonymous with the global variable ServiceUrl. The technique specified in the Application Settings tab to determine the user name for a user session. Possible return values: ADAttribute: the cloud service sets the user name to the specified AD attribute of the current user. If this is a user-password web application, the cloud service asks the user to enter a password the first time the user asks for a connection to this web application. The cloud service stores the password for subsequent connections. Fixed: the cloud service sets the user name to the value entered in the Application Settings tab. If this is a user-password web application, this technique also sets the password to the value entered in the Application Settings tab. SetByUser: the cloud service asks the user to enter a user name the first time the user asks for a connection to this web application. If this is a user-password web application, the cloud service also asks for a password. The cloud service stores the user name (and password if applicable) for subsequent connections. UseScript: the cloud service executes the user map script to determine the user name. The custom user-password script set in the Advanced tab. The authentication method used by the web application. Possible return values: SAML UsernamePassword The response object The cloud service creates a single response object for each user session for a user-password web application. The object is an instance of the WebSignInResponse class and is a readwrite object. The response object defines the HTML response that the cloud service creates to send to the web application. The object does not have any publicly accessible properties. The script Cloud Manager user s guide 1168

Scripting environment reference defines HTML response fields using the object s single public method, response.addformfield(). Method Name response.addformfield( fieldname, fieldvalue) An example of setting an HTML response field: This method defines an HTML response field to add to the HTML response for this user session. The method takes as its first argument a string that specifies the property to return. Its arguments are: fieldname, a string that defines the name of the HTML response field. fieldvalue, a string that defines the value presented in the HTML response field. It s best to supply this string processed through the global method encode(), which ensures that the string is HTML-safe by properly encoding any special symbols such as @. response.addformfield("username", encode(loginuser.username)); This example adds an HTML response field named username and sets its value to the current user name specified in the LoginUser object. The encode() method ensures that there are no non-html-compliant characters in the string returned by the attribute LoginUser.Username. Global variables The cloud service creates a set of global variable for each user session. These variables are synonyms for common attributes of the LoginUser and Application objects, and are a convenience: you can use a global variable instead of specifying a LoginUser attribute or using Application.Get() to read an Application attribute. Global Variable ApplicationUrl LoginPassword ServiceUrl A read-only variable that contains the contact URL specified in the URL field in the Application Settings tab. Synonymous with the Application attribute Url. A read-write variable that contains the password used to log the current user on to the web application, used only for a user-password application. The cloud service determines the password for this user session depending on the Map to User Accounts setting in the Application Settings tab. Synonymous with the attribute LoginUser.Password. A read-only variable that contains the contact URL specified in the URL field in the Application Settings tab. Synonymous with the Application attribute Url. Chapter 2 User-password application scripting guide 1169

Scripting environment reference Global functions The cloud service provides global functions available in a user session for a user-password application. Function Name encode(stringvalue) Hash(stringvalue, hashalgorithm, x2 ) This function takes a string as its argument and returns an HTML-safe version of the string for transmission via HTML. It converts each non- HTML-safe character into a string that the receiver will interpret as the original character. This function takes a string and hash algorithm as arguments and returns a hash in the specified algorithm. Supported algorithms are: SHA-1 SHA-256 MD5 For example: var hashedvalue = Hash("raw_string", "sha256", "x2"); Cloud Manager user s guide 1170