You can create the following types of extensions:
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.
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.
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. |
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.
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. |
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. |
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.
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. |
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.
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. |