Security schema is the main syntax for the security-related definitions of any deployment plan. Security schema is normally imported by the host schema.
Security schema namespace is: http://geronimo.apache.org/xml/ns/security-1.1 Security schema file is geronimo-security-1.1.xsd.

The usual namespace prefix for the security schema is security. So if you want to refer to the elements of this namespace from some other namespace, you will do it this way: security:security.

Here is the syntactic reference for the security schema. All security schema types are global (in the xml schema sense). There are only two global security elements: security:security and security:defaultPrincipal.

Note that although default-principal is declared to be a global element, security schema does not make use of it and defines local default-principal element of the same type every time it needs it.

The following sections describe the syntax and meaning of the security schema element.

It has been used simple x-path path expressions such as /a/b/c and attribute expressions such as @attribute as a short-hand.

Type securityType

security:securityType is the global type that defines security requirements of an application with respect to the J2EE role mapping to Principals.

<xsd:complexType name="securityType">
   <xsd:sequence>
      <xsd:element name="description" type="security:descriptionType" 
         minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="default-principal" type="security:default-principalType"/>
      <xsd:element name="role-mappings" type="security:role-mappingsType" 
         minOccurs="0"/>
   </xsd:sequence>
   <xsd:attribute name="doas-current-caller" type="xsd:boolean" default="false"/>
   <xsd:attribute name="use-context-handler" type="xsd:boolean" default="false"/>
   <xsd:attribute name="default-role" type="xsd:string"/>
</xsd:complexType>

@doas-current-caller - Set this attribute to true if the work is to be performed as the calling Subject. This attribute is optional, the default value is false.
@use-context-handler - Set this attribute to true if the installed JACC policy contexts will use PolicyContextHandlers. This attribute is optional, the default value is false.
@default-role - Used by the Deployer to assign method permissions for all of the unspecified methods, either by assigning them to security roles or by marking them as unchecked. If the value of default-role is empty then the unspecified methods are marked unchecked.

description - optional element. 0 to many description elements.
default-principal - required element. Defines default principal for anonymous access.
role-mappings - optional element. Maps J2EE roles to principals.

Back to Top

Type defaultPrincipalType

Default principal is used for anonymous access.

security:default-principalType is a sequence of optional description, the choice of principal, login-domain-principal, realm-principal, followed by a sequence of
named-username-password-credential elements.

<xsd:complexType name="default-principalType">
   <xsd:sequence>
      <xsd:element name="description" type="security:descriptionType" 
         minOccurs="0" maxOccurs="unbounded"/>
      <xsd:choice>
         <xsd:element name="principal" type="security:principalType"/>
         <xsd:element name="login-domain-principal" 
            type="security:loginDomainPrincipalType"/>
         <xsd:element name="realm-principal" type="security:realmPrincipalType"/>
      </xsd:choice>
      <xsd:element name="named-username-password-credential" 
         type="security:named-username-password-credentialType" minOccurs="0" 
            maxOccurs="unbounded"/>
   </xsd:sequence>
</xsd:complexType>

description - optional. 0 to many description elements.
principal - required choice element. Defines default principal to be of the security:princpalType.
login-domain-principal - required choice element. Defines default principal to be of the security:loginDomainPrincipalType.
realm-principal - required choice element. Defines default principal to be of the security:realmPrincipalType.
named-username-password-credential - optional sequence of 0 to many elements of the security:named-username-password-credentialType.

Back to Top

Type principalType

security:principalType defines authenticated principal.

<xsd:complexType name="principalType">
   <xsd:sequence>
      <xsd:element name="description" type="geronimo:descriptionType" 
         minOccurs="0" maxOccurs="unbounded"/>
   </xsd:sequence>
   <xsd:attribute name="class" type="xsd:string" use="required"/>
   <xsd:attribute name="name" type="xsd:string" use="required"/>
   <xsd:attribute name="designated-run-as" type="xsd:boolean" default="false"/>
</xsd:complexType>

@class is principal implementation class.
@name is authenticated principal name.
@designated-run-as if set to true makes this principal a run-as principal for the role that maps this principal.

Back to Top

Type loginDomainPrincipalType

security:loginDomainPrincipalType type associates a Principal with the Login Domain that authenticated that principal. If Security Realm into which login module (Login Domain) is wired up is configured to wrap Principals, every Principal produced by every login module will be wrapped into the DomainPrincipal.

login-domainPrincipalType extends principalType.

<xsd:complexType name="loginDomainPrincipalType">
   <xsd:complexContent>
      <xsd:extension base="security:principalType">
         <xsd:attribute name="domain-name" type="xsd:string" use="required"/>
      </xsd:extension>
   </xsd:complexContent>
</xsd:complexType>

@domain-name - Login Domain name.

Note that elements of the security:loginDomainPrincipalType wrap elements of security:principalType, so the @class attribute value must be the value of the Principal implementation class that is wrapped by the security:loginDomainPrincipal.

Back to Top

Type realmPrincipalType

Realm principal associates a Principal with the realm in which it was authenticated. If Security Realm is configured to wrap Principals, each DomainPrincipal will be wrapped into the RealmPrincipal.

realmPrincipalType extends security:loginDomainPrincipalType.

<xsd:complexType name="realmPrincipalType">
   <xsd:complexContent>
      <xsd:extension base="security:loginDomainPrincipalType">
         <xsd:attribute name="realm-name" type="xsd:string" use="required"/>
      </xsd:extension>
   </xsd:complexContent>
</xsd:complexType>

@realm-name is required attribute that defines realm name.

Note that elements of security:realmPrincipalType wrap elements of security:principalType, that wrap elements of security:loginDomainPrincipalType. So the @class attribute value must be the value of the Principal implementation class that is wrapped by the security:loginDomainPrincipal.

Back to Top

Type named-username-password-credentialType

This element defines username - password credential.

<xsd:complexType name="named-username-password-credentialType">
   <xsd:sequence>
      <xsd:element name="name" type="xsd:string"/>
      <xsd:element name="username" type="xsd:string"/>
      <xsd:element name="password" type="xsd:string"/>
   </xsd:sequence>
</xsd:complexType>

name - required element. Names this credential set.
username - required element. User name.
password - required element. User password.

Back to Top

Type role-mappingsType

security:role-mappingsType defines mappings of J2EE roles to principals.

<xsd:complexType name="role-mappingsType">
<xsd:sequence>
<xsd:element name="role" type="security:roleType" minOccurs="1"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>

role - required sequence of 1 or more elements of security:roleType.

Back to Top

Type roleType

security:roleType element defines J2EE role mapping to a set of Principals. Mapped principals can be any kind of principal: domain-principal, realm-principal, principal, or a distinguished name (dn).

Note that ideally we want to map to DomainPrincipals or RealmPrincipals. This type of mapping is not supported in Geronimo M5 or earlier milestones. The only type of mapping in M5 and before is principalType mapping and dn mapping.

<xsd:complexType name="roleType">
   <xsd:sequence>
      <xsd:element name="description" type="security:descriptionType" minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="realm-principal" type="security:realmPrincipalType" minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="login-domain-principal" 
         type="security:loginDomainPrincipalType" minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="principal" type="security:principalType" minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="distinguished-name" 
         type="security:distinguishedNameType" minOccurs="0" maxOccurs="unbounded"/>
   </xsd:sequence>
   <xsd:attribute name="role-name" type="xsd:string" use="required"/>
</xsd:complexType>

@role-name - J2EE role name. This is required attribute.

description - optional sequence from 0 to many security:description elements.
realm-principal - optional sequence from 0 to many security:realmPrincipalType elements. Not supported for Geronimo M5 or earlier milestones.
login-domain-principal - optional sequence from 0 to many security:loginDomainPrincipal type elements. Not supported for Geronimo M5 or earlier milestones.
principal - optinal sequence from 0 to many security:principalType elements.
distinguished-name - optional sequence of security:distinguishedNameType elements.

Back to Top

Type distinguishedNameType

<xsd:complexType name="distinguishedNameType">
   <xsd:sequence>
      <xsd:element name="description" type="security:descriptionType" 
         minOccurs="0" maxOccurs="unbounded"/>
   </xsd:sequence>
   <xsd:attribute name="name" type="xsd:string" use="required"/>
   <xsd:attribute name="designated-run-as" type="xsd:boolean" default="false"/>
</xsd:complexType>

@designated-run-as - Set this attribute to true if this principal is to be used as the run-as principal for this role. This is optional attribute, default value is false.

desciption - optional sequence from 0 to many elements of security:descriptionType.

Back to Top

Type descriptionType

security:descriptionType element allows description to be inserted in any other element. This type extends schema string type with the reference to the global xml:lang attribute.

<xsd:complexType name="descriptionType">
   <xsd:simpleContent>
      <xsd:extension base="xsd:string">
         <xsd:attribute ref="xml:lang"/>
      </xsd:extension>
   </xsd:simpleContent>
</xsd:complexType>

@xml:lang - language attribute. This attribute is optional.

Back to Top