Figure 1 - Password Rules Class Diagram
|
|||||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | ||||||||||
See:
Description
| Interface Summary | |
|---|---|
| PasswordGenerator | Interface which needs to be implemented by all custom password generators. |
| Rule | This interface needs to be implemented by all standard and custom password rule classes. |
| ValidationInfo | Interface for classes providing contextual information used to validate passwords. |
| Class Summary | |
|---|---|
| BehavioralRule | Abstract base class for Rule implementations that provide validation of password's behavior. |
| LexicalRule | Abstract base class for Rule implementations that provide validation of password's lexical content. |
| Test | |
| Exception Summary | |
|---|---|
| IncompatibleRulesException | IncompatibleRulesException is thrown when given two rules cannot be joined because they are not compatible. |
| InvalidPasswordException | Objects of this class are thrown when a password violates one of the rules. |
| IterationsExceededException | Class represents an exception, which is thrown if the allowed number of iterations was exceeded while generating a random password satisfying all associated password rules. |
Provides a framework and an application programming interface to generate and validate passwords.
The Password Rules API has been developed to provide the developers a means for adding custom rules to the password validation engine of Identity Manager or for overriding the default password generation algorithm that Identity Manager uses. The Identity Manager password engine will invoke custom logic for both of these purposes if the steps outlined below are taken.
The Password Rules API is organized at two levels of abstraction. The base level of abstraction only addresses a generic password environment. The only context of the password engine is a single generic object with a password and other general attributes. The second level of abstraction is specific to provisioning. At this level, the context of the password engine is assumed to be an account, whereby the attributes of the account are available, as well as the attributes of the identity that owns the account and the service that hosts the account. The engine being extended will determine the abstraction, or the context, being used when executing rules. In other words, if the client is customizing the password engine of a simple identity password management application the base context will be available, whereas if the client is customizing the Identity Manager provisioning product the provisioning context will be available. A better explanation of this will be provided below.
The Password Rules API consists of a set of classes that provide interfaces that clients can implement so that their custom algorithms can participate in the password validation and password generation frameworks. The UML class diagram in Figure 1 below illustrates the primary objects in these frameworks and their relationships.
Figure 1 - Password Rules Class Diagram
Rule is an interface that defines the requirements of one specific password rule. The client will provide an implementation to these requirements and this interface in order for their custom rule algorithm to be integrated into the rules framework. A Rule gets its context, id of password protected object, password history, and other attributes of the password protected object, from an implementation of the ValidationInfo interface. The password rules engine generates the context and provides it to the Rule implementation at the time of evaluation.
The password rules framework supports the merging, or joining, of multiple rule sets with overlapping rules when validating a single password. For example, the framework can evaluate to two rule sets, each defining a minimum length rule. The engine will attempt to validate the single password against both rules. In this example, this appears simple, the engine could simply evaluate the password against the rules one at a time. However, it is not so easy to relay to a client what the password rule requirements are without listing them one at a time, which could become overwhelming if there are many rules and many rule sets that are configured. For this reason, any class implementing Rule interface is expected to provide logic in a join() method, which would allow joining parameters of two rules of the same type and returning that one rule definition. So, in our example of two rule sets with a minimum length rule, if one rule defined a minimum length of 6 and the other defined 8, the join() method on the Rule implementation would return 8. This is the resulting requirement for the minimum length of a password.
A Rule is also involved in the password generation process. The PasswordGenerator interface defines the requirements of the password generation engine. To override the generation algorithm of the platform, the client can provide an alternative implementation of this interface. At the time of password generation, the PasswordGenerator will be passed to each Rule instance in the framework as a visitor where the Rule can provide information to the PasswordGenerator to constrain the construction of the password being generated. For example, if a Rule defines a minimum of 6 characters is required for a password; this information is provided to the PasswordGenerator so that it does not generate a password with under 6 characters.
As an extension to the base password rules framework, the Identity Manager provisioning product provides additional provisioning specific context information, such as owner and service related attributes, to the Rules in the framework through the ProvisioningValidationInfo interface. This interface extends the ValidationInfo interface. Rule implementations that are built specifically for provisioning can make use of this information by down-casting the ValidationInfo object passed to the Rule at validation time. This, however, makes the Rule implementation provisioning specific and can not be used in a more general purpose password management rules engine. The ProvisioningValidationInfo interface can be found in the com.ibm.passwordrules.provisioning package.
The com.ibm.itim.passwordrules.standard package provides a set of standard password rules and a standard password generator. This package is available by default in a password rules engine utilizing this framework. Clients of this API can extend these classes if they wish to add logic to the existing algorithms.
For a working code example of the Password Rules API usage, please see the tim_home/extensions/examples/passwordrules directory.
After a custom password rule has been developed that implements the Rule interface, that rule must be compiled and placed in the Identity Manager classpath. At this point the class can be instantiated within the Identity Manager process, however the password rules framework does not know that this class should be used within the engine. The class must then be registered with the engine by placing the full class name of the new rule in the passwordrules.properties file. The class is listed as a key in the properties file. The prefix for the password rule key is "password.rule". The format of the line in the properties file is:
password.rule.classname=true|false.
The line below illustrates registering an "illegal pattern" rule implemented by the com.ibm.itim.examples.IllegalPatternRule class.
password.rule.com.ibm.itim.examples.IllegalPatternRule=true
‘=true' in this example indicates, that the rule requires an input parameter.
A custom password rule may be one of two types:
For example, the built-in minimum length rule requires a numeric parameter indicating what the minimum length is. However, the check dictionary rule does not need a parameter. It just needs to be toggled on or off by the administrator. If a rule requires a parameter, the Identity Manager password rules user interface will display a text field in which the administrator can provide a value. It is up to the administrator to format the contents of the parameter text in the way expected by the custom rule implementation. The password rules engine will pass unprocessed contents of the text field to the custom rule implementation class.
Finally, in order to provide an intuitive queue to the password rules administrator in the user interface, a label can be associated with the rule. This label, as are all labels in Identity Manager, can be localized. The label is defined in the CustomLabels.properties with other labels, using a key=label property format. The key will be the same full class name of the Rule implementation and the label can be any text. To complete our example of the illegal pattern rule, the following line would be added to CustomLabels.properties:
password.rule.com.ibm.itim.examples.IllegalPatternRule=Illegal Pattern:
Just as custom password rules must be registered with the Identity Manager engine, so must custom password generators. The custom password generator class must first be compiled and placed in the Identity Manager classpath. Then the class must be specified in the passwordrules.properties file. The prefix of the generator property is "generator." The full class name of the custom generator class is appended to that prefix. The line below illustrates registering a custom password generator implemented by the com.ibm.itim.examples.CustomGenerator class.
generator.com.ibm.itim.examples.CustomGenerator
If initialization context information s required for the custom generator implementation, they can be specified in the passwordrules.properties file as a value to the generator class key shown above. The format is:
generator.classname=context information
This information will be passed to the custom class’s initialize() method. In our CustomGenerator example, we will add two parameters that indicate we are using the generator in a provisioning system and that we’re deployed in a government environment. Since the property key-value pair format does not support multiple values out-of-the-box, we have delimited our value data. This is only an example as the engine will pass everything after the ‘=’ as one string to the initialize() call anyway.
generator.com.ibm.itim.examples.CustomGenerator=provisioning?government
The value of the string passed to CustomGenerator’s initialize() method will be "provisioning?government".
|
|||||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | ||||||||||