Shiro User Manual-Configuration

1. Configuration
Shiro可以运行在任何环境下，从命令行应用到企业级集群应用。由于环境的不同，配置也不同。这部分所讲述的配置，只需要Shiro的core包支持即可。Shiro的SecurityManager实现和支持的所有组件服务，都与JavaBeans兼容，因此，可以通过任何形式配置，如Java，XML，YAML，JSON，Groovy，Builder Markup等。

2. Programmatic Configuration
创建SecurityManager最简单的方式就是实例化org.apache.shiro.mgt.DefaultSecurityManager：

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);

简单的几行代码，就可以让Shiro支持大部分的应用。

2.1 SecurityManager Object Graph
Shiro的SecurityManager实现本质上是一个嵌套的安全组件的模块化对象图。由于JavaBeans的兼容性，可以通过getter和setter方法调用嵌套的组件，以达到配置SecurityManager的目的。例如，如果想自定义Session Management(session管理)，可通过配置SecurityManager的SessionDAO：

...

DefaultSecurityManager securityManager = new DefaultSecurityManager(realm);

SessionDAO sessionDAO = new CustomSessionDAO();

((DefaultSessionManager)securityManager.getSessionManager()).setSessionDAO(sessionDAO);
...

使用这种直接的方法调用，可以对SecurityManager进行任何配置。虽然这种方式很简单，但是它并不能满足真实的应用需求。

3. INI Configuration
很多应用通过文本式方式，使配置即脱离了源代码的依赖，又简单易懂，更不需要熟悉相关的API。Shiro通过文本式INI文件,对SecurityManager和其组件进行配置。INI易读，易配置，且适用于很多应用。

3.1 Creating a SecurityManager from INI
  下面两个例子演示了如何通过INI文件配置SecurityManager。
  a. SecurityManager from an INI resource(INI资源式)
   使用INI文件配置SecurityManager，INI文件存放路劲可以是文件系统，类路径或URL，对应的资源前缀为：file, classpath, url。以下是使用工厂式加载存在根路径下的INI文件：

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);

b. SecurityManager from an INI instance
还可以使用org.apache.shiro.config.Ini类进行编程式配置，org.apache.shiro.config.Ini类和java.util.Properties功能类似，只不过添加了模块化配置的支持：

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);

c. INI Sections
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

[main]
这部分用于配置SecurityManager和其依赖部分，比如Realms。下面是一个有效的配置样例：

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

1. Defining an object(定义一个对象)

[main]
myRealm = com.company.shiro.realm.MyRealm

这一行定义，就实例化了以myRealm为键的com.company.shiro.realm.MyRealm对象，其他地方就可以通过myRealm引用这个实例。如果com.company.shiro.realm.MyRealm实现了org.apache.shiro.util.Nameable接口，MyRealm实例就会通过Nameable的setName获取myRealm键。

2. Setting object properties(设置对象属性)
  a. Primitive Values(原始类型)
直接使用等号=赋值：

myRealm.connectionTimeout = 30000
myRealm.username = jsmith

使用方法调用的方式：

myRealm.setConnectionTimeout(30000);
myRealm.setUsername("jsmith");

Shiro使用Apache Commons BeanUtils把值赋给目标对象(BeanUtils通过反射可以把字符串转换为对应的原始类型)。
  b. Reference Values(引用类型)
使用"$"符号引用先前定义的类型：

sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher
...
myRealm.credentialsMatcher = $sha256Matcher

c. Nested Properties(嵌套属性)
使用逗号"."进行嵌套属性的定义：

securityManager.sessionManager.globalSessionTimeout = 1800000

这句话被转义为如下逻辑:

securityManager.getSessionManager().setGlobalSessionTimeout(1800000);

属性的嵌套可以是N层。
d. Byte Array Values(字节数组)
对于字节数据，需要将其转换为加密的文本，可以使用Base64或16进制加密字符串，默认使用Base64，因为Base64加密后的文本少。

# 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==

如果用16进制加密，必须添加前缀"0x"：

securityManager.rememberMeManager.cipherKey = 0x3707344A4093822299F31D008

e. Collection Properties(集合属性)
对于Lists和Sets集合属性，使用逗号","分隔指定即可:

sessionListener1 = com.company.my.SessionListenerImplementation
...
sessionListener2 = com.company.my.other.SessionListenerImplementation
...
securityManager.sessionManager.sessionListeners = $sessionListener1, $sessionListener2

对于Map，键和值之间用冒号":"，多项键值对间用逗号"," ：

object1 = com.company.some.Class
object2 = com.company.another.Class
...
anObject = some.class.with.a.Map.property

anObject.mapProperty = key1:$object1, key2:$object2

上面例子中，key1对应$object1值，map.get("key1")就返回object1。键也可以为其他引用：

anObject.map = $objectKey1:$objectValue1, $objectKey2:$objectValue2

3. Considerations
  a. Order Matters(顺序问题)
INI配置方式，简单易用，其配置的顺序即为Shiro初始化实例的顺序，所以定义的顺序非常重要。
  b. Overriding Instances(覆盖实例)
同块中的同键配置，后者将覆盖前者：

myRealm = com.company.security.MyRealm
...
myRealm = com.company.security.DatabaseRealm

值为DatabaseRealm的实例最终将被使用，其覆盖了com.company.security.MyRealm。
c. Default SecurityManager
你可能注意到，在开始的那个完整例子中，没有SecurityManager实例的配置，只是配置了其内部的属性：

myRealm = ...

securityManager.sessionManager.globalSessionTimeout = 1800000
...

这是因为，securityManager比较特殊，它不需要配置其实现类。
如果想自定义securityManager，直接覆盖就可以了：

securityManager = com.company.security.shiro.MyCustomSecurityManager

不过，真的需要么自定义securityManager？

[users]
这部分允许你定义一些静态用户。这对应用中存在很少用户或不需要动态创建用户的应用比较有用。

[users]
admin = secret
lonestarr = vespa, goodguy, schwartz
darkhelmet = ludicrousspeed, badguy, schwartz

a. Automatic IniRealm
定义不为空的[users]和[roles]，后台会自动创建org.apache.shiro.realm.text.IniRealm实例，并使用iniRealm键被[main]所引用。
b. Line Format
[users]部分的定义必须符合以下格式：

username = password, roleName1, roleName2, ..., roleNameN

  1. 等号左边是用户名
  2. 等号右边第一个值是密码。密码是必须的。
  3. 紧接密码后面的用逗号分隔的值是用户的角色，角色信息选填。
c. Encrypting Passwords
如果不想用明文进行密码配置，可以使用hash算法进行加密。使用hash算法加密密码，需要让Shiro知道密码是经过加密的。在[main]部分引用iniRealm，配置CredentialsMatcher，来指定使用的hash算法：

[main]
...
sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher
...
iniRealm.credentialsMatcher = $sha256Matcher
...

[users]
# user1 = sha256-hashed-hex-encoded password, role1, role2, ...
user1 = 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b, role1, role2, ... 

也可以对CredentialsMatcher进行属性设置，比如设置盐值，hash迭代周期等。下面的例子使用Base64加密用户的密码：

[main]
...
# true = hex, false = base64:
sha256Matcher.storedCredentialsHexEncoded = false

[roles]
这部分允许通过角色的形式配置用户的权限。对于一些只有少数角色或不需要动态创建角色的应用比较有用。

[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. Line Format
[roles]定义以键值对形式，键对应角色，值对应权限，必须符合以下格式：

rolename = permissionDefinition1, permissionDefinition2, ..., permissionDefinitionN

permissionDefinition可以为任意字符，但是更多情况下是符合org.apache.shiro.authz.permission.WildcardPermission的通配符。如果permissionDefinition内含有逗号","(printer:5thFloor:print,info)，
需要用引号引用起来:"printer:5thFloor:print,info"。
如果角色没有对应的权限，可以不在[roles]部分定义，只要在[users]部分定义角色即可。