Oracle® Containers for J2EE Security Guide 10g (10.1.3.5.0) Part Number E13977-01 |
|
|
View PDF |
This chapter contains reference information for the jazn.xml
and system-jazn-data.xml
configuration files for the OracleAS JAAS Provider, covering the following topics:
Note:
Elements insystem-jazn-data.xml
relating to a user and role repository for the file-based provider also may appear in an application-specific jazn-data.xml
file.The jazn.xml
file has a simple hierarchy, as follows:
<jazn> <property>
Note:
Do not use the<jazn-web-app>
subelement of <jazn>
in the jazn.xml
file. The <jazn-web-app>
element is intended for use in the orion-application.xml
file.See Also:
"The jazn.xml File" for an overview of this file
This section is an alphabetical dictionary of elements of the jazn.xml
file.
Note:
Where attributes are discussed, note that attribute values are always set inside quotes:attribute="value"
.See Also:
"The jazn.xml File" for an overview of this file
Parent element: n/a (root)
Child elements: <property>
Required? Required; one only
This is the top-level element in the jazn.xml
file, for configuration of the OracleAS JAAS Provider.
Note:
This element (optionally with any of its subelements) may also appear in anorion-application.xml
file for application-level settings.Table D-1 <jazn> Attributes
Name | Description |
---|---|
config |
Values: n/a Default: n/a This attribute is unused in the OC4J 10.1.3.1 implementation. |
default-realm |
Values: String Default: n/a This specifies the realm that is used for an authentication or authorization request if no realm is explicitly specified. If multiple realms are defined in your repository, you must specify a default realm. Note: While there is no default if this attribute is not set, be aware that |
jaas-mode |
Values: Default: This is used to specify JAAS mode, a fine-grained authorization feature provided by OC4J that is related to standard functionality of the See Also: "Introduction to JAAS Mode" |
location |
Values: String Default: n/a For the file-based provider, this attribute in For Oracle Identity Management (the LDAP-based provider), this specifies the URL of the Oracle Internet Directory instance and is set automatically when you associate the Oracle Internet Directory instance with the OC4J instance through Application Server Control. |
persistence |
Values: Default: This specifies a persistence mode that governs how often changes are written to the |
provider |
Values: Default: Specifies an instance-level security provider setting. At the OC4J instance level in Note: An application-level security provider is specified by the |
schema-major-version |
Values: String Default: No default The major version number of the Note: This attribute is not defined directly in the XSD for |
schema-minor-version |
Values: String Default: No default The minor version number of the Note: This attribute is not defined directly in the XSD for |
Parent element: <jazn>
Child elements: None
Required? Optional; zero or more
Specify a property setting as a name/value pair. Each security provider and usage mode supports its own set of properties. For example, there are properties specific to the LDAP-based provider (when using Oracle Identity Management), and properties specific to the identity management framework and Java SSO, as documented in earlier chapters. For example:
For LDAP:
<property name="ldap.protocol" value="no-ssl"/>
For the identity management framework:
<property name="idm.token.asserter.class" value="oracle.security.jazn.sso.SSOCookieTokenAsserter" />
For Java SSO (which is an implementation of the identity management framework):
<property name="idm.authentication.name" value="JavaSSO" /> <property name="custom.sso.url.login" value="http://host:port/jsso/SSOLogin" />
This section shows the element hierarchy of the system-jazn-data.xml
file. The immediate subelements of <jazn-data>
are <jazn-policy>
, <jazn-realm>
, <jazn-loginconfig>
, <jacc-repository>
, <jazn-permission-classes>
, and <jazn-principal-classes>
, but the latter three are not intended for customer use in this release.
Note:
Elements under<jazn-realm>
can also be used in an application-specific jazn-data.xml
file.Hierarchy of system-jazn-data.xml |
---|
<jazn-data> |
<jazn-policy> <grant> <grantee> <display-name> <principals> <principal> <realm-name> <type> <class> <name> <codesource> <url> <permissions> <permission> <class> <name> <actions> |
<jazn-realm> <realm> <name> <users> <user> <name> <display-name> <description> <guid> <credentials> <roles> <role> <name> <display-name> <description> <guid> <members> <member> <type> <name> <jazn-policy> DO NOT USE AS SUBELEMENT OF <realm> |
<jazn-loginconfig> <application> <name> <login-modules> <login-module> <class> <control-flag> <options> <option> <name> <value> |
<jacc-repository> NOT INTENDED FOR CUSTOMER USE; SUBHIERARCHY NOT SHOWN |
<jazn-permission-classes> NOT INTENDED FOR CUSTOMER USE; SUBHIERARCHY NOT SHOWN |
<jazn-principal-classes> NOT INTENDED FOR CUSTOMER USE; SUBHIERARCHY NOT SHOWN |
See Also:
"The system-jazn-data.xml File" for an overview of this file
This section is an alphabetical dictionary of elements of the system-jazn-data.xml
file.
Notes:
Elements under <jazn-realm>
can also be used in an application-specific jazn-data.xml
file.
Most settings in system-jazn-data.xml
can be made through Application Server Control, as documented elsewhere in this document.
Where attributes are discussed, note that attribute values are always set inside quotes: attribute="value"
.
See Also:
"The system-jazn-data.xml File" for an overview of this file
Parent element: <permission>
Child elements: None
Required? Optional; zero or one
As applicable, this element can specify the actions that are permitted with respect to the associated permission class and name. For example:
<permission> <class>oracle.security.jazn.realm.RealmPermission</class> <name>jazn.com</name> <actions>droprealm</actions> </permission>
Parent element: <jazn-loginconfig>
Child elements: <name>, <login-modules>
Required? Optional; zero or more
In login module configuration, this element (through its subelements) specifies the name of an application and configures login modules to be used by that application.
See Also:
<jazn-loginconfig> for an example
Parent element: <principal>, <permission>, or <login-module>
Child elements: None
Required? Required within parent element; one only
This element has several uses:
Within the <principal>
element (for granting permissions to a principal), it specifies the fully qualified name of the principal class—the class that is instantiated to represent a principal that is being granted a set of permissions. For example (for a principal of type "role"):
<class>oracle.security.jazn.spi.xml.XMLRealmRole</class>
Within the <permission>
element (for granting permissions to a principal), it specifies the fully qualified name of the permission class. For example (for RMI permission, used in accessing EJBs):
<class>com.evermind.server.rmi.RMIPermission</class>
Within the <login-module>
element, it specifies the fully qualified name of the login module class. For example:
<class> oracle.security.jazn.login.module.db.DBTableOraDataSourceLoginModule </class>
Parent element: <grantee>
Child elements: <url>
Required? Optional; zero or one
For policy configuration, either a <principals>
element or a <codesource>
element is used within a <grantee>
element to specify what the permissions in question are being granted to. A <codesource>
element specifies a codesource URL, to grant permissions to that codesource.
Parent element: <login-module>
Child elements: None
Required? Required within parent element; one only
This element specifies one of the following control settings for a login module:
<control-flag>required</control-flag> <control-flag>requisite</control-flag> <control-flag>sufficient</control-flag> <control-flag>optional</control-flag>
These are used according to standard functionality of the javax.security.auth.login.Configuration
class. The overall authentication succeeds only if all "required" and "requisite" login modules succeed, possibly unless a "sufficient" login module is configured and succeeds—in that case, only the required and requisite login modules prior to the sufficient login module in the login module list must succeed.
See Also:
Table 9-5, "Login Module Control Flags" for additional information about the control flag settings
<jazn-loginconfig> for an example
Parent element: <user>
Child elements: None
Required? Optional; zero or one
This element contains the authentication password for the user.
By default, OC4J uses password obfuscation for passwords specified in system-jazn-data.xml
(or optionally in an application-specific jazn-data.xml
file).
To instead use a cleartext (human-readable) password, set the clear
attribute to "true
" or precede the password with "!" (in which case "!" is not considered part of the password). Using cleartext passwords is discouraged, however.
The following are equivalent:
<credentials clear="true">welcome</credentials> <credentials>!welcome</credentials>
Table D-3 <credentials> Attributes
Name | Description |
---|---|
clear |
Values: Default: Set this to " |
Note:
Theclear
attribute is not specified in the system-jazn-data.xml
schema definition, but is supported by the OracleAS JAAS Provider runtime implementation.See Also:
<jazn-realm> for an example
Parent element: <user> or <role>
Child elements: None
Required? Optional; zero or one
This contains a text string to describe the item (user or role, depending on the parent element). For example (for the user oc4jadmin
):
<description>The OC4J user with administrative privileges</description>
Parent element: <grantee>, <user>, or <role>
Child elements: None
Required? Optional; zero or one
This contains a text string to specify a display name to be used for the item (grantee, user, or role, depending on the parent element), such as for display by a GUI tool. For example (for the user oc4jadmin
):
<display-name>OC4J Administrator</display-name>
Parent element: <jazn-policy>
Child elements: <grantee>, <permissions>
Required? Optional; zero or more
For policy configuration, this element contains a grant entry that assigns a set of permissions to a grantee (a codesource or set of principals).
Note:
Do not use thegrantee-names
attribute (specified in the system-jazn-data.xml
schema definition). Specify grantees through <grantee>
subelements.See Also:
<jazn-policy> for an example
Parent element: <grant>
Child elements: <display-name>, <principals>, <codesource>
Required? Required within parent element; one only
When a policy grant is specified through a <grant>
element, the <grantee>
element (used in conjunction with a <permissions>
element) specifies who or what the permissions are granted to—either a set of principals or a codesource.
See Also:
<jazn-policy> for an example
Parent element: <user> or <role>
Child elements: None
Required? Optional; zero or one
This element specifies the globally unique identifier (GUID) of the item (either a user or role, depending on the parent element). A GUID is sometimes generated and used internally by the OracleAS JAAS Provider, such as in migrating a user or role to a different security provider. It is not an item that you would set yourself.
Parent element: <jazn-data>
Child elements: <jacc-policy>
Required? n/a
This element and its subhierarchy (shown here) are not intended for customer use in the OC4J 10.1.3.1 implementation.
<jacc-repository> <jacc-policy> <contextID> <excluded-policy> SAME SUBHIERARCHY AS <jazn-policy> <unchecked-policy> SAME SUBHIERARCHY AS <jazn-policy> <role-policy> SAME SUBHIERARCHY AS <jazn-policy>
Parent element: n/a (root)
Child elements: <jazn-policy>, <jazn-realm>, <jazn-loginconfig> (considering only those intended for customer use)
Required? Required; one only
This is the top-level element in the system-jazn-data.xml
file, for configuration of the OracleAS JAAS Provider.
Table D-4 <jazn-data> Attributes
Name | Description |
---|---|
schema-major-version |
Values: String Default: No default The major version number of the Note: This attribute is not defined directly in the XSD for |
schema-minor-version |
Values: String Default: No default The minor version number of the Note: This attribute is not defined directly in the XSD for |
Parent element: <jazn-data>
Child elements: <application>
Required? Optional; zero or one
This is the top-level element for configuring login modules associated with the specified applications (specified as part of the configuration). Here is an example for the Oracle-supplied DBTableOraDataSourceLoginModule
(subelements shown here are described elsewhere in this appendix):
<jazn-loginconfig>
<application>
<name>application_name</name>
<login-modules>
<login-module>
<class>
oracle.security.jazn.login.module.db.DBTableOraDataSourceLoginModule
</class>
<control-flag>required</control-flag>
<options>
<option>
<name>data_source_name</name>
<value>jdbc/OracleDS</value>
</option>
<option>
<name>table</name>
<value>userinfo</value>
</option>
<option>
<name>roles_fk_column</name>
<value>userName</value>
</option>
<option>
<name>groupMembershipGroupFieldName</name>
<value>role</value>
</option>
<option>
<name>user_pk_column</name>
<value>userName</value>
</option>
<option>
<name>passwordField</name>
<value>passWord</value>
</option>
<option>
<name>groupMembershipTableName</name>
<value>groupinfo</value>
</option>
<option>
<name>usernameField</name>
<value>userName</value>
</option>
<option>
<name>casing</name>
<value>sensitive</value>
</option>
</options>
</login-module>
</login-modules>
</application>
...
</jazn-loginconfig>
Parent element: <jazn-data>
Child elements: <permission-class>
Required? n/a
This element and its subhierarchy (shown here) are not intended for customer use in the OC4J 10.1.3.1 implementation.
<jazn-permission-classes> <permission-class> <name> <description> <type> <class> <target-descriptors> <target-descriptor> <name> <description> <action-descriptors> <action-descriptor> <name> <description>
Parent element: <jazn-data>
Child elements: <grant>
Required? Optional; zero or one
This is the top-level element for policy configuration, specifying policy grants that associate grantees (principals or codesources) with sets of permissions. Here is an example (subelements shown here are described elsewhere in this appendix):
<jazn-policy> <grant> <grantee> <principals> <principal> <realm-name>jazn.com</realm-name> <type>role</type> <class>oracle.security.jazn.spi.xml.XMLRealmRole</class> <name>jazn.com/oc4j-administrators</name> </principal> </principals> </grantee> <permissions> <permission> <class>com.evermind.server.AdministrationPermission</class> <name>administration</name> <actions>administration</actions> </permission> <permission> <class>oracle.security.jazn.realm.RealmPermission</class> <name>jazn.com</name> <actions>modifyrealmmetadata</actions> </permission> <permission> <class>oracle.security.jazn.realm.RealmPermission</class> <name>jazn.com</name> <actions>createrealm</actions> </permission> <permission> <class>oracle.security.jazn.realm.RealmPermission</class> <name>jazn.com</name> <actions>dropuser</actions> </permission> <permission> <class>oracle.security.jazn.realm.RealmPermission</class> <name>jazn.com</name> <actions>droprealm</actions> </permission> <permission> <class>com.evermind.server.rmi.RMIPermission</class> <name>login</name> </permission> <permission> <class>com.evermind.server.rmi.RMIPermission</class> <name>subject.propagation</name> </permission> <permission> <class>oracle.security.jazn.policy.RoleAdminPermission</class> <name>jazn.com/*</name> </permission> </permissions> </grant> ... </jazn-policy>
Note:
Do not use<jazn-policy>
as a subelement of <realm>
.Parent element: <jazn-data>
Child elements: <principal-class>
Required? n/a
This element and its subhierarchy (shown here) are not intended for customer use in the OC4J 10.1.3.1 implementation.
<jazn-principal-classes> <principal-class> <name> <description> <type> <class> <name-description-map> <name-description-pair> <name> <description>
Parent element: <jazn-data>
Child elements: <realm>
Required? Optional; zero or one
This is the top-level element for user and role information, specifying security realms and the users and roles they include. Here is an example (subelements shown here are described elsewhere in this appendix):
<jazn-realm> <realm> <name>jazn.com</name> <users> <user deactivated="true"> <name>anonymous</name> <guid>D3D41721D3E311DABFFC25CB9F57C041</guid> <description>The default guest/anonymous user</description> </user> <user> <name>oc4jadmin</name> <display-name>OC4J Administrator</display-name> <guid>D3DB1C00D3E311DABFFC25CB9F57C041</guid> <description>OC4J Administrator</description> <credentials>{903}r7VKkMgJqP8fkDZCG7YMo7UZnT/B+HcK</credentials> </user> ... </users> <roles> <role> <name>ascontrol_admin</name> <display-name>ASControl Admin Role</display-name> <description>Administrative role for ASControl</description> <guid>D3DB1C05D3E311DABFFC25CB9F57C041</guid> <members> <member> <type>user</type> <name>oc4jadmin</name> </member> </members> </role> <role> <name>oc4j-administrators</name> <display-name>OC4J Admin Role</display-name> <description>Administrative role for OC4J</description> <guid>D3DB1C02D3E311DABFFC25CB9F57C041</guid> <members> <member> <type>user</type> <name>oc4jadmin</name> </member> ... </members> </role> ... </roles> </realm> </jazn-realm>
Parent element: <login-modules>
Child elements: <class>, <control-flag>, <options>
Required? Required within parent element; one or more
This element specifies and configures a login module for a given application, with subelements specifying the class name, control flag, and option settings for the login module.
See Also:
<jazn-loginconfig> for an example
Parent element: <application>
Child elements: <login-module>
Required? Required within parent element; one only
This element, through one or more <login-module>
subelements, configures the set of login modules for a given application.
See Also:
<jazn-loginconfig> for an example
Parent element: <members>
Child elements: <type>, <name>
Required? Optional; zero or more
The element specifies the name of a member of the applicable role, and whether the member is a user or another role (according to the <type>
subelement).
See Also:
<jazn-realm> for an example
Parent element: <role>
Child elements: <member>
Required? Required within parent element; one only
This element specifies the members of a role. Members can be either users or other roles.
See Also:
<jazn-realm> for an example
Parent element: <principal>, <realm>, <role>, <user>, <member>, <application>, or <option>
Child elements: None
Required? Required within parent element; one only
This element has several uses:
Within the <realm>
element, it specifies the name of a realm. For example:
<name>jazn.com</name>
Within the <user>
element, it specifies the unique name of a user in the applicable realm. For example:
<name>oc4jadmin</name>
Within the <role>
element, it specifies the unique name of a role in the applicable realm. For example:
<name>oc4j-administrators</name>
Within the <member>
subelement of <role>
, it specifies the name of a member of the role. For example (if the user oc4jadmin
is to be a member of the role):
<name>oc4jadmin</name>
Within the <principal>
element (for granting permissions to a principal), it specifies the unique name of a principal within the given realm. For example:
<name>jazn.com/oc4j-administrators</name>
Within the <application>
element, it specifies the fully qualified name of the application whose login modules are being configured. For example:
<name>oracle.security.jazn.tools.Admintool</name>
Within the <option>
element, it specifies the name of an option for configuration of a login module. (There is an accompanying <value>
element for the option value.) For example, an option for DBTableOraDataSourceLoginModule
:
<option> <name>data_source_name</name> <value>jdbc/OracleDS</value> </option>
(This element as a subelement of <permission>
is documented separately, immediately below.)
Parent element: <permission>
Child elements: None
Required? Optional; zero or one
As applicable, this element can specify the name of a permission that is meaningful to the permission class. For example:
<permission> <class>com.evermind.server.rmi.RMIPermission</class> <name>login</name> </permission>
(This element as a subelement of <principal>
, <realm>
, <role>
, <user>
, <member>
, <application>
, or <option>
is documented separately, immediately above.)
Parent element: <options>
Child elements: <name>, <value>
Required? Required within parent element; one or more
Each <option>
element, through a <name>
subelement and a <value>
subelement, specifies the name and value for an option setting for a login module.
See Also:
<jazn-loginconfig> for an example
Parent element: <login-module>
Child elements: <option>
Required? Optional; zero or one
This element, through its <option>
subelements, specifies option settings for a login module.
See Also:
<jazn-loginconfig> for an example
Parent element: <permissions>
Child elements: <class>, <name>, <actions>
Required? Required within parent element; one or more
When a <permissions>
element is used in policy grant configuration, each <permission>
subelement specifies one permission being granted to the principal in question.
See Also:
<jazn-policy> for an example
Parent element: <grant>
Child elements: <permission>
Required? Required within parent element; one only
When a policy grant is specified through a <grant>
element, the <permissions>
element (used in conjunction with a <grantee>
element) specifies the permissions being granted, through a set of <permission>
subelements.
Note:
Thesystem-jazn-data.xml
schema definition does not specify this as a required element, but the OracleAS JAAS Provider runtime implementation requires its use within any <grant>
element.See Also:
<jazn-policy> for an example
Parent element: <principals>
Child elements: <realm-name>, <class>, <type>, <name>
Required? Optional; zero or more
When a <principals>
element is used in policy grant configuration, each <principal>
subelement specifies one principal being granted the permissions in question.
See Also:
<jazn-policy> for an example
Parent element: <grantee>
Child elements: <principal>
Required? Optional; zero or one
For policy configuration, either a <principals>
element or a <codesource>
element is used within a <grantee>
element to specify what the permissions in question are being granted to. A <principals>
element specifies a set of principals being granted the permissions.
For a subject to be granted these permissions, the subject should include all the specified principals.
See Also:
<jazn-policy> for an example
Parent element: <jazn-realm>
Child elements: <name>, <users>, <roles>
Required? Optional; zero or more
This element specifies a realm and the users and roles that belong to the realm.
Note:
Do not use<jazn-policy>
as a subelement of <realm>
.See Also:
<jazn-realm> for an example
Parent element: <principal>
Child elements: None
Required? Optional; zero or one
For granting permissions to a principal, this element specifies the name of the realm to which the principal belongs. (Its value would correspond to the value of a <name>
subelement of a <realm>
element where the realm is configured.) For example:
<realm-name>jazn.com</realm-name>
If a realm name is not specified, the default realm is assumed.
Parent element: <roles>
Child elements: <name>, <display-name>, <description>, <guid>, <members>
Required? Optional; zero or more
This element specifies a role and the members of that role.
See Also:
<jazn-realm> for an example
Parent element: <realm>
Child elements: <role>
Required? Optional; zero or one
This element specifies the set of roles that belong to a realm
See Also:
<jazn-realm> for an example
Parent element: <member>
Child elements: None
Required? Required, one only
As a subelement of <member>
, in specifying the member of a role, this element specifies the type of member—that is, whether the member is a user or another role. For example:
<type>user</type>
(This element as a subelement of <principal>
is documented separately, immediately below.)
See Also:
<jazn-realm> for an example
Parent element: <principal>
Child elements: None
Required? Optional; zero or one
As a subelement of <principal>
, in granting permissions to a principal, this element can optionally specify the type of principal—that is, whether the principal is a user or a role. For example:
<type>role</type>
(This element as a subelement of <member>
is documented separately, immediately above.)
See Also:
<jazn-policy> for an example
Parent element: <codesource>
Child elements: None
Required? Required within parent element; one only
When a <codesource>
element is used in policy grant configuration, the <url>
subelement specifies the URL of the codesource being granted the permissions in question. For example:
"file:${oracle.home}/j2ee/home/jazn.jar"
(This follows the same format as shown for a java2.policy
file in "Creating or Updating a Java 2 Policy File".)
Parent element: <users>
Child elements: <name>, <display-name>, <description>, <guid>, <credentials>
Required? Optional; zero or more
This element specifies a user within a realm.
Table D-5 <user> Attributes
Name | Description |
---|---|
deactivated |
Values: true|false Default: false You can set this attribute to " |
See Also:
<jazn-realm> for an example
Parent element: <realm>
Child elements: <user>
Required? Optional; zero or one
This element specifies the set of users who belong to a realm.
See Also:
<jazn-realm> for an example
Parent element: <option>
Child elements: None
Required? Required within the parent element; one only
The element specifies the value of an option for configuration of a login module. (There is an accompanying <name>
element for the option name.) For example, an option for DBTableOraDataSourceLoginModule
:
<option> <name>data_source_name</name> <value>jdbc/OracleDS</value> </option>