global methods

The Privileged Access 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 Privileged Access 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.

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

global Method

Description

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

setDigestMethodAlgorithm('algorithm')

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