attribute ATTR_SSOZONE in the createSSOToken

Products

• CA Single Sign On Secure Proxy Server (SiteMinder)
• CA Single Sign On Agents (SiteMinder)
• CA Single Sign On Federation (SiteMinder)
• CA Single Sign On SOA Security Manager (SiteMinder)
• SITEMINDER

Issue/Introduction

We're reading the documentation from SDK Java API and we don't find
the attribute ATTR_SSOZONE in the createSSOToken from

  https://techdocs.broadcom.com/content/dam/broadcom/techdocs/us/en/assets/docops/casso1283/javadoc-sdk_127.zip

On one hand, as per this documentation, the createSSOToken function won't honor the
attribute ATTR_SSOZONE :

createSSOToken

public int createSSOToken(SessionDef sd,
                          AttributeList al,
                          java.lang.StringBuffer SSOToken)

    Creates and encrypts a single sign-on token.

[...]

al - The attributes to include in the token. Valid values:

    ATTR_USERDN. The user's distinguished name.
    ATTR_USERNAME. The user's name.
    ATTR_CLIENTIP. The IP address of the machine where the user initiated a request for a protected resource.
    ATTR_SESSIONDOMAIN. The host domain stored in the SSO token. 

Any other attribute is ignored.

On the other hand, documentation also states that since 12.52SP1,
support for Zones in SDK is available :

  Agent SDK Updated to Support SSO Zones (168974)

    The CreateSSOToken interface now supports inserting the
    SM_AGENTAPI_ATTR_SSOZONE attribute into the session token. The
    DecodeSSOToken reads the SSOZONE attribute from the provided token
    and places its value in the attribute list.

    The JAVA Agent APi SDK, includes the new attribute type ATTR_SSOZONE
    in the AttributeList class.

    If the token has no SSOZONE attribute, the default value is "SM."

  https://techdocs.broadcom.com/content/broadcom/techdocs/us/en/ca-enterprise-software/layer7-identity-and-access-management/single-sign-on/12-52-01/release-notes/cumulative-releases/defects-fixed-in-12-52.html

Can we use the constant ATTR_SSOZONE and pass it as attribute in
createSSOToken and DecodeSSOToken Java functions from SDK ?

Environment

SDK 12.52SP1CR09 on RedHat 6;

Resolution

If you run SDK 12.52SP1, then the ATTR_SSOZONE attribute should be
used in createSSOToken and decodeSSOToken, the documentation doesn't
seem to be up to date.

Here's a snippet how it could be used :

  - AttributeList al = new AttributeList ();
  - al.addAttribute( AgentAPI.ATTR_SSOZONE, 0, 0, '", ssoZoneName.getBytes());
  - int result = agent.createSSOToken(sd, al, ssoTokenBuffer);

And here's what the Java documentation mentions :

>>

  netegrity.siteminder.javaagent
  Class AgentAPI

  java.lang.Object
    extended by netegrity.siteminder.javaagent.AgentAPI

  Direct Known Subclasses:
      ServiceAPI 

  public class AgentAPI
  extends java.lang.Object

  Provides Java access to the SiteMinder Agent API.

  This class is essentially a one-to-one cover over the C-language
  version of the SiteMinder Agent API. It relies on Java Native
  Interfaces (jdk 1.1.x or above), and requires the JavaAgentAPI library
  (dll or shared library) to be co-located with the JVM and accessible
  through PATH or LD_LIBRARY_PATH settings.

  Field Summary

   static int  ATTR_SSOZONE
         Constant denoting the SSo Attribute zone

  Constructor Summary

  AgentAPI()
     Constructs but does not initialize an Agent API object.

  Method Summary

    int  decodeSSOToken(java.lang.String SSOToken, TokenDescriptor td, AttributeList al, boolean UpdateToken, java.lang.StringBuffer UpdatedSSOToken)
     Decodes a single sign-on token.

    int  createSSOToken(SessionDef sd, AttributeList al, java.lang.StringBuffer SSOToken)
     Creates and encrypts a single sign-on token

Parameters:
    sd - The session information for the authenticated user.
    al - The attributes to include in the token. Valid values:

        ATTR_USERDN. The user's distinguished name.
        ATTR_USERNAME. The user's name.
        ATTR_CLIENTIP. The IP address of the machine where the user initiated a request for a protected resource.
        ATTR_SESSIONDOMAIN. The host domain stored in the SSO token. 

    Any other attribute is ignored.

<<

This last section should be corrected. Again, the SDK version should
be higher than 12.52SP1CR00 for that to work.