4.3 Creating an Extension

4.3.1 Creating a Context Data Extension

A context data extension can be used for a Role policy, an Authorization policy, an Identity Injection policy, or an External Attribute Source policy. When the extension is used for an Authorization policy, it can only be used to evaluate a condition. When it is used for a Role policy, it can be designed to do the following:

  • A condition to determine whether the user meets the requirements for a role assignment

  • An action for activating roles based on the values returned by the extension.

When the extension is used for an Identity Injection policy, it injects data into the Authentication header, the custom header, or the query string.

The following sections describe the interfaces, methods, and configuration parameters available for a context data extension:

For sample code for this type of extension, see the LDAPGroupDataElement.java and LDAPGroupDataElementFactory.java file.

Context Data Interfaces and Methods

When creating a context data element extension, you need to implement the following interfaces and methods:

Interface

Method

Purpose

NxpeContextDataElementFactory

Contains the method required to create a context data element object.

 

getinstance

Creates the NxpeContextDataElement object.

NxpeContextDataElement

Contains methods required to create a context data element that can be used for injection, for activating roles, or in a condition.

 

initialize

Called by policy engine and therefore must be implemented. It initializes the element and sends configuration values you have requested to your extension. These parameters contain valid information only if the parameters contain information independent of the request that triggers policy evaluation.

The data in the configurationValues parameter is valid only during the lifetime of the initialize method. If your extension needs to preserve this configuration data, you must maintain a reference.

The get methods in this interface allow you to retrieve information about the parameters when the policy is being evaluated.

getEnumerativeValue

Returns -1. Reserved for future releases.

 

getName

Retrieves the name of the data element of the policy.

 

getParameter

Retrieves the string value of the parameter of the policy.

 

getValue

Called by the policy engine when a request triggers a policy evaluation. The informationContext object contains parameter values that you need from the policy engine for the evaluation.

When you configure a condition in a policy, you select a condition and a value. The condition sets up the left operand for the comparison and the value sets up the right operand for the comparison.

Available Configuration Parameters for a Data Context Extension

You can use any of the data items listed in the Table 4.1 to create configuration parameters to retrieve information about the request and the user making the request. Select the parameters that are useful for your extension. Many of the available data items might not be useful for your implementation.

Table 4-1 Configuration Parameters for a Role Policy

Data Item

Returns

Authentication IDP

The name of Identity Server that authenticated the user.

Authenticating Contact

The URI of the contract that the user used for authentication.

Authentication Method

The name of the method the user used for authentication.

Authentication Type

The type of authentication the user used, such as Name Password, Secure Name Password, x509, Smart Card, Smart Card PKI, and Token.

Credential Profile

The credentials the user used for authentication, such as LDAP Credentials (CN, DN, and password), X509 Credentials (with certificate subject, with certificate issuer, with public certificate, and with serial number), and SAML Credentials.

If a custom contract is created that uses other credentials for authentication, these credentials are not available within the credential profile.

LDAP Group

The DNs of any LDAP groups the user belongs to. If it is multi-valued, this item returns a string array.

LDAP OU

The DNs of any OUs that are part of the user’s DN. If it is multi-valued, this item returns a string array.

LDAP Attribute

The value or values stored in the specified LDAP attribute. If it is multi-valued, this item returns a string array.

Liberty User Profile

The value or values stored in the specified Liberty User Profile attribute.

Roles from Identity Provider

The names of the Roles assigned to the user by Identity Server when the user authenticated. If it is multi-valued, this item returns a string array.

User Store

The name of the user store that authenticated the user.

User Store Replica

The URL of the replica that authenticated the user.

String Constant

The static value the administrator has been instructed to enter.

Table 4-2 Configuration Parameters for an Identity Injection Policy

Data Item

Returns

Authenticating Contact

The URI of the contract that the user used for authentication.

Client IP

The IP address of the user.

Credential Profile

Credentials the user used for authentication, such as LDAP Credentials (CN, DN, and password), X509 Credentials (with certificate subject, with certificate issuer, with public certificate, and with serial number), and SAML Credentials.

If a custom contract has been created that uses other credentials for authentication, these credentials aren’t available within the credential profile.

LDAP Attribute

The value or values stored in the specified LDAP attribute. If it is multi-valued, this item returns a string array.

Liberty User Profile

The value or values stored in the specified Liberty User Profile attribute.

Proxy Session Cookie

The session cookie associated with the user.

Roles

The roles that have been assigned to the user

Shared Secret

The value of the specified shared secret.

String Constant

The static value the administrator has been instructed to enter.

Table 4-3 Configuration Parameters for an Authorization Policy

Data Item

Returns

Authentication Contract

The URI of the contract used for authentication or the URI of the specified contract.

Client IP

The IP address of the user.

Credential Profile

The credentials of the user. You can ask for LDAP credentials (username, DN, and password), X.509 credentials (public certificate subject, public certificate issuer, public certificate, serial number), or the SAML assertion.

Current Date

The date when the request was sent.

Day of Week

The day when the request was sent.

Current Day of Month

The day of the month when the request was sent.

Current Time of Day

The time of day when the request was sent.

HTTP Request Method

The HTTP method in the request.

LDAP Attribute

The value of the specified LDAP attribute.

LDAP OU

The value of any OUs in the user’s DN.

Liberty User Profile

The value of the specified Liberty attribute.

Roles

The roles that have been assigned to the user.

URL

The URL of the current request.

URL Scheme

The HTTP scheme (HTTP or HTTPS) of the current request.

URL Host

The hostname specified in the URL of the current request.

URL Path

The path specified in the URL of the current request.

URL File Name

The filename specified in the URL of the current request.

URL File Extension

The file extension specified in the URL of the current request.

X-Forwarded-For IP

The value in the X-Forwarded-For header in the current request.

String Constant

The static value the administrator has been instructed to enter.

Table 4-4 Configuration Parameters for an External Attribute Source Policy

Data Item

Returns

Authentication IDP

The name of Identity Server that authenticated the user.

Authenticating Contact

The URI of the contract that the user used for authentication.

Authentication Method

The name of the method the user used for authentication.

Authentication Type

The type of authentication the user used, such as Name Password, Secure Name Password, x509, Smart Card, Smart Card PKI, and Token.

Credential Profile

Credentials the user used for authentication, such as LDAP Credentials (CN, DN, and password), X509 (with certificate subject, with certificate issuer, with public certificate, and with serial number), and SAML Credentials.

If a custom contract uses other credentials for authentication, these credentials are not available within the credential profile.

LDAP Group

DNs of any LDAP groups the user belongs to. If it is multi-valued, this item returns a string array.

LDAP OU

DNs of any OUs that are part of the user’s DN. If it is multi-valued, this item returns a string array.

LDAP Attribute

The values stored in the specified LDAP attribute. If it is multi-valued, this item returns a string array.

Liberty User Profile

The values stored in the specified Liberty User Profile attribute.

Roles from Identity Provider

The names of the Roles assigned to the user by Identity Server when the user authenticated. If it is multi-valued, this item returns a string array.

User Store

The name of the user store that authenticated the user.

User Store Replica

The URL of the replica that authenticated the user.

String Constant

The static value the administrator has been instructed to enter.

4.3.2 Creating a Condition Extension

A condition extension can be used in a Role policy or an Authorization policy. In both types of policy, the policy engine provides the extension with some data about the user and the request. The extension retrieves additional data from an external source, then evaluates the condition. The extension returns True, False, or Error to the policy engine.

The following sections describe the interfaces, methods, and configuration parameters available for a condition extension.

Interfaces and Methods for a Condition Extension

When creating a condition extension, you need to implement the following interfaces and methods:

Interface

Method

Purpose

NxpeConditionFactory

Contains the method required to create a condition object.

 

getInstance

Creates the NxpeCondition object.

NxpeCondition

Contains the methods required to evaluate the condition for a policy.

 

initialize

Called by policy engine and therefore must be implemented. It initializes the element and passes to your extension any configuration values you have requested. These parameters contain valid information only if the parameters contain information independent of the request that triggers policy evaluation.

The data in the configurationValues parameter is valid only during the lifetime of the initialize method. If your extension needs to preserve this configuration data, you must maintain a reference.

evaluate

Called by the policy engine when the condition extension needs to be evaluated for a policy. The informationContext parameter contains the parameter information the extension needs from the policy engine to evaluate the condition. The responseContext parameter contains the results of the extension’s evaluation of the condition.

 

setInterfaceId

Sets the unique string value for the condition. This value is used for tracing evaluation.

Available Configuration Parameters for a Condition Extension

You can use the configuration parameters to gather information about the user. You can then use this information when evaluating your condition and use it to determine whether the condition should return True or False. The available configuration parameters depend upon whether it is a condition for a Role policy or a condition for a Authorization policy. Select the parameters that are useful for your extension. Many of the available data items might not be useful for your implementation.

Table 4-5 Configuration Parameters for a Role Condition

Data Item

Returns

Authentication IDP

The name of Identity Server that authenticated the user.

Authenticating Contact

The URI of the contract that the user used for authentication.

Authentication Method

The name of the method the user used for authentication.

Authentication Type

The type of authentication the user used, such as Name Password, Secure Name Password, x509, Smart Card, Smart Card PKI, and Token.

Credential Profile

The credentials the user used for authentication, such as LDAP Credentials (CN, DN, and password), X509 Credentials (with certificate subject, with certificate issuer, with public certificate, and with serial number), and SAML Credentials.

If a custom contract has been created that uses other credentials for authentication, these credentials are not available within the credential profile.

LDAP Group

The DNs of any LDAP groups the user belongs to. If it is multi-valued, this item returns a string array.

LDAP OU

The DNs of any OUs that are part of the user’s DN. If it is multi-valued, this item returns a string array.

LDAP Attribute

The value or values stored in the specified LDAP attribute. If it is multi-valued, this item returns a string array.

Liberty User Profile

The value or values stored in the specified Liberty User Profile attribute.

Roles from Identity Provider

The names of the Roles assigned to the user by Identity Server when the user authenticated. If it is multi-valued, this item returns a string array.

User Store

The name of the user store that authenticated the user.

User Store Replica

The URL of the replica that authenticated the user.

String Constant

The static value the administrator has been instructed to enter.

Table 4-6 Configuration Parameters for an Authorization Condition

Data Item

Returns

Authentication Contract

The URI of the contract used for authentication or the URI of the specified contract.

Client IP

The IP address of the user.

Credential Profile

The credentials of the user. You can ask for LDAP credentials (username, dn, and password), X.509 credentials (public certificate subject, public certificate issuer, public certificate, serial number), or the SAML assertion.

Current Date

The date when the request was sent.

Day of Week

The day when the request was sent.

Current Day of Month

The day of the month when the request was sent.

Current Time of Day

The time of day when the request was sent.

Destination IP

The destination IP address of the request.

HTTP Request Method

The HTTP method in the request.

LDAP Attribute

The value of the specified LDAP attribute.

LDAP OU

The value of any OUs in the user’s DN.

Liberty User Profile

The value of the specified Liberty attribute.

Roles

The roles that have been assigned to the user.

URL

The URL of the current request.

URL Scheme

The HTTP scheme (HTTP or HTTPS) of the current request.

URL Host

The hostname specified in the URL of the current request.

URL Path

The path specified in the URL of the current request.

URL File Name

The filename specified in the URL of the current request.

URL File Extension

The file extension specified in the URL of the current request.

X-Forwarded-For IP

The value in the X-Forwarded-For header in the current request.

String Constant

The static value the administrator has been instructed to enter.

4.3.3 Creating an Action Extension

There are the three types of actions: deny, permit, and obligation. The following sections describe the interfaces, methods, and configuration parameters available for an action extension.

Action Interfaces and Methods

When creating an action extension, you need to implement the following interfaces and methods:

Interface

Method

Purpose

NxpeActionFactory

Contains the methods required to create an action object.

 

getInstance

Creates the NxpeAction object.

NxpeAction

 

Contains the methods required to implement a deny, permit, or obligation action.

 

Initialize

Called by the policy engine and therefore must be implemented. It initializes the element and passes to your extension any configuration values you have requested. These parameters contain valid information only if the parameters contain information independent of the request that triggers policy evaluation.

The data in the configurationValues parameter is valid only during the lifetime of the initialize method. If your extension needs to preserve this configuration data, you must maintain a reference.

 

doAction

Called by the policy engine when the action extension needs to be evaluated for a policy. The informationCtx parameter contains the parameter information the extension needs from the policy engine to evaluate the condition. The responseCtx parameter contains the results of the action.

 

setInterfaceId

Sets the unique string value for the action. This value is used for tracing the action during policy evaluation.

Actions

A policy rule can have multiple obligation actions but only one terminating action of either permit or deny. A permit or deny action needs to return either success or failure to the policy engine. An obligation action can return either success or failure; the policy engine just needs the acknowledgment that the obligation extension has performed its action.

An extension that implements an obligation action can use the doAction method to enter a log or audit event in another system or send an email message.

An extension that implements a deny or permit action can use the doAction method to ask another database or policy to evaluate a condition and then return the results of that evaluation to the Access Manager policy engine.

Available Configuration Parameters for an Action Extension

You can use any of the data items in the list to retrieve information about the user and the user’s request to create a configuration parameter. Your extension can then use this information in determining the type of action to take. Select the parameters that are useful for your extension. Many of the available data items might not be useful for your implementation.

Data Item

Returns

Authentication Contract

The URI of the contract used for authentication or the URI of the specified contract.

Client IP

The IP address of the user.

Credential Profile

The credentials of the user. You can ask for LDAP credentials (username, dn, and password), X.509 credentials (public certificate subject, public certificate issuer, public certificate, serial number), or the SAML assertion.

Current Date

The date when the request was sent.

Day of Week

The day when the request was sent.

Current Day of Month

The day of the month when the request was sent.

Current Time of Day

The time of day when the request was sent.

HTTP Request Method

The HTTP method in the request.

LDAP Attribute

The value of the specified LDAP attribute.

LDAP OU

The value of any OUs in the user’s DN.

Liberty User Profile

The value of the specified Liberty attribute.

Roles

The roles that have been assigned to the user.

URL

The URL of the current request.

URL Scheme

The HTTP scheme (HTTP or HTTPS) of the current request.

URL Host

The hostname specified in the URL of the current request.

URL Path

The path specified in the URL of the current request.

URL File Name

The filename specified in the URL of the current request.

URL File Extension

The file extension specified in the URL of the current request.

X-Forwarded-For IP

The value in the X-Forwarded-For header in the current request.

String Constant

The static value the administrator has been instructed to enter.