geronimo-scm mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Geronimo v3.0 > Configuring run-as and Default Subjects, and principal-role mapping
Date Mon, 31 Jan 2011 03:22:01 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2036/9/4/_/styles/combined.css?spaceKey=GMOxDOC30&amp;forWysiwyg=true" type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/GMOxDOC30/Configuring+run-as+and+Default+Subjects%2C+and+principal-role+mapping">Configuring run-as and Default Subjects, and principal-role mapping</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~maojia508">maojia</a>
    </h4>
        <br/>
                         <h4>Changes (8)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-unchanged" >h1. Introduction <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >{excerpt}Starting <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">in</span> <span class="diff-added-words"style="background-color: #dfd;">from version 2.0.1,</span> Geronimo <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">2.0.1 we have adopted</span> <span class="diff-added-words"style="background-color: #dfd;">adopts</span> the basic principle that all security flows from Subjects that result from logging in to a security realm.{excerpt}  In previous <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">geronimo releases</span> <span class="diff-added-words"style="background-color: #dfd;">Geronimo releases,</span> security information for run-as and default subjects was constructed entirely outside any security realm.  As a result of following the new <span class="diff-changed-words">principle<span class="diff-added-chars"style="background-color: #dfd;">,</span></span> run-as and default identities can now participate fully in security using such features as named credentials to access such external systems as connectors and web services, and the JACC system is now more fully pluggable. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >However, <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">since</span> <span class="diff-added-words"style="background-color: #dfd;">because</span> run-as and default subjects now result from logging <span class="diff-changed-words">in<span class="diff-added-chars"style="background-color: #dfd;"> </span>to</span> a security realm, to use such a subject you need to supply the login information for each such subject.  This information is encapsulated in a CredentialStore.  We supply a simple CredentialStore implementation using <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">xml</span> <span class="diff-added-words"style="background-color: #dfd;">XML</span> in your <span class="diff-changed-words"><span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">g</span><span class="diff-added-chars"style="background-color: #dfd;">G</span>eronimo</span> plan.  Note that this includes <span class="diff-changed-words">plain<span class="diff-added-chars"style="background-color: #dfd;"> </span>text</span> passwords for the run-as and default subjects.  This <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">may</span> <span class="diff-added-words"style="background-color: #dfd;">might</span> not be a suitable implementation for many environments. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>Each application can choose to use a default, global, credential store or specify a specific store, perhaps specific to that application. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h1. Configuring a SimpleCredentialStoreImpl <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >For each Subject accessible through a credential <span class="diff-changed-words">store<span class="diff-added-chars"style="background-color: #dfd;">,</span></span> you need to specify an id, the realm to log in to, and credentials, which depend on the security realm requirements but are typically the name and password.  The schema is as follows: <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{snippet:url=geronimo/server/tags/2.1.0/plugins/j2ee/geronimo-security-builder/src/main/xsd/geronimo-credential-store-1.0.xsd|lang=xml} <br> <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >At the <span class="diff-changed-words">moment<span class="diff-added-chars"style="background-color: #dfd;">,</span></span> Geronimo supplies callback handlers for name and password.  For other security realm requirements (e.g. <span class="diff-changed-words">certificates)<span class="diff-added-chars"style="background-color: #dfd;">,</span></span> you will have to write a callback handler. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>A simple example of credential store configuration would look like this: <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >Again, note that the PasswordCallbackHandler value element contains a <span class="diff-changed-words">plain<span class="diff-added-chars"style="background-color: #dfd;"> </span>text</span> password for the user. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h1. Configuring your application to use a particular CredentialStore <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >Note that this aspect of <span class="diff-changed-words"><span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">g</span><span class="diff-added-chars"style="background-color: #dfd;">G</span>eronimo</span> security is completely pluggable and only the default implementation is described here. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >Geronimo security for JavaEE applications requires including a &lt;security&gt; element in (one of) the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">geronimo</span> <span class="diff-added-words"style="background-color: #dfd;">GHeronimo</span> plans for your application.  This describes the principal-role mappings to connect the Subjects from your security realm to the roles used in the spec deployment descriptors (and annotations).  It also describes how to interpret run-as roles as subjects through specifying a credential store and the id and realm for each role used as a run-as.  Similarly a default subject can be specified in the credential store. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>The schema for security configuration is as follows: <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The credential store to use is specified in the credential-store-ref.  Normally you only need only supply the name component of the credential store name: for most purposes you are likely to include an app specific credential store in the <span class="diff-changed-words">app<span class="diff-added-chars"style="background-color: #dfd;">lication</span></span> plan, but otherwise you need to assure that the credential store gbean is in the ancestor configurations of the application. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>A default subject or each run-as role specifies the information needed to get the subject using a subject-infoType element. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="Configuringrun-asandDefaultSubjects%2Candprincipal-rolemapping-Introduction"></a>Introduction</h1>

<p>Starting from version 2.0.1, Geronimo adopts the basic principle that all security flows from Subjects that result from logging in to a security realm.  In previous Geronimo releases, security information for run-as and default subjects was constructed entirely outside any security realm.  As a result of following the new principle, run-as and default identities can now participate fully in security using such features as named credentials to access such external systems as connectors and web services, and the JACC system is now more fully pluggable.</p>

<p>However, because run-as and default subjects now result from logging in to a security realm, to use such a subject you need to supply the login information for each such subject.  This information is encapsulated in a CredentialStore.  We supply a simple CredentialStore implementation using XML in your Geronimo plan.  Note that this includes plain text passwords for the run-as and default subjects.  This might not be a suitable implementation for many environments.</p>

<p>Each application can choose to use a default, global, credential store or specify a specific store, perhaps specific to that application.</p>

<h1><a name="Configuringrun-asandDefaultSubjects%2Candprincipal-rolemapping-ConfiguringaSimpleCredentialStoreImpl"></a>Configuring a SimpleCredentialStoreImpl</h1>

<p>For each Subject accessible through a credential store, you need to specify an id, the realm to log in to, and credentials, which depend on the security realm requirements but are typically the name and password.  The schema is as follows:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;?xml version=<span class="code-quote">"1.0"</span> encoding=<span class="code-quote">"UTF-8"</span>?&gt;</span>
&lt;!--
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the <span class="code-quote">"License"</span>); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an <span class="code-quote">"AS IS"</span> BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
--&gt;

<span class="code-tag"><span class="code-comment">&lt;!-- $Rev$ $Date$ --&gt;</span></span>

&lt;xsd:schema <span class="code-keyword">xmlns:xsd</span>=<span class="code-quote">"http://www.w3.org/2001/XMLSchema"</span>
            <span class="code-keyword">xmlns:cs</span>=<span class="code-quote">"http://geronimo.apache.org/xml/ns/credentialstore-1.0"</span>
            targetNamespace=<span class="code-quote">"http://geronimo.apache.org/xml/ns/credentialstore-1.0"</span>
            elementFormDefault=<span class="code-quote">"qualified"</span> attributeFormDefault=<span class="code-quote">"unqualified"</span>
            version=<span class="code-quote">"1.0"</span>&gt;

    <span class="code-tag">&lt;xsd:annotation&gt;</span>
        <span class="code-tag">&lt;xsd:documentation&gt;</span>
            This is an XML Schema Definition for credential store configuration.
            CredentialStore configuration is
            specified by the element credential-store with namespace
            specified as xmlns =
            <span class="code-quote">"http://geronimo.apache.org/xml/ns/credentialstore-1.0"</span>.
        <span class="code-tag">&lt;/xsd:documentation&gt;</span>
    <span class="code-tag">&lt;/xsd:annotation&gt;</span>

    <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"credential-store"</span> type=<span class="code-quote">"cs:credential-storeType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:annotation&gt;</span>
            <span class="code-tag">&lt;xsd:documentation&gt;</span>
                The root element for Geronimo credential store configuration. This
                is a tree structure of realm, id, and sets of credentials such as name and password
            <span class="code-tag">&lt;/xsd:documentation&gt;</span>
        <span class="code-tag">&lt;/xsd:annotation&gt;</span>
    <span class="code-tag">&lt;/xsd:element&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"credential-storeType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:annotation&gt;</span>
            <span class="code-tag">&lt;xsd:documentation&gt;</span>
                Defines the list of realms
            <span class="code-tag">&lt;/xsd:documentation&gt;</span>
        <span class="code-tag">&lt;/xsd:annotation&gt;</span>
        <span class="code-tag">&lt;xsd:sequence&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"realm"</span> type=<span class="code-quote">"cs:realmType"</span> minOccurs=<span class="code-quote">"0"</span> maxOccurs=<span class="code-quote">"unbounded"</span>&gt;</span>
                <span class="code-tag">&lt;xsd:annotation&gt;</span>
                    <span class="code-tag">&lt;xsd:documentation&gt;</span>
                        The realm element contains the credentials for subjects in that realm.
                    <span class="code-tag">&lt;/xsd:documentation&gt;</span>
                <span class="code-tag">&lt;/xsd:annotation&gt;</span>
            <span class="code-tag">&lt;/xsd:element&gt;</span>
        <span class="code-tag">&lt;/xsd:sequence&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"realmType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:sequence&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"subject"</span> type=<span class="code-quote">"cs:subjectType"</span> minOccurs=<span class="code-quote">"0"</span> maxOccurs=<span class="code-quote">"unbounded"</span>/&gt;</span>
        <span class="code-tag">&lt;/xsd:sequence&gt;</span>
        <span class="code-tag">&lt;xsd:attribute name=<span class="code-quote">"name"</span> type=<span class="code-quote">"xsd:string"</span> use=<span class="code-quote">"required"</span>&gt;</span>
            <span class="code-tag">&lt;xsd:annotation&gt;</span>
                <span class="code-tag">&lt;xsd:documentation&gt;</span>
                    The name attribute specifies the login realm name
                <span class="code-tag">&lt;/xsd:documentation&gt;</span>
            <span class="code-tag">&lt;/xsd:annotation&gt;</span>
        <span class="code-tag">&lt;/xsd:attribute&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"subjectType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:sequence&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"id"</span> type=<span class="code-quote">"xsd:string"</span>&gt;</span>
                <span class="code-tag">&lt;xsd:annotation&gt;</span>
                    <span class="code-tag">&lt;xsd:documentation&gt;</span>
                        The id element serves to identify the subject externally. For subjects with meaningful
                        names it might be convenient to use the name as id.
                    <span class="code-tag">&lt;/xsd:documentation&gt;</span>
                <span class="code-tag">&lt;/xsd:annotation&gt;</span>
            <span class="code-tag">&lt;/xsd:element&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"credential"</span> type=<span class="code-quote">"cs:credentialType"</span> minOccurs=<span class="code-quote">"0"</span> maxOccurs=<span class="code-quote">"unbounded"</span>/&gt;</span>
        <span class="code-tag">&lt;/xsd:sequence&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"credentialType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:sequence&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"type"</span> type=<span class="code-quote">"xsd:string"</span>&gt;</span>
                <span class="code-tag">&lt;xsd:annotation&gt;</span>
                    <span class="code-tag">&lt;xsd:documentation&gt;</span>
                        Class name or alias of the callback handler that will accept this credential
                    <span class="code-tag">&lt;/xsd:documentation&gt;</span>
                <span class="code-tag">&lt;/xsd:annotation&gt;</span>
            <span class="code-tag">&lt;/xsd:element&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"value"</span> type=<span class="code-quote">"xsd:string"</span>&gt;</span>
                <span class="code-tag">&lt;xsd:annotation&gt;</span>
                    <span class="code-tag">&lt;xsd:documentation&gt;</span>
                        credential value as a string.
                    <span class="code-tag">&lt;/xsd:documentation&gt;</span>
                <span class="code-tag">&lt;/xsd:annotation&gt;</span>
            <span class="code-tag">&lt;/xsd:element&gt;</span>
        <span class="code-tag">&lt;/xsd:sequence&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>


<span class="code-tag">&lt;/xsd:schema&gt;</span>
</pre>
</div></div>


<p>At the moment, Geronimo supplies callback handlers for name and password.  For other security realm requirements (e.g. certificates), you will have to write a callback handler.</p>

<p>A simple example of credential store configuration would look like this:</p>

<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><b>Credential Store Example</b></div><div class="codeContent panelContent">
<pre class="code-xml">
    <span class="code-tag">&lt;gbean name=<span class="code-quote">"CredentialStore"</span> class=<span class="code-quote">"org.apache.geronimo.security.credentialstore.SimpleCredentialStoreImpl"</span>&gt;</span>
        <span class="code-tag">&lt;xml-attribute name=<span class="code-quote">"credentialStore"</span>&gt;</span>
            <span class="code-tag">&lt;credential-store xmlns=<span class="code-quote">"http://geronimo.apache.org/xml/ns/credentialstore-1.0"</span>&gt;</span>
                <span class="code-tag">&lt;realm name=<span class="code-quote">"my-properties-realm"</span>&gt;</span>
                    <span class="code-tag">&lt;subject&gt;</span>
                        <span class="code-tag">&lt;id&gt;</span>admin-run-as<span class="code-tag">&lt;/id&gt;</span>
                        <span class="code-tag">&lt;credential&gt;</span>
                            <span class="code-tag">&lt;type&gt;</span>org.apache.geronimo.security.credentialstore.NameCallbackHandler<span class="code-tag">&lt;/type&gt;</span>
                            <span class="code-tag">&lt;value&gt;</span>system<span class="code-tag">&lt;/value&gt;</span>
                        <span class="code-tag">&lt;/credential&gt;</span>
                        <span class="code-tag">&lt;credential&gt;</span>
                            <span class="code-tag">&lt;type&gt;</span>org.apache.geronimo.security.credentialstore.PasswordCallbackHandler<span class="code-tag">&lt;/type&gt;</span>
                            <span class="code-tag">&lt;value&gt;</span>manager<span class="code-tag">&lt;/value&gt;</span>
                        <span class="code-tag">&lt;/credential&gt;</span>
                    <span class="code-tag">&lt;/subject&gt;</span>
                    <span class="code-tag">&lt;subject&gt;</span>
                        <span class="code-tag">&lt;id&gt;</span>user-run-as<span class="code-tag">&lt;/id&gt;</span>
                        <span class="code-tag">&lt;credential&gt;</span>
                            <span class="code-tag">&lt;type&gt;</span>org.apache.geronimo.security.credentialstore.NameCallbackHandler<span class="code-tag">&lt;/type&gt;</span>
                            <span class="code-tag">&lt;value&gt;</span>user<span class="code-tag">&lt;/value&gt;</span>
                        <span class="code-tag">&lt;/credential&gt;</span>
                        <span class="code-tag">&lt;credential&gt;</span>
                            <span class="code-tag">&lt;type&gt;</span>org.apache.geronimo.security.credentialstore.PasswordCallbackHandler<span class="code-tag">&lt;/type&gt;</span>
                            <span class="code-tag">&lt;value&gt;</span>user-password<span class="code-tag">&lt;/value&gt;</span>
                        <span class="code-tag">&lt;/credential&gt;</span>
                    <span class="code-tag">&lt;/subject&gt;</span>
                    <span class="code-tag">&lt;subject&gt;</span>
                        <span class="code-tag">&lt;id&gt;</span>default<span class="code-tag">&lt;/id&gt;</span>
                        <span class="code-tag">&lt;credential&gt;</span>
                            <span class="code-tag">&lt;type&gt;</span>org.apache.geronimo.security.credentialstore.NameCallbackHandler<span class="code-tag">&lt;/type&gt;</span>
                            <span class="code-tag">&lt;value&gt;</span>default<span class="code-tag">&lt;/value&gt;</span>
                        <span class="code-tag">&lt;/credential&gt;</span>
                        <span class="code-tag">&lt;credential&gt;</span>
                            <span class="code-tag">&lt;type&gt;</span>org.apache.geronimo.security.credentialstore.PasswordCallbackHandler<span class="code-tag">&lt;/type&gt;</span>
                            <span class="code-tag">&lt;value&gt;</span>default<span class="code-tag">&lt;/value&gt;</span>
                        <span class="code-tag">&lt;/credential&gt;</span>
                    <span class="code-tag">&lt;/subject&gt;</span>
                <span class="code-tag">&lt;/realm&gt;</span>
            <span class="code-tag">&lt;/credential-store&gt;</span>
        <span class="code-tag">&lt;/xml-attribute&gt;</span>
    <span class="code-tag">&lt;/gbean&gt;</span>

</pre>
</div></div>

<p>Again, note that the PasswordCallbackHandler value element contains a plain text password for the user.</p>

<h1><a name="Configuringrun-asandDefaultSubjects%2Candprincipal-rolemapping-ConfiguringyourapplicationtouseaparticularCredentialStore"></a>Configuring your application to use a particular CredentialStore</h1>

<p>Note that this aspect of Geronimo security is completely pluggable and only the default implementation is described here.</p>

<p>Geronimo security for JavaEE applications requires including a &lt;security&gt; element in (one of) the GHeronimo plans for your application.  This describes the principal-role mappings to connect the Subjects from your security realm to the roles used in the spec deployment descriptors (and annotations).  It also describes how to interpret run-as roles as subjects through specifying a credential store and the id and realm for each role used as a run-as.  Similarly a default subject can be specified in the credential store.</p>

<p>The schema for security configuration is as follows:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;?xml version=<span class="code-quote">"1.0"</span> encoding=<span class="code-quote">"UTF-8"</span>?&gt;</span>
&lt;!--

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the <span class="code-quote">"License"</span>); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an <span class="code-quote">"AS IS"</span> BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
--&gt;

<span class="code-tag"><span class="code-comment">&lt;!-- $Rev$ $Date$ --&gt;</span></span>

&lt;xsd:schema
        <span class="code-keyword">xmlns:xsd</span>=<span class="code-quote">"http://www.w3.org/2001/XMLSchema"</span>
        <span class="code-keyword">xmlns:j2ee</span>=<span class="code-quote">"http://java.sun.com/xml/ns/j2ee"</span>
        <span class="code-keyword">xmlns:geronimo</span>=<span class="code-quote">"http://geronimo.apache.org/xml/ns/security-2.0"</span>
        targetNamespace=<span class="code-quote">"http://geronimo.apache.org/xml/ns/security-2.0"</span>
        <span class="code-keyword">xmlns:app</span>=<span class="code-quote">"http://geronimo.apache.org/xml/ns/j2ee/application-2.0"</span>
        <span class="code-keyword">xmlns:sys</span>=<span class="code-quote">"http://geronimo.apache.org/xml/ns/deployment-1.2"</span>
        elementFormDefault=<span class="code-quote">"qualified"</span>
        attributeFormDefault=<span class="code-quote">"unqualified"</span>
        version=<span class="code-quote">"2.0"</span>&gt;

    <span class="code-tag">&lt;xsd:import namespace=<span class="code-quote">"http://www.w3.org/XML/1998/namespace"</span> schemaLocation=<span class="code-quote">"http://www.w3.org/2001/xml.xsd"</span>/&gt;</span>
    <span class="code-tag">&lt;xsd:import namespace=<span class="code-quote">"http://geronimo.apache.org/xml/ns/j2ee/application-2.0"</span> schemaLocation=<span class="code-quote">"geronimo-application-2.0.xsd"</span>/&gt;</span>
    <span class="code-tag">&lt;xsd:import namespace=<span class="code-quote">"http://geronimo.apache.org/xml/ns/deployment-1.2"</span>  schemaLocation=<span class="code-quote">"geronimo-module-1.2.xsd"</span>/&gt;</span>

    <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"security"</span> type=<span class="code-quote">"geronimo:securityType"</span> substitutionGroup=<span class="code-quote">"app:security"</span>/&gt;</span>
    <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"credential-store"</span> type=<span class="code-quote">"sys:patternType"</span>/&gt;</span>
    <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"default-subject"</span> type=<span class="code-quote">"geronimo:subject-infoType"</span>/&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"securityType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:annotation&gt;</span>
            <span class="code-tag">&lt;xsd:documentation&gt;</span>
                Security entries

                If this element is present, all web and EJB modules MUST make the
                appropriate access checks as outlined in the JACC spec.
            <span class="code-tag">&lt;/xsd:documentation&gt;</span>
        <span class="code-tag">&lt;/xsd:annotation&gt;</span>
        <span class="code-tag">&lt;xsd:complexContent&gt;</span>
            <span class="code-tag">&lt;xsd:extension base=<span class="code-quote">"app:abstract-securityType"</span>&gt;</span>

                <span class="code-tag">&lt;xsd:sequence&gt;</span>
                    &lt;xsd:element name=<span class="code-quote">"description"</span> type=<span class="code-quote">"geronimo:descriptionType"</span> minOccurs=<span class="code-quote">"0"</span>
                                 maxOccurs=<span class="code-quote">"unbounded"</span>/&gt;
                    <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"credential-store-ref"</span> type=<span class="code-quote">"sys:patternType"</span> minOccurs=<span class="code-quote">"0"</span>/&gt;</span>
                    <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"default-subject"</span> type=<span class="code-quote">"geronimo:subject-infoType"</span> minOccurs=<span class="code-quote">"0"</span>/&gt;</span>
                    <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"role-mappings"</span> type=<span class="code-quote">"geronimo:role-mappingsType"</span> minOccurs=<span class="code-quote">"0"</span>/&gt;</span>
                <span class="code-tag">&lt;/xsd:sequence&gt;</span>
                <span class="code-tag">&lt;xsd:attribute name=<span class="code-quote">"doas-current-caller"</span> type=<span class="code-quote">"xsd:boolean"</span> default=<span class="code-quote">"false"</span>&gt;</span>
                    <span class="code-tag">&lt;xsd:annotation&gt;</span>
                        <span class="code-tag">&lt;xsd:documentation&gt;</span>
                            Set this attribute to <span class="code-quote">"true"</span> if the work is to be performed
                            as the calling Subject.
                        <span class="code-tag">&lt;/xsd:documentation&gt;</span>
                    <span class="code-tag">&lt;/xsd:annotation&gt;</span>
                <span class="code-tag">&lt;/xsd:attribute&gt;</span>
                <span class="code-tag">&lt;xsd:attribute name=<span class="code-quote">"use-context-handler"</span> type=<span class="code-quote">"xsd:boolean"</span> default=<span class="code-quote">"false"</span>&gt;</span>
                    <span class="code-tag">&lt;xsd:annotation&gt;</span>
                        <span class="code-tag">&lt;xsd:documentation&gt;</span>
                            Set this attribute to <span class="code-quote">"true"</span> if the installed JACC policy
                            contexts will use PolicyContextHandlers.
                        <span class="code-tag">&lt;/xsd:documentation&gt;</span>
                    <span class="code-tag">&lt;/xsd:annotation&gt;</span>
                <span class="code-tag">&lt;/xsd:attribute&gt;</span>
                <span class="code-tag">&lt;xsd:attribute name=<span class="code-quote">"default-role"</span> type=<span class="code-quote">"xsd:string"</span>&gt;</span>
                    <span class="code-tag">&lt;xsd:annotation&gt;</span>
                        <span class="code-tag">&lt;xsd:documentation&gt;</span>
                            Used by the 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
                        <span class="code-tag">&lt;/xsd:documentation&gt;</span>
                    <span class="code-tag">&lt;/xsd:annotation&gt;</span>
                <span class="code-tag">&lt;/xsd:attribute&gt;</span>
            <span class="code-tag">&lt;/xsd:extension&gt;</span>
        <span class="code-tag">&lt;/xsd:complexContent&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"descriptionType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:simpleContent&gt;</span>
            <span class="code-tag">&lt;xsd:extension base=<span class="code-quote">"xsd:string"</span>&gt;</span>
                <span class="code-tag">&lt;xsd:attribute ref=<span class="code-quote">"xml:lang"</span>/&gt;</span>
            <span class="code-tag">&lt;/xsd:extension&gt;</span>
        <span class="code-tag">&lt;/xsd:simpleContent&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"named-username-password-credentialType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:sequence&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"name"</span> type=<span class="code-quote">"xsd:string"</span>/&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"username"</span> type=<span class="code-quote">"xsd:string"</span>/&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"password"</span> type=<span class="code-quote">"xsd:string"</span>/&gt;</span>
        <span class="code-tag">&lt;/xsd:sequence&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"role-mappingsType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:sequence&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"role"</span> type=<span class="code-quote">"geronimo:roleType"</span> minOccurs=<span class="code-quote">"1"</span> maxOccurs=<span class="code-quote">"unbounded"</span>/&gt;</span>
        <span class="code-tag">&lt;/xsd:sequence&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"roleType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:sequence&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"description"</span> type=<span class="code-quote">"geronimo:descriptionType"</span> minOccurs=<span class="code-quote">"0"</span> maxOccurs=<span class="code-quote">"unbounded"</span>/&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"run-as-subject"</span> type=<span class="code-quote">"geronimo:subject-infoType"</span> minOccurs=<span class="code-quote">"0"</span>/&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"realm-principal"</span> type=<span class="code-quote">"geronimo:realmPrincipalType"</span> minOccurs=<span class="code-quote">"0"</span> maxOccurs=<span class="code-quote">"unbounded"</span>/&gt;</span>
            &lt;xsd:element name=<span class="code-quote">"login-domain-principal"</span> type=<span class="code-quote">"geronimo:loginDomainPrincipalType"</span> minOccurs=<span class="code-quote">"0"</span>
                         maxOccurs=<span class="code-quote">"unbounded"</span>/&gt;
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"principal"</span> type=<span class="code-quote">"geronimo:principalType"</span> minOccurs=<span class="code-quote">"0"</span> maxOccurs=<span class="code-quote">"unbounded"</span>/&gt;</span>
            &lt;xsd:element name=<span class="code-quote">"distinguished-name"</span> type=<span class="code-quote">"geronimo:distinguishedNameType"</span> minOccurs=<span class="code-quote">"0"</span>
                         maxOccurs=<span class="code-quote">"unbounded"</span>/&gt;
        <span class="code-tag">&lt;/xsd:sequence&gt;</span>
        <span class="code-tag">&lt;xsd:attribute name=<span class="code-quote">"role-name"</span> type=<span class="code-quote">"xsd:string"</span> use=<span class="code-quote">"required"</span>/&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"realmPrincipalType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:complexContent&gt;</span>
            <span class="code-tag">&lt;xsd:extension base=<span class="code-quote">"geronimo:loginDomainPrincipalType"</span>&gt;</span>
                <span class="code-tag">&lt;xsd:attribute name=<span class="code-quote">"realm-name"</span> type=<span class="code-quote">"xsd:string"</span> use=<span class="code-quote">"required"</span>/&gt;</span>
            <span class="code-tag">&lt;/xsd:extension&gt;</span>
        <span class="code-tag">&lt;/xsd:complexContent&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"loginDomainPrincipalType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:complexContent&gt;</span>
            <span class="code-tag">&lt;xsd:extension base=<span class="code-quote">"geronimo:principalType"</span>&gt;</span>
                <span class="code-tag">&lt;xsd:attribute name=<span class="code-quote">"domain-name"</span> type=<span class="code-quote">"xsd:string"</span> use=<span class="code-quote">"required"</span>/&gt;</span>
            <span class="code-tag">&lt;/xsd:extension&gt;</span>
        <span class="code-tag">&lt;/xsd:complexContent&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"principalType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:sequence&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"description"</span> type=<span class="code-quote">"geronimo:descriptionType"</span> minOccurs=<span class="code-quote">"0"</span> maxOccurs=<span class="code-quote">"unbounded"</span>/&gt;</span>
        <span class="code-tag">&lt;/xsd:sequence&gt;</span>
        <span class="code-tag">&lt;xsd:attribute name=<span class="code-quote">"class"</span> type=<span class="code-quote">"xsd:string"</span> use=<span class="code-quote">"required"</span>/&gt;</span>
        <span class="code-tag">&lt;xsd:attribute name=<span class="code-quote">"name"</span> type=<span class="code-quote">"xsd:string"</span> use=<span class="code-quote">"required"</span>/&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"distinguishedNameType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:sequence&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"description"</span> type=<span class="code-quote">"geronimo:descriptionType"</span> minOccurs=<span class="code-quote">"0"</span> maxOccurs=<span class="code-quote">"unbounded"</span>/&gt;</span>
        <span class="code-tag">&lt;/xsd:sequence&gt;</span>
        <span class="code-tag">&lt;xsd:attribute name=<span class="code-quote">"name"</span> type=<span class="code-quote">"xsd:string"</span> use=<span class="code-quote">"required"</span>/&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag">&lt;xsd:complexType name=<span class="code-quote">"subject-infoType"</span>&gt;</span>
        <span class="code-tag">&lt;xsd:sequence&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"description"</span> type=<span class="code-quote">"geronimo:descriptionType"</span> minOccurs=<span class="code-quote">"0"</span> maxOccurs=<span class="code-quote">"unbounded"</span>/&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"realm"</span> type=<span class="code-quote">"xsd:string"</span>/&gt;</span>
            <span class="code-tag">&lt;xsd:element name=<span class="code-quote">"id"</span> type=<span class="code-quote">"xsd:string"</span>/&gt;</span>
        <span class="code-tag">&lt;/xsd:sequence&gt;</span>
    <span class="code-tag">&lt;/xsd:complexType&gt;</span>

    <span class="code-tag"><span class="code-comment">&lt;!--&lt;xsd:complexType name=<span class="code-quote">"credential-storeType"</span>&gt;</span>--&gt;</span>
        <span class="code-tag"><span class="code-comment">&lt;!--&lt;xsd:sequence&gt;</span>--&gt;</span>
            <span class="code-tag"><span class="code-comment">&lt;!--&lt;xsd:element name=<span class="code-quote">"pattern"</span> type=<span class="code-quote">"sys:patternType"</span>&gt;</span>--&gt;</span>
                <span class="code-tag"><span class="code-comment">&lt;!--&lt;xsd:annotation&gt;</span>--&gt;</span>
                    <span class="code-tag"><span class="code-comment">&lt;!--&lt;xsd:documentation&gt;</span>--&gt;</span>
                        <span class="code-tag"><span class="code-comment">&lt;!--The pattern element defines a components of the--&gt;</span></span>
                        <span class="code-tag"><span class="code-comment">&lt;!--abstract name of GBean referred. It (optionally) includes--&gt;</span></span>
                        <span class="code-tag"><span class="code-comment">&lt;!--the groupId, artifactId, version,--&gt;</span></span>
                        <span class="code-tag"><span class="code-comment">&lt;!--module, type, and name of the GBean module.--&gt;</span></span>
                    <span class="code-tag"><span class="code-comment">&lt;!--&lt;/xsd:documentation&gt;</span>--&gt;</span>
                <span class="code-tag"><span class="code-comment">&lt;!--&lt;/xsd:annotation&gt;</span>--&gt;</span>
            <span class="code-tag"><span class="code-comment">&lt;!--&lt;/xsd:element&gt;</span>--&gt;</span>
        <span class="code-tag"><span class="code-comment">&lt;!--&lt;/xsd:sequence&gt;</span>--&gt;</span>
    <span class="code-tag"><span class="code-comment">&lt;!--&lt;/xsd:complexType&gt;</span>--&gt;</span>

<span class="code-tag">&lt;/xsd:schema&gt;</span>
</pre>
</div></div>


<p>The credential store to use is specified in the credential-store-ref.  Normally you only need only supply the name component of the credential store name: for most purposes you are likely to include an app specific credential store in the application plan, but otherwise you need to assure that the credential store gbean is in the ancestor configurations of the application.</p>

<p>A default subject or each run-as role specifies the information needed to get the subject using a subject-infoType element.</p>

<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><b>Example Security Configuration</b></div><div class="codeContent panelContent">
<pre class="code-xml">
      <span class="code-tag">&lt;security use-context-handler=<span class="code-quote">"false"</span> xmlns=<span class="code-quote">"http://geronimo.apache.org/xml/ns/security-2.0"</span>&gt;</span>
        <span class="code-tag">&lt;default-subject&gt;</span>
          <span class="code-tag">&lt;realm&gt;</span>my-properties-realm<span class="code-tag">&lt;/realm&gt;</span>
          <span class="code-tag">&lt;id&gt;</span>default<span class="code-tag">&lt;/id&gt;</span>
        <span class="code-tag">&lt;/default-subject&gt;</span>
        <span class="code-tag">&lt;role-mappings&gt;</span>
          <span class="code-tag">&lt;role role-name=<span class="code-quote">"Administrator"</span>&gt;</span>
            <span class="code-tag">&lt;principal class=<span class="code-quote">"org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"</span> name=<span class="code-quote">"system"</span>/&gt;</span>
          <span class="code-tag">&lt;/role&gt;</span>
          <span class="code-tag">&lt;role role-name=<span class="code-quote">"User"</span>&gt;</span>
            <span class="code-tag">&lt;run-as-subject&gt;</span>
                <span class="code-tag">&lt;realm&gt;</span>my-properties-realm<span class="code-tag">&lt;/realm&gt;</span>
                <span class="code-tag">&lt;id&gt;</span>user-run-as<span class="code-tag">&lt;/id&gt;</span>
            <span class="code-tag">&lt;/run-as-subject&gt;</span>the loi
            <span class="code-tag">&lt;principal class=<span class="code-quote">"org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"</span> name=<span class="code-quote">"user"</span>/&gt;</span>
          <span class="code-tag">&lt;/role&gt;</span>
        <span class="code-tag">&lt;/role-mappings&gt;</span>
      <span class="code-tag">&lt;/security&gt;</span>
</pre>
</div></div>

<p>The sample above shows the simplest principal-role mapping: you specify the principal class and name for each principal that maps to a certain role.  Normally this will be entirely sufficient to distinguish principals.  However, you might have several login modules or security realms that can produce the same principal but with different meanings.  In this case you can include the login domain name or realm name to distinguish the principals.</p>

<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><b>Additional principal specifications</b></div><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag"><span class="code-comment">&lt;!-- normal, no domain or realm info --&gt;</span></span>
<span class="code-tag">&lt;principal class=<span class="code-quote">"org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"</span> name=<span class="code-quote">"user"</span>/&gt;</span>

<span class="code-tag"><span class="code-comment">&lt;!-- login domain name specified --&gt;</span></span>
<span class="code-tag">&lt;login-domain-principal domain-name=<span class="code-quote">"mydomain"</span> class=<span class="code-quote">"org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"</span> name=<span class="code-quote">"user"</span>/&gt;</span>

<span class="code-tag">&lt;~-- realm name and login domain name specified&gt;</span>
<span class="code-tag">&lt;realm-principal realm-name=<span class="code-quote">"my-properties-realm"</span> domain-name=<span class="code-quote">"mydomain"</span> class=<span class="code-quote">"org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"</span> name=<span class="code-quote">"user"</span>/&gt;</span>

</pre>
</div></div>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/GMOxDOC30/Configuring+run-as+and+Default+Subjects%2C+and+principal-role+mapping">View Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=20645468&revisedVersion=2&originalVersion=1">View Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/GMOxDOC30/Configuring+run-as+and+Default+Subjects%2C+and+principal-role+mapping?showComments=true&amp;showCommentArea=true#addcomment">Add Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message