Web Server Installation
Configuration Options
The Web Services SSM has a configuration file named: default.properties. All configuration settings for the Web Server SSM instance are defined in this file. This file is pre-configured and placed in the proper location for you.
If you want to edit the default.properties file for your particular environment, refer to the parameters descriptions in the following sections:
Session Settings
The WebLogic Enterprise Security services are stateless services, so it is the calling web services client that is responsible for determining session related information. In addition, in a web environment a session does not necessarily have a hard logout, so session termination must be inferred by a lack of activity.
Table 7-1 describes the settings used to manage session behavior. You use these settings to configure the web server session related behavior for the security configuration to which it applies.
Table 7-1 Session Settings
|
Session Setting
|
Description
|
|
session.inactivity.timeout
|
The number of seconds of inactivity that causes a session to expire.
Default value: 600 seconds (10 minutes)
|
|
session.absolute.
timeout
|
The number of seconds an active session is allowed to be available before it expires and the user is forced to re-authenticate. If this setting is set to zero, then established active sessions can continue indefinitely.
Default value: 3600 seconds (60 minutes)
|
|
Session.cookie.name
|
The name of the session cookie.
Default value: ALESIdentityAssertion.
|
|
session.forcedlogoffURL
|
The name of the URL that, when accessed, forces the session to logoff.
|
Authentication Settings
Table 7-2 describes the settings that you use to configure the web server authentication behavior for the security configuration to which it applies. Also, for information on mapping JAAS Callbacks, see Mapping JAAS Callback Type to Form and Form Fields.
Table 7-2 Authentication Settings
|
Authentication Setting
|
Description
|
|
authentication.precedence
|
An ordered, comma-separated list of types of identity creation. If identity information is available from multiple types of identity transfers, this list determines which identity to use. The valid identity type is:
Default value: FORM
|
|
authentication.initialForm
|
Specifies the first form presented for form-based authentication.
|
|
authentication.
<callback type>[<prompt>] = <field>,<form URL>
|
Given a question, this setting specifies what field on what form will answer that question. Notice that the <prompt> is shown as optional. However, the prompt is required if there are multiple callbacks of the same type, because there is no other way for the SSM to distinguish identical callback types. The prompt is obtained from the callback by calling the getPrompt() method, but it is not used in the display of the form. If the prompt setting is missing, then the Web Server SSM attempts to answer the callbacks in the order of the settings. If the order does not match the order of the providers, then authentication fails. For more information on using this setting, see Mapping JAAS Callback Type to Form and Form Fields.
|
|
authentication.onatnfailure
|
If authentication fails, and this setting is set to a URL, then rather than issuing a 401 Authentication Failed, the user will be redirected to the URL.
|
|
authentication.onatzfailure
|
If authorization fails and this setting is set to a URL, then rather than issuing a 403 Permission Denied, the user is redirected to this URL.
|
Table 7-3 describes the different types of authentication callbacks that are supported by the Web Server SSM.
Table 7-3 Authentication Callback Type Descriptions
|
Authentication Callback Type
|
Description
|
|
authentication.
nameCallback
|
The form template responsible for collecting a name for a name callback. This form must exist in the same directory as the post handler.
|
|
authentication.
passwordCallback
|
The form template is responsible for collecting a password for a password callback. This form must exist in the same directory as the post handler.
|
|
authentication.
choiceCallback
|
The form template is responsible for collecting a choice for a choice callback. This form must exist in the same directory as the post handler.
|
|
authentication.
confirmationCallback
|
The form template is responsible for collecting a confirmation for a confirmation callback. This form must exist in the same directory as the POST handler.
|
|
authentication.
textInputCallback
|
The form template is responsible for collecting some text input for a text input callback. This form must exist in the same directory as the post handler.
|
Mapping JAAS Callback Type to Form and Form Fields
There are two required and one optional configuration setting that specify what form and what field contain the information required to satisfy the authentication callbacks. The credential gathering form must use an HTTP POST method to specify this information. Listing 7-1 shows an example of how to use the POST method in the credential gathering form.
Listing 7-1 Example of Using the POST Method in the Credential Gathering Form
<FORM METHOD=POST ACTION="LoginNamePwdTextIn.html">
<!--#AUTHSTATE -->
<TABLE BGCOLOR="C0C0C0"><TR><TD>
<TABLE BGCOLOR="#FFFFFF">
<TR><TD COLSPAN="2" BGCOLOR="#C0C0C0">Please Login</TD></TR>
<TR><TD COLSPAN="2">User Name </TD><TR>
<TR><TD><!--#PROMPT --></TD><TD><INPUT NAME="username"></TD></TR>
<TR><TD COLSPAN="2">Password </TD><TR>
<TR><TD><!--#PROMPT.1--></TD><TD><INPUT TYPE=
PASSWORD NAME="password"></TD></TR>
<TR><TD COLSPAN="2">Input Text </TD><TR>
<TR><TD><!--#PROMPT --></TD><TD><INPUT NAME="textinput"></TD></TR>
<TR><TD COLSPAN="2"> </TD><TR>
<TR><TD COLSPAN="2" ALIGN="CENTER"><INPUT TYPE="SUBMIT" VALUE="OK"></TD><TR>
</TABLE>
</TD></TR></TABLE>
</FORM>
The form field defines the HTTP POST data name that results from a submitted form.
The settings have the following format:
authentication.<callback type>[<prompt>] = <field>:<form URL>
Given a question, this setting specifies what field on what form will answer that question. Notice that the <prompt> is shown as optional. However, if there are multiple callbacks of the same type, the <prompt> is required because there is no other way for the Web Server SSM to distinguish identical callback types. The <prompt> is obtained from the callback by calling the getPrompt() method, but it is not used in the display of the form. If the <prompt> setting is missing, then the Web Server SSM attempts to answer the callbacks in the order of the settings. If the order does not match the order of the authentication providers, then authentication fails.
The supported callback types are: nameCallback, passwordCallback, textInputCallback, textOutputCallback.
Table 7-4 provides examples of callback usage and more information on each supported callback type.
Table 7-4 Authentication Callback Usage Examples
|
Authentication Callback Types
|
Example/Discussion
|
|
Name and password callbacks
|
authentication.nameCallback[]=username: /wles/NamePasswordForm.htm
authentication. passwordCallback []= password: /wles/NamePasswordForm.htm
|
|
Name, password, and textInput callbacks
|
authentication.initialForm=/test/NamePasswordForm.html
# username/password
authentication.nameCallback[]=username:/test/
NamePasswordForm.html
authentication.passwordCallback[]=password:/test/
NamePasswordForm.html
# username/password/textInput
authentication.nameCallback[]=username:/test/
LoginNamePwdTextIn.html
authentication.passwordCallback[]=password:/test/
LoginNamePwdTextIn.html
authentication.textInputCallback[]=textinput:/test/
LoginNamePwdTextIn.html
In this example the user will be prompted for username/password. The authentication provider then prompts for the user's mother's maiden name. The Web Server SSM redirects to QuestionForm.htm and knows from what field to get the information.
|
|
Name, password, and textInput callbacks
|
authentication.nameCallback[]=username: /wles/NamePasswordForm.htm
authentication. passwordCallback []= password: /wles/NamePasswordForm.htm
authentication. textInputCallback ["maiden name"]=maiden_name: /wles/ QuestionForm.htm
authentication. textInputCallback ["social security number"]=maiden_name: /wles/ QuestionForm.htm
In this example two providers require username/password callbacks, a third provider requires a textInputCallback for mother's maiden name, and a fourth provider requires a textInputCallback for a social security number: The prompts distinguish between the two textInputCallbacks.
Note: The textInputCallback prompt requires quotes only if it contains embedded strings.
|
|
TextOutput Callback
|
The textOutputCallback is used to display a message to the user. Because the Web Server SSM does not create or update forms, if it gets a textOutputCallback, it redirects it to the form URL and adds the field as a query string argument and the message value. The application that processes the URL is responsible for parsing the query string and displaying the message.
|
|
Language callback
|
Language callbacks are handled internally by the web server; the user is never prompted, so no configuration is needed. The user's browser Accept-Language header is checked for the preferred language it supports and that locale is returned to the authentication provider. If the user's browser has no Accept-Language header, the system default locale is used.
|
Role Mapping Settings
Table 7-5 describes the settings that you use to configure the web server role mapping behavior for the policy domain to which it applies.
Table 7-5 Role Mapping Settings
|
Role Mapping Setting
|
Description
|
|
rolemapping.enable
|
If set to true, then roles are injected into the request stream as a comma separated list.
|
|
rolemapping.name
|
The name of the variable in which to put the rolls. The default is: WLES_ROLES.
|
Credential Mapping Settings
Table 7-6 describes the settings that you use to configure the web server credential mapping behavior for the policy domain to which it applies.
Table 7-6 Credential Mapping Settings
|
Credential Mapping Setting
|
Description
|
|
credentialmapping.
enable
|
If set to true, then credentials for each request are injected into the request stream.
|
|
credentialmapping.
credtypes
|
List of credential types to ask for in this policy domain. Only credentials that are mapped and that are supported by configured Credential Mapping provider are returned for a specific request. Therefore, asking for a credential does not guarantee that it is there.
For example, to configure credential mapping to support the password for the database server, perform the following steps:
Note: The Database Credential Mapper provider provides identity credentials. Identity credentials are the same as PasswordCredential in Java. Others credentials, such SAML assertions, ALES Identity Assertions IA, and so on, are identity assertions. They are the same as GenericCredentials in Java. The Web Services SSM can have only one identity credential defined, but many identity assertions.
|
|
credentialmapping.
prefix
|
Prefix to prepend to credential names, for example CRED.
|
Naming Authority Settings
Table 7-7 describes the settings that you use to configure the Web Server SSM naming authority.
Table 7-7 Naming Authority Settings
|
Setting
|
Description
|
|
namingauthority.resource
|
Specifies the naming authority for the resource. The naming authority is configured in the Web Services SSM.
|
|
namingauthority.action
|
Specifies the action naming authority.
|
|
namingauthority.audit
|
Specifies the audit naming authority.
|
|
webservice.registry.url
|
Specifies the URL of the Web Services Registry Service. For example: http://localhost:8000/ServiceRegistry
|
Logging Level Setting
Table 7-8 describes the settings that you use to configure the Web Server SSM naming authority.
Table 7-8 Logging Level Setting
|
Setting
|
Description
|
|
log.level
|
Specifies the logging level for the log4j Auditing provider.
|
Environment Variables Accessible Using CGI
The Web Server Security Service Module (SSM) tool kit enables you to access user environment variables using Common Gateway Interface (CGI).
Although security is embedded within the web server itself, requiring no special programming (if the user does not have access, your code will never run), a security administrator may want to use CGI to access and modify environment variables passed in by the Web Server Security Service Module. In order to customize the application according to the details of the security being enforced, a web application may access several environmental values in order to provide a more integrated user experience.
You can use CGI to access the following environment variables:
WLES_IDENTITY—This is an authentication environment variable. It is available to a CGI programmer after a user successfully authenticates. This variable contains the username of the user, if available. It specifies the name of the HTTP header that will be added. The value of the variable is a list of the identity principles, including username and groups.- WLES_DECISIONTIME—This is an authorization environment variable. It is available to a CGI programmer after a user is authorized to access a secure resource. It contains the date and time this authorization decision was rendered and has this format: "Monday June 23 15:14:21 EDT 2003"
- WLES_ROLES—This is a role environment variable that stores a list of roles calculated for the user.
- Credential Environment Variable—Table 7-9 describes the credential that is injected into the request stream when the user is authenticated. A CGI application can use this variable to access an LDAP store or database with an appropriate credential, rather than hard coding usernames and passwords. The prefix to this credential variable is configurable, although
CRED is the default. Different credential types are handled differently, but the general format of the variable is: CRED_{NAME}={VALUE}
Table 7-9 Credential Environment Variables
|
Environment Variable
|
Description
|
|
Password Credentials
|
Password credentials conform to the format javax.resource.spi.security.PasswordCredential. The ManagedConnectionFactory element of this class is ignored. This credential type is rendered in the CGI environment as:
{PREFIX}_PASSWORD={NAME}:{PASSWORD}
where PREFIX is the configured prefix, NAME is the username, and PASSWORD is the password as a string. This name must match the requested credential type from credential/mapping credtypes.
For example:
CRED_PASSWORD=system:weblogic
|
