Programming Guides › Programming Guide for Perl › Policy Management API

Policy Management API

This section contains the following topics:

About the Policy Server and the Policy Management API

Write a Script against the Policy Management API

Federation Manager: Legacy Federation

Affiliate Domains

Authentication Scheme Configuration

About the Policy Server and the Policy Management API

A SiteMinder Policy Server manages data that describes protected resources and the requirements for accessing those resources. A Policy Server also manages information about the administrators of the protected domains. This security data is located in a policy store such as LDAP.

The Policy Management API (module Netegrity::PolicyMgtAPI) lets you perform most of the Policy Server design and administration operations that you can perform with the Administrative UI. For example, you can:

• Create, modify, and delete policy store objects such as domains, realms, rules, and policies
• Manage administrators and user directories

The following illustration shows some of the policy store objects you can manage with the Policy Management API:

In addition, the Policy Management API data management object (PolicyMgtDataMgr) lets you copy specific objects from one policy store to another, rather than an entire policy store or domain as allowed by the SiteMinder smobjexport and smobjmport tools.

Location of the Policy Management API

The Policy Management API must be installed on the machine where the target Policy Server is located. The Policy Management API cannot access a remote Policy Server. However, the policy store can be on a remote machine as long as the Policy Server is configured to point to the remote policy store.

Write a Script against the Policy Management API

When you write a script against the Policy Management API, take the following basic steps:

1. Reference the Policy Management API at the beginning of your script:

   use Netegrity::PolicyMgtAPI;
   

2. Use the New() method to create a Policy Management API object:

   $policymgtapi = Netegrity::PolicyMgtAPI‑>New();
   

3. Optionally, set one or more Policy Server initialization flags through PolicyMgtAPI methods such as DisableValidation(). By default, all initialization flags are set to 0.
4. Create a session with the Policy Server:

   $session = $policymgtapi‑>CreateSession("userid", 
                                           "password", 
                                           "127.0.0.1" );
   

You can now perform operations against Policy Server objects. For example, you could retrieve and print out a list of configured agents in the Policy Server:

@agents = $session‑>GetAllAgents();
foreach $agent (@agents) {
   print "Agent Name = " . $agent‑>Name() . "\n";
}

Script Execution Performance Enhancement

You can reduce the time it takes for Policy Management scripts to make changes in the policy store. To do so, pass 0 in PreLoadCache() during initialization. By default, cache pre-loading is disabled.

Federation Manager: Legacy Federation

The SiteMinder federation programming interfaces allows businesses in a federated relationship across the Internet to securely share information about users visiting any of the federated sites. Users can access federated sites without having to supply credentials more than once.

Affiliated sites share user information through an industry-standard Security Assertion Markup Language (SAML) document called an assertion.

The SiteMinder federation product supports SAML 1.x and SAML 2.0 protocols.

SAML Assertions

A SAML assertion includes:

• Affiliate attributes, such as:
  • User profile information from a user directory, such as a user’s email address or business title.
  • User entitlements, such as the user’s credit limit at the affiliate site.
• Session information (SAML 1.x assertions)—for example, whether the assertion producer and the consumer can maintain separate sessions.

Note: You can modify the default assertion that the Policy Server generates. You do so through a custom Java class that you create with the SiteMinder Java SDK.

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 Attribute Authority

SiteMinder supports authorization for user access to a resource by requesting the values of predetermned user attributes from a remote site and then using those values 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 prefered 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 the appropriate rate sheet to the customer.

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.

The Perl Policy Management API includes the following three methods in the PolicyMgtSession object to support authorization based on user attributes:

• AddAttributeToSAMLScheme()
• GetAllSAMLSchemeAttributes()
• RemoveAttributeFromSAMLScheme()

The PolicyMgtSAMLServiceProvider‑>AddAttribute method supports the addition of an attribute to the Service Provider (the Attribute Authority) that can be requested by a SAML Requester.

SAML 2.0 Indexed Endpoints

When configuring single sign-on at the Identity Provider, you can specify more than one endpoint for the Assertion Consumer Service, the service that enables a Service Provider to consume a SAML assertion. Each endpoint 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 part of a Service Provider's 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.

In a Perl script, you specify the index value, the protocol binding, and the URL of the indexed endpoint using the AddAssertionConsumerServiceToSAMLSP() method in the PolicyMgtSAMLServiceProvider object as follows:

$res = $sp‑>AddAssertionConsumerServiceToSAMLSP(index, protocolBinding, URL);

This method returns a PolicyMgtSAMLSPACS object. There are also methods in PolicyMgtSAMLServiceProvider for retrieving all Assertion Consumer Service objects and for removing an Assertion Consumer Service.

The PolicyMgtSAMLSPACS object includes methods to retrieve values for the index, protocol binding, and Assertion Consumer URL.

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 sign-out in this environment are implemented 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.

In a Perl script, you define a Resource Partner by calling the PolicyMgtAffDomain‑>CreateWSFEDResourcePartner method as follows:

$aff = $affDomain‑>CreateWSFEDResourcePartner(propsHash_ref);

propsHash_ref is a reference to a hash table of metadata properties defined for the Resource Partner.

This method returns a PolicyMgtWSFEDResourcePartner object. The PolicyMgtWSFEDResourcePartner object includes methods for managing users in the Resource Partner (AddUser, GetAllUsers, and RemoveUser). Note that the PolicyMgtWSFEDResourcePartner‑>Property() method does not submit changes to the data store. You must call the PolicyMgtWSFEResourcePartner‑>Save() method.

To define an Account Partner in a Perl script you create an instance of a WS-Federation authentication scheme by calling PolicyMgtSession‑>CreateWSFEDAuthScheme(). You can set or retrieve metadata properties for this authentication scheme by calling PolicyMgtSession‑>WSFEDAuthSchemeProperties().

There are no methods for deleting or retrieving a WS-Federation authentication scheme specifically. You use the DeleteAuthScheme, GetAuthScheme, and GetAllAuthSchemes as you would for any other type of authentication scheme. .

More Information:

WS-Federation Resource Partner Methods

WS-Federation Resource Partner Attribute Methods

Sample Scripts

The sample scripts AffiliateDemo.pl, SAMLServiceProvider.pl, WSFEDAccountPartner.pl, and WSFEDResourcePartner.pl are provided with Federation Security Services.

If not installed already Import ampolicy.smdif into the Policy Store before using the sample script. The default location of ampolicy.smdif is <siteminder_install_dir>\db\SMdif.

Affiliate Domains

Affiliate objects representing sites in a federated business network are contained within a Policy Server affiliate domain. An affiliate domain can contain SAML 1.x affiliates and SAML 2.0 Service Providers.

An affiliate domain also contains references to one or more user directories associated with the affiliates and Service Providers in the domain, and to the administrator accounts that can manage the domain.

You can use the Command Line Interface to configure affiliate objects and the affiliate domain where they reside.

Note: For more information about affiliate objects and affiliate domains, including prerequisites for using affiliate functionality, see the Policy Server Configuration Guide.

Authentication Scheme Configuration

When you configure an authentication scheme through a Perl script, you provide information that would otherwise be provided through the Authentication Scheme Properties dialog of the Administrative UI. This section describes the information you need to configure a given authentication scheme using the Policy Management API.

Note: When modifying an authentication scheme, be sure to call Save() after calling all the configuration methods.

Configuration Information

Typically, you configure an authentication scheme when you create the scheme with CreateAuthScheme() or when you modify the scheme with the methods in the PolicyMgtAuthScheme object.

Note: The exception to this rule is an authentication scheme based on the SAML 2.0 Template. You create and configure a SAML 2.0 authentication scheme with the method CreateSAMLAuthScheme().

You can provide the following kinds of configuration information for an authentication scheme. Not every authentication scheme template uses all categories of configuration information:

• Scheme type

  SiteMinder provides a number of standard authentication scheme types (also known as templates). Each authentication scheme type is configured differently.

• Description

  Brief description of the authentication scheme.

• Protection level

  Protection level values can range from 1 through 1000. The higher the number, the greater the degree of protection provided by the scheme.

• Library

  An authentication scheme library performs authentication processing for the associated authentication scheme type. Each predefined authentication scheme is shipped with a default library. Optionally, you can use a custom library instead of the default.

• Parameter

  Additional information that the authentication scheme requires, such as the URL of an HTML login page.

  With some authentication schemes, the parameter information is constructed from field values in the Scheme Type Setup tab of the Authentication Scheme Properties dialog. To see how a parameter string is constructed for a given scheme type, open this dialog, select the appropriate scheme type, provide values to the fields in the Scheme Type Setup tab, and view the constructed parameter in the Advanced tab.

• Shared Secret

  Information that is known to both the authentication scheme and the Policy Server. Different authentication schemes use different kinds of secrets. Most schemes use no secret.

• Is template?

  A flag that specifies whether the authentication scheme is a template.

  Note: Setting an authentication scheme as a template with the Perl Policy Management API is deprecated in SiteMinder v6.0 SP3.

• Is used by administrator?

  A flag that specifies whether the authentication scheme can be used to authenticate administrators.

• Save Credentials?

  A flag that specifies whether the user’s credentials are saved.

• Is RADIUS?

  A flag that specifies whether the scheme can be used with RADIUS agents.

• Ignore password check?

  A flag that specifies whether password policies for the scheme are enabled. If 1, password policies are disabled.

  Note: The Ignore password check flag must be set to True for anonymous authentication schemes.

Configuration Tables

The following tables will help you configure authentication schemes. Each table applies to a particular authentication scheme type and contains the following information:

• The PolicyMgtAuthScheme method that sets or retrieves a particular kind of configuration value.
• The default configuration value, if applicable, or a variable name, shown in italics, that represents the configuration value to be supplied.
• The name of the CreateAuthScheme() argument used to supply the configuration value when you are creating an authentication scheme.

The values in the Information Type column can be used for different purposes in different authentication schemes. For example, with TeleID authentication schemes, the shared secret is used to supply the encryption seed.

Anonymous Template

Use this table when configuring an authentication scheme based on the scheme type Anonymous.

Note: The Ignore password check flag must be set to True for anonymous authentication schemes.

Basic Over SSL Template

Use this table when configuring an authentication scheme based on the scheme type Basic over SSL.

Basic Template

Use this table when configuring an authentication scheme based on the scheme type Basic.

Custom Template

Use this table when configuring an authentication scheme based on the scheme type Custom. You create custom schemes using the C-language Authentication API, which is available with the SiteMinder SDK.

HTML Form Template

Use this table when configuring an authentication scheme based on the scheme type HTML Form.