Using the Service Connector SamlSenderVouchesSecurityHandler Method

If you are using the Java Service Connector API and want to implement SSO using a signed SAML 2.0 token, the client application must use the SamlSenderVouchesSecurityHandler instead of the DefaultSecurityHandler.

For more information about the DefaultSecurityHandler, see "Setting up the Security Handler" in the TIBCO ActiveMatrix BPM Developer's Guide.

The SamlSenderVouchesSecurityHandler method creates a Sender-Vouches SAML assertion for the LDAP Distinguished Name (DN) of the BPM user to be authenticated. The assertion is signed using a specified private keystore and certificate.

The full syntax for the SamlSenderVouchesSecurityHandler method is:

   public com.tibco.n2.service.connector.config.context
   SamlSenderVouchesSecurityHandler(String issuer,
                                    String keystoreFilePath,
                                    String keystorePassword,
                                    String aliasKey,
                                    String aliasKeyPassword
                                    String ldapDistinguishedName,
                                    boolean applyConditions,
                                    DateTime timeStamp,
                                    int validityDuration)

where:

• issuer identifies the issuer of the assertion (the Issuer value in the assertion). If this value is omitted, a default value of "CN=bpmserver, C=US, ST=CA, L=Palo Alto, OU=BPM, O=TIBCO Inc" is used.
• keystoreFilePath is the pathname for the private keystore file used to sign the assertion. Note that this is not an absolute path to the keystore file on the host’s file system. It is a pathname that needs to be resolved via the classpath (the same as for regular property files). The following are two examples:
  • keystoreFilePath = /com/tibco/sample/app/amx-bpm-wss-keystore.jks

    The package name is com.tibco.sample.app (the .jar containing the package is in the classpath).

  • keystoreFilePath = /resources/keystores/admin_keystore.jks

    The classpath contains the current directory (.), which causes the file ./resources/keystores/admin_keystore.jks to be readable.

    Note: The BPM runtime must hold the corresponding public certificate of the private certificate used to sign the SAML assertion
• keystorePassword is the password for the keystore file.
• aliasKey is the alias for the keystore certificate used to sign the SAML assertion.
• aliasKeyPassword is the password of the alias for the keystore certificate used to sign the SAML assertion.
• ldapDistinguishedName is the LDAP Distinguished Name (DN) of the BPM user to be authenticated.
  Note: This DN must match the DN of the primary LDAP source of the LDAP container from which the BPM user was derived.
• applyConditions specifies whether you want to define a validity period for the assertion, using the timeStamp and validityDuration values. The default value of false (0) is not to define these values, generating an assertion that is valid for the default period of validityDuration — that is, for 20 minutes. Setting applyConditions to true (1) enables you to define values for timeStamp and validityDuration. (See Handling Time Differences when using Validity Periods in a SAML Assertion.)
• timeStamp is the date/time that used to define when the assertion was issued (the IssueInstant value in the assertion). If this value is omitted, the current timestamp of the client machine is used.
• validityDuration is the period of time for which the assertion will remain valid, in minutes. (The timeStamp and validityDuration values are used to set the NotBefore and NotOnOrAfter values in the assertion.) If this value is omitted or set to -1, a default value of 20 minutes is used.