Chapter 4 SAML application scripting - Centrify 4 SAML application scripting ... For an introduction...

Chapter 4

SAML application scripting

You can use the custom SAML application template (described in Custom SAML applications) to add a SAML-enabled web application to the app catalog. This template creates a SAML application profile for a web application that defines how the Centrify Directory Service presents an authenticated user to the web application via a SAML assertion.

Each SAML application profile requires a custom SAML script. The script defines how the Centrify Directory Service creates and presents a SAML assertion 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 for use in the SAML assertion. Both scripts are written in JavaScript.

This guide provides these sections: SAML authentication overview is an overview of the SAML authentication process for a

user session with a web application. It shows how the Centrify Directory Service works with a set of JavaScript objects during the process.

Writing a user map script describes how to write an optional user map script to specify an application user log-on name for a user session.

Writing a custom SAML script describes how to write the required custom SAML script to define a SAML assertion for a user session.

Scripting environment reference is a reference section for the objects, methods, and variables in the user map and SAML scripting environment.

To write a SAML script, you need to know how to write code in JavaScript. You also need to know the basics of SAML authentication to understand how to specify a SAML assertion. This guide provides some guidance about SAML configuration values, but for specifics you can consult the SAML specifications provided at http://saml.xml.org/saml-specifications. For an introduction to SAML, try the overviews provided at http://saml.xml.org/wiki/saml-introduction.

SAML authentication overviewWhen a user asks to connect to a SAML-enabled web application in the user portal, the traditional SAML roles are these: The principal is the user, who’s already been authenticated in the user portal through

the Centrify Directory Service. The principal is using a web browser (connected to the

20

http://saml.xml.org/saml-specifications

http://saml.xml.org/wiki/saml-introduction


http://saml.xml.org/saml-specifications



SAML authentication overview

user portal) or the mobile application as his user agent to request a web application connection.

The identity provider is the Centrify Directory Service, which provides a SAML assertion that presents the user as an authenticated principal.

The service provider is the web application host that receives the SAML assertion and decides whether or not to grant resource access to the principal (the user).

The SAML authentication process

When the Centrify Directory Service presents a user to a SAML-enabled web application, it creates a SAML assertion for the user session that satisfies the requirements of the service provider (the web application host) and presents necessary information about the current user. The following figure shows the steps the Centrify Directory Service takes when it authenticates a user to a SAML application added to the app catalog using the generic SAML application template. The steps follow.

1 The user clicks the web application in the user portal.

Chapter 4 • 21

SAML authentication overview

2 The user portal notifies the Centrify Directory Service that the user wants a session with the web application.

3 The Centrify Directory Service creates a set of JavaScript objects for this SAML 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 SAML application template and include the application name, the URL, the issuer, the IdP sign-in URL, 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 user identity recognized by the web application (which is not necessarily the user portal login user name) and so on. This is a read-write object that the Centrify Directory Service or the user map script may alter before it’s used later in the custom SAML script to set the user name in the SAML assertion.

A private assertion object that defines the elements of the SAML assertion that the Centrify Directory Service builds to send to the web application. This object isn’t visible to the custom SAML script, but the script may set the assertion object’s properties using a family of global “set” methods (described later).

4 The Centrify Directory Service determines the web application log-on user name as it was specified in the generic SAML application template. The template specifies one of these three methods:

The Centrify Directory Service checks the user’s Active Directory user record through the connector, retrieves the specified attribute as the application user name, then assigns the user name to the LoginUser.Username property. The directory service caches the returned attribute so that it doesn’t have to retrieve it again from Active Directory for later identical queries.

The directory service reads the shared single user name specified in the template and assigns it to LoginUser.Username.

The directory service executes the user map script set in the template, which creates a user name and assigns it to LoginUser.Username.

5 The directory service executes the custom SAML script to specify a SAML assertion for the user session.

The script must define all the SAML assertion elements required by the web application. The script uses the global assertion-set methods to define the elements in the private assertion object.

6 The directory service creates a SAML assertion based on the properties of the private assertion object and includes the assertion in a SAML response.

Admin Portal user’s guide 22

Writing a user map script

7 The directory service signs the SAML response (or the SAML assertion within the response, depending on what’s specified in the custom SAML script). It uses the directory service certificate private key unless the application profile is set to provide a different certificate. (Certificate assignment is set in the Application Settings tab of the generic SAML application template.)

8 The directory service sends the SAML response to the user portal (or the browser running it). The SAML response has a redirection that instructs the user portal to send the response to the web application at the URL specified in the SAML assertion.

9 The user portal sends the SAML response to the specified URL.

10 The web application reads the SAML response and then (if the key and assertion check out) logs the user into the web application.

Writing a user map scriptThe user map script is JavaScript that you may set up as an optional way to determine the user name 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 SAML 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 Custom SAML applications for more information about using the generic SAML application template.

User map script elements

The user map script is an optional way to determine the user name to present to a web application 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. The user map script must, at some

Chapter 4 • 23

Writing a user map script

point, assign a user name to the LoginUser.Username property, where it’s retrieved later to create a SAML assertion.

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, 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 for anyone belonging to the admin group, and specify another single user name for anyone belonging to the sales group.

You can also use the LoginUser.ServiceName and LoginUser.ServiceType properties to distinguish between directory sources. For example, if the user is managed by Active Directory, some attributes might be different than users managed by LDAP (userprincipalname for AD and UID for LDAP). Use either of these properties to determine the user’s directory source.

Retrieving the user’s directory attributes

The LoginUser object offers a single method, Get(), that 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 Centrify Directory 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 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 connector set up in Acme’s internal network. If a directory service user has logged in, executing LoginUser.Get() queries the Cloud Directory Service (CDS).


Writing a custom SAML script

Note 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 The LoginUser object for more information.

Exampleif(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.

Specifying the user log-on name

Once your script has created a web application log-on name as a string value, it must assign it to the LoginUser.Username property. The script can assign the user name string directly to the property.

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 SAML script will find the user name later and use it for the SAML assertion.

Writing a custom SAML scriptThe 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 Centrify Directory Service follows the script’s specifications to create a SAML assertion and its enclosing SAML response.

Chapter 4 • 25


The custom SAML script is JavaScript and is required for each application profile created using the generic 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.

Entering a custom SAML script

To enter the custom SAML script in the SAML Response tab of the generic SAML 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.

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 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 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 Custom SAML applications for more information about using the generic SAML application template.

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 at http://login.salesforce.com/help/doc/en/sso_saml_idp_values.htm. 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.


http://login.salesforce.com/help/doc/en/sso_saml_idp_values.htm





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 the 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 Centrify Directory Service creates for a user session.

Retrieving application information

The read-only Application object created by the Centrify Directory Service for a user session contains the properties set in the application profile. Create a web application’s profile using the generic SAML application template in the Admin Portal (described in Custom SAML applications). You must set appropriate application properties in the application profile before the custom SAML 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 some of the most useful application properties for SAML information. Note that these property names are case-sensitive. Note also that some of the properties have a synonymous global variable that you can use in place of using Application.Get().

Retrieving LoginUser properties

The properties of this user session’s LoginUser object provide information about the user being authenticated for this SAML user session. The LoginUser object describes all of the

Property name Description

Name The name of the application as entered in the Application Settings page.

Url The SAML contact URL specified in the URL field in the Application Settings page. Synonymous with the global variable ServiceUrl.

Issuer The entity ID specified in the Issuer field of the Application Settings page. Synonymous with the global variable Issuer.

Chapter 4 • 27


LoginUser properties. The following table describes some of the most useful properties for SAML.

Retrieving the user’s directory attributes

The LoginUser object offers a single method, Get(), that 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 Centrify Directory 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 user portal as a member of the


LoginUser.Username The user name used to log the current user on to the web application. The user name is determined by the Centrify Directory Service 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.

LoginUser.GroupNames 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.

This property returns the same value as LoginUser.EffectiveGroupNames.

LoginUser.GroupNames2 An array of group names for groups in which the user is an effective member (according to the user’s Active Directory account), returning only the user’s groups’ name attribute.

LoginUser.EffectiveGroupNames 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.

This property returns the same value as LoginUser.GroupNames.

LoginUser.GroupDNs An array of distinguished names of groups in which the user is an effective member.

This property returns the same value as LoginUser.EffectiveGroupDNs.

LoginUser.EffectiveGroupDNs An array of distinguished names of groups in which the user is an effective member.

This property returns the same value as LoginUser.GroupDNs.

LoginUser.ServiceType The type of directory service managing the user’s user object. Possible values are:

• ADProxy

• LDAPProxy

• CDS (Cloud Directory Service)

• FDS (Federated Directory Service)

LoginUser.ServiceName The name of the directory service managing the user’s user object. These values are set by the network administrator. This property is useful in environments with more than one LDAP proxy.



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).

Note 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 The LoginUser object for more information.

Exampleif(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.

Specifying SAML assertion elements

The Centrify Directory 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 Centrify Directory 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. Assertion-set methods describes these methods in full.

Global Method Description

setVersion(samlVersion) Specifies the version of the SAML assertion. “1” specifies version 1.1, “2” specifies version 2.0. The default is 2 if this method isn’t present in the script.

setIssuer(issuer) Specifies the issuer in the SAML assertion. Typically a URL provided by retrieving the Application property Issuer or by using the property’s synonymous variable Issuer.

Chapter 4 • 29


setSubjectName(username) Specifies the subject in the SAML assertion, which is the log-on name used for the web application. It’s typically provided by retrieving the LoginUser.Username property or by using the property’s synonymous variable UserIdentifier.

If you have multiple directory sources, use the LoginUser.ServiceName or LoginUser.ServiceType properties to set an appropriate subject name. For example:

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

setSubjectName(LoginUser.Get('uid'));

} else {

setSubjectName(LoginUser.Username);

}

setAudience(audience) Specifies the audience in an audience restriction in the SAML assertion. This typically takes the entityID URL such as “https://login/myapp.com”.

setRecipient(recipient) Specifies the recipient in the SAML assertion’s SubjectConfirmationData element. This typically takes the ACS/entityID URL such as https://login/myapp.com”.

setSignatureType(signingPref ) Specifies whether the SAML assertion should be signed, or the SAML response that contains the assertion. The two possible values are “Response” or “Assertion”. The default is “Response” if this method isn’t present in the script.

setServiceUrl(targetUrl) Specifies the value for the TARGET form element (the resource requested for the user session) when posting the SAML response. This is typically a URL that is the same as that used for the setHttpDestination() method, typically retrieved through the Application property Url or by using the property’s synonymous variable ServiceUrl.

setHttpDestination(responseUrl) Specifies the URL to which to post the SAML response in the response’s HTTP POST binding (the value in the “action=” argument). Typically a URL provided by retrieving the Application property Url or by using the property’s synonymous variable ServiceUrl.

You can repeat this assertion-set method at the end of the script using a string to specify an absolute URI if you want to post the SAML response to a specific address, such as a proxy provided by a cloud access security broker (CASB).

setDigestMethodAlgorithm('algorithm')

Specifies the digest method algorithm to use in the SAML response. Possible values are:

• sha1

• sha256

• sha384

• sha512

The default value is the same as the SignatureMethod algorithm for the signing certificate selected for the app. For example, setDigestMethodAlgorithm('sha256').




Using the custom SAML script template

You can use the sample SAML script in the SAML Response tab as a template for your own custom SAML script. It sets the most common SAML elements. Some of these elements it sets by retrieving values from the Application and LoginUser objects. Others it simply specifies by providing a string such as a URL.

These provided sample string values won’t work for your particular SAML web application; you need to fill them in with values that will work. You may also have to trim out some of assertion-set methods if they specify SAML elements that are not required by your web application, or you may have to add new methods for elements that are required but aren’t in the sample script.

Sample: Using custom user attributes

As part of configuring SAML applications, you can use JavaScript to define if users can be authenticated by the service provider (SP) using the custom attribute. In the sample script below, we are defining that all users with access to this application can be authenticated by the service provider (SP) using the custom attribute (IsFull_TimeEmployee). “FullTime” is the corresponding SP attribute.var um = module("User");var u = um.GetUserData(null);var IsFull_TimeEmployee = u.IsFull_TimeEmployee;setAttribute("FullTime", IsFull_TimeEmployee);

The sample script below is specific to B2B SAML applications:var fc =LoginUser.Get ("IsFull_TimeEmployee");

setAttribute(elementName, elementValue)

This method is needed if the service provider requires a specific value, such as email, to be passed within the SAML assertion.

Takes two arguments. The first is a string that specifies the name of a SAML response attribute to set, the second specifies the attribute value. For example, setAttribute(“Email”, LoginUser.Get(“mail”)); specifies the SAML attribute named “Email” to be set to the current user’s email address.

Note: Because Javascript treats the \ (backslash) character as an escape character, if you want to use a \ in your elementValue, you must precede it with another \.

For example, if you want to use an elementValue of string "DOMAIN\user" in a SAML response attribute named "exampleAttr", you write:

setAttribute("exampleAttr", "DOMAIN\\user");

setAttributeArray(elementName, elementArray)

Takes two arguments. The first is a string that specifies the name of a SAML response attribute to set, the second specifies an array as the attribute value. For example, setAttributeArray('Groups', LoginUser.GroupNames); specifies the SAML attribute named “Groups” to be set to an array of group names in which the current user is a direct member.

Note: Because Javascript treats the \ (backslash) character as an escape character, if you want to use a \ in an elementValue in the elementArray, you must precede it with another \.


Chapter 4 • 31

Scripting environment reference

setAttribute("FullTime", IsFull_TimeEmployee);

Scripting environment referenceThe Centrify Directory Service creates a set of JavaScript objects, global variables, and global methods for each SAML user session. These objects provide information that a user map script or a custom SAML script can read and act on. Some of the objects also accept values that specify elements with the SAML assertion that the Centrify Directory Service presents to a web application.

This section describes the SAML user-session JavaScript environment in which the user map script and the custom SAML 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 Centrify Directory 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 LoginUser object’s properties describe the user as he or she is presented to the web application. The following table describes those properties.


LoginUser.Username The user identity presented in the SAML assertion to the web application. The Centrify Directory Servicedetermines the user ID for this user session depending on the “Map to User Accounts” setting in the Application Settings tab. (These settings determine the user name, which is the user ID presented in the SAML assertion.)

LoginUser.FirstName The first name of the user presented in the SAML assertion to the web application. Note the following special cases for parsing this attribute for users in directory services that do not have the FirstName attribute, such as Centrify Directory:

• FirstName attribute is parsed from the first string of DisplayName.

• If DisplayName is a single string, the same string is used for the FirstName and LastName attributes.

• If DisplayName is null, FirstName and LastName return as null. SAML apps that require non-empty values will fail to launch in this case.

LoginUser.LastName The last name of the user presented in the SAML assertion to the web application. Note the following special cases for parsing this attribute for users in directory services that do not have the LastName attribute, such as Centrify Directory:

• The LastName attribute is parsed from the last string of DisplayName. Any additional strings between the first string and the last string are ignored.

• If DisplayName is a single string, the same string is used for the FirstName and LastName attributes.

• If DisplayName is null, FirstName and LastName return as null. SAML apps that require non-empty values will fail to launch in this case.



The LoginUser object has the following methods:

LoginUser.GroupNames 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.

This property returns the same value as LoginUser.EffectiveGroupNames.

LoginUser.GroupNames2 An array of group names for groups in which the user is an effective member (according to the user’s Active Directory account), returning only the user’s group’ ‘name attribute.

LoginUser.EffectiveGroupNames 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.

This property returns the same value as LoginUser.GroupNames.

LoginUser.GroupDNs An array of distinguished names of groups in which the user is an effective member.

This property returns the same value as LoginUser.EffectiveGroupDNs.

LoginUser.EffectiveGroupDNs An array of distinguished names of groups in which the user is an effective member.

This property returns the same value as LoginUser.GroupDNs.

LoginUser.ServiceType The type of directory service managing the user’s user object. Possible values are:

• ADProxy

• LDAPProxy

• CDS (Cloud Directory Service)

• FDS (Federated Directory Service)

LoginUser.ServiceName The name of the directory service managing the user’s user object. These values are set by the network administrator. This property is useful in environments with more than one LDAP proxy.

Method name Description

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.


Chapter 4 • 33


The Application object

The Centrify Directory 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 generic SAML application template (described in Custom SAML applications).

The Application object does not have any publicly accessible properties. A script accesses the object’s properties using the object’s single public method.

The following section describes the property arguments this method can take.

Application properties

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

LoginUser.GetValues(ADkey) This method returns an array with all values of an Active Directory attribute with multiple values for the current user. It takes as its argument a string that specifies the key of the attribute to retrieve. For example, the line

setAttributeArray('proxies',

LoginUser.GetValues('proxyAddresses'));

sets an attribute array named proxies that includes all values for the logged in user for the AD key proxyAddresses.

LoginUser.GetGroupAttributeValues(ADkey)

This method returns the values of the current user's groups specified AD attribute. It takes as its argument a string that specifies the key of the attribute to retrieve. An example: LoginUser.GetGroupAttributeValues(“sAMAccountName”) returns the user’s groups sAMAccountName value as stored in the user’s Active Directory account.

Method Name Description

Application.Get(property) 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.

Property Name Description

_PartitionKey The customer ID used to establish the user session. An example: BZ284.

_RowKey The UUID (universally unique identifier) of the application.

Description The text description of the web application entered in the description field of the Application Settings tab.

Method name Description



Global variables

The Centrify Directory Service creates a set of global variables for each SAML 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.

Icon The graphic file used as the icon for this application as set in the Application Settings tab.

Issuer The entity ID specified in the Issuer field of the Application Settings tab. Synonymous with the global variable Issuer.

Name The name of the application as entered in the Application Settings tab.

SamlScript The custom SAML script set in the SAML Response tab.

TemplateName The type of generic application template used to define this web application’s profile. Possible return values:

• Generic SAML

• Generic User-Password

Url The contact URL specified in the URL field in the Application Settings tab. Synonymous with the global variable ServiceUrl.

UserName Strategy The technique specified in the Application Settings tab to determine the user name (user identity) for a user session. Possible return values:

• ADAttribute: the Centrify Directory Service sets the user name to the specified AD attribute of the current user. The Centrify Directory Service queries the connector for the AD attribute. The Centrify Directory Service caches the user name so that it doesn’t have to query the connector for this user’s future sessions.

• Fixed: the Centrify Directory Service sets the user name to the value entered in the Application Settings tab.

• UseScript: the Centrify Directory Service executes the user map script to determine the user name.

WebAppType The authentication method used by the web application. Possible return values:

• SAML

• UsernamePassword

Global Variable Description

ApplicationUrl A variable that contains the string value specified in the Assertion Consumer Service URL field in the Application Settings tab. Synonymous with the Application attribute “Url.”

AssertionConsumerServiceIndex A variable in the SAML request that contains the Assertion Consumer Service index value used to identify the Assertion Consumer Service URL.

This variable is mutually exclusive with AssertionConsumerServiceURL.

Property Name Description

Chapter 4 • 35


Global methods

The Centrify Directory Service provides a set of global methods available in a SAML user session that specify elements within a SAML assertion.

Assertion-set methods

Assertion-set methods set the attributes of the private SAML assertion object in a user session. The assertion object specifies how the Centrify Directory Service constructs the SAML assertion for this SAML 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. Use these methods to add SAML assertion elements that can’t be specified by any of the other assertion set methods.

AssertionConsumerServiceURL A variable that contains the specific Assertion Consumer Service URL that specifies the URL to which the Centrify Identity Services sends the SAML response.

This variable is mutually exclusive with AssertionConsumerServiceIndex.

Issuer A variable that contains the entity ID specified in the Issuer field of the Application Settings tab. Synonymous with the Application attribute “Issuer.”

ServiceUrl A variable that contains the string value specified in the Assertion Consumer Service URL field in the Application Settings tab. Synonymous with the Application attribute “Url.”

Global Variable Description



The following table lists global assertion-set methods available in a user session.


setAttribute(elementName, elementValue)

Sets a specified SAML assertion element to a value. Takes two arguments. The first is a string that specifies the name of a SAML assertion element to set, the second specifies that attribute’s value. For example, setAttribute(“Email”, LoginUser.Get(“mail”)); specifies the SAML assertion element named “Email” to be set to the current user’s email address.

Note: Because Javascript treats the \ (backslash) character as an escape character, if you want to use a \ in your elementValue, you must precede it with another \.

For example, if you want to use an elementValue of string "DOMAIN\user" in a SAML response attribute named "exampleAttr", you write:

setAttribute("exampleAttr", "DOMAIN\\user");

setAttributeArray(elementName, elementArray)

Sets a specified SAML assertion element to an array. Takes two arguments. The first is a string that specifies the name of a SAML assertion element to set, the second specifies an array as that attribute’s value. For example, setAttributeArray('Groups', LoginUser.GroupNames); specifies the SAML assertion element named “Groups” to be set to an array of group names in which the current user is a direct member.

Note: Because Javascript treats the \ (backslash) character as an escape character, if you want to use a \ in an elementValue in the elementArray, you must precede it with another \.

setAudience(audience) Specifies the audience in an audience restriction in the SAML assertion. This argument typically takes a URL such as “https://login/myapp.com”.

setAuthenticationMethod(authenticationUri)

Specifies the type of authentication used to authenticate the user. This takes a URI as described in section 2.4.3 of the SAML 2.0 core specification. The same specification lists possible URI values in section 7.1. An example: urn:oasis:names:tc:SAML:1.0:am:password specifies that the user was authenticated via password.

setHttpDestination(responseUrl) Specifies the URL to which to post the SAML response in the response’s HTTP POST binding (the value in the “action=” argument). Typically a URL provided by retrieving the Application property Url or by using the property’s synonymous variable ServiceUrl.

You can repeat this assertion-set method at the end of the script using a string to specify an absolute URI if you want to post the SAML response to a specific address, such as a proxy provided by a cloud access security broker (CASB).

setIssuer(issuer) Specifies the issuer in the SAML assertion. Typically a URL provided by retrieving the Application property Issuer or by using the property’s synonymous variable Issuer.

setNameFormat(format) Specifies the Format value (the value following “Format=”) in the SAML assertion’s NameID element. This element is only used in a SAML 2.0 assertion.

setRecipient(recipient) Specifies the recipient in the SAML assertion’s SubjectConfirmationData element. This typically takes a URL such as https://login/myapp.com”.

Chapter 4 • 37


setDigestMethodAlgorithm('algorithm')

Specifies the digest method algorithm to use in the SAML response. Possible values are:

• sha1

• sha256

• sha384

• sha512

The default value is the same as the SignatureMethod algorithm for the signing certificate selected for the app. For example, setDigestMethodAlgorithm('sha256').

setRelayState(relayState, overwrite)

Takes two arguments. The first is a relayState parameter to send with the SAML response if specified by the service provider. This parameter is specified in section 3.6.3.1 of “Bindings and Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0.”

The second is an optional boolean overwrite parameter that specifies whether the first relayState argument overwrites the SP’s RelayState. For example,

• setRelayState("/myapps-relay-state", true): always overwrites the SP's RelayState as /myapps-relay-state

• setRelayState("/myapps-relay-state", false): does NOT overwrite the SP's RelayState

• setRelayState("/myapps-relay-state") is the same as setRelayState("/myapps-relay-state", false)

setServiceUrl(targetUrl) Specifies the value for the TARGET form element (the resource requested for the user session) when posting the SAML response. This is typically a URL that is the same as that used for the setHttpDestination() method, typically retrieved through the Application property Url or by using the property’s synonymous variable ServiceUrl.

setSignatureType(signingPref ) Specifies what should be signed using a certificate: the SAML assertion or the SAML response that contains the assertion. The two possible values are “Response” or “Assertion”. The default is “Response” if this method isn’t present in the script.

setSubjectConfirmationMethod(methodUri)

Specifies the SAML confirmation method identifier for the SAML assertion’s binding. This takes a URI as described in section 4.1.2.1 of “Bindings and Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0.” An example: urn:oasis:names:tc:SAML:1.0:cm:bearer specifies the Bearer confirmation method.

setSubjectName(username) Specifies the subject in the SAML assertion, which is the user identity (user name) presented to the SAML web application. It’s typically provided by retrieving the LoginUser.Username property or by using the property’s synonymous variable UserIdentifier.

setVersion(samlVersion) Specifies the version of the SAML assertion. “1” specifies version 1.1, “2” specifies version 2.0. The default is 2 if this method isn’t present in the script.



Chapter 4 SAML application scripting - Centrify 4 SAML application scripting ... For an introduction...

Documents

Transcript of Chapter 4 SAML application scripting - Centrify 4 SAML application scripting ... For an introduction...