http://git-wip-us.apache.org/repos/asf/shiro-site/blob/a2ce402a/configuration.html.vtl ---------------------------------------------------------------------- diff --git a/configuration.html.vtl b/configuration.html.vtl deleted file mode 100644 index fd76cfc..0000000 --- a/configuration.html.vtl +++ /dev/null @@ -1,474 +0,0 @@ -<h1><a name="Configuration-ApacheShiroConfiguration"></a>Apache Shiro Configuration</h1> - -<div class="toc"> -<ul><li><a href="#Configuration-ProgrammaticConfiguration">Programmatic Configuration</a></li><ul><li><a href="#Configuration-SecurityManagerObjectGraph">SecurityManager Object Graph</a></li></ul><li><a href="#Configuration-INIConfiguration">INI Configuration</a></li><ul><li><a href="#Configuration-CreatingaSecurityManagerfromINI">Creating a SecurityManager from INI</a></li><ul><li><a href="#Configuration-SecurityManagerfromanINIresource">SecurityManager from an INI resource</a></li><li><a href="#Configuration-SecurityManagerfromanINIinstance">SecurityManager from an INI instance</a></li></ul><li><a href="#Configuration-INISections">INI Sections</a></li><ul><li><a href="#Configuration-%5Cmain%5C">[main]</a></li><ul><li><a href="#Configuration-Defininganobject">Defining an object</a></li><li><a href="#Configuration-Settingobjectproperties">Setting object properties</a></li><ul><li><a href="#Configuration-PrimitiveValues">Primitive Values</a></li><li><a href="#Configuration-ReferenceV alues">Reference Values</a></li><li><a href="#Configuration-NestedProperties">Nested Properties</a></li><li><a href="#Configuration-ByteArrayValues">Byte Array Values</a></li><li><a href="#Configuration-CollectionProperties">Collection Properties</a></li></ul><li><a href="#Configuration-Considerations">Considerations</a></li><ul><li><a href="#Configuration-OrderMatters">Order Matters</a></li><li><a href="#Configuration-OverridingInstances">Overriding Instances</a></li><li><a href="#Configuration-DefaultSecurityManager">Default SecurityManager</a></li></ul></ul><li><a href="#Configuration-%5Cusers%5C">[users]</a></li><ul><li><a href="#Configuration-LineFormat">Line Format</a></li><li><a href="#Configuration-EncryptingPasswords">Encrypting Passwords</a></li></ul><li><a href="#Configuration-%5Croles%5C">[roles]</a></li><ul><li><a href="#Configuration-LineFormat">Line Format</a></li></ul><li><a href="#Configuration-%5Curls%5C">[urls]</a></li></ul></ul><li><a href="#Configuration-Lendaha ndwithdocumentation">Lend a hand with documentation</a></li></ul></div> - -<p>Shiro is designed to work in any environment, from simple command-line applications to the largest enterprise clustered applications. Because of this diversity of environments, there are a number of configuration mechanisms that are suitable for configuration. This section covers the configuration mechanisms that are supported by Shiro core only.</p> - -#tip('Many Configuration Options', 'Shiro''s <tt>SecurityManager</tt> implementations and all supporting components are all JavaBeans compatible. This allows Shiro to be configured with practically any configuration format such as regular Java, XML (Spring, JBoss, Guice, etc), <a class="external-link" href="http://www.yaml.org/"; rel="nofollow">YAML</a>, JSON, Groovy Builder markup, and more.') - -<h2><a name="Configuration-ProgrammaticConfiguration"></a>Programmatic Configuration</h2> - -<p>The absolute simplest way to create a SecurityManager and make it available to the application is to create an <tt>org.apache.shiro.mgt.DefaultSecurityManager</tt> and wire it up in code. For example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Realm realm = <span class="code-comment">//instantiate or acquire a Realm instance. We'll discuss Realms later. -</span> -<span class="code-object">SecurityManager</span> securityManager = <span class="code-keyword">new</span> DefaultSecurityManager(realm); - -<span class="code-comment">//Make the <span class="code-object">SecurityManager</span> instance available to the entire application via <span class="code-keyword">static</span> memory: -</span>SecurityUtils.setSecurityManager(securityManager); -</pre> -</div></div> - -<p>Surprisingly, after only 3 lines of code, you now have a fully functional Shiro environment suitable for many applications. How easy was that!?</p> - -<h3><a name="Configuration-SecurityManagerObjectGraph"></a>SecurityManager Object Graph</h3> - -<p>As discussed in the <a href="architecture.html" title="Architecture">Architecture</a> chapter, Shiro's <tt>SecurityManager</tt> implementations are essentially a modular object graph of nested security-specific components. Because they are also JavaBeans-compatible, you can call any of the nested components <tt>getter</tt> and <tt>setter</tt> methods to configure the <tt>SecurityManager</tt> and its internal object graph.</p> - -<p>For example, if you wanted to configure the <tt>SecurityManager</tt> instance to use a custom <tt>SessionDAO</tt> to customize <a href="session-management.html" title="Session Management">Session Management</a>, you could set the <tt>SessionDAO</tt> directly with the nested SessionManager's <tt>setSessionDAO</tt> method:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -... - -DefaultSecurityManager securityManager = <span class="code-keyword">new</span> DefaultSecurityManager(realm); - -SessionDAO sessionDAO = <span class="code-keyword">new</span> CustomSessionDAO(); - -((DefaultSessionManager)securityManager.getSessionManager()).setSessionDAO(sessionDAO); -... -</pre> -</div></div> - -<p>Using direct method invocations, you can configure any part of the <tt>SecurityManager</tt>'s object graph.</p> - -<p>But, as simple as programmatic customization is, it does not represent the ideal configuration for most real world applications. There are a few reasons why programmatic configuration may not be suitable for your application:</p> - -<ul><li>It requires you to know about and instantiate a direct implementation. It would be nicer if you didn't have to know about concrete implementations and where to find them. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li>Because of Java's type-safe nature, you're required to cast objects obtained via <tt>get*</tt> methods to their specific implementation. So much casting is ugly, verbose, and tightly-couples you to implementation classes. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li>The <tt>SecurityUtils.setSecurityManager</tt> method call makes the instantiated <tt>SecurityManager</tt> instance a VM static singleton, which, while fine for many applications, would cause problems if more than one Shiro-enabled application was running on the same JVM. It could be better if the instance was an application singleton, but not a static memory reference. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li>It requires you to recompile your application every time you want to make a Shiro configuration change.</li></ul> - - -<p>However, even with these caveats, the direct programmatic manipulation approach could still be valuable in memory-constrained environments, like smart-phone applications. If your application does not run in a memory-constrained environment, you'll find text-based configuration to be easier to use and read.</p> - -<h2><a name="Configuration-INIConfiguration"></a>INI Configuration</h2> - -<p>Most applications instead benefit from text-based configuration that could be modified independently of source code and even make things easier to understand for those not intimately familiar with Shiro's APIs.</p> - -<p>To ensure a common-denominator text-based configuration mechanism that can work in all environments with minimal 3rd party dependencies, Shiro supports the <a class="external-link" href="https://en.wikipedia.org/wiki/INI_file"; rel="nofollow">INI format</a> to build the <tt>SecurityManager</tt> object graph and its supporting components. INI is easy to read, easy to configure, and is simple to set-up and suits most applications well.</p> - -<h3><a name="Configuration-CreatingaSecurityManagerfromINI"></a>Creating a SecurityManager from INI</h3> - -<p>Here are two examples of how to build a SecurityManager based on INI configuration.</p> - -<h4><a name="Configuration-SecurityManagerfromanINIresource"></a>SecurityManager from an INI resource</h4> - -<p>We can create the SecurityManager instance from an INI resource path. Resources can be acquired from the file system, classpath, or URLs when prefixed with <tt>file:</tt>, <tt>classpath:</tt>, or <tt>url:</tt> respectively. This example uses a <tt>Factory</tt> to ingest a <tt>shiro.ini</tt> file from the root of the classpath and return the <tt>SecurityManager</tt> instance:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">import</span> org.apache.shiro.SecurityUtils; -<span class="code-keyword">import</span> org.apache.shiro.util.Factory; -<span class="code-keyword">import</span> org.apache.shiro.mgt.<span class="code-object">SecurityManager</span>; -<span class="code-keyword">import</span> org.apache.shiro.config.IniSecurityManagerFactory; - -... - -Factory<<span class="code-object">SecurityManager</span>> factory = <span class="code-keyword">new</span> IniSecurityManagerFactory(<span class="code-quote">"classpath:shiro.ini"</span>); -<span class="code-object">SecurityManager</span> securityManager = factory.getInstance(); -SecurityUtils.setSecurityManager(securityManager); -</pre> -</div></div> - -<h4><a name="Configuration-SecurityManagerfromanINIinstance"></a>SecurityManager from an INI instance</h4> - -<p>The INI configuration can be constructed programmatically as well if desired via the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/config/Ini.html">org.apache.shiro.config.Ini</a></tt> class. The Ini class functions similarly to the JDK <tt><a class="external-link" href="http://download.oracle.com/javase/6/docs/api/java/util/Properties.html"; rel="nofollow">java.util.Properties</a></tt> class, but additionally supports segmentation by section name. </p> - -<p>For example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">import</span> org.apache.shiro.SecurityUtils; -<span class="code-keyword">import</span> org.apache.shiro.util.Factory; -<span class="code-keyword">import</span> org.apache.shiro.mgt.<span class="code-object">SecurityManager</span>; -<span class="code-keyword">import</span> org.apache.shiro.config.Ini; -<span class="code-keyword">import</span> org.apache.shiro.config.IniSecurityManagerFactory; - -... - -Ini ini = <span class="code-keyword">new</span> Ini(); -<span class="code-comment">//populate the Ini instance as necessary -</span>... -Factory<<span class="code-object">SecurityManager</span>> factory = <span class="code-keyword">new</span> IniSecurityManagerFactory(ini); -<span class="code-object">SecurityManager</span> securityManager = factory.getInstance(); -SecurityUtils.setSecurityManager(securityManager); -</pre> -</div></div> - -<p>Now that we know how to construct a <tt>SecurityManager</tt> from INI configuration, let's take a look at exactly how to define a Shiro INI configuration.</p> - -<h3><a name="Configuration-INISections"></a>INI Sections</h3> - -<p>INI is basically a text configuration consisting of key/value pairs organized by uniquely-named sections. Keys are unique per section only, not over the entire configuration (unlike the JDK <a class="external-link" href="http://java.sun.com/javase/6/docs/api/java/util/Properties.html"; rel="nofollow">Properties</a>). Each section may be viewed like a single <tt>Properties</tt> definition however.</p> - -<p>Commented lines can start with either with an Octothorpe (# - aka the 'hash', 'pound' or 'number' sign) or a Semi-colon (';')</p> - -<p>Here is an example of the sections understood by Shiro:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -# ======================= -# Shiro INI configuration -# ======================= - -[main] -# Objects and their properties are defined here, -# Such as the securityManager, Realms and anything -# <span class="code-keyword">else</span> needed to build the <span class="code-object">SecurityManager</span> - -[users] -# The 'users' section is <span class="code-keyword">for</span> simple deployments -# when you only need a small number of statically-defined -# set of User accounts. - -[roles] -# The 'roles' section is <span class="code-keyword">for</span> simple deployments -# when you only need a small number of statically-defined -# roles. - -[urls] -# The 'urls' section is used <span class="code-keyword">for</span> url-based security -# in web applications. We'll discuss <span class="code-keyword">this</span> section in the -# Web documentation -</pre> -</div></div> - -<h4><a name="Configuration-%5Cmain%5C"></a>[main]</h4> - -<p>The <tt><b>[main]</b></tt> section is where you configure the application's <tt>SecurityManager</tt> instance and any of its dependencies, such as <a href="realm.html" title="Realm">Realm</a>s.</p> - -<p>Configuring object instances like the SecurityManager or any of its dependencies sounds like a difficult thing to do with INI, where we can only use name/value pairs. But through a little bit of convention and understanding of object graphs, you'll find that you can do quite a lot. Shiro uses these assumptions to enable a simple yet fairly concise configuration mechanism.</p> - -<p>We often like to refer to this approach as "poor man's" Dependency Injection, and although not as powerful as full-blown Spring/Guice/JBoss XML files, you'll find it gets quite a lot done without much complexity. Of course those other configuration mechanism are available as well, but they're not required to use Shiro.</p> - -<p>Just to whet your appetite, here is an example of a valid <tt>[main]</tt> configuration. We'll cover it in detail below, but you might find that you understand quite a bit of what is going on already by intuition alone:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] -sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher - -myRealm = com.company.security.shiro.DatabaseRealm -myRealm.connectionTimeout = 30000 -myRealm.username = jsmith -myRealm.password = secret -myRealm.credentialsMatcher = $sha256Matcher - -securityManager.sessionManager.globalSessionTimeout = 1800000 -</pre> -</div></div> - -<h5><a name="Configuration-Defininganobject"></a>Defining an object</h5> - -<p>Consider the following <tt>[main]</tt> section snippet:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] -myRealm = com.company.shiro.realm.MyRealm -... -</pre> -</div></div> - -<p>This line instantiates a new object instance of type <tt>com.company.shiro.realm.MyRealm</tt> and makes that object available under the <b>myRealm</b> name for further reference and configuration.</p> - -<p>If the object instantiated implements the <tt>org.apache.shiro.util.Nameable</tt> interface, then the the <tt>Nameable.setName</tt> method will be invoked on the object with the name value (<b>myRealm</b> in this example).</p> - -<h5><a name="Configuration-Settingobjectproperties"></a>Setting object properties</h5> - -<h6><a name="Configuration-PrimitiveValues"></a>Primitive Values</h6> - -<p>Simple primitive properties can be assigned just by using the equals sign:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -... -myRealm.connectionTimeout = 30000 -myRealm.username = jsmith -... -</pre> -</div></div> - -<p>these lines of configuration translate into method calls:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -... -myRealm.setConnectionTimeout(30000); -myRealm.setUsername(<span class="code-quote">"jsmith"</span>); -... -</pre> -</div></div> - -<p>How is this possible? It assumes that all objects are <a class="external-link" href="https://en.wikipedia.org/wiki/JavaBean"; rel="nofollow">Java Beans</a>-compatible <a class="external-link" href="https://en.wikipedia.org/wiki/Plain_Old_Java_Object"; rel="nofollow">POJO</a>s.</p> - -<p>Under the covers, Shiro by default uses Apache Commons <a class="external-link" href="http://commons.apache.org/proper/commons-beanutils/";>BeanUtils</a> to do all the heavy lifting when setting these properties. So although INI values are text, BeanUtils knows how to convert the string values to the proper primitive types and then invoke the corresponding JavaBeans setter method.</p> - -<h6><a name="Configuration-ReferenceValues"></a>Reference Values</h6> - -<p>What if the value you need to set is not a primitive, but another object? Well, you can use a dollar sign ($) to reference a previously-defined instance. For example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -... -sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher -... -myRealm.credentialsMatcher = $sha256Matcher -... -</pre> -</div></div> - -<p>This simply locates the object defined by the name <b>sha256Matcher</b> and then uses BeanUtils to set that object on the <b>myRealm</b> instance (by calling the <tt>myRealm.setCredentialsMatcher(sha256Matcher)</tt> method).</p> - -<h6><a name="Configuration-NestedProperties"></a>Nested Properties</h6> - -<p>Using dotted notation on the left side of the INI line's equals sign, you can traverse an object graph to get to the final object/property that you want set. For example, this config line:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -... -securityManager.sessionManager.globalSessionTimeout = 1800000 -... -</pre> -</div></div> - -<p>Translates (by BeanUtils) into the following logic:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -securityManager.getSessionManager().setGlobalSessionTimeout(1800000); -</pre> -</div></div> - -<p>The graph traversal can be as deep as necessary: <tt>object.property1.property2....propertyN.value = blah</tt></p> - -#tip('BeanUtils Property Support', 'Any property assignment operation supported by the BeanUtils.<a class="external-link" href="https://commons.apache.org/proper/commons-beanutils/apidocs/org/apache/commons/beanutils/BeanUtils.html#setProperty-java.lang.Object-java.lang.String-java.lang.Object-";>setProperty</a> method will work in Shiro''s [main] section, including set/list/map element assignments. See the <a class="external-link" href="http://commons.apache.org/proper/commons-beanutils/";>Apache Commons BeanUtils Website</a> and documentation for more information.') - -<h6><a name="Configuration-ByteArrayValues"></a>Byte Array Values</h6> - -<p>Because raw byte arrays can't be specified natively in a text format, we must use a text encoding of the byte array. The values can be specified either as a Base64 encoded string (the default) or as a Hex encoded string. The default is Base64 because Base64 encoding requires less actual text to represent values - it has a larger encoding alphabet, meaning your tokens are shorter (a bit nicer for text config).</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -# The 'cipherKey' attribute is a <span class="code-object">byte</span> array. By <span class="code-keyword">default</span>, text values -# <span class="code-keyword">for</span> all <span class="code-object">byte</span> array properties are expected to be Base64 encoded: - -securityManager.rememberMeManager.cipherKey = kPH+bIxk5D2deZiIxcaaaA== -... -</pre> -</div></div> - -<p>However, if you prefer to use Hex encoding instead, you must prefix the String token with <tt>0x</tt> ('zero' 'x'):</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -securityManager.rememberMeManager.cipherKey = 0x3707344A4093822299F31D008 -</pre> -</div></div> - -<h6><a name="Configuration-CollectionProperties"></a>Collection Properties</h6> - -<p>Lists, Sets and Maps can be set like any other property - either directly or as a nested property. For sets and lists, just specify a comma-delimited set of values or object references.</p> - -<p>For example, some SessionListeners:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -sessionListener1 = com.company.my.SessionListenerImplementation -... -sessionListener2 = com.company.my.other.SessionListenerImplementation -... -securityManager.sessionManager.sessionListeners = $sessionListener1, $sessionListener2 -</pre> -</div></div> - -<p>For Maps, you specify a comma-delimited list of key-value pairs, where each key-value pair is delimited by a colon ':'</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -object1 = com.company.some.<span class="code-object">Class</span> -object2 = com.company.another.<span class="code-object">Class</span> -... -anObject = some.class.with.a.Map.property - -anObject.mapProperty = key1:$object1, key2:$object2 -</pre> -</div></div> - -<p>In the above example, the object referenced by <tt>$object1</tt> will be in the map under the String key <tt>key1</tt>, i.e. <tt>map.get("key1")</tt> returns <tt>object1</tt>. You can also use other objects as the keys:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -anObject.map = $objectKey1:$objectValue1, $objectKey2:$objectValue2 -... -</pre> -</div></div> - -<h5><a name="Configuration-Considerations"></a>Considerations</h5> - -<h6><a name="Configuration-OrderMatters"></a>Order Matters</h6> - -<p>The INI format and conventions above are very convenient and easy to understand, but it is not as powerful as other text/XML-based configuration mechanisms. The most important thing to understand when using the above mechanism is that <b>Order Matters!</b></p> - -#warning('Be Careful', 'Each object instantiation and each value assignment is executed <em>in the order they occur in the [main] section</em>. These lines ultimately translate to a JavaBeans getter/setter method invocation, and so those methods are invoked in the same order! -<p>Keep this in mind when writing your configuration.</p>') - -<h6><a name="Configuration-OverridingInstances"></a>Overriding Instances</h6> - -<p>Any object can be overridden by a new instance defined later in the configuration. So for example, the 2nd <tt>myRealm</tt> definition would overwrite the first:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -... -myRealm = com.company.security.MyRealm -... -myRealm = com.company.security.DatabaseRealm -... -</pre> -</div></div> - -<p>This would result in <tt>myRealm</tt> being a <tt>com.company.security.DatabaseRealm</tt> instance and the previous instance will never be used (and garbage collected).</p> - -<h6><a name="Configuration-DefaultSecurityManager"></a>Default SecurityManager</h6> - -<p>You may have noticed in the complete example above that the SecurityManager instance's class isn't defined, and we jumped right in to just setting a nested property:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -myRealm = ... - -securityManager.sessionManager.globalSessionTimeout = 1800000 -... -</pre> -</div></div> - -<p>This is because the <tt>securityManager</tt> instance is a special one - it is already instantiated for you and ready to go so you don't need to know the specific <tt>SecurityManager</tt> implementation class to instantiate.</p> - -<p>Of course, if you actually <em>want</em> to specify your own implementation, you can, just define your implementation as specified in the "Overriding Instances" section above:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -... -securityManager = com.company.security.shiro.MyCustomSecurityManager -... -</pre> -</div></div> - -<p>Of course, this is rarely needed - Shiro's SecurityManager implementations are very customizable and can typically be configured with anything necessary. You might want to ask yourself (or the user list) if you really need to do this.<br clear="none"> -<a href="#Configuration-users">users</a></p> -<h4><a name="Configuration-%5Cusers%5C"></a>[users]</h4> - -<p>The <tt><b>[users]</b></tt> section allows you to define a static set of user accounts. This is mostly useful in environments with a very small number of user accounts or where user accounts don't need to be created dynamically at runtime. Here's an example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[users] -admin = secret -lonestarr = vespa, goodguy, schwartz -darkhelmet = ludicrousspeed, badguy, schwartz -</pre> -</div></div> - -#info('Automatic IniRealm', 'Just defining non-empty [users] or [roles] sections will automatically trigger the creation of an <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/text/IniRealm.html">org.apache.shiro.realm.text.IniRealm</a></tt> instance and make it available in the [main] section under the name <tt><b>iniRealm</b></tt>. You can configure it like any other object as described above.') - -<h5><a name="Configuration-LineFormat"></a>Line Format</h5> - -<p>Each line in the [users] section must conform to the following format:</p> - -<p><tt>username</tt> = <tt>password</tt>, <em>roleName1</em>, <em>roleName2</em>, ..., <em>roleNameN</em></p> - -<ul><li>The value on the left of the equals sign is the username</li><li>The first value on the right of the equals sign is the user's password. A password is required.</li><li>Any comma-delimited values after the password are the names of roles assigned to that user. Role names are optional.</li></ul> - - -<h5><a name="Configuration-EncryptingPasswords"></a>Encrypting Passwords</h5> - -<p>If you don't want the [users] section passwords to be in plain-text, you can encrypt them using your favorite hash algorithm (MD5, Sha1, Sha256, etc) however you like and use the resulting string as the password value. By default, the password string is expected to be Hex encoded, but can be configured to be Base64 encoded instead (see below).</p> - -#tip('Easy Secure Passwords', 'To save time and use best-practices, you might want to use Shiro''s <a href="command-line-hasher.html" title="Command Line Hasher">Command Line Hasher</a>, which will hash passwords as well as any other type of resource. It is especially convenient for encrypting INI <tt>[users]</tt> passwords.') - -<p>Once you've specified the hashed text password values, you have to tell Shiro that these are encrypted. You do that by configuring the implicitly created <tt>iniRealm</tt> in the [main] section to use an appropriate <tt>CredentialsMatcher</tt> implementation corresponding to the hash algorithm you've specified:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] -... -sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher -... -iniRealm.credentialsMatcher = $sha256Matcher -... - -[users] -# user1 = sha256-hashed-hex-encoded password, role1, role2, ... -user1 = 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b, role1, role2, ... -</pre> -</div></div> - -<p>You can configure any properties on the <tt>CredentialsMatcher</tt> like any other object to reflect your hashing strategy, for example, to specify if salting is used or how many hash iterations to execute. See the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/HashedCredentialsMatcher.html">org.apache.shiro.authc.credential.HashedCredentialsMatcher</a></tt> JavaDoc to better understand hashing strategies and if they might be useful to you. </p> - -<p>For example, if your users' password strings were Base64 encoded instead of the default Hex, you could specify:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] -... -# <span class="code-keyword">true</span> = hex, <span class="code-keyword">false</span> = base64: -sha256Matcher.storedCredentialsHexEncoded = <span class="code-keyword">false</span> -</pre> -</div></div> - -<h4><a name="Configuration-%5Croles%5C"></a>[roles]</h4> - -<p>The <tt><b>[roles]</b></tt> section allows you to associate <a href="permissions.html" title="Permissions">Permissions</a> with the roles defined in the [users] section. Again, this is useful in environments with a small number of roles or where roles don't need to be created dynamically at runtime. Here's an example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[roles] -# 'admin' role has all permissions, indicated by the wildcard '*' -admin = * -# The 'schwartz' role can <span class="code-keyword">do</span> anything (*) with any lightsaber: -schwartz = lightsaber:* -# The 'goodguy' role is allowed to 'drive' (action) the winnebago (type) with -# license plate 'eagle5' (instance specific id) -goodguy = winnebago:drive:eagle5 -</pre> -</div></div> - -<h5><a name="Configuration-LineFormat"></a>Line Format</h5> - -<p>Each line in the [roles] section must must define a role-to-permission(s) key/value mapping with in the following format:</p> - -<p><tt>rolename</tt> = <em>permissionDefinition1</em>, <em>permissionDefinition2</em>, ..., <em>permissionDefinitionN</em></p> - -<p>where <em>permissionDefinition</em> is an arbitrary String, but most people will want to use strings that conform<br clear="none"> -to the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authz/permission/WildcardPermission.html">org.apache.shiro.authz.permission.WildcardPermission</a></tt> format for ease of use and flexibility. See the <a href="permissions.html" title="Permissions">Permissions</a> documentation for more information on Permissions and how you can benefit from them. </p> - -#info('Internal commas', 'Note that if an individual <em>permissionDefinition</em> needs to be internally comma-delimited (e.g. <tt>printer:5thFloor:print,info</tt>), you will need to surround that definition with double quotes (") to avoid parsing errors:<br clear="none"><tt>"printer:5thFloor:print,info"</tt>') - -#tip('Roles without Permissions', 'If you have roles that don''t require permission associations, you don''t need to list them in the [roles] section if you don''t want to. Just defining the role names in the [users] section is enough to create the role if it does not exist yet.') - -<h4><a name="Configuration-%5Curls%5C"></a>[urls]</h4> - -<p>This section and its options is described in the <a href="web.html" title="Web">Web</a> chapter.</p> - -<h2><a name="Configuration-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2> - -<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p> - -<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/"; rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p> \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/shiro-site/blob/a2ce402a/configuration.md.vtl ---------------------------------------------------------------------- diff --git a/configuration.md.vtl b/configuration.md.vtl new file mode 100644 index 0000000..f7408a8 --- /dev/null +++ b/configuration.md.vtl @@ -0,0 +1,497 @@ +<a name="Configuration-ApacheShiroConfiguration"></a> +Apache Shiro Configuration +========================== + +* [Programmatic Configuration](#Configuration-ProgrammaticConfiguration) + + * [SecurityManager Object Graph](#Configuration-SecurityManagerObjectGraph) + +* [INI Configuration](#Configuration-INIConfiguration) + + * [Creating a SecurityManager from INI](#Configuration-CreatingaSecurityManagerfromINI) + + * [SecurityManager from an INI resource](#Configuration-SecurityManagerfromanINIresource) + * [SecurityManager from an INI instance](#Configuration-SecurityManagerfromanINIinstance) + + * [INI Sections](#Configuration-INISections) + + * [`[main]`](#Configuration-%5Cmain%5C) + + * [Defining an object](#Configuration-Defininganobject) + * [Setting object properties](#Configuration-Settingobjectproperties) + + * [Primitive Values](#Configuration-PrimitiveValues) + * [Reference Values](#Configuration-ReferenceValues) + * [Nested Properties](#Configuration-NestedProperties) + * [Byte Array Values](#Configuration-ByteArrayValues) + * [Collection Properties](#Configuration-CollectionProperties) + + * [Considerations](#Configuration-Considerations) + + * [Order Matters](#Configuration-OrderMatters) + * [Overriding Instances](#Configuration-OverridingInstances) + * [Default SecurityManager](#Configuration-DefaultSecurityManager) + + * [`[users]`](#Configuration-%5Cusers%5C) + + * [Line Format](#Configuration-LineFormat) + * [Encrypting Passwords](#Configuration-EncryptingPasswords) + + * [`[roles]`](#Configuration-%5Croles%5C) + + * [Line Format](#Configuration-LineFormat) + + * [`[urls]`](#Configuration-%5Curls%5C) + +* [Lend a hand with documentation](#Configuration-Lendahandwithdocumentation) + +Shiro is designed to work in any environment, from simple command-line applications to the largest enterprise clustered applications. Because of this diversity of environments, there are a number of configuration mechanisms that are suitable for configuration. This section covers the configuration mechanisms that are supported by Shiro core only. + +#tip('Many Configuration Options', 'Shiro''s <code>SecurityManager</code> implementations and all supporting components are all JavaBeans compatible. This allows Shiro to be configured with practically any configuration format such as regular Java, XML (Spring, JBoss, Guice, etc), <a class="external-link" href="http://www.yaml.org/"; rel="nofollow">YAML</a>, JSON, Groovy Builder markup, and more.') + +<a name="Configuration-ProgrammaticConfiguration"></a> +Programmatic Configuration +-------------------------- + +The absolute simplest way to create a SecurityManager and make it available to the application is to create an `org.apache.shiro.mgt.DefaultSecurityManager` and wire it up in code. For example: + +``` java +Realm realm = //instantiate or acquire a Realm instance. We'll discuss Realms later. +SecurityManager securityManager = new DefaultSecurityManager(realm); + +//Make the SecurityManager instance available to the entire application via static memory: +SecurityUtils.setSecurityManager(securityManager); +``` + +Surprisingly, after only 3 lines of code, you now have a fully functional Shiro environment suitable for many applications. How easy was that!? + +<a name="Configuration-SecurityManagerObjectGraph"></a> +#[[###SecurityManager Object Graph]]# + +As discussed in the [Architecture](architecture.html "Architecture") chapter, Shiro's `SecurityManager` implementations are essentially a modular object graph of nested security-specific components. Because they are also JavaBeans-compatible, you can call any of the nested components `getter` and `setter` methods to configure the `SecurityManager` and its internal object graph. + +For example, if you wanted to configure the `SecurityManager` instance to use a custom `SessionDAO` to customize [Session Management](session-management.html "Session Management"), you could set the `SessionDAO` directly with the nested SessionManager's `setSessionDAO` method: + +``` java +... + +DefaultSecurityManager securityManager = new DefaultSecurityManager(realm); + +SessionDAO sessionDAO = new CustomSessionDAO(); + +((DefaultSessionManager)securityManager.getSessionManager()).setSessionDAO(sessionDAO); +... +``` + +Using direct method invocations, you can configure any part of the `SecurityManager`'s object graph. + +But, as simple as programmatic customization is, it does not represent the ideal configuration for most real world applications. There are a few reasons why programmatic configuration may not be suitable for your application: + +* It requires you to know about and instantiate a direct implementation. It would be nicer if you didn't have to know about concrete implementations and where to find them. + +* Because of Java's type-safe nature, you're required to cast objects obtained via `get*` methods to their specific implementation. So much casting is ugly, verbose, and tightly-couples you to implementation classes. + +* The `SecurityUtils.setSecurityManager` method call makes the instantiated `SecurityManager` instance a VM static singleton, which, while fine for many applications, would cause problems if more than one Shiro-enabled application was running on the same JVM. It could be better if the instance was an application singleton, but not a static memory reference. + +* It requires you to recompile your application every time you want to make a Shiro configuration change. + +However, even with these caveats, the direct programmatic manipulation approach could still be valuable in memory-constrained environments, like smart-phone applications. If your application does not run in a memory-constrained environment, you'll find text-based configuration to be easier to use and read. + +<a name="Configuration-INIConfiguration"></a> +INI Configuration +----------------- + +Most applications instead benefit from text-based configuration that could be modified independently of source code and even make things easier to understand for those not intimately familiar with Shiro's APIs. + +To ensure a common-denominator text-based configuration mechanism that can work in all environments with minimal 3rd party dependencies, Shiro supports the [INI format](https://en.wikipedia.org/wiki/INI_file) to build the `SecurityManager` object graph and its supporting components. INI is easy to read, easy to configure, and is simple to set-up and suits most applications well. + +<a name="Configuration-CreatingaSecurityManagerfromINI"></a> +#[[###Creating a SecurityManager from INI]]# + +Here are two examples of how to build a SecurityManager based on INI configuration. + +<a name="Configuration-SecurityManagerfromanINIresource"></a> +#[[####SecurityManager from an INI resource]]# + +We can create the SecurityManager instance from an INI resource path. Resources can be acquired from the file system, classpath, or URLs when prefixed with `file:`, `classpath:`, or `url:` respectively. This example uses a `Factory` to ingest a `shiro.ini` file from the root of the classpath and return the `SecurityManager` instance: + +``` java +import org.apache.shiro.SecurityUtils; +import org.apache.shiro.util.Factory; +import org.apache.shiro.mgt.SecurityManager; +import org.apache.shiro.config.IniSecurityManagerFactory; + +... + +Factory<SecurityManager> factory = new IniSecurityManagerFactory("classpath:shiro.ini"); +SecurityManager securityManager = factory.getInstance(); +SecurityUtils.setSecurityManager(securityManager); +``` + +<a name="Configuration-SecurityManagerfromanINIinstance"></a> +#[[####SecurityManager from an INI instance]]# + +The INI configuration can be constructed programmatically as well if desired via the [`org.apache.shiro.config.Ini`](static/current/apidocs/org/apache/shiro/config/Ini.html) class. The Ini class functions similarly to the JDK [`java.util.Properties`](http://download.oracle.com/javase/6/docs/api/java/util/Properties.html) class, but additionally supports segmentation by section name. + +For example: + +``` java +import org.apache.shiro.SecurityUtils; +import org.apache.shiro.util.Factory; +import org.apache.shiro.mgt.SecurityManager; +import org.apache.shiro.config.Ini; +import org.apache.shiro.config.IniSecurityManagerFactory; + +... + +Ini ini = new Ini(); +//populate the Ini instance as necessary +... +Factory<SecurityManager> factory = new IniSecurityManagerFactory(ini); +SecurityManager securityManager = factory.getInstance(); +SecurityUtils.setSecurityManager(securityManager); +``` + +Now that we know how to construct a `SecurityManager` from INI configuration, let's take a look at exactly how to define a Shiro INI configuration. + +<a name="Configuration-INISections"></a> +#[[###INI Sections]]# + +INI is basically a text configuration consisting of key/value pairs organized by uniquely-named sections. Keys are unique per section only, not over the entire configuration (unlike the JDK [Properties](http://java.sun.com/javase/6/docs/api/java/util/Properties.html)). Each section may be viewed like a single `Properties` definition however. + +Commented lines can start with either with an Octothorpe (# - aka the 'hash', 'pound' or 'number' sign) or a Semi-colon (';') + +Here is an example of the sections understood by Shiro: + +``` ini +# ======================= +# Shiro INI configuration +# ======================= + +[main] +# Objects and their properties are defined here, +# Such as the securityManager, Realms and anything +# else needed to build the SecurityManager + +[users] +# The 'users' section is for simple deployments +# when you only need a small number of statically-defined +# set of User accounts. + +[roles] +# The 'roles' section is for simple deployments +# when you only need a small number of statically-defined +# roles. + +[urls] +# The 'urls' section is used for url-based security +# in web applications. We'll discuss this section in the +# Web documentation +``` + +<a name="Configuration-%5Cmain%5C"></a> +#[[####[main]]]# + +The **`[main]`** section is where you configure the application's `SecurityManager` instance and any of its dependencies, such as [Realm](realm.html "Realm")s. + +Configuring object instances like the SecurityManager or any of its dependencies sounds like a difficult thing to do with INI, where we can only use name/value pairs. But through a little bit of convention and understanding of object graphs, you'll find that you can do quite a lot. Shiro uses these assumptions to enable a simple yet fairly concise configuration mechanism. + +We often like to refer to this approach as "poor man's" Dependency Injection, and although not as powerful as full-blown Spring/Guice/JBoss XML files, you'll find it gets quite a lot done without much complexity. Of course those other configuration mechanism are available as well, but they're not required to use Shiro. + +Just to whet your appetite, here is an example of a valid `[main]` configuration. We'll cover it in detail below, but you might find that you understand quite a bit of what is going on already by intuition alone: + +``` ini +[main] +sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher + +myRealm = com.company.security.shiro.DatabaseRealm +myRealm.connectionTimeout = 30000 +myRealm.username = jsmith +myRealm.password = secret +myRealm.credentialsMatcher = $sha256Matcher + +securityManager.sessionManager.globalSessionTimeout = 1800000 +``` + +<a name="Configuration-Defininganobject"></a> +#[[#####Defining an object]]# + +Consider the following `[main]` section snippet: + +``` ini +[main] +myRealm = com.company.shiro.realm.MyRealm +... +``` + +This line instantiates a new object instance of type `com.company.shiro.realm.MyRealm` and makes that object available under the **myRealm** name for further reference and configuration. + +If the object instantiated implements the `org.apache.shiro.util.Nameable` interface, then the the `Nameable.setName` method will be invoked on the object with the name value ( **`myRealm`** in this example). + +<a name="Configuration-Settingobjectproperties"></a> +#[[#####Setting object properties]]# + +<a name="Configuration-PrimitiveValues"></a> +#[[######Primitive Values]]# + +Simple primitive properties can be assigned just by using the equals sign: + +``` ini +... +myRealm.connectionTimeout = 30000 +myRealm.username = jsmith +... +``` + +these lines of configuration translate into method calls: + +``` ini +... +myRealm.setConnectionTimeout(30000); +myRealm.setUsername("jsmith"); +... +``` + +How is this possible? It assumes that all objects are [Java Beans](https://en.wikipedia.org/wiki/JavaBean)-compatible [POJO](https://en.wikipedia.org/wiki/Plain_Old_Java_Object)s. + +Under the covers, Shiro by default uses Apache Commons [BeanUtils](http://commons.apache.org/proper/commons-beanutils/) to do all the heavy lifting when setting these properties. So although INI values are text, BeanUtils knows how to convert the string values to the proper primitive types and then invoke the corresponding JavaBeans setter method. + +<a name="Configuration-ReferenceValues"></a> +#[[######Reference Values]]# + +What if the value you need to set is not a primitive, but another object? Well, you can use a dollar sign ($) to reference a previously-defined instance. For example: + +``` java +... +sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher +... +myRealm.credentialsMatcher = $sha256Matcher +... +``` + +This simply locates the object defined by the name **sha256Matcher** and then uses BeanUtils to set that object on the **myRealm** instance (by calling the `myRealm.setCredentialsMatcher(sha256Matcher)` method). + +<a name="Configuration-NestedProperties"></a> +#[[######Nested Properties]]# + +Using dotted notation on the left side of the INI line's equals sign, you can traverse an object graph to get to the final object/property that you want set. For example, this config line: + +``` java +... +securityManager.sessionManager.globalSessionTimeout = 1800000 +... +``` + +Translates (by BeanUtils) into the following logic: + +``` java +securityManager.getSessionManager().setGlobalSessionTimeout(1800000); +``` + +The graph traversal can be as deep as necessary: `object.property1.property2....propertyN.value = blah` + +#tip('BeanUtils Property Support', 'Any property assignment operation supported by the BeanUtils.<a class="external-link" href="https://commons.apache.org/proper/commons-beanutils/apidocs/org/apache/commons/beanutils/BeanUtils.html#setProperty-java.lang.Object-java.lang.String-java.lang.Object-";>setProperty</a> method will work in Shiro''s [main] section, including set/list/map element assignments. See the <a class="external-link" href="http://commons.apache.org/proper/commons-beanutils/";>Apache Commons BeanUtils Website</a> and documentation for more information.') + +<a name="Configuration-ByteArrayValues"></a> +#[[######Byte Array Values]]# + +Because raw byte arrays can't be specified natively in a text format, we must use a text encoding of the byte array. The values can be specified either as a Base64 encoded string (the default) or as a Hex encoded string. The default is Base64 because Base64 encoding requires less actual text to represent values - it has a larger encoding alphabet, meaning your tokens are shorter (a bit nicer for text config). + +``` ini +# The 'cipherKey' attribute is a byte array. By default, text values +# for all byte array properties are expected to be Base64 encoded: + +securityManager.rememberMeManager.cipherKey = kPH+bIxk5D2deZiIxcaaaA== +... +``` + +However, if you prefer to use Hex encoding instead, you must prefix the String token with `0x` ('zero' 'x'): + +``` ini +securityManager.rememberMeManager.cipherKey = 0x3707344A4093822299F31D008 +``` + +<a name="Configuration-CollectionProperties"></a> +#[[######Collection Properties]]# + +Lists, Sets and Maps can be set like any other property - either directly or as a nested property. For sets and lists, just specify a comma-delimited set of values or object references. + +For example, some SessionListeners: + +``` ini +sessionListener1 = com.company.my.SessionListenerImplementation +... +sessionListener2 = com.company.my.other.SessionListenerImplementation +... +securityManager.sessionManager.sessionListeners = $sessionListener1, $sessionListener2 +``` + +For Maps, you specify a comma-delimited list of key-value pairs, where each key-value pair is delimited by a colon ':' + +``` ini +object1 = com.company.some.Class +object2 = com.company.another.Class +... +anObject = some.class.with.a.Map.property + +anObject.mapProperty = key1:$object1, key2:$object2 +``` + +In the above example, the object referenced by `$object1` will be in the map under the String key `key1`, i.e. `map.get("key1")` returns `object1`. You can also use other objects as the keys: + +``` ini +anObject.map = $objectKey1:$objectValue1, $objectKey2:$objectValue2 +... +``` + +<a name="Configuration-Considerations"></a> +#[[#####Considerations]]# + +<a name="Configuration-OrderMatters"></a> +#[[######Order Matters]]# + +The INI format and conventions above are very convenient and easy to understand, but it is not as powerful as other text/XML-based configuration mechanisms. The most important thing to understand when using the above mechanism is that **Order Matters!** + +#warning('Be Careful', 'Each object instantiation and each value assignment is executed <em>in the order they occur in the [main] section</em>. These lines ultimately translate to a JavaBeans getter/setter method invocation, and so those methods are invoked in the same order! +<p>Keep this in mind when writing your configuration.</p>') + +<a name="Configuration-OverridingInstances"></a> +#[[######Overriding Instances]]# + +Any object can be overridden by a new instance defined later in the configuration. So for example, the 2nd `myRealm` definition would overwrite the first: + +``` ini +... +myRealm = com.company.security.MyRealm +... +myRealm = com.company.security.DatabaseRealm +... +``` + +This would result in `myRealm` being a `com.company.security.DatabaseRealm` instance and the previous instance will never be used (and garbage collected). + +<a name="Configuration-DefaultSecurityManager"></a> +#[[######Default SecurityManager]]# + +You may have noticed in the complete example above that the SecurityManager instance's class isn't defined, and we jumped right in to just setting a nested property: + +``` ini +myRealm = ... + +securityManager.sessionManager.globalSessionTimeout = 1800000 +... +``` + +This is because the `securityManager` instance is a special one - it is already instantiated for you and ready to go so you don't need to know the specific `SecurityManager` implementation class to instantiate. + +Of course, if you actually _want_ to specify your own implementation, you can, just define your implementation as specified in the "Overriding Instances" section above: + +``` ini +... +securityManager = com.company.security.shiro.MyCustomSecurityManager +... +``` + +Of course, this is rarely needed - Shiro's SecurityManager implementations are very customizable and can typically be configured with anything necessary. You might want to ask yourself (or the user list) if you really need to do this. +[users](#Configuration-users) + +<a name="Configuration-%5Cusers%5C"></a> +#[[####[users]]]# + +The **`[users]`** section allows you to define a static set of user accounts. This is mostly useful in environments with a very small number of user accounts or where user accounts don't need to be created dynamically at runtime. Here's an example: + +``` ini +[users] +admin = secret +lonestarr = vespa, goodguy, schwartz +darkhelmet = ludicrousspeed, badguy, schwartz +``` + +#info('Automatic IniRealm', 'Just defining non-empty [users] or [roles] sections will automatically trigger the creation of an <a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/text/IniRealm.html"><code>org.apache.shiro.realm.text.IniRealm</code></a> instance and make it available in the [main] section under the name <b><code>iniRealm</code></b>. You can configure it like any other object as described above.') + +<a name="Configuration-LineFormat"></a> +#[[#####Line Format]]# + +Each line in the [users] section must conform to the following format: + +`username` = `password`, _roleName1_, _roleName2_, ..., _roleNameN_ + +* The value on the left of the equals sign is the username +* The first value on the right of the equals sign is the user's password. A password is required. +* Any comma-delimited values after the password are the names of roles assigned to that user. Role names are optional. + +<a name="Configuration-EncryptingPasswords"></a> +#[[#####Encrypting Passwords]]# + +If you don't want the [users] section passwords to be in plain-text, you can encrypt them using your favorite hash algorithm (MD5, Sha1, Sha256, etc) however you like and use the resulting string as the password value. By default, the password string is expected to be Hex encoded, but can be configured to be Base64 encoded instead (see below). + +#tip('Easy Secure Passwords', 'To save time and use best-practices, you might want to use Shiro''s <a href="command-line-hasher.html" title="Command Line Hasher">Command Line Hasher</a>, which will hash passwords as well as any other type of resource. It is especially convenient for encrypting INI <code>[users]</code> passwords.') + +Once you've specified the hashed text password values, you have to tell Shiro that these are encrypted. You do that by configuring the implicitly created `iniRealm` in the [main] section to use an appropriate `CredentialsMatcher` implementation corresponding to the hash algorithm you've specified: + +``` ini +[main] +... +sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher +... +iniRealm.credentialsMatcher = $sha256Matcher +... + +[users] +# user1 = sha256-hashed-hex-encoded password, role1, role2, ... +user1 = 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b, role1, role2, ... +``` + +You can configure any properties on the `CredentialsMatcher` like any other object to reflect your hashing strategy, for example, to specify if salting is used or how many hash iterations to execute. See the [`org.apache.shiro.authc.credential.HashedCredentialsMatcher`](static/current/apidocs/org/apache/shiro/authc/credential/HashedCredentialsMatcher.html) JavaDoc to better understand hashing strategies and if they might be useful to you. + +For example, if your users' password strings were Base64 encoded instead of the default Hex, you could specify: + +``` ini +[main] +... +# true = hex, false = base64: +sha256Matcher.storedCredentialsHexEncoded = false +``` + +<a name="Configuration-%5Croles%5C"></a> +#[[####[roles]]]# + +The `**[roles]**` section allows you to associate [Permissions](permissions.html "Permissions") with the roles defined in the [users] section. Again, this is useful in environments with a small number of roles or where roles don't need to be created dynamically at runtime. Here's an example: + +``` ini +[roles] +# 'admin' role has all permissions, indicated by the wildcard '*' +admin = * +# The 'schwartz' role can do anything (*) with any lightsaber: +schwartz = lightsaber:* +# The 'goodguy' role is allowed to 'drive' (action) the winnebago (type) with +# license plate 'eagle5' (instance specific id) +goodguy = winnebago:drive:eagle5 +``` + +<a name="Configuration-LineFormat"></a> +#[[#####Line Format]]# + +Each line in the [roles] section must must define a role-to-permission(s) key/value mapping with in the following format: + +`rolename` = _permissionDefinition1_, _permissionDefinition2_, ..., _permissionDefinitionN_ + +where _permissionDefinition_ is an arbitrary String, but most people will want to use strings that conform +to the [`org.apache.shiro.authz.permission.WildcardPermission`](static/current/apidocs/org/apache/shiro/authz/permission/WildcardPermission.html) format for ease of use and flexibility. See the [Permissions](permissions.html "Permissions") documentation for more information on Permissions and how you can benefit from them. + +#info('Internal commas', 'Note that if an individual <em>permissionDefinition</em> needs to be internally comma-delimited (e.g. <code>printer:5thFloor:print,info</code>), you will need to surround that definition with double quotes (") to avoid parsing errors:<code>"printer:5thFloor:print,info"</code>') + +#tip('Roles without Permissions', 'If you have roles that don''t require permission associations, you don''t need to list them in the [roles] section if you don''t want to. Just defining the role names in the [users] section is enough to create the role if it does not exist yet.') + +<a name="Configuration-%5Curls%5C"></a> +#[[####[urls]]]# + +This section and its options is described in the [Web](web.html "Web") chapter. + +<a name="Configuration-Lendahandwithdocumentation"></a> +Lend a hand with documentation +------------------------------ + +While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. + +The easiest way to contribute your documentation is to send it to the [User Forum](http://shiro-user.582556.n2.nabble.com/) or the [User Mailing List](mailing-lists.html "Mailing Lists"). \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/a2ce402a/guice.html.vtl ---------------------------------------------------------------------- diff --git a/guice.html.vtl b/guice.html.vtl deleted file mode 100644 index e20f51b..0000000 --- a/guice.html.vtl +++ /dev/null @@ -1,184 +0,0 @@ -<h1><a name="Guice-IntegratingApacheShirointoGuicebasedApplication"></a>Integrating Apache Shiro into Guice based Application</h1> - -<p>Shiro <a class="external-link" href="https://github.com/google/guice"; rel="nofollow">Guice</a> integration was added in Shiro 1.2. This page covers the ways to integrate Shiro into Guice-based applications using standard Guice conventions and mechanisms. Prior to reading this integration document, you should be a least somewhat familiar with Guice.</p> - -<h2><a name="Guice-Overview"></a>Overview</h2> - -<p>shiro-guice provides three Guice modules that can be included in your application.</p> - -<ul><li>ShiroModule - <ul><li>Provides basic integration for setting up the <tt>SecurityManager</tt>, any <tt>Realms</tt>, and any other Shiro configuration.</li><li>This module is used by extending it and adding your own custom configuration.</li></ul> - </li></ul> - - -<ul><li>ShiroWebModule - <ul><li>Extension of <tt>ShiroModule</tt> that sets up the web environment and also allows for filter chain configuration. This uses the <a class="external-link" href="https://github.com/google/guice/wiki/ServletModule"; rel="nofollow">Guice Servlet Module</a> to configure the filters, and so requires that to be setup.</li><li>Like the <tt>ShiroModule</tt>, this module is used by extending it and adding your own custom configuration.</li></ul> - </li></ul> - - -<ul><li>ShiroAopModule - <ul><li>Uses <a class="external-link" href="https://github.com/google/guice/wiki/AOP"; rel="nofollow">Guice AOP</a> to implement the Shiro AOP annotations. This module is primarily concerned with adapting Shiro <tt>AnnotationMethodInterceptors</tt> to the Guice method interceptor model.</li><li>This module is typically used by simply installing it. However, if you have your own <tt>AnnotationMethodInterceptors</tt> written for Shiro, they can be easily incorporated by extending it.</li></ul> - </li></ul> - - -<h2><a name="Guice-GettingStarted"></a>Getting Started</h2> - -<p>The most simple configuration is to extend <tt>ShiroModule</tt> to install your own <tt>Realm</tt>. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - class MyShiroModule <span class="code-keyword">extends</span> ShiroModule { - <span class="code-keyword">protected</span> void configureShiro() { - <span class="code-keyword">try</span> { - bindRealm().toConstructor(IniRealm.class.getConstructor(Ini.class)); - } <span class="code-keyword">catch</span> (NoSuchMethodException e) { - addError(e); - } - } - - @Provides - Ini loadShiroIni() { - <span class="code-keyword">return</span> Ini.fromResourcePath(<span class="code-quote">"classpath:shiro.ini"</span>); - } - } -</pre> -</div></div> - -<p>In this case, user and role configuration would go in the <tt>shiro.ini</tt> file.</p> - -#warning('shiro.ini usage in Guice', 'It is important to note that, in this above configuration, only the <tt>users</tt> and <tt>roles</tt> sections from the ini file are used.') - -<p>Then, the module is used to create a Guice injector, and the injector is used to obtain a <tt>SecurityManager</tt>. The following example serves the same purpose as the first three lines in the <a class="external-link" href="10-minute-tutorial.html#10MinuteTutorial-Quickstart.java">Quickstart</a> example.</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - Injector injector = Guice.createInjector(<span class="code-keyword">new</span> MyShiroModule()); - <span class="code-object">SecurityManager</span> securityManager = injector.getInstance(<span class="code-object">SecurityManager</span>.class); - SecurityUtils.setSecurityManager(securityManager); -</pre> -</div></div> - -<h2><a name="Guice-AOP"></a>AOP</h2> - -<p>Shiro includes several annotations and method interceptors useful for performing authorization via AOP. It also provides a simple API for writing Shiro-specific method interceptors. shiro-guice supports this with the <tt>ShiroAopModule</tt>.</p> - -<p>To use it, simply instantiate and install the module alongside your application module and your <tt>ShiroModule</tt>. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - Injector injector = Guice.createInjector(<span class="code-keyword">new</span> MyShiroModule(), <span class="code-keyword">new</span> ShiroAopModule(), <span class="code-keyword">new</span> MyApplicationModule()); -</pre> -</div></div> - -<p>If you have written custom interceptors that conform to Shiro's api, you may find it useful to extend the <tt>ShiroAopModule</tt>. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - class MyShiroAopModule <span class="code-keyword">extends</span> ShiroAopModule { - <span class="code-keyword">protected</span> void configureInterceptors(AnnotationResolver resolver) - { - bindShiroInterceptor(<span class="code-keyword">new</span> MyCustomAnnotationMethodInterceptor(resolver)); - } - } -</pre> -</div></div> - -<h2><a name="Guice-Web"></a>Web</h2> - -<p>shiro-guice's web integration is designed to integrate Shiro and its filter paradigm with Guice's servlet module. If you are using Shiro in a web environment, and using Guice's servlet module, then you should extend ShiroWebModule rather than ShiroModule. Your web.xml should be setup exactly as Guice's servlet module recommends.</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - class MyShiroWebModule <span class="code-keyword">extends</span> ShiroWebModule { - MyShiroWebModule(ServletContext sc) { - <span class="code-keyword">super</span>(sc); - } - - <span class="code-keyword">protected</span> void configureShiroWeb() { - <span class="code-keyword">try</span> { - bindRealm().toConstructor(IniRealm.class.getConstructor(Ini.class)); - } <span class="code-keyword">catch</span> (NoSuchMethodException e) { - addError(e); - } - - addFilterChain(<span class="code-quote">"/<span class="code-keyword">public</span>/**"</span>, ANON); - addFilterChain(<span class="code-quote">"/stuff/allowed/**"</span>, AUTHC_BASIC, config(PERMS, <span class="code-quote">"yes"</span>)); - addFilterChain(<span class="code-quote">"/stuff/forbidden/**"</span>, AUTHC_BASIC, config(PERMS, <span class="code-quote">"no"</span>)); - addFilterChain(<span class="code-quote">"/**"</span>, AUTHC_BASIC); - } - - @Provides - Ini loadShiroIni() { - <span class="code-keyword">return</span> Ini.fromResourcePath(<span class="code-quote">"classpath:shiro.ini"</span>); - } - } -</pre> -</div></div> - -<p>In the previous code, we have bound an <tt>IniRealm</tt> and setup four filter chains. These chains would be equivalent to the following ini configuration. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - [urls] - /<span class="code-keyword">public</span>/** = anon - /stuff/allowed/** = authcBasic, perms[<span class="code-quote">"yes"</span>] - /stuff/forbidden/** = authcBasic, perms[<span class="code-quote">"no"</span>] - /** = authcBasic -</pre> -</div></div> - -<p>In shiro-guice, the filter names are Guice keys. All of the default Shiro filters are available as constants, but you are not limited to those. In order to use a custom filter in a filter chain, you would do </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - Key customFilter = Key.get(MyCustomFilter.class); - - addFilterChain(<span class="code-quote">"/custom/**"</span>, customFilter); -</pre> -</div></div> - -<p>We still have to tell guice-servlets about our Shiro filter. Since the <tt>ShiroWebModule</tt> is private, and guice-servlets does not give us a way to expose a filter mapping, we have to bind it manually. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - ShiroWebModule.guiceFilterModule() -</pre> -</div></div> - -<p>Or, from within an application module, </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - ShiroWebModule.bindGuiceFilter(binder()) -</pre> -</div></div> - -<h2><a name="Guice-Properties"></a>Properties</h2> - -<p>A number of Shiro classes expose configuration parameters via setter methods. shiro-guice will inject these if it finds a binding for <tt>@Named("shiro.{propName}")</tt>. For instance, to set the session timeout, you could do the following. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - bindConstant().annotatedWith(Names.named(<span class="code-quote">"shiro.globalSessionTimeout"</span>)).to(30000L); -</pre> -</div></div> - -<p>If this paradigm doesn't work for you, you may also consider using a provider to instantiate the object and invoking the setters directly.</p> - -<h2><a name="Guice-InjectionofShiroObjects"></a>Injection of Shiro Objects</h2> - -<p>shiro-guice uses a Guice <tt>TypeListener</tt> to perform injection on native Shiro classes (any class in a subdirectory of <tt>org.apache.shiro</tt> but not <tt>org.apache.shiro.guice</tt>). However, Guice only considers explicitly bound types as candidates for <tt>TypeListeners</tt>, so if you have a Shiro object that you want injected, you have to declare it explicitly. For instance, to set the <tt>CredentialsMatcher</tt> for a realm, we would need to add the following bindings:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - bind(CredentialsMatcher.class).to(HashedCredentialsMatcher.class); - bind(HashedCredentialsMatcher.class); - bindConstant().annotatedWith(Names.named(<span class="code-quote">"shiro.hashAlgorithmName"</span>)).to(Md5Hash.ALGORITHM_NAME); -</pre> -</div></div> - -<h2><a name="Guice-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2> - -<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p> - -<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/"; rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/a2ce402a/guice.md.vtl ---------------------------------------------------------------------- diff --git a/guice.md.vtl b/guice.md.vtl new file mode 100644 index 0000000..8075376 --- /dev/null +++ b/guice.md.vtl @@ -0,0 +1,175 @@ +<a name="Guice-IntegratingApacheShirointoGuicebasedApplication"></a> +Integrating Apache Shiro into Guice based Application +===================================================== + +Shiro [Guice](https://github.com/google/guice) integration was added in Shiro 1.2\. This page covers the ways to integrate Shiro into Guice-based applications using standard Guice conventions and mechanisms. Prior to reading this integration document, you should be a least somewhat familiar with Guice. + +<a name="Guice-Overview"></a> +Overview +-------- + +shiro-guice provides three Guice modules that can be included in your application. + +* ShiroModule + * Provides basic integration for setting up the `SecurityManager`, any `Realms`, and any other Shiro configuration. + * This module is used by extending it and adding your own custom configuration. + +* ShiroWebModule + * Extension of `ShiroModule` that sets up the web environment and also allows for filter chain configuration. This uses the [Guice Servlet Module](https://github.com/google/guice/wiki/ServletModule) to configure the filters, and so requires that to be setup. + * Like the `ShiroModule`, this module is used by extending it and adding your own custom configuration. + +* ShiroAopModule + * Uses [Guice AOP](https://github.com/google/guice/wiki/AOP) to implement the Shiro AOP annotations. This module is primarily concerned with adapting Shiro `AnnotationMethodInterceptors` to the Guice method interceptor model. + * This module is typically used by simply installing it. However, if you have your own `AnnotationMethodInterceptors` written for Shiro, they can be easily incorporated by extending it. + +<a name="Guice-GettingStarted"></a> +Getting Started +--------------- + +The most simple configuration is to extend `ShiroModule` to install your own `Realm`. + +``` java +class MyShiroModule extends ShiroModule { + protected void configureShiro() { + try { + bindRealm().toConstructor(IniRealm.class.getConstructor(Ini.class)); + } catch (NoSuchMethodException e) { + addError(e); + } + } + + @Provides + Ini loadShiroIni() { + return Ini.fromResourcePath("classpath:shiro.ini"); + } +} +``` + +In this case, user and role configuration would go in the `shiro.ini` file. + +#warning('shiro.ini usage in Guice', 'It is important to note that, in this above configuration, only the `users` and `roles` sections from the ini file are used.') + +Then, the module is used to create a Guice injector, and the injector is used to obtain a `SecurityManager`. The following example serves the same purpose as the first three lines in the [Quickstart](10-minute-tutorial.html#10MinuteTutorial-Quickstart.java) example. + +``` java +Injector injector = Guice.createInjector(new MyShiroModule()); +SecurityManager securityManager = injector.getInstance(SecurityManager.class); +SecurityUtils.setSecurityManager(securityManager); +``` + +<a name="Guice-AOP"></a> +AOP +--- + +Shiro includes several annotations and method interceptors useful for performing authorization via AOP. It also provides a simple API for writing Shiro-specific method interceptors. shiro-guice supports this with the `ShiroAopModule`. + +To use it, simply instantiate and install the module alongside your application module and your `ShiroModule`. + +``` java +Injector injector = Guice.createInjector(new MyShiroModule(), new ShiroAopModule(), new MyApplicationModule()); +``` + +If you have written custom interceptors that conform to Shiro's api, you may find it useful to extend the `ShiroAopModule`. + +``` java +class MyShiroAopModule extends ShiroAopModule { + protected void configureInterceptors(AnnotationResolver resolver) + { + bindShiroInterceptor(new MyCustomAnnotationMethodInterceptor(resolver)); + } +} +``` + +<a name="Guice-Web"></a> +Web +--- + +shiro-guice's web integration is designed to integrate Shiro and its filter paradigm with Guice's servlet module. If you are using Shiro in a web environment, and using Guice's servlet module, then you should extend ShiroWebModule rather than ShiroModule. Your web.xml should be setup exactly as Guice's servlet module recommends. + +``` java +class MyShiroWebModule extends ShiroWebModule { + MyShiroWebModule(ServletContext sc) { + super(sc); + } + + protected void configureShiroWeb() { + try { + bindRealm().toConstructor(IniRealm.class.getConstructor(Ini.class)); + } catch (NoSuchMethodException e) { + addError(e); + } + + addFilterChain("/public/**", ANON); + addFilterChain("/stuff/allowed/**", AUTHC_BASIC, config(PERMS, "yes")); + addFilterChain("/stuff/forbidden/**", AUTHC_BASIC, config(PERMS, "no")); + addFilterChain("/**", AUTHC_BASIC); + } + + @Provides + Ini loadShiroIni() { + return Ini.fromResourcePath("classpath:shiro.ini"); + } +} +``` + +In the previous code, we have bound an `IniRealm` and setup four filter chains. These chains would be equivalent to the following ini configuration. + +``` ini +[urls] +/public/** = anon +/stuff/allowed/** = authcBasic, perms["yes"] +/stuff/forbidden/** = authcBasic, perms["no"] +/** = authcBasic +``` + +In shiro-guice, the filter names are Guice keys. All of the default Shiro filters are available as constants, but you are not limited to those. In order to use a custom filter in a filter chain, you would do + +``` java +Key customFilter = Key.get(MyCustomFilter.class); + +addFilterChain("/custom/**", customFilter); +``` + +We still have to tell guice-servlets about our Shiro filter. Since the `ShiroWebModule` is private, and guice-servlets does not give us a way to expose a filter mapping, we have to bind it manually. + +``` java +ShiroWebModule.guiceFilterModule() +``` + +Or, from within an application module, + +``` java +ShiroWebModule.bindGuiceFilter(binder()) +``` + +<a name="Guice-Properties"></a> +Properties +---------- + +A number of Shiro classes expose configuration parameters via setter methods. shiro-guice will inject these if it finds a binding for `@Named("shiro.{propName}")`. For instance, to set the session timeout, you could do the following. + +``` java +bindConstant().annotatedWith(Names.named("shiro.globalSessionTimeout")).to(30000L); +``` + +If this paradigm doesn't work for you, you may also consider using a provider to instantiate the object and invoking the setters directly. + +<a name="Guice-InjectionofShiroObjects"></a> +Injection of Shiro Objects +-------------------------- + +shiro-guice uses a Guice `TypeListener` to perform injection on native Shiro classes (any class in a subdirectory of `org.apache.shiro` but not `org.apache.shiro.guice`). However, Guice only considers explicitly bound types as candidates for `TypeListeners`, so if you have a Shiro object that you want injected, you have to declare it explicitly. For instance, to set the `CredentialsMatcher` for a realm, we would need to add the following bindings: + +``` java +bind(CredentialsMatcher.class).to(HashedCredentialsMatcher.class); +bind(HashedCredentialsMatcher.class); +bindConstant().annotatedWith(Names.named("shiro.hashAlgorithmName")).to(Md5Hash.ALGORITHM_NAME); +``` + +<a name="Guice-Lendahandwithdocumentation"></a> +Lend a hand with documentation +------------------------------ + +While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. + +The easiest way to contribute your documentation is to send it to the [User Forum](http://shiro-user.582556.n2.nabble.com/) or the [User Mailing List](mailing-lists.html "Mailing Lists"). \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/a2ce402a/securitymanager.html.vtl ---------------------------------------------------------------------- diff --git a/securitymanager.html.vtl b/securitymanager.html.vtl deleted file mode 100644 index b98eff5..0000000 --- a/securitymanager.html.vtl +++ /dev/null @@ -1,77 +0,0 @@ -<h1><a name="SecurityManager-UnderstandingtheSecurityManagerinApacheShiro"></a>Understanding the SecurityManager in Apache Shiro</h1> - -<p>The <a class="external-link" href="static/current/apidocs/org/apache/shiro/mgt/SecurityManager.html">SecurityManager</a> lies at the heart of Shiro's architecture. While the <a href="subject.html" title="Subject">Subject</a> represents security functionality and state for a <em>single</em> application user, the <tt>SecurityManager</tt> performs security operations and manages state for <em>all</em> application users.</p> - -<p>Because Shiro's API encourages a <tt>Subject</tt>-centric programming approach, most application developers will rarely, if ever, interact with the <tt>SecurityManager</tt> directly (framework developers however might sometimes find it useful). Even so, it is still important to know how the <tt>SecurityManager</tt> functions, especially when configuring one for an application.</p> - -<h2><a name="SecurityManager-Design"></a>Design</h2> - -<p>As stated previously, the application's <tt>SecurityManager</tt> performs security operations and manages state for <em>all</em> application users. In Shiro's default <tt>SecurityManager</tt> implementations, this includes:</p> - -<ul> - <li>Authentication</li> - <li>Authorization</li> - <li>Session Management</li> - <li>Cache Management</li> - <li><a href="realm.html" title="Realm">Realm</a> coordination</li> - <li>Event propagation</li> - <li>"Remember Me" Services</li> - <li>Subject creation</li> - <li>Logout<br clear="none">and more.</li></ul> - -<p>But this is a lot of functionality to try to manage in a single component. And, making these things flexible and customizable would be very difficult if everything were lumped into a single implementation class. </p> - -<p>To simplify configuration and enable flexible configuration/pluggability, Shiro's implementations are all highly modular in design - so modular in fact, that the SecurityManager implementation (and its class-hierarchy) does not do much at all. Instead, the <tt>SecurityManager</tt> implementations mostly act as a lightweight 'container' component, delegating almost all behavior to nested/wrapped components.</p> - -<h3><a name="SecurityManager-Modularity"></a>Modularity</h3> - -<p>To simplify the <tt>SecurityManager</tt> implementation complexity and allow for pluggable behavior, the Shiro <tt>SecurityManager</tt> implementations delegate almost all logic to a nested set of modular components that actually perform the necessary functionality. While the components actually execute the logic, the <tt>SecurityManager</tt> implementation knows how and when to coordinate the components for the correct behavior.</p> - -<p>The nested components that the <tt>SecurityManager</tt> coordinates and delegates to are:</p> - -<ul> - <li>Authenticator (<tt>org.apache.shiro.authc.Authenticator</tt>)</li> - <li>Authorizer (<tt>org.apache.shiro.authz.Authorizer</tt>)</li> - <li>SessionManager (<tt>org.apache.shiro.session.mgt.SessionManager</tt>)</li> - <li><a href="cachemanager.html" title="CacheManager">CacheManager</a> (<tt>org.apache.shiro.cache.CacheManager</tt>)</li> - <li>RememberMeManager (<tt>org.apache.shiro.mgt.RememberMeManager</tt>)</li> - <li>SubjectFactory(<tt>org.apache.shiro.mgt.SubjectFactory</tt>)</li></ul> - - -<p>The <tt>SecurityManager</tt> implementations and are also JavaBeans compatible, which allows you (or a configuration mechanism) to easily customize the pluggable components via standard JavaBeans accessor/mutator methods (get*/set*). This means the Shiro's architectural modularity can translate into very easy configuration for custom behavior.</p> - -#tip('Easy Configuration', 'Because of JavaBeans compatibility, it is very easy to configure the <tt>SecurityManager</tt> with custom components via any mechanism that supports JavaBeans-style configuration, such as <a href="spring.html" title="Spring">Spring</a>, Guice, JBoss, etc.') - -<h3><a name="SecurityManager-ProgrammaticConfiguration"></a>Programmatic Configuration</h3> - -<p>The absolute simplest way to create a SecurityManager and make it available to the application is to create a <tt>org.apache.shiro.mgt.DefaultSecurityManager</tt> and wire it up in code:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Realm realm = <span class="code-comment">//instantiate or acquire a Realm instance. We'll discuss Realms later. -</span><span class="code-object">SecurityManager</span> securityManager = <span class="code-keyword">new</span> DefaultSecurityManager(realm); -<span class="code-comment">//Make the <span class="code-object">SecurityManager</span> instance available to the entire application: -</span>SecurityUtils.setSecurityManager(securityManager); -</pre> -</div></div> - -<p>Surprisingly, after only 3 lines of code, you now have a fully functional Shiro environment suitable for most applications. How easy was that!?</p> - -<p>You could additionally call any of the <tt>SecurityManager</tt> instance's setter methods with custom implementations of the nested components listed above to fully customize its behavior.</p> - -<p>But, as simple as programmatic customization is, these 3 lines of code do not represent the ideal configuration for most real world applications. There are a few reasons why programmatic configuration may not be suitable for your application:</p> - -<ol><li>It requires you to know about and instantiate a direct implementation. It would be nicer if you didn't have to know about concrete implementations and where to find them.</li><li>The <tt>SecurityUtils.setSecurityManager</tt> method call makes the instantiated <tt>SecurityManager</tt> instance a VM static singleton, which, while fine for many applications, would cause problems if more than one Shiro-enabled application was running on the same JVM. It could be better if the instance was an application singleton, but not a static memory reference.</li><li>It requires you to recompile your application every time you want to make a Shiro configuration change.</li></ol> - - -<p>Most applications instead benefit from text-based configuration that could be modified independently of source code and even make things easier to understand for those not intimately familiar with Shiro's APIs. </p> - -<h3><a name="SecurityManager-TextConfiguration"></a>Text Configuration</h3> - -<p>Shiro provides a simple INI-based <a href="configuration.html" title="Configuration">configuration</a> that can be used out of the box, but any other JavaBeans-compatible mechanism can be used as well. For example, Shiro has excellent <a href="spring.html" title="Spring">Spring support</a> too. Other similar frameworks (Guice, JBoss, etc) could also be used.</p> - -<h2><a name="SecurityManager-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2> - -<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p> - -<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/"; rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p>
