Writing a Custom SAML Script

You can write SAML response scripts in JavaScript in the Custom Logic area of the SAML Response page of a SAML application.

The custom SAML script specifies elements that must be present in the SAML assertion used to start the current user session with a web application. To write the script, you must know what SAML elements 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 SAML elements and their values using assertion-set methods. After the script executes, the Privileged Access Service follows the script’s specifications to create a SAML assertion and its enclosing SAML response.

A SAML script is required for each application profile created using the custom SAML application template. To see examples of SAML scripts used to connect to web services, open the application profile for any SAML application in the Apps panel of Admin Portal. Click the SAML Response tab to see the application’s SAML script.

To assist with writing SAML response scripts, the SAML Script Editor includes a context-sensitive autocomplete feature.

Determining SAML requirements for the web application

Each SAML web application typically requires its own set of SAML elements in a SAML assertion. Although many of the elements will be the same from application to application, there are enough variations that one script won’t cover all applications.

To write a script for a SAML web application, you must find out from the application’s publishers what its SAML requirements are. If the application is a large public application, its publishers may present their SAML requirements on their web site. As an example, Salesforce publishes SAML requirements for authentication here. Most large public SAML web applications, however, will probably already be in the app catalog so you won’t need to add them via the generic SAML application template.

For web applications that don’t provide their SAML requirements publicly, you’ll have to contact technical support or their development team to ask about their SAML requirements. This requires some familiarity with SAML. Reading through a public SAML application’s SAML requirements (such as Salesforce’s requirements) is a good start to understanding what a typical SAML application requires.

Retrieving information

The custom SAML script has access to the same JavaScript objects, global methods, and global variables that the user map script has along with some additional application-set methods used to specify SAML elements. To retrieve application and user information, use the Application and LoginUser objects that the Privileged Access Service creates for a user session.

Application object

The Privileged Access Service creates a single Application object for each SAML user session. The object is an instance of the ReadOnlyDataEntity class, and is a read-only object.

The Application object’s properties describe the SAML web application as it’s defined in the application profile. Create a SAML web application profile in the Admin Portal using the customSAML application template (described in Custom SAML Applications.

A script accesses the object’s properties using the object’s single public function.

The Application.Get() function may take the following property names as an argument. Each argument returns a different application property. The property names are case-sensitive.

LoginUser object

The Privileged Access Service creates a single LoginUser object for each SAML user session. The object is an instance of the LoginUser class, and is a read/write object.

The function LoginUser.Get() retrieves any one of the current user’s 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 Privileged Access Service contacts the source directory through the connector for the user’s organization and retrieves the attribute. If, for example, an Active Directory user has logged into the Admin 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 connector set up in Acme’s internal network. If a user has logged in, executing LoginUser.Get() queries the Cloud Directory Service (CDS).

Not all attributes are common between directory services. If you have uses managed by different directory services (for example, AD and LDAP), use the LoginUser.ServiceType or Login.User.ServiceName properties to determine the user’s source directory and then get the appropriate attribute key. Refer to LoginUser Object for more information.

Example

if(LoginUser.ServiceType == 'LDAPProxy'){

UserIdentifier = LoginUser.Get('uid');

} else {

UserIdentifier = LoginUser.Username;

}

Explanation

The preceding example checks to see if the user is managed by LDAP. If the user’s service type is LDAPProxy, the script gets the current user’s UID attribute, otherwise it uses the LoginUser.Username property.

The LoginUser object has the following methods:

The LoginUser object’s properties describe the user as he or she is presented to the web application. The following table describes those properties.

Specifying SAML assertion elements

The Privileged Access Service offers a group of global assertion-set methods in a user session. These methods set the attributes of the private assertion object, which specifies how the Privileged Access Service will construct the SAML assertion for this user session. Most of these methods take as an argument the value for a specific SAML assertion element. setIssuer(), for example, accepts an entity ID and uses it to specify the issuer URL in the SAML assertion.

Two of the assertion-set methods, setAttribute() and setAttributeArray(), specify a SAML response attribute by name and then specify a value for that attribute that is either a single argument or an array.

The following table lists the most commonly used assertion-set methods. Global Methods describes these methods in full.

To enable autocomplete suggestions in the SAML Script Editor

1. In the SAML Script Editor, press Ctrl+Spacebar.

   A menu appears showing available functions.

   

2. Use the arrow keys to select from available options, then press Enter to select the option.

   Note the help text that appears with each selection.

   

   In addition, each available selection is coded based on type. For example:

   • F: Function

   • S: String

   • O: Object

     

3. Continue editing the script, using Ctrl+Spacebar as necessary for suggestions.

   If you have already entered most of the function and only one possibility remains, Ctrl+Spacebar completes the string rather than showing available choices.

To enter a custom SAML script in the SAML Response page

1. Scroll down to the Custom Logic area and click in the SAML Script Editor where you want to edit the script.

   

2. Enter the SAML script in the text panel, replacing the existing script or using it as a template script.

   Remember that you can press Ctrl + Spacebar to enable the autocomplete feature. In addition, Script Help showing available methods, objects, and variables is available to the right of the Script Editor.

   

   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.

   The template script present in the text panel by default will not work as a custom SAML script. You must modify or replace the script to meet the specific requirements of the web application.

3. (Optional) Click Preview SAML Response, then select a user to preview the results of the script for that user.

   

   The Preview SAML Response 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 .

   Read Custom SAML Applications for more information about using the generic SAML application template.