Administration Application Guide
|
 |
 |
|
|
 |
 |
The ASI Authorization and Role Mapper providers use an external server process to evaluate authorization decisions. This process is called the Authorization and Role Mapping Engine (ARME).
This section describes the Application Programming Interface (API) for writing custom extension libraries (plug-ins) for this process to enhance features available through the policy language, such as routines for dynamic computation of an attribute value (credential function) or custom predicate (evaluation function).
The following plug-in function pointers are described in this API:
*CredFunc() - Custom Credential Function Pointer
*EvalFunc() - Custom Evaluation Function Pointer
*ShutdownFunc () - Custom Shutdown Function Pointer
*PluginInitFunc() - Plug-in Initialization Function Pointer
registerCustomCredentialFunction() - Register Credential Function
registerCustomEvaluationFunction() - Register Evaluation Function
These extension functions (called plug-ins) take two kinds of parameters: required and optional. Parameters also have one of two modes: in or out. Input parameters pass data to an extension. Output parameters receive data from an extension.
Pointer to a function that computes the value of a credential function. Your plug-in function is internally referenced by this pointer. The registerCustomCredentialFunction() function assigns the pointer to your function. For example, this function declares a credential function:
bool MyCredentialFunction (Session &sess, const char *cvarname)
The ARME then connects a function pointer (assign a handle) to your function:
returnCode = registerCustomCredentialFunction( "MyCredentialFunctionsName", MyCredentialFunction);
bool (*CredFunc)(Session &sess, const char *cvarname);
*cvarname is a required input parameter, that points to a null-terminated character string (a character array) and contains the name of a credential function.
&sess is a required output parameter that references the address of a Session object and a session that contains the computed value of the credential function.
TRUE if the computation is successful
FALSE if the computation is unsuccessful
bool GetAccountID(Session &sess, const char *cvarname)
{
...
}
*EvalFunc()
Points to a function that computes the value of an evaluation function. Your plug-in function is internally referenced by the ARME through this pointer. The registerCustomEvaluation Function() function assigns the pointer to your plug-in function. For example, you could declare a evaluation function like this:
TruthValue MyEvalFunction(Session &sess,const char *fname, char **argv);
The ARME then connects a function pointer (assign a handle) to your function:
returnCode = registerCustomEvaluationFunction("MyEvaluationFunctionsName", MyEvalFunction);
TruthValue (*EvalFunc)(Session &sess,const char *fname, char **argv);
&sess is a required output parameter that references the address of a Session object and a session that contains the computed value of the credential variable.
*fname is a required input parameter that points to a null-terminated character string (a character array) and contains the name of an evaluation function.
**argv is a required input parameter and is a pointer to a null-terminated array (also a pointer) of null-terminated strings (character arrays), containing a list of arguments for the function.
TruthValue enumerated list, containing one of three constants:
TV_UNKNOWN is an error or undefined result
TruthValue isValidAccountID(Session &sess, const char* fname, char **argv)
{...}
*CredFunc()
Points to a function that is called when the ARME is about to be shutdown. Put all cleanup code inside this function that you want the plug-in to perform before the shutdown; for example, open windows handlers, open file pointers, and database connections. Your plug-in function is internally referenced by the ARME by this pointer. The registerShutdownFunction() function assigns the pointer to your plug-in function. For example, to declare a shutdown function, use the following:
MyShutdownFunction ()
Assign a handle to your function to connect the ARME to your function pointer:
returnCode = registerShutdownFunction(MyShutdownFunction);
void (*ShutdownFunc)();
void MyShutdownFunction()
{
// Code that needs to run for the plugin to release
// any resources or open connections that it created
}
*PluginInitFunc()
Points to a function that initializes an ARME plug-in. The name of this function must appear in the ARME configuration file. For example, for the following statement, include the function name initMyplugins() in the ARME configuration file.
ARME.Instance1.plugin1 F:/BEA/MyPlugins/ Plugin01.dll(initMyplugins 'plugin1')
void (*PluginInitFunc)(const char *argp);
*argp is a required input parameter and is a pointer to a null-terminated array of null-terminated character strings that contains a list of arguments for the initialization.
void initPlugin(const char *pluginName)
{
...
}
Registers a credential function with a ARME.
bool registerCustomCredentialFunction(const char *credname,CredFunc credfunc);
*credname is a required input parameter and points to a null-terminated character string that contains the name of a custom credential function.
credFunc is a required input parameter used to register the credential function.
TRUE if the registration is successful
FALSE if the registration is unsuccessful
returnCode = registerCustomCredentialFunction("MyCredentialFunctionsName", MyCredentialFunction);
registerCustomEvaluationFunction()
Registers a custom evaluation function with a ARME.
bool registerCustomEvaluationFunction(const char *evalname, CredFunc evalfunc);
*evalname is a required input parameter and points to a null-terminated character string that contains the name of an evaluation function.
evalFunc is a required input parameter used to register the evaluation function.
TRUE if the registration is successful
FALSE if the registration is unsuccessful
returnCode = registerCustomEvaluationFunction("MyEvaluationFunctionsName", MyEvalFunction);
registerCustomCredentialFunction()
Registers a shutdown function.
bool registerShutdownFunction(ShutdownFunc shutdownfunc);
ShutdownFunc is a required input parameter used to register the function.
TRUE if the registration is successful
FALSE if the registration is unsuccessful
returnCode = registerShutdownFunction(MyShutdownFunction);
registerCustomEvaluationFunction()
registerCustomCredentialFunction()
A session object keeps all data related to a single access or role query. All attributes used during evaluation are accessible through the session object.
Subject and resource attributes are always accessible. A dynamic attribute, either computed by an evaluation function or passed in, may be accessible, but this is not guaranteed as they are loaded as needed. A attribute used as an argument for an evaluation function is computed before that function is invoked.
The following session objects are described in this API:
Session::SetAttribute() - Append AttributeValue Object
Session::getAttribute() - Get AttributeValue Object from Attribute
Session::getEvalResult() - Get Evaluation Result
Session::appendReturnData() - Return Evaluation Results
Session::getDomainName() - Get Domain Name for the Session
Session::getLocationName() - Get Location Name for Session
Session::getApplicationName() - Get Application Name for Session
Session::getUserID() - Get User Name for Session
Sets an attribute value for a credential attribute by appending an AttributeValue object to the named credential.
bool setAttribute(const char *name, AttributeValue *value, bool overwrite)
*name is a required input parameter that points to a null-terminated character string (a character array), referencing the name of the credential attribute. This parameter must be passed a const char * and not as a char * variable. Simply placing the name directly into the function (in quotation marks) does not work.
*value is a required input parameter that points to an AttributeValue object and contains the value of the credential. Allocate this object with a new operator because the session object takes ownership of the object.
Warning: Passing in a pointer to a local object or deleting this pointer inside your plug-in may lead to unexpected results, most likely terminating the ARME process.
overwrite is a required input parameter Boolean value (TRUE or FALSE), that determines whether to overwrite existing attributes of the same name. During evaluation, values set with this call take precedence over static or dynamic values defined for the same credential attribute. There are no safeguards to prevent modifying the values of these credential attributes. You should set the value of a credential function only for the attribute to which it is registered.
TRUE if operation was successful
FALSE if it was not successful
AttributeValue* SomeAttributeValue = new AttributeValue(false);
const char *CredName = "SongCount";
const char *Value = "small";
SomeAttributeValue.setValue(Value);
retcode = sess.setAttribute(CredName, SomeAttributeValue, true);
Warning: Some AttributeValue methods may cause an exception and memory leak if you call them before calling setAttribute().
getAttribute()
Gets an attribute value for a credential attribute by requiring that you pass it the address of an existing AttributeValue object. You can use getAttribute("my_roles", SomeAttributeValue) to retrieve a list containing the role for a subject.
Warning: BEA strongly recommends that you not modify the contents of the AttributeValue object. Some AttributeValue objects are shared between credentials objects and evaluation threads. Manipulating their values can lead to unexpected results.
bool getAttribute(const char * name, AttributeValue *& value)
*name is a required input parameter that points to a null-terminated character string (a character array) and references the name of a credential attribute. You must pass this parameter as a const char * and not a char * variable. Simply putting the name directly into the function in quotation marks does not work.
*&value is a required input parameter that points to an AttributeValue object and contains the value of the attribute.
TRUE if operation was successful
FALSE if it was not successful
const char *inputvalue = "LillyLiverCount";
retcode = sess.getAttribute(inputvalue,SomeAttributeValue);
setAttribute()
Returns a pointer to a temporary EvalResult object containing the data returned, along with the access decision upon the execution of the rule containing the evaluation or credential function. The plug-in does not know in advance if the rule containing the plug-in function executes (other rules that preclude it may execute first), so modifying this object does not guarantee the information is returned. BEA recommends using the appendReturnData() method. In many cases, you may find using the report() and report_as() functions easier and more flexible.
EvalResult* getEvalResult();
Pointer to an EvalResult object containing the evaluation results (output attributes) that may be returned by the executing rule.
EvalResult *MyEvalResultPtr = getEvalResult();
getEnumValue()
Sets the evaluation results returned through an EvalResult object upon successful execution of a rule containing the evaluation or credential function that references the plug-in function. It does so by copying the contents of the AttributeValue object that is passed to it.
If the same attribute value is redefined by another plug-in within the same rule, the return value is overwritten.
The evaluation result is returned only if the rule actually executes. It might not if another rule makes evaluating it superfluous. For example, once a user is explicitly denied access with a deny rule, a thousand grant rules cannot undo the one deny. Knowing this, as soon as a single grant rule for an access attempt is found, BEA WebLogic Enterprise Security only looks for deny rules. When a single deny rule is found, it stops looking.
The exception to this is if the findAllFacts flag is enabled, which you have to consciously set. When you set the findAllFacts flag to true, you are telling BEA WebLogic Enterprise Security to return the rule attributes for all rules affecting the access attempt, whether or not the rules are redundant. Setting the findAllFacts flag to true does change the fact that once a deny rule has executed, grant rules are not evaluated. The sole purpose is to evaluate and possibly append return results from all deny rules or all grant rules if no deny rules fired.
Warning: Setting the findAllFacts flag to true dramatically slows down each access attempt because all rules are checked every time. Avoid setting the flag to true, unless there is no other way to accomplish your goal.
Warning: Each EvaluationResult object contains the relevant rule identification number, the name of the object and privilege in that rule, and a collection of return attributes in list form. Single values are represented as single-value lists.
Warning: Unlike the setAttribute() method, this method copies the content of the data. If you allocate the AttributeValue object with the new operator, you have to delete the object. If you do not, a memory leak may result. You are free to pass in a pointer to a local variable, like that retrieved by the getAttribute() method.
void appendReturnData(const char *name, const AttributeValue *data);
*name is a required input parameter that points to a null-terminated character string (a character array) and references the name of the output credential attribute. This parameter must be passed a const char * and not a char * variable. Simply putting the name directly into the function in quotation marks does not work.
*data is a required input parameter that points to an AttributeValue object and contains the value of the attribute.
AttributeValue LocalValue(true);
const char *OutputAttributeName = "SomeCount";
const char *ValueSample = "shopping";
LocalValue.addValue(ValueSample);
appendReturnData(OutputAttributeName, &LocalValue);
getEvalResult()
Retrieves the name of the domain for the session object to which it belongs.
const char *getDomainName() const;
Points to a null-terminated character string (a character array) and references the name of the session domain.
const char *CLDomainNameStr = getDomainName();
getLocationName()
Retrieves the name of the location for the session object to which it belongs.
const char *getLocationName() const;
Points to a null-terminated character string (a character array) and references the name of the session location.
const char *CLLocationNameStr = getLocationName();
getDomainName()
Retrieves the name of the application for the session object to which it belongs.
const char *getApplicationName() const;
Points to a null-terminated character string (a character array) and references the name of the session application.
const char *CLAppNameStr = getApplicationName();
getUserID()
Retrieves the name of the user for the session object to which it belongs.
const char *getUserId() const;
Points to a null-terminated character string (a character array) and references the name of the session user.
const char *CLUserNameStr = getUserId();
getApplicationName()
Contains the methods for manipulating AttributeValue objects, which is how attribute values are stored for each user credential attribute.
This section describes the following AttributeValue objects:
AttributeValue::addValue() - Add and Set a String List Attribute Value
AttributeValue::AttributeValue() - Constructor
AttributeValue::entries() - Count Number of List Elements
AttributeValue::getValue() - Get Single Attribute Value
AttributeValue::has() - Check If Value is Already Present in a List
AttributeValue::IsList() - Is Attribute Value an Indexed List?
AttributeValue::IsSingle() - Is Attribute Value a Single Value?
AttributeValue::isUndefined() - Is Attribute Value an undefined object?
AttributeValue::setValue() - Set Single Attribute Value
AttributeValue::removeAt() - Remove Indexed List Attribute Value
AttributeValue::removeValue() - Remove Named List Attribute Value
AttributeValue::size() - Count Number of List Elements
AttributeValue [ ] Operator - Returns the Value of an Indexed String List Element
AttributeValue objects store values in one of two ways:
Single values are nothing more than one string of characters per AttributeValue object and are the most common type of attribute value. The methods that are exclusively for manipulating single values are:
setValue()
getValue()
Lists of values are collections of strings for one AttributeValue object. They are accessed by their index value (in square brackets), just like a one-dimensional array. Normally, list values are not set with duplicate string values. The methods that are exclusively for manipulating lists of values are:
addValue()
removeValue()
removeAt()
entries()
There is also an undefined type of AttributeValue object created by a default constructor with no arguments. It becomes either a single or a list type after the first call to the setValue() method (single), addValue() method (list), or operator=().
Several methods are available for both single and list attributes. Most of them are for testing what type of attribute you have. These include:
size() (returns 1 for single value, or entries() for list value)
operator[0] (same as getValue() for index 0), or operator[] for list type
isList()
isSingle()
isUndefined()
has()
The header files contain many methods related to this class and ones that are not documented. These are used internally by the ARME and are not recommended for use. BEA cannot guarantee these methods work at all or will work in the future due to deprecation. These include operator+=(), operator-=(), all those taking non-const char*, enumeration-related, and type-checking-related methods.
Warning: BEA does not recommend using any method not documented in this guide.
Adds and sets a string value to a string list AttributeValue object. Use isList() to determine if the object contains a list of values. If you call this method for an undefined AttributeValue object, it becomes a list type.
void addValue(const char *value, bool check_unique = false)
*value is a required input parameter that points to a null-terminated character string (a character array). This parameter adds an element to the end of a string list increasing the list index value by one and must be passed a const char * and not a char * variable. Simply putting the value directly into the function in quotation marks does not work.
check_unique is an input parameter that defaults to false. If this parameter is set to TRUE, duplicate values are not added to the list.
const char *FavoriteSongValue = "foreveryours";
if (FaveSongAvObj.isList())
FaveSongAVObj.addValue(FavoriteSongValue);
setValue()
getValue()
isList()
The AttributeValue class constructor is polymorphic. You can pass it different sets of parameters depending on your goals.
AttributeValue();
AttributeValue(const char *value);
For an empty list of values or a single value:
AttributeValue(bool isList);
To copy an existing AttributeValue:
AttributeValue(const AttributeValue &value);
*value (String) is a required input parameter used to create a single-value attribute that points to a null-terminated character string (a character array). This parameter references the name of a credential attribute and must be passed a const char * and not a char * variable. Simply putting the value directly into the function in quotation marks does not work.
&value (AttributeValue Object) is a required input parameter (for copying an AttributeValue object) that points to an AttributeValue object.
isList is set to TRUE if the attribute and contains an enumerated list of strings; set to FALSE for a single value attribute.
const char *MyAttrName = "SomeCount";
AttributeValue *MyAttrValPtr = new
AttributeValue(MyAttrName);
AttributeValue *MyAVListPtr = AttributeValue(true);
To copy an existing AttributeValue object:
AttributeValue *MyAttrValPtr = new
AttributeValue(MyExistingAttrValObj);
setValue()
Returns a count of the total number of elements in an indexed list.
int entries() const
An integer that contains the total count of elements.
if (FaveSongAvObj.isList())int elementCount = FaveSongAVObj.entries();
addValue()
AttributeValue::size()
Gets a single string value for an AttributeValue object. Use isSingle() to determine if the object contains a single value.
const char *getValue() const
A pointer to a constant, null-terminated character string (a character array) that contains the string value of the AttributeValue object. This value must be a const char * and not a char * variable.
const char *FavoriteSongValue;
if (FaveSongAvObj.isSingle())FavoriteSongValue =
FaveSongAVObj.getValue();
addValue()
setValue()
isSingle()
Checks if a value is present in a list or if a single-value attribute is equal to it. AttributeValue objects of the list type should not contain redundant values.
bool has(const char * value) const
Points to a null-terminated character string (a character array)
TRUE if the supplied value is present in a list, or is equal to the value of a single type value.
Bool A = AttributeValue.has("SomeValue");
addValue()
setValue()
AttributeValue::size()
Returns TRUE if the AttributeValue object contains a list of strings or integers. The list attribute values are accessed by their index value.
bool isList() const;
TRUE if the attribute contains a list of values
bool AttrIsList = MyAttrValueObj.isList();
isSingle()
Returns TRUE if the AttributeValue object contains a single value and not a list of values.
bool isSingle() const;
TRUE if the attribute is a single-value type
bool AttrIsSingle = MyAttrValueObj.isSingle();
isList()
Returns TRUE if the AttributeValue object is constructed with a default constructor and does not have a list or single type. The type can be set by calling setValue(), or addValue() methods and becomes a single value or a list correspondingly, or by using an assignment operator. Once set, the type cannot be changed.
bool isUndefined() const;
TRUE if the attribute is undefined
bool AttrIsSingle = MyAttrValueObj.isUndefined();
isList()
Sets a single string value for an AttributeValue object. Use isSingle() to determine if the object is the correct type for a single value. If you call this method for an undefined AttributeValue object, it becomes a single type.
void setValue(const char *value)
*value is a required input parameter that points to a null-terminated character string (a character array) and sets the string value of an AttributeValue object. This parameter must be passed a const char * and not a char * variable. Simply putting the value directly into the function in quotation marks does not work.
const char *FavoriteSongValue = "foreveryours";
FaveSongAVObj.setValue(FavoriteSongValue);
addValue()
getValue()
Removes a value identified by index in a string or integer list AttributeValue object. Use isList() to ensure that it is a list of values.
char *removeAt(int idx)
idx is a required input parameter with an integer value that removes a string or integer element in the list by the index value of the element (index starts at 0).
A pointer to the string representing the value. This is provided as a convenience to use the value so you do not have to retrieve the value with a separate call.
Warning: You must delete the returned value with the delete[] operator within the plug-in.
//Remove the second value, which is "Apple":
char * MrValue = someAttrValuePtr->removeValue(1);
//MrValue now points to "Apple" if the index position
//contained such value, to null if not..
//Delete value, even if null:
delete[] MrValue;
addValue()
removeValue()
Removes a named element from a string list AttributeValue object. Use isList() to determine if the object contains a list of values.
char *removeValue(const char *value)
*value is a required input parameter that points to a null-terminated character string (a character array) and identifies an element in the list by the value of the element. This parameter must be passed a const char * and not a char * variable. Simply putting the value directly into the function in quotation marks does not work.
A pointer to the sting representing the value. This is provided as a convenience to use the value so you do not have to retrieve the value with a separate call.
Warning: To avoid a memory leak, you must delete the returned value with the delete[] operator within the plug-in.
char * MrValue = someAttrValuePtr->removeValue("Apple");
//MrValue now points to "Apple" if someAttrValuePtr
//contained such value, to null if not..
//Delete value, even if null:
delete[] MrValue;
addValue()
removeAt()
isList()
This method returns a count of the total number of elements in an indexed list and returns the value 1 for single-type attributes. That is, for lists, it is equivalent to entries().
int entries() const
An integer value that contains the total count of elements.
if (FaveSongAvObj.isList())int elementCount = FaveSongAVObj.size();
addValue()
AttributeValue::size()
Retrieves the value of a specific list element by integer index, use the [] overloaded operator. For example, to retrieve the third element in the Colors string list, use this syntax:
const char *FavoriteColor = Colors[2];
You can use isList() beforehand to determine if the object contains a list of values and entries() or size() to ensure the index is valid. This method also works with single-type object. In such a case, the index is 0. When used in this way, the method is equivalent to the getValue() method.
|
|
|