Sun Java System Access Manager 6 2005Q1 Developer's Guide |
Appendix A
AMConfig.properties FileAMConfig.properties is the resource configuration file for Sun Java System Access Manager 6 2005Q1. It provides instructions for the Access Manager deployment. This chapter explains the attributes of AMConfig.properties. It contains the following sections:
OverviewAccess Manager is configured by placing application properties in plain text configuration files. These configuration files contain one property per line and each has a corresponding value. Properties and their values are case-sensitive. Indentation of the properties is consistent throughout the file. Lines which begin with the characters “/*” are comments, and ignored by the application. Comments are completed with a last line that contains the closing characters “*/”. The main configuration file for Access Manager is AMConfig.properties located in IdentityServer_base/SUNWam/lib. The following sections describe the properties and default values of AMConfig.properties.
Note
The Access Manager must be restarted for any modification in AMConfig.properties to take effect.
Deployment PropertiesFollowing are the deployment-specific attributes configured in AMConfig.properties.
Access Manager
This section describe properties that define the Access Manager application.
Installation
These properties are defined during installation.
This property identifies the full LDAP DN of the super user configured during installation of Access Manager; it is amadmin by default. This user must always log in using LDAP authentication as they will always be authenticated against the Directory Server. The UID alone is generally used to login but the full DN as defined in this property can also be used.
Console
These properties are specific to the Access Manager console.
The following directives can be added to the AMConfig.properties file to add their respective functionality to the Access Manager console.
If specified, Access Manager will not perform the initial search for a specified identity object that is done in the Navigation frame when the view menu is changed. For example, after a successful login, the default console view is the organization view. When the view is changed to Users, the Navigation frame is redrawn to display all users; a search is performed to obtain this information. With a large number of users, disabling this search can drastically reduce the time it takes to load the Access Manager console. A filter can then be used to find the desired users. This option is available for any of the view menu types. To disable the search, add any of the following values: orgs, orgUnits, users, policies, groups, roles, groupContainers, and peopleContainers. If more than one value, they are comma-separated.
Cookies
These properties are specific to Access Manager cookies.
Miscellaneous
This section is a catch-all for some miscellaneous and self-explanatory values.
The value of this property is the path to the serverconfig.xml file. This file is discussed in Appendix B, "serverconfig.xml File."
Directory Server
This section describe the properties for the Directory Server data store.
Installation
These properties define the Directory Server to which the Access Manager points.
Directory Server Tree
The values of these properties are the top-level organization of the Directory Server tree defined during the installation process.
Configuration PropertiesThere are a number of services configured in AMConfig.properties that can not be configured using the Access Manager console. These back-end services, and several attributes for other services, are defined in this section.
Debug Service
The Debug Service logs developer information in the case of application errors. (The Logging Service writes logs to be monitored by the application administrator.) More information on the Debug Service can be found in Debug Files of Chapter 12, "Auditing Features."
Stats Service
The following properties are used to configure the Stats Service for recording service statistics. This service is used by the Access Manager SDK and the Session Service. Code Example A-1 is a portion of the stats file to illustrate the information that is recorded. The file is named amSDKStats by default.
Notification Service
The Notification Service allows Access Manager to send notifications to registered applications when an event has occurred (session destroyed, session timeout, etc.). This service also allows the single sign-on cache to stay up to date. The notification is basically a HTTP post message containing the component notification in its body.
When a notification task comes in, it is processed in the task queue. If it reaches the maximum length, further incoming requests will be rejected along with a ThreadPoolException, until the queue has vacancy
This parameter specifies the maximum size of the task queue in the thread pool. A task is queued when no thread is available. If the number of unprocessed tasks reaches the value specified, no additional notification tasks will be accepted until there are vacancies. This value is dependent on the system memory resource; each task takes about 3k.
SDK Caching
The caching function in Access Manager is memory-based therefore when an identity-related object is created, deleted or modified, the cache is cleaned up. Each SDK cache entry stores a set of attributes and values of AMObject for a user. Because the size of each object is dependent upon the number of attributes it has, modifying these properties will affect the performance of Access Manager.
Online Certificate Status Protocol (OCSP)
OCSP is a protocol that specifies the syntax for communication between a server which holds certificate status and a client which is informed of said status.When a user attempts to access a server, OCSP sends a request for certificate status information and receives back a response of current, expired or unknown. If these properties are set, the certificate in question must be in the deployment container’s certificate database. If the OCSP URL is set, the OCSP responder nickname must also be set or both will be ignored. If neither is set, the OCSP responder URL presented in the user’s certificate will be used. If there is none in the user’s certificate, no OCSP validation will be performed.
Identity Object Processing
This property has a value equal to the implementation class of the module used for processing user creates, deletes, and modifies.
Security
This property is used to enable Java security permissions. This permission is used to protect the Access Manager resources which should only be accessed by trusted resources. This permission is used to protect the admin DN and password as well as access to the encryption and decryption methods used to encrypt passwords. The default value is false. If enabled, modifications must be made to the deployed web container’s Java policy file. This should be done as detailed in Code Example A-2.
Code Example A-2 Changes To Java Policy File
grant codeBase "file:{directory where jars are located}/-" {
com.sun.identity.security.ISSecurityPermission "access",
"adminpassword,crypt";
};
SSL
This property is used to enable Secure Socket Layers (SSL). The default is false.
Certificate Database
These properties are used by the command line utilities and SDK as well as the LDAP and Certificate-based authentication modules when initiating SSL connections to the Directory Server. It is also used when opening HTTP(S) connections from within the servlet container in the deployment container.
Replication
These two properties are not required to support replication but they may be helpful in limiting errors due to latency. Enabling them may have a negative impact on performance but, if replication has significant latency, the retries may be enough to prevent Entry Not Found errors. For example, assume an Access Manager console is pointing to a read-only consumer configured to refer writes to a master. If a new organization is created, all write requests are referred to the master and then replicated back to the consumer. If Access Manager reads the organization back before it has been replicated to the consumer, it will get an Entry Not Found error.
Note
It is not recommended to run the Access Manager console against a read-only consumer. The exception to this rule is when operating against user entries whose creations and modifications do not have the same latency problems as the SDK has special behavior to prevent such problems for these entries.
Event And LDAP Connection
These sets of properties are implemented when load balancers are used between the Identity SDK and the Directory Server. When the SDK performs an operation which fails, it will retry the operation as long as the exception is one defined in the ldap.error.codes property. These properties are necessary for failover configuration when it is accomplished via a load balancer as not all load balancers return the same error codes.
Event Connection
LDAP Connection
The following keys are used to configure an LDAP connection for the add, delete modify, read and search methods.
SAML
These properties identify SAML-related configurations including properties relating to the Access Manager keystore file.
Keystore Properties
Each Access Manager has a keystore file used to store the certificates used for XML signing and verification. A stored certificate might include a partner site’s certificate and the public key used by Access Manager to verify SAML responses and assertions from the partner. The keystore also holds the Access Manager certificate and the private key it uses to sign assertions. For more information on generating the keystore, certificate aliases and other functions, read about the keytool, a key and certificate management utility, in the Readme.html and keystore.html files located in the IdentityServer_base/SUNWam/samples/saml/ xmlsig directory.
Miscellaneous Services
The following directives define the URIs for miscellaneous services.
Read-Only PropertiesThe following properties are read-only and should not be modified. Any changes to these directives may render the Access Manager unusable.
Installation
These properties identify values defined during the installation process.
Deployment
These properties are used to identify the URIs for specific services and agents.
- com.iplanet.am.services.deploymentDescriptor=/amserver
- com.iplanet.am.console.deploymentDescriptor=/amconsole
- com.iplanet.am.policy.agents.url.deploymentDescriptor=AGENT_DEPLOY_URI
This last property contains the name of the deployment container. Possible values here are BEA6.1, IBM 4.0.5, S1AS7.0, or WS.
- com.sun.identity.webcontainer=WEB_CONTAINER
Shared Secret
This property is the shared secret for the Authentication Service.
Session Properties
These properties are configurations for the Session Service.
This property allows the session server (For example Access Manager) to look for the IP address from the host property and log it. If set to true, a reverse DNS lookup will be used to obtain the Domain Name from the IP address for logging purposes. If false, the IP address will be used thus, increasing performance.
This property defines the purge delay period in minutes. After a session times out, this is the extended time period for which the token will reside in the Session Service. This can be used by the client application to check if the session has timed out or not (using the SSO APIs). After this time period, the session is destroyed. The session token is in the INVALID state during this extended period.
Simple Mail Transfer Protocol (SMTP)
The following directives can be set to any valid SMTP server and port.
Authentication
The following sections define properties used by the Authentication Service.
LDAP
This property specifies a list of user attributes whose values will be retrieved from an external Directory Server during LDAP Authentication if the Authentication Service is configured for dynamically creating users. The new user created in the local Directory Server will have the values for these attributes retrieved from the external Directory Server.
SecurID
Unix
Security
Following are properties that define parameters for security purposes.
SecureRandom
This property specifies the factory class name for SecureRandomFactory.
SocketFactory
This property specifies the factory class name for LDAPSocketFactory.
Encryption
These properties specify encryption information.
This is the Data Encryption Standard (DES) encryption key password. The client needs this to decrypt the session ID for token creation. If decryption fails, the client will not be able to retrieve the protocol, server host and the server port information to construct the URL needed to search for a service. Do not change the value of this property without also re-encrypting the passwords in serverconfig.xml. For information, see Appendix B, "serverconfig.xml File."
IP Address Checking
This property specifies whether the IP address of the client will be checked in SSOToken creations and validations.
Remote Policy API
These properties are defined for the Remote Policy API to use with policy agents.
Policy
This property defines weights for policy subjects, rules and conditions. These weights influence the order in which these components are evaluated. The value is three integers delimited by ":". These integers indicate the proportional CPU cost for evaluating the three components, respectively.
Federation
These properties configure information for the Federation Management module.
FQDN Map
The Fully Qualified Domain Name (FQDN) Map is a simple map that enables the Authentication Service to take corrective action in the case where a user may have typed in an incorrect URL either by specifying partial hostname or IP address to access a protected resource.
Valid values must comply with the syntax of this property which represent invalid FQDN values mapped to correct counterparts. The valid format for specifying these maps is:
com.sun.identity.server.fqdnMap[invalid_name]=valid_name
where invalid_name is a possible invalid FQDN host name that may be used by the user, and valid_name is the FQDN host name to which the filter will redirect the user.
This property can also be used for creating a mapping for more than one host name. This may be the case when applications hosted on a server are accessible by more than one host name. It may also be used to configure Access Manager to NOT take corrective action for certain hostname URLs. For example, if no corrective action (such as a redirect) is desired for users who access application resources using a raw IP address, the map entry would look like:
com.sun.identity.server.fqdnMap[IP_address]=IP_address
Any number of values may be specified as long as they are valid and conform to the above stated requirements.
Examples of FQDN mapping might be:
Encryption Key
The value of this property is the password used to generate a symmetric key to encrypt and decrypt other sensitive data including the shared secret.
am.encryption.pwd=ro/LiN3pOxMXxtvbwf+owRFyzDYwxRTw