Programming Guides › Programming Guide for C › Policy Management API › SM--Federation Security Services

SM--Federation Security Services

The Federation Security Services interface supports the manipulation of policy store data related to Affiliate Domain objects, which can include Affiliates, Service Providers, and Resource Partners.

Federation Security Services supports SAML 1.x, SAML 2.0, and WS-Federation profiles and it enables SiteMinder the ability to exchange user profile information with partners in a secure manner.

For information about federation in a SiteMinder environment, see the Federation Security Services Guide.

More Information:

Federation Functions

SAML 2.0 Configuration Functions

SAML 1.x

SAML 1.x support lets a user access a consumer site directly or from an assertion producer site without having to supply credentials more than once.

When a user requests access to a protected resource at an affiliate site, the Policy Server at the producer site is notified. After authenticating the user (if the user has not yet been authenticated), the Policy Server generates a SAML assertion from the affiliate object associated with the consumer site.

An application at the affiliate site then retrieves the SAML assertion from the Policy Server, and uses the information for authorization purposes and any other required purpose.

For example, suppose a user logs into a site for a bank (the producer site). The producer includes Policy Server software. The Policy Server contains an affiliate object that represents a site offering credit card services, and also other affiliate objects that represent other sites affiliated with the bank. When a user is authenticated at the producer, the user can click the link for the credit-card site and access the site without having to re-enter his credentials.

SAML 1.x Pseudo-code Example

The pseudo-code in this section illustrates the following operations:

1. Initialize the API.
2. Add an affiliate domain.
3. Add a user directory to an affiliate domain.
4. Create an affiliate in an affiliate domain.
5. Add users to an affiliate.
6. Add an attribute to an affiliate.
7. Get an existing affiliate domain.
8. Get all the affiliates in an affiliate domain.
9. Get all the attributes in an affiliate.
10. Remove an affiliate domain.

Note: Comments using <> notation represent code omitted for ease of understanding. Return code checking is omitted for ease of understanding.

# 1. Initialize the API
use Netegrity::PolicyMgtAPI;
$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");

# 2. Add an affiliate domain
$affdomain = $session‑>CreateAffDomain("name", "description");

# 3. Add a previously obtained user directory to the affiliate domain
# <Obtain $userdir via $session‑>GetAllUserDirs>
$affdomain‑>AddUserDir($userdir);

# 4. Create an affiliate in the affiliate domain
$affiliate = $affdomain‑>CreateAffiliate("affname", "password",
                                          http://authurl, 60, 30);

# 5. Add users from a previously obtained user table to the affiliate
# <Obtain $user via $userdir‑>GetContents>
$affdomain‑>AddUser($user);

# 6. Add an attribute for the affiliate
$affdomain‑>AddAttribute(1, "staticAttrName=StaticAttrValue");
# 7. Get an existing affiliate domain
$affiliate = $affdomain‑>GetAffiliate("affname");

# 8. Get all the affiliates in an affiliate domain
@affiliates = $affdomain‑>GetAllAffiliate();

# 9. Get all the attributes in an affiliate
@affiliateAttrs = $affiliate‑>GetAllAttributes();

# 10. Remove an affiliate domain
$session‑>DeleteAffDomain($affiliate);

SAML 2.0

With SAML 2.0, security assertions are shared between the following entities within a federation:

Identity Provider

An Identity Provider generates assertions for principals within a SAML 2.0 federation. The Identity Provider sends the SAML assertion to the Service Provider where the principal is attempting to access resources.

Service Provider

A Service Provider makes applications and other resources available to principals within a federation, using the identity information provided in an assertion. A principal is a user or another federation entity.

The Service Provider uses a SAML 2.0 authentication scheme to validate a user based on the information in a SAML 2.0 assertion.

Identity Providers and Service Providers can belong to a SAML affiliation. A SAML affiliation is a group of SAML entities that share a name identifier for a single principal.

Service Providers and Identity Providers can belong to an affiliation; however, an entity can belong to no more than one affiliation. Service Providers share the Name ID definition across the affiliation. Identity Providers share the user disambiguation properties across the affiliation.

Using affiliations reduces the configuration required at each Service Provider. Additionally, using one name ID for a principal saves storage space at the Identity Provider.

Single Sign-on Example

By sharing security assertions, a principal can log in at one site (the site acting as the Identity Provider), and then access resources at another site (the Service Provider) without explicitly supplying credentials at the second site.

For example:

1. The user is a home buyer who authenticates at a realtor’s web site.

   Any authentication scheme can be used to authenticate the user.

2. While viewing real estate listings, the user notices a link to a bank with an attractive mortgage rate.
3. The user clicks the link.
4. At the realtor’s site, an entity acting as the Identity Provider packages the user’s information in a SAML assertion, then transports the assertion to the bank’s site using the SAML 2.0 POST binding.
5. At the bank’s site, an entity acting as the Service Provider uses the SAML 2.0 Authentication scheme associated with the Identity Provider to validate the user for the resources on the bank’s site.

   This validation is transparent to the user.

6. If the user is successfully validated, the user is allowed on the bank’s site to view the rate information.

SAML 2.0 Pseudo-code Example

The pseudo-code in this section illustrates the following operations:

1. Initialize the API.
2. Retrieve the affiliate domain for the Service Provider.
3. Assign metadata constants to variables.
4. Assign values to the Service Provider metadata.
5. Create the Service Provider.
6. Retrieve users from the directory associated with the affiliate domain.
7. Add the users to the Service Provider.
8. Update the Service Provider's default skew time to 100.
9. Save the update.
10. Print the updated skew time.

    # 1. Initialize the API
    use Netegrity::PolicyMgtAPI;
    $policyapi = Netegrity::PolicyMgtAPI‑>New();
    $session = $policyapi‑>CreateSession("adminid", "adminpwd");
    
    # 2. Retrieve the affiliate domain for the Service Provider
    $affDom=$session‑>GetAffDomain("AffiliateDomain");
    
    # 3. Assign metadata constants to variables
    $SAML_NAME=SAML_NAME;
    $SAML_SP_AUTHENTICATION_URL=SAML_SP_AUTHENTICATION_URL;
    $SAML_KEY_SPID=SAML_KEY_SPID;
    $SAML_SP_IDPID=SAML_SP_IDPID;
    $SAML_AUDIENCE=SAML_AUDIENCE;
    $SAML_SP_ASSERTION_CONSUMER_DEFAULT_URL=
                               SAML_SP_ASSERTION_CONSUMER_DEFAULT_URL;
    $SAML_SP_NAMEID_ATTRNAME=SAML_SP_NAMEID_ATTRNAME;
    $SAML_SKEWTIME=SAML_SKEWTIME;
    
    # 4. Assign values to the Service Provider metadata
    %hsh=($SAML_NAME=>'My Service Provider',
       $SAML_SP_AUTHENTICATION_URL=>
                                 'http://www.mysite.com/redirect.jsp',
       $SAML_KEY_SPID=>'http://www.spprovider.com',
       $SAML_SP_IDPID=>'http://www.idpprovider.com',
       $SAML_AUDIENCE=>'SSOAudience',
       $SAML_SP_ASSERTION_CONSUMER_DEFAULT_URL=>
                                     'http://www.defaultconsumer.com',
       $SAML_SP_NAMEID_ATTRNAME=>'attribute'
       );
    # 5. Create the Service Provider
    $sp=$affDom‑>CreateSAMLServiceProvider(\%hsh);
    
    # 6. Retrieve users from the directory associated with the #    affiliate domain—in this case, users in the group HR
    $userDir=$session‑>GetUserDir("MyNtDirectory");
    $usr=$userDir‑>LookupEntry("HR");
    
    # 7. Add the users to the Service Provider
    $sp‑>AddUser($usr);
    
    # 8. Update the Service Provider's default skewtime to 100
    $sp‑>Property($SAML_SKEWTIME,"100");
    
    # 9. Save the update
    $sp‑>Save();
    
    # 10. Print the updated skewtime
    print "\n";
    print $sp‑>Property($SAML_SKEWTIME);
    

SAML 2.0 Affiliations

A SAML 2.0 affiliation consists of Service Providers and Identity Providers that have a shared Name ID namespace. Identity Providers also share the user disambiguation properties across the affiliation.

A SAML 2.0 affiliation can have multiple Service Providers and Identity Providers. However, a Service Provider or Identity Provider can belong to no more than one SAML 2.0 affiliation.

Example:

By sharing security assertions, a principal can log in at one site (the site acting as the Identity Provider), and then access resources at another site (the Service Provider) without explicitly supplying credentials at the second site:

1. The user is a home buyer who authenticates at a realtor's web site.

   Any authentication scheme can be used to authenticate the user.

2. While viewing real estate listings, the user notices a link to a bank with an attractive mortgage rate.
3. The user clicks the link.
4. At the realtor's site, an entity acting as the Identity Provider packages the user's information in a SAML assertion, then transports the assertion to the bank's site using the SAML 2.0 POST binding.
5. At the bank's site, an entity acting as the Service Provider uses the SAML 2.0 Authentication scheme associated with the Identity Provider to validate the user for the resources on the bank's site.

   This validation occurs transparently to the user.

6. If the user is successfully validated, the user is allowed on the bank's site to view the rate information.

SAML 2.0 Attribute Authority

SiteMinder supports authorization that uses the values of predetermined user attributes from a remote site as the basis for the authorization decision. The request contains no session information, because the user is not necessarily authenticated on the remote site.

For example, imagine a customer logs on to a car rental agency site to inquire about rates. The customer is authenticated by the agency, but to provide a competitive rate, the agency uses information from the customer's preferred airline. The car rental agency puts in a request to the airline's Web site to obtain the customer's quality code, which is based on the customer's accrued frequent flier miles. The airline returns the value of the quality code, for instance, 1A, and the car agency displays a customized rate sheet.

In this example, the car rental agency acts as what is know as the the SAML Requester, and the airline acts as what is known as a SAML Attribute Authority. Note that the customer is not authenticated by the Attribute Authority.

The Policy Server implements this kind of authorization decision by using variables within policy expressions. In the policy expressions, Federation Attribute Variables associate an attribute with a remote Attribute Authority. When the policy server attempts to resolve the Federation attribute variable, it determines the Attribute Authority from which to request the value of the attribute.

In the Policy Management API, the Sm_PolicyApi_SAMLRequesterAttr_t structure defines an attribute that can be requested by the SAML Requester. It specifies the actual name of the attribute known by the Attribute Authority, as well as a local name used in Federation attribute variables. The local name maps to a variable defined in the SAML 2.0 authentication scheme.

More Information:

Sm_PolicyApi_SAMLRequesterAttr_t

SAML 2.0 Attribute Authority Functions

SAML 2.0 Indexed Endpoints

When configuring single sign-on at the Identity Provider, you can configure more than one endpoint for the Assertion Consumer Service, the service that enables a Service Provider to consume a SAML assertion. Each endpoint you configure is assigned a unique index value, instead of a single, explicit reference to an Assertion Consumer Service URL.

The assigned index can be used as a part of a Service Provider request for an assertion that it sends to the Identity Provider. This enables you to have a different Assertion Consumer Service at the Service Provider for different protocol bindings (Artifact or POST).

In the Policy Management API, you can, for example, add a new Assertion Consumer Service to the Service Provider programmatically by calling the Sm_PolicyApi_AddAssertionConsumerServiceToSAMLSP() function as follows:

iSmApiRetCode = Sm_PolicyApi_AddAssertionConsumerServiceToSAMLSP (

pSmApiSessionHandle,
&structSAMLSPACS2,
pszOid);

Parameters:

• pSmAPiSessionHandle is a pointer to a structure that holds information about the administrative session and the client session.
• pstructSAMLSPACS2 is a pointer to Sm_PolicyApi_SAMLSPAssertionConsumerService_t. This structure specifes the index, binding, and Assertion Consumer Service URL.
• pszOid is a pointer to a string containng the OID of the Service Provider.

In addition, the API includes a function to remove an Assertion Consumer Service and a function to retrieve all the Assertion Consumer Services defined in the Service Provider object. The C Policy Management API sample program, smpolicyapiexample.cpp, shows how these functions are implemented.

More Information:

SAML 2.0 Indexed Endpoint Functions

Sample Application for Affiliates

The C sample program smpolicyapi has been augmented for the affiliate functionality.

To run the affiliate portions

1. Install the SiteMinder Option Pack on the Policy Server
2. Define the Affiliate Policy Store objects in smpolicy.smdif and import the objects to the Policy Store.
3. Install the sample. This creates a sample user directory, which is used by the affiliate sample.

Three options have been added to the smpolicyapi program.

• Do you wish to install Affiliate Sample Api? (Y/N):

  Answering Y causes smpolicyapi to:

  • Add an affiliate domain
  • Add the sample user directory to the affiliate domain
  • Add an affiliate to the affiliate domain
  • Add users from the sample user directory to the affiliate
  • Add an affiliate attribute to the affiliate
• Do you wish to traverse affiliate domain? (Y/N):

  Answering Y causes smpolicyapi to:

  • Get the affiliate domain and print it.
  • Get all user dir OIDs in the sample affiliate domain and print them
  • Get all affiliate OIDs in the sample affiliate domain and print them
  • Get all affiliates in the sample affiliate domain and print their properties
  • Get all users in Affiliate and print them
  • Get all attributes in Affiliate and print them
• Do you wish to uninstall Affiliate Sample Api? (Y/N):

  Answering Y causes smpolicyapi to delete the affiliate domain.

WS-Federation

The WS-Federation specification provides a protocol for how passive clients (such as Web browsers) implement the federation framework. ADFS is Microsoft's implementation of the WS-Federation Passive Requestor Profile.

Web SSO and Signout in the WS-Federation environment are implmented using Account Partners and Resource Partners. An Account Partner authenticates users, provides WS-Federation security tokens and passes them to a Resource Partner. The Resource Partner consumes security tokens and establishes a session based on the contents of the WS-Federation security token.

For SiteMinder to act as an Account Partner, an administrator must define the Resource Partner that will be consuming security tokens. This is done by defining a Resource Partner in an Affiliate domain. For SiteMinder to act as a Resource Partner, an administrator must define the Account Partner that is going to supply security tokens. This is done by defining a WS-Federation authentication scheme.

The C Policy Management API sample program, smpolicyapiexample.cpp, includes examples of how to define, list, and delete a Resource Partner, as well as define, list, and delete a WS-Federation authentication scheme.

More Information:

Sm_PolicyApi_WSFEDProviderProp_t

Sm_PolicyApi_WSFEDResourcePartner_t

WS-Federation Functions

Policy Management API Data Structures

Each data structure represents an entity in the SiteMinder policy store. The structures have a common format:

• The first field in each structure denotes the type of the structure, so that it can be freed by the correct Policy Management API memory function. When the structure is used as an input parameter, the first field is ignored by the Policy Management API. When the structure is used for a return, the first field is set properly by the Policy Management API.
• The last field of each structure is a pointer to the next item in a returned linked list. On input, this field is ignored, since the Policy Management API does not accept linked lists as input parameters. (If you supply a linked list as an input parameter, the function examines only the first item in the list.)

All the character arrays within the following structures are sized according to BFSIZE, which is set to 1024 characters. A 24-character TIMESIZE buffer is used for policy time restrictions.

Sm_PolicyApi_Admin_t

Defines a SiteMinder Administrator object.

Syntax

typedef struct Sm_PolicyApi_Admin_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                    /* Required */
   char pszDesc[BFSIZE];
   char pszPassword[BFSIZE];
   char pszUserDirOid[BFSIZE];
   char pszSchemeOid[BFSIZE];
   Sm_PolicyApi_AdminRights_t nRights;      /* Required */
   struct Sm_PolicyApi_Admin_s* next;
} Sm_PolicyApi_Admin_t;

Sm_PolicyApi_Affiliate_t

Represents an affiliate object.

Syntax

typedef struct Sm_PolicyApi_Affiliate_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];
   char pszDesc[BFSIZE];
   char pszAffiliateDomainOid[BFSIZE];
   char pszPassword[BFSIZE];
   bool bIsEnabled;
   bool bAllowNotification;
   char pszAuthURL[BFSIZE];
   char pszAudience[BFSIZE];
   long nValidityDuration;
   bool bSharedSession;
   long nSyncInterval;
   long nSkewTime;
   long nStartTime;
   long nEndTime;
   unsigned char pszTimeGrid[TIMESIZE];
   Sm_PolicyApi_IPAddress_t *pIPAddress;
   struct Sm_PolicyApi_Affiliate_s* next;
   long nSAMLVersion;
   char pszAssertionPluginClass[BFSIZE];
   char pszAssertionPluginParameters[BFSIZE];
   Sm_PolicyApi_SAML_Profile_t SAMLProfile;
   char pszConsumerURL[BFSIZE];
} Sm_PolicyApi_Affiliate_t;

Sm_PolicyApi_AffiliateAttr_t

Represents affiliate attributes. Used with affiliate methods to manipulate affiliate attributes.

Syntax

typedef struct Sm_PolicyApi_AffiliateAttr_s
{
   int iStructId;
   Sm_PolicyApi_AffiliateAttrType_t nAttrType;
   char pszValue[BFSIZE];
   struct Sm_PolicyApi_AffiliateAttr_s* next;
} Sm_PolicyApi_AffiliateAttr_t;

Sm_PolicyApi_AffiliateDomain_t

Represents an affiliate domain.

Syntax

typedef struct Sm_PolicyApi_Domain_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];
   char pszDesc[BFSIZE];
   struct Sm_PolicyApi_Domain_s*   next;
} Sm_PolicyApi_Domain_t, Sm_PolicyApi_AffiliateDomain_t;

Sm_PolicyApi_Agent_t

Defines a SiteMinder Agent object.

Syntax

typedef struct Sm_PolicyApi_Agent_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                     /* Required */
   char pszDesc[BFSIZE];
   char pszIpAddr[BFSIZE];
   char pszSecret[BFSIZE];
   char pszAgentTypeOid[BFSIZE];             /* Required */
   int nRealmHintAttrId;                     /* Required */
   struct Sm_PolicyApi_Agent_s* next;
} Sm_PolicyApi_Agent_t;

Sm_PolicyApi_AgentConfig_t

Defines an agent configuration object.

Syntax

typedef struct Sm_PolicyApi_AgentConfig_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                    /* Required */
   char pszDesc[BFSIZE];
   struct Sm_PolicyApi_AgentConfig_s* next;
} Sm_PolicyApi_AgentConfig_t;

Sm_PolicyApi_AgentType_t

Defines a SiteMinder Agent Type object.

Syntax

typedef struct Sm_PolicyApi_AgentType_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];
   char pszDesc[BFSIZE];
   int nRfcId;
   int nAgentType;
   int nResourceType;
   int nAgentTypeSpecific;
   struct Sm_PolicyApi_AgentType_s* next;
} Sm_PolicyApi_AgentType_t;

Sm_PolicyApi_AgentTypeAttr_t

Defines a SiteMinder Agent Type Attribute object.

Syntax

typedef struct Sm_PolicyApi_AgentTypeAttr_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];
   char pszDesc[BFSIZE];
   char pszAgentTypeOid[BFSIZE];
   struct Sm_PolicyApi_AgentTypeAttr_s* next;
} Sm_PolicyApi_AgentTypeAttr_t;

Sm_PolicyApi_Association_t

Defines a configuration parameter name and its associated value for an agent configuration object.

Syntax

typedef struct Sm_PolicyApi_Association_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                    /* Required */
   char* pszValue;
   int iFlags;
   struct Sm_PolicyApi_Association_s* next;
} Sm_PolicyApi_Association_t;

Sm_PolicyApi_AuthAzMap_t

Defines a SiteMinder authentication and authorization mapping object.

Syntax

typedef struct Sm_PolicyApi_AuthAzMap_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszAuthDirOid[BFSIZE];              /* Required */
   char pszAuthDirName[BFSIZE];
   char pszAzDirOid[BFSIZE];                /* Required */
   char pszAzDirName[BFSIZE];
   Sm_PolicyApi_AuthAzMapType_t nMapType;   /* Required */
   struct Sm_PolicyApi_AuthAzMap_s *next;
} Sm_PolicyApi_AuthAzMap_t;

Sm_PolicyApi_CertMap_t

Defines a SiteMinder certification mapping object.

Syntax

typedef struct Sm_PolicyApi_CertMap_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszDesc[BFSIZE];
   char pszUserDirOid[BFSIZE];              /* Required */
   char pszIssuerDN[BFSIZE];                /* Required */
   char pszCaDN[BFSIZE];
   char pszMapAttr[BFSIZE];
   Sm_PolicyApi_CertMapFlags_t nFlags;      /* Required */
   Sm_PolicyApi_CertMapAttrType_t nAttrType;
   Sm_PolicyApi_DirType_t nDirType;         /* Required */
   struct Sm_PolicyApi_CertMap_s *next;
} Sm_PolicyApi_CertMap_t;

Sm_PolicyApi_Domain_t

Defines a SiteMinder Domain object.

Syntax

typedef struct Sm_PolicyApi_Domain_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                    /* Required */
   char pszDesc[BFSIZE];
   struct Sm_PolicyApi_Domain_s* next;
   Sm_PolicyApi_DomainFlags_t iFlags;
} Sm_PolicyApi_Domain_t;

Sm_PolicyApi_Group_t

Defines a SiteMinder Group object. SiteMinder Groups are defined in the Sm_PolicyApi_Groups_t enumeration.

Syntax

typedef struct Sm_PolicyApi_Group_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                      /* Required */
   char pszDesc[BFSIZE];
   char pszAgentTypeOid[BFSIZE];              /* Required */
   struct Sm_PolicyApi_Group_s* next;
} Sm_PolicyApi_Group_t;

Sm_PolicyApi_HostConfig_t

Defines a host configuration object.

Syntax

typedef struct Sm_PolicyApi_HostConfig_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                    /* Required */
   char pszDesc[BFSIZE];
   char pszIPAdress[BFSIZE];
   bool bEnableFailOver;
   int iMaxSocketsPerPort;
   int iMinSocketsPerPort;
   int iNewSocketStep;
   int iRequestTimeout;
   struct Sm_PolicyApi_HostConfig_s* next;
   Sm_PolicyApi_Server_t* pServer;
   Sm_PolicyApi_Server_t* pCluster;
   long nFailoverThreshold;
} Sm_PolicyApi_HostConfig_t;

Sm_PolicyApi_IPAddress_t

Defines an IP address restriction for an object-for example, you can define IP address restrictions that must be met for a policy to fire.

You can specify a single host IP address, a range of IP addresses, a host name, or a subnet mask.

Syntax

typedef struct Sm_PolicyApi_IPAddress_s
{
   int iStructId;
   Sm_PolicyApi_IPAddressType_t iIPAddressType;
   unsigned long nIPAddress;
   unsigned long nEndIPAddress;
   unsigned long nSubnetMask;
   char pszHostName[BFSIZE];
   struct Sm_PolicyApi_IPAddress_s *next;
} Sm_PolicyApi_IPAddress_t;

11111111 11111111 11111111 10000000

Sm_PolicyApi_ManagementCommand_t

Defines a management command. Management commands enable an agent to retrieve information from the Policy Server.

Syntax

typedef struct Sm_PolicyApi_ManagementCommand_s
{
   Sm_PolicyApi_ManagementCommands_t iCommand;
   char pszData[BFSIZE];
} Sm_PolicyApi_ManagementCommand_t;

Sm_PolicyApi_ODBCQueryScheme_t

Defines a SiteMinder ODBC Query Scheme object.

Syntax

typedef struct Sm_PolicyApi_ODBCQueryScheme_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                    /* Required */
   char pszDesc[BFSIZE];
   char pszQueryEnumerate[BFSIZE];          /* Required */
   char pszQueryGetObjInfo[BFSIZE];         /* Required */
   char pszQueryLookup[BFSIZE];             /* Required */
   char pszQueryInitUser[BFSIZE];           /* Required */
   char pszQueryAuthenticateUser[BFSIZE];   /* Required */
   char pszQueryGetUserProp[BFSIZE];        /* Required */
   char pszQuerySetUserProp[BFSIZE];        /* Required */
   char pszQueryGetUserProps[BFSIZE];       /* Required */
   char pszQueryLookupUser[BFSIZE];         /* Required */
   char pszQueryGetGroups[BFSIZE];          /* Required */
   char pszQueryIsGroupMember[BFSIZE];      /* Required */
   char pszQueryGetGroupProp[BFSIZE];       /* Required */
   char pszQuerySetGroupProp[BFSIZE];       /* Required */
   char pszQueryGetGroupProps[BFSIZE];      /* Required */
   char pszQueryLookupGroup [BFSIZE];       /* Required */
   char pszQuerySetPassword [BFSIZE];       /* Required */
   struct Sm_PolicyApi_ODBCQueryScheme_s* next;
} Sm_PolicyApi_ODBCQueryScheme_t;

Sm_PolicyApi_Oid_t

Used by the following functions to retrieve a SiteMinder object collection:

• Sm_PolicyApi_GetDomainObjects()
• Sm_PolicyApi_GetChildren()
• Sm_PolicyApi_GetGlobalObjects()
• Sm_PolicyApi_GetGroupOids().

Syntax

typedef struct Sm_PolicyApi_Oid_s
{
   int iStructId;
   int iObjectId;
   char pszOid[BFSIZE];
   struct Sm_PolicyApi_Oid_s *next;
} Sm_PolicyApi_Oid_t;

Sm_PolicyApi_PasswordMsgField_t

Describes a password policy message field. A password policy message field contains information about an error that occurred during a validation attempt for a new password.

A password policy message field is associated with a password policy message identifier. This identifier is returned in the nMsgId parameter of Sm_PolicyApi_GetPasswordMsg().

This structure is returned in the ppStructMsgField parameter of Sm_PolicyApi_GetPasswordMsg().

Syntax

typedef struct Sm_PolicyApi_PasswordMsgField_s
{
   int iStructId;
   Sm_PolicyApi_PasswordMsgFieldId_t nId;
   Sm_PolicyApi_FieldType_t nType;
   char pszMsg[BFSIZE];
   int nValue;
   struct Sm_PolicyApi_PasswordMsgField_s* next;
} Sm_PolicyApi_PasswordMsgField_t;

Sm_PolicyApi_PasswordPolicy_t

Defines a SiteMinder password policy object.

Syntax

typedef struct Sm_PolicyApi_PasswordPolicy_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                    /* Required */
   char pszDesc[BFSIZE];
   bool bEntireDir;                         /* Required */
   bool bIsEnabled;                         /* Required */
   char pszUserDirectoryOid[BFSIZE];        /* Required */
   char pszPath[BFSIZE];                    /* Required */
   char pszClass[BFSIZE];                   /* Required */
   int nResolution;                         /* Required */
   int nLoginMaxFailures;                   /* Required */
   int nLoginMaxInactivity;                 /* Required */
   int nLoginInactivityWarn;
   int nLoginDaysGrace;                     /* Required */
   char pszDictionaryName[BFSIZE];
   int nDictionaryPartial;                  /* Required */
   int nExpirationDelay;                    /* Required */
   int nReenablement;                       /* Required */
   int nPasswordBehavior;                   /* Required */
   char pszPasswordServicesRedirect[BFSIZE];
   int nPWMaxLength;                        /* Required */
   int nPWMinLength;                        /* Required */
   int nPWMaxRepeatingChar;                 /* Required */
   int nPWMinAlphaNum;                      /* Required */
   int nPWMinAlpha;                         /* Required */
   int nPWMinNonAlpha;                      /* Required */
   int nPWMinNonPrintable;                  /* Required */
   int nPWMinNumbers;                       /* Required */
   int nPWMinPunctuation;                   /* Required */
   int nPWReuseCount;                       /* Required */
   int nPWReuseDelay;                       /* Required */
   int nPWPercentDifferent;                 /* Required */
   int nPWPercentSequence;                  /* Required */
   int nPWSpecialsLength;                   /* Required */
   struct Sm_PolicyApi_PasswordPolicy_s* next;
   int nPriority;                           /* Required */
   int nPWMinLowerAlpha;                    /* Required */
   int nPWMinUpperAlpha;                    /* Required */
   int nReserved1;
   int nReserved2;
   int nReserved3;
   int nReserved4[BFSIZE];
} Sm_PolicyApi_PasswordPolicy_t;

Sm_PolicyApi_Policy_t

Defines a SiteMinder Policy object.

Syntax

typedef struct Sm_PolicyApi_Policy_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                    /* Required */
   char pszDesc[BFSIZE];
   char pszActiveExpr[BFSIZE];
   bool bIsEnabled;                         /* Required */
   char pszDomainOid[BFSIZE];               /* Required */
   long nStartTime;
   long nEndTime;
   unsigned char   pszTimeGrid[TIMESIZE];
   Sm_PolicyApi_IPAddress_t *pIPAddress;
   struct Sm_PolicyApi_Policy_s* next;
   char pszVariableExpr[BFSIZE]
   Sm_PolicyApi_Oid_t* pVariableList;
} Sm_PolicyApi_Policy_t;

Time Grid Array

The time grid array (used with the field pszTimeGrid) holds time restrictions for an entire week. The array contains a one-byte element for every hour of the day, starting with 12 AM. In every byte, the seven days of the week are represented, beginning with Sunday as the lowest order bit. Bits that are set enable the policy to fire. A zero bit prevents the policy from firing on that day during the associated hour.

Examples:

• To disable policy firing for the hour 12-1 AM on Saturdays and Sundays, the hexadecimal value for the entire grid is:

  3E7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F
  

• To fire the policy at all times, leave all bits set:

  7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F7F
  

• To restrict the policy from being fired all day Thursday, turn off the Thursday bit in all the hour elements:

  6F6F6F6F6F6F6F6F6F6F6F6F6F6F6F6F6F6F6F6F6F6F6F6F
  

• To restrict the policy from being fired from 8 AM to 10AM on Tuesday, turn off the Tuesday bit in hours 8 AM and 9 AM:

  7F7F7F7F7F7F7F7F7C7C7F7F7F7F7F7F7F7F7F7F7F7F7F7F
  

• To fire between 8 AM and 8 PM on all days:

  00000000000000007F7F7F7F7F7F7F7F7F7F7F7F00000000
  

Sm_PolicyApi_PolicyLink_t

Defines a SiteMinder Policy Link object.

Syntax

typedef struct Sm_PolicyApi_PolicyLink_s

{
   int iStructId;
   char pszOid[BFSIZE];
   char pszRuleOid[BFSIZE];                  /* Required */
   char pszResponseOid[BFSIZE];
   struct Sm_PolicyApi_PolicyLink_s* next;
} Sm_PolicyApi_PolicyLink_t;

Sm_PolicyApi_Realm_t

Sm_PolicyApi_Realm_t type defines a SiteMinder Realm object.

Syntax

typedef struct Sm_PolicyApi_Realm_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                     /* Required */
   char pszDesc[BFSIZE];
   char pszResourceFilter[BFSIZE];
   char pszAgentOid[BFSIZE];                 /* Required */
   char pszSchemeOid[BFSIZE];                /* Required */
   char pszParentRealmOid[BFSIZE];           /* Required */
   char pszDomainOid[BFSIZE];                /* Required */
   char pszAzUserDirOid[BFSIZE];             /* Required */
   char pszRegSchemeOid[BFSIZE];             /* Required */
   bool bProcessAuthEvents;                  /* Required */
   bool bProcessAzEvents;                    /* Required */
   bool bProtectAll;                         /* Required */
   int nMaxTimeout;                          /* Required */
   int nIdleTimeout;                         /* Required */
   bool bSyncAudit;                          /* Required */
   struct Sm_PolicyApi_Realm_s* next;
} Sm_PolicyApi_Realm_t;

Sm_PolicyApi_RegistrationScheme_t

Defines a SiteMinder registration scheme object.

Syntax

typedef struct Sm_PolicyApi_RegistrationScheme_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                     /* Required */
   char pszDesc[BFSIZE];
   char pszUserDirOid[BFSIZE];               /* Required */
   char pszWelcomePageURL[BFSIZE];
   char pszTemplatePath[BFSIZE];
   bool bEnableLogging;                      /* Required */
   struct Sm_PolicyApi_RegistrationScheme_s* next;
} Sm_PolicyApi_RegistrationScheme_t;

Sm_PolicyApi_RegularExpression_t

Defines a regular expression.

Syntax

typedef struct Sm_PolicyApi_RegularExpression_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];
   char ExpressionDef[BFSIZE];
   bool matchExpression;
   struct Sm_PolicyApi_RegularExpression_s *next;
} Sm_PolicyApi_RegularExpression_t;

Sm_PolicyApi_Response_t

Defines a SiteMinder Response object.

Syntax

typedef struct Sm_PolicyApi_Response_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                     /* Required */
   char pszDesc[BFSIZE];
   char pszAgentTypeOid[BFSIZE];             /* Required */
   char pszDomainOid[BFSIZE];                /* Required */
   struct Sm_PolicyApi_Response_s* next;
} Sm_PolicyApi_Response_t;

Sm_PolicyApi_ResponseAttr_t

Defines a SiteMinder Response attribute object.

Syntax

typedef struct Sm_PolicyApi_ResponseAttr_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszAgentTypeAttrOid [BFSIZE];        /* Required */
   char pszValue[BFSIZE];
   int iTTL;                                 /* Required */
   int iFlags;
   struct Sm_PolicyApi_ResponseAttr_s* next;
   char pszActiveExpr[BFSIZE];
   Sm_PolicyApi_Oid_t* pVariableList;
} Sm_PolicyApi_ResponseAttr_t;

Response Attribute Types

The field pszValue contains one of the following response attribute types:

Note: The non-alphanumeric characters in the formats below are required characters.

• Static. A string that is part of a SiteMinder response. The string has the following format:

  variable-name=variable-value
  

  In the format example:

  • variable-name is the name for the name/value pair that this response attribute will return to the Web Agent.
  • variable-value is the static text that will be returned as the second half of the name/value pair.
• User Attribute. A string containing profile information from a user's entry in a user directory. The string has the following format:

  User-Attr-variable-name=<%userattr="user-attr-name"%>
  

  In the format example:

  • User-Attr-variable-name is the name for the name/value pair that this response attribute will return to the Web Agent.
  • user-attr-name is a user attribute that can be retrieved from an LDAP, WinNT, or ODBC user directory.
• DN Attribute. A string containing profile information from a directory object in an LDAP or ODBC user directory. The string has the following format:

  DN-Variable-Name=<#dn="DN-Spec" attr="DN-Attribute-Name"#>
  

  In the format example:

  • DN-Variable-Name is the name for the name/value pair that this response attribute will return to the Web Agent.
  • DN-Spec is the distinguished name of the user group from which you want to retrieve the user attribute.
  • DN-Attribute-Name is an attribute associated with an LDAP or ODBC directory object to which the user is related, such as a group or an organizational unit (OU).
• Active Response. An active expression associated with the Response Attribute. The expression is a string of variable definitions in the following format:

  Name=<@lib="LibName" func="FuncName" param="Param"@>
  

  In the format example:

  • Name is the name of the variable (with WebAgent-HTTP-Header-Variable response attributes) or cookie (with WebAgent-HTTP-Cookie-Variable response attributes) associated with the name/value pairs in the active expression.
  • LibName is the name of the shared library that supports the Active Response.
  • FuncName is the name of the actual function in the shared library that implements the Active Response.
  • Param is an optional list of parameters to be passed to the function in the shared library.

  Note: For information about configuring active expressions in responses, rules, or policies, see Policy Design.

Sm_PolicyApi_Rule_t

Defines a SiteMinder Rule object.

Syntax

typedef struct Sm_PolicyApi_Rule_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                     /* Required */
   char pszDesc[BFSIZE];
   char pszRealmOid[BFSIZE];                 /* Required */
   char pszAction[BFSIZE];                   /* Required */
   char pszResource[2*BFSIZE];
   bool bAllowAccess;                        /* Required */
   bool bRegularExpression;                  /* Required */
   char pszActiveExpr[BFSIZE];
   bool bIsEnabled;                          /* Required */
   long nStartTime;
   long nEndTime;
   unsigned char   pszTimeGrid[TIMESIZE];
   struct Sm_PolicyApi_Rule_s* next;
   char pszAgentOid[BFSIZE];                 /* Required */
} Sm_PolicyApi_Rule_t;

Sm_PolicyApi_SAMLAffiliation_t

Defines a SAML 2.0 affiliation object. A SAML 2.0 affiliation is a set of entities that share a single federated namespace of unique Name IDs for principals.

Syntax

typedef struct Sm_PolicyApi_SAMLAffiliation_s
{
   int iStructId;
   Sm_PolicyApi_SAMLProviderProp_t *pProps;
   struct Sm_PolicyApi_SAMLAffiliation_s *next;
} Sm_PolicyApi_SAMLAffiliation_t;

Sm_PolicyApi_SAMLProviderProp_t

Defines a SAML 2.0 metadata property as a name/value pair.

An Sm_PolicyApi_SAMLProviderProp_t structure consists of a single name/value pair. You define a set of properties for a given SAML 2.0 object through a linked list of Sm_PolicyApi_SAMLProviderProp_t structures.

Use the following structures and function to define a set of properties for a SAML 2.0 Service Provider, affiliation, or authentication scheme and associated Identity Provider:

• Sm_PolicyApi_SAMLSP_t
• Sm_PolicyApi_SAMLAffiliation_t
• Sm_PolicyApi_AddSAMLScheme()

Syntax

typedef struct Sm_PolicyApi_SAMLProviderProp_s
{
   int iStructId;
   char pszName[BFSIZE];
   char pszValue[BFSIZE];
   struct Sm_PolicyApi_SAMLProviderProp_s *next;
} Sm_PolicyApi_SAMLProviderProp_t;

Example

The following is an example of a helper method that creates an instance of Sm_PolicyApi_SAMLProviderProp_t and assigns it the name/value pair that is passed into it:

Sm_PolicyApi_SAMLProviderProp_t * CreateSAMLProp(
                                         const char *pszName,
                                         const char *pszValue)
{
   Sm_PolicyApi_SAMLProviderProp_t * pProp = new
                                Sm_PolicyApi_SAMLProviderProp_t;
   memset(pProp, 0, sizeof(Sm_PolicyApi_SAMLProviderProp_t));
   pProp->iStructId = Sm_PolicyApi_SAMLProviderProp_ID;
   strncpy(pProp->pszName, pszName, BFSIZE);
   strncpy(pProp->pszValue, pszValue, BFSIZE);
   return pProp;
}

The following is an example of a helper method that retrieves the value of the property whose name is passed into it:

char * FindSAMLParam(const Sm_PolicyApi_SAMLSP_t *pStructSP,
                     const char *pszName)
{
   for(Sm_PolicyApi_SAMLProviderProp_t *pCurProp=pStructSP->pProps;
       pCurProp != NULL;
       pCurProp = pCurProp->next)
   {
       if (0 == strcmp(pCurProp->pszName, pszName))
      {
          return pCurProp->pszValue;
      }
   }

   return NULL;
}

Property Lists

Each Sm_PolicyApi_SAMLProviderProp_t structure contains a SAML 2.0 metadata property defined as a name/value pair. A complete set of properties for a particular SAML 2.0 object is defined as a linked list of Sm_PolicyApi_SAMLProviderProp_t structures.

The following metadata properties apply to a given type of SAML 2.0 object:

• Service Provider Properties
• SAML Affiliation Properties
• SAML 2.0 Authentication Scheme Properties

Note: Some properties are used with multiple object types.

Service Provider Properties

A Service Provider object contains information that an Identity Provider needs to produce assertions for the Service Provider. Service Provider properties are stored within an Sm_PolicyApi_SAMLSP_t structure.

The properties of a SAML 2.0 Service Provider object are listed following.

SAML Affiliation Properties

The properties of a SAML 2.0 affiliation object are listed below. Properties are grouped according to the way they are presented on the SAML Affiliation Properties dialog box.

SAML affiliation properties are stored within an Sm_PolicyApi_SAMLAffiliation_t structure.

SAML 2.0 Authentication Scheme Properties

The properties listed in this section define:

• Authentication schemes based on the SAML 2.0 Template.
• Metadata properties of the associated Identity Provider. The properties are stored with the authentication scheme.

You define a SAML 2.0 authentication scheme to represent an Identity Provider for a particular Service Provider.

The properties of a SAML 2.0 authentication scheme and its associated Identity Provider are listed below. Properties are grouped according to the way they are presented on the SAML Authentication Scheme Properties dialog box for the SAML 2.0 Template.

You define properties for a SAML 2.0 authentication scheme and its associated Identity Provider by calling Sm_PolicyApi_AddSAMLScheme().

More Information:

Property Reference

Sm_PolicyApi_SAMLRequesterAttr_t

Defines an attribute that can be requested by a SAML Requester in an AttributeQuery message.

Syntax

typedef struct Sm_PolicyApi_SAMLRequesterAttr_s
{
   int iStructId;
   Sm_PolicyApi_SAMLSPAttrNameFormat_t nAttrNameFormat;
   char pszLocalName[BFSIZE];
   char pszName[BUFSIZE];
   struct Sm_PolicyApi_SAMLRequesterAttr_s* next;
} Sm_PolicyApi_SAMLRequesterAttr_t;

Sm_PolicyApi_SAMLSP_t

Defines a SAML 2.0 Service Provider object for an Identity Provider.

A Service Provider offers services (such as access to applications and other resources) to principals within a federation.

Syntax

typedef struct Sm_PolicyApi_SAMLSP_s
{
   int iStructId;
   Sm_PolicyApi_SAMLProviderProp_t *pProps;
   Sm_PolicyApi_IPAddress_t *pIPAddress;
   unsigned char   pszTimeGrid[TIMESIZE];
   struct Sm_PolicyApi_SAMLSP_s *next;
} Sm_PolicyApi_SAMLSP_t;

Sm_PolicyApi_SAMLSPAssertionConsumerService_t

Defines a structure that supports the Assertion Consumer Service.

Syntax

typedef struct Sm_PolicyApi_SAMLSPAssertionConsumerService_s
{
   int iStructId;
   int iIndex;
   Sm_PolicyApi_SAMLSPACSBinding_t nACSBinding;
   char pszAssertionConsumerURL[BFSIZE};
   bool bIsDefault;
   struct Sm_PolicyApi_SAMLSPAssertionConsumerService_s* next;
} Sm_PolicyApi_SAMLSPAsserttionConsumer_t;

Sm_PolicyApi_SAMLSPAttr_t

Defines an attribute of a principal for a particular SAML 2.0 Service Provider.

Syntax

typedef struct Sm_PolicyApi_SAMLSPAttr_s
{
   int iStructId;
   Sm_PolicyApi_SAMLSPAttrNameFormat_t nAttrNameFormat;
   char pszValue[BFSIZE];
   bool bEncrypted;
   struct Sm_PolicyApi_SAMLSPAttr_s* next;
   Sm_PolicyApi_SAMLSPAttrMode_t  nMode;
} Sm_PolicyApi_SAMLSPAttr_t;

Sm_PolicyApi_Scheme_t

Defines a SiteMinder authentication scheme object.

Syntax

typedef struct Sm_PolicyApi_Scheme_s
{
   int iStructId;
   char pszOid[BFSIZE];
   char pszName[BFSIZE];                    /* Required */
   char pszDesc[BFSIZE];
   int nLevel;                              /* Required */
   char pszLib[BFSIZE];
   char pszParam[BFSIZE];
   char pszSecret[BFSIZE];
   bool bIsTemplate;
   bool bIsUsedbyAdmin;
   Sm_Api_SchemeType_t nType;               /* Required */
   bool bAllowSaveCreds;                    /* Required */
   bool bIsRadius;                          /* Required */
   bool bIgnorePwCheck;                     /* Required */
   struct Sm_PolicyApi_Scheme_s* next;
} Sm_PolicyApi_Scheme_t;