Seam的安全框架身份管理（Identity Management）（译）

注释	状态	描述
`@UserPrincipal`	必选	标明字段或方法包含用户的用户名。
`@UserPassword`	必选	标明字段或方法包含用户的密码。它允许指定一个`hash`算法来对密码进行散列。可选的值包括`md5`, `sha`和`none`。例如： @UserPassword(hash = "md5") public String getPasswordHash() { return passwordHash; } 如果一个应用需要一个不被Seam原生支持的散列算法，可以通过扩展`PasswordHash`组件来实现其他的散列算法。
`@UserFirstName`	可选	标明字段或方法包含用户的姓。
`@UserLastName`	可选	标明字段或方法包含用户的名。
`@UserEnabled`	可选	标明字段或方法包含用户的可用状态。它是一个布尔属性，如果没有指定，那么所有用户账户都被假定为可用。
`@UserRoles`	必选	标明字段或方法包含用户的角色。这个属性将在下文进行更详细的描述。

表 15.2. 角色实体注释

注释	状态	描述
`@RoleName`	必选	标明字段或方法包含角色的名称。
`@RoleGroups`	可选	标明字段或方法包含角色的组关系。
`@RoleConditional`	可选	标明字段或方法说明角色是否有依赖性。依赖性角色将在后文中解释。

15.4.2.3. 实体Bean示例

如前所述，JpaIdentityStore被设计成尽可能的灵活，以应对你的数据库模式中的用户和角色的表设计。在本节中，将看到一些可能被用到的存储用户和角色纪录的数据库模式。

15.4.2.3.1. 简化模式示例

在这个简化的示例中，一个简单的用户和角色表通过一个名为UserRoles的交叉引用表实现了多对多的关系。

@Entity
public class User {

  private Integer userId;
  private String username;
  private String passwordHash;
  private Set<Role> roles;

  @Id @GeneratedValue
  public Integer getUserId() { return userId; }
  public void setUserId(Integer userId) { this.userId = userId; }

  @UserPrincipal
  public String getUsername() { return username; }
  public void setUsername(String username) { this.username = username; }

  @UserPassword(hash = "md5")
  public String getPasswordHash() { return passwordHash; }
  public void setPasswordHash(String passwordHash) { this.passwordHash = passwordHash; }

  @UserRoles
  @ManyToMany(targetEntity = Role.class)
  @JoinTable(name = "UserRoles",
    joinColumns = @JoinColumn(name = "UserId"),
    inverseJoinColumns = @JoinColumn(name = "RoleId"))
  public Set<Role> getRoles() { return roles; }
  public void setRoles(Set<Role> roles) { this.roles = roles; }

}

@Entity
public class Role {
  private Integer roleId;
  private String rolename;

  @Id @Generated
  public Integer getRoleId() { return roleId; }
  public void setRoleId(Integer roleId) { this.roleId = roleId; }

  @RoleName
  public String getRolename() { return rolename; }
  public void setRolename(String rolename) { this.rolename = rolename; }
}

15.4.2.3.2. 复杂模式示例

本例建立在上面的简化示例基础上，包括了所有的可选字段以及允许角色拥有组关系。

@Entity
public class User {

  private Integer userId;
  private String username;
  private String passwordHash;
  private Set<Role> roles;
  private String firstname;
  private String lastname;
  private boolean enabled;

  @Id @GeneratedValue
  public Integer getUserId() { return userId; }
  public void setUserId(Integer userId) { this.userId = userId; }

  @UserPrincipal
  public String getUsername() { return username; }
  public void setUsername(String username) { this.username = username; }

  @UserPassword(hash = "md5")
  public String getPasswordHash() { return passwordHash; }
  public void setPasswordHash(String passwordHash) { this.passwordHash = passwordHash; }

  @UserFirstName
  public String getFirstname() { return firstname; }
  public void setFirstname(String firstname) { this.firstname = firstname; }

  @UserLastName
  public String getLastname() { return lastname; }
  public void setLastname(String lastname) { this.lastname = lastname; }

  @UserEnabled
  public boolean isEnabled() { return enabled; }
  public void setEnabled(boolean enabled) { this.enabled = enabled; }

  @UserRoles
  @ManyToMany(targetEntity = Role.class)
  @JoinTable(name = "UserRoles",
    joinColumns = @JoinColumn(name = "UserId"),
    inverseJoinColumns = @JoinColumn(name = "RoleId"))
  public Set<Role> getRoles() { return roles; }
  public void setRoles(Set<Role> roles) { this.roles = roles; }

}

@Entity
public class Role {
  private Integer roleId;
  private String rolename;
  private boolean conditional;

  @Id @Generated
  public Integer getRoleId() { return roleId; }
  public void setRoleId(Integer roleId) { this.roleId = roleId; }

  @RoleName
  public String getRolename() { return rolename; }
  public void setRolename(String rolename) { this.rolename = rolename; }

  @RoleConditional
  public boolean isConditional() { return conditional; }
  public void setConditional(boolean conditional) { this.conditional = conditional; }

  @RoleGroups
  @ManyToMany(targetEntity = Role.class)
  @JoinTable(name = "RoleGroups",
    joinColumns = @JoinColumn(name = "RoleId"),
    inverseJoinColumns = @JoinColumn(name = "GroupId"))
  public Set<Role> getGroups() { return groups; }
  public void setGroups(Set<Role> groups) { this.groups = groups; }

}

属性	缺省值	描述
`server-address`	`localhost`	LDAP服务器地址。
`server-port`	`389`	LDAP服务器监听端口号。
`user-context-DN`	`ou=Person,dc=acme,dc=com`	包含用户纪录的上下文的标识名(DN)。
`user-DN-prefix`	`uid=`	This value is prefixed to the front of the username to locate the user's record.
`user-DN-suffix`	`,ou=Person,dc=acme,dc=com`	This value is appended to the end of the username to locate the user's record.
`role-context-DN`	`ou=Role,dc=acme,dc=com`	The DN of the context containing role records.
`role-DN-prefix`	`cn=`	This value is prefixed to the front of the role name to form the DN for locating the role record.
`role-DN-suffix`	`,ou=Roles,dc=acme,dc=com`	This value is appended to the role name to form the DN for locating the role record.
`bind-DN`	`cn=Manager,dc=acme,dc=com`	This is the context used to bind to the LDAP server.
`bind-credentials`	`secret`	These are the credentials (the password) used to bind to the LDAP server.
`user-role-attribute`	`roles`	This is the name of the attribute of the user record that contains the list of roles that the user is a member of.
`role-attribute-is-DN`	`true`	This boolean property indicates whether the role attribute of the user record is itself a distinguished name.
`user-name-attribute`	`uid`	Indicates which attribute of the user record contains the username.
`user-password-attribute`	`userPassword`	Indicates which attribute of the user record contains the user's password.
`first-name-attribute`	`null`	Indicates which attribute of the user record contains the user's first name.
`last-name-attribute`	`sn`	Indicates which attribute of the user record contains the user's last name.
`full-name-attribute`	`cn`	Indicates which attribute of the user record contains the user's full (common) name.
`enabled-attribute`	`null`	Indicates which attribute of the user record determines whether the user is enabled.
`role-name-attribute`	`cn`	Indicates which attribute of the role record contains the name of the role.
`object-class-attribute`	`objectClass`	Indicates which attribute determines the class of an object in the directory.
`role-object-classes`	`organizationalRole`	An array of the object classes that new role records should be created as.
`user-object-classes`	`person,uidObject`	An array of the object classes that new user records should be created as.

15.4.3.2. LdapIdentityStore Configuration Example

The following configuration example shows how LdapIdentityStore may be configured for an LDAP directory running on fictional host directory.mycompany.com. The users are stored within this directory under the context ou=Person,dc=mycompany,dc=com, and are identified using the uid attribute (which corresponds to their username). Roles are stored in their own context, ou=Roles,dc=mycompany,dc=com and referenced from the user's entry via the roles attribute. Role entries are identified by their common name (the cn attribute) , which corresponds to the role name. In this example, users may be disabled by setting the value of their enabled attribute to false.

<security:ldap-identity-store
    server-address="directory.mycompany.com"
    bind-DN="cn=Manager,dc=mycompany,dc=com"
    bind-credentials="secret"
    user-DN-prefix="uid="
    user-DN-suffix=",ou=Person,dc=mycompany,dc=com"
    role-DN-prefix="cn="
    role-DN-suffix=",ou=Roles,dc=mycompany,dc=com"
    user-context-DN="ou=Person,dc=mycompany,dc=com"
    role-context-DN="ou=Roles,dc=mycompany,dc=com"
    user-role-attribute="roles"
    role-name-attribute="cn"
    user-object-classes="person,uidObject"
    enabled-attribute="enabled"
    />

15.4.4. 编写你自己的IdentityStore

编写你自己的身份存储实现允许你验证和执行不被Seam支持的其他安全提供者的身份管理操作。只需要一个简单的就能达到这个目标，它必须实现 org.jboss.seam.security.management.IdentityStore接口。

必须实现的方法请参考IdentityStore的JavaDoc。

15.4.5. 身份管理中的验证

如果你正在你的Seam应用中使用身份管理，那么不需要提供一个验证器组件（参考前面的验证章节）来进行验证。简单的忽略 components.xml文件中的 identity配置的authenticator-method,并且 SeamLoginModule将默认使用IdentityManager来验证你的应用的用户，而不需要特别的配置。

15.4.6. 使用IdentityManager

IdentityManger可以通过以下的注入Seam组件的方式获得：

@In IdentityManager identityManager;

或者通过它的静态方法instance()获得:

IdentityManager identityManager = IdentityManager.instance();

下表描述了IdentityManager的方法:

表 15.4. 身份管理API

方法	返回值	描述
`createUser(String name, String password)`	`boolean`	用指定的用户名和密码创建一个用户账户。如果成功返回`true`，反之，返回`false`。
`deleteUser(String name)`	`boolean`	删除一个指定用户名的用户账户。如果成功返回`true`，反之，返回`false`。
`createRole(String role)`	`boolean`	使用指定的名称创建一个角色。如果成功返回`true`，反之，返回`false`。
`deleteRole(String name)`	`boolean`	删除一个指定名称的角色。如果成功返回`true`，反之，返回`false`。
`enableUser(String name)`	`boolean`	启用一个指定名称的用户账户。不能验证的账户不能启用。如果成功返回`true`，反之，返回`false`。
`disableUser(String name)`	`boolean`	禁用一个指定名称的用户账户。如果成功返回`true`，反之，返回`false`。
`changePassword(String name, String password)`	`boolean`	修改指定用户名的账户的密码。如果成功返回`true`，反之，返回`false`。
`isUserEnabled(String name)`	`boolean`	如果账户是启用的返回`true`，反之，返回`false`。
`grantRole(String name, String role)`	`boolean`	为指定的用户或角色赋予指定的角色。角色必须是已经存在的。如果成功授权返回`true`，如果已经给用户授权过了，返回`false`。
`revokeRole(String name, String role)`	`boolean`	撤销从指定的用户或角色的特定角色。如果指定用户是角色的成员并且成功撤销，返回`true`；如果用户不是角色的成员，返回`false`。
`userExists(String name)`	`boolean`	如果存在指定的用户返回`true`，反之，返回`false`。
`listUsers()`	`List`	按照字母序返回用户用户名的列表。
`listUsers(String filter)`	`List`	按照字母序返回使用指定的过滤参数过滤的用户用户名的列表。
`listRoles()`	`List`	返回所有角色名称的列表。
`getGrantedRoles(String name)`	`List`	返回一个所有角色的名字明确授予指定的用户名的列表。
`getImpliedRoles(String name)`	`List`	返回一个所有角色的名字隐式授予指定的用户名列表。隐式授予角色包括那些不直接授予一个用户，而他们给予该用户的角色是其成员。例如，管理员角色是用户的角色的成员，而用户是管理员角色的成员，那么该用户的暗示作用都是管理员和用户角色。
`authenticate(String name, String password)`	`boolean`	验证指定的用户名和密码存储配置的身份。如果成功返回`true`，如果身份验证失败返回`false`。该方法在成功的认证后除了返回值不改变什么。它不改变`Identity`组件的状态-实际上也不是一定要执行一个适当的Seam登录的`Identity.login()`。
`addRoleToGroup(String role, String group)`	`boolean`	添加作为指定组的成员中指定的角色。如果操作成功返回true。
`removeRoleFromGroup(String role, String group)`	`boolean`	从指定的角色组中删除指定的角色。如果操作成功返回true。
`listRoles()`	`List`	列出所有关角色的名字。

使用这些身份管理API需要调用用户有合适的授权才能调用这些方法。下表描述了 IdentityManager中每一个方法需要的权限。表中列出的权限目标是字符串值。

表 15.5. 身份管理安全权限

方法	权限目标	权限动作
`createUser()`	`seam.user`	`create`
`deleteUser()`	`seam.user`	`delete`
`createRole()`	`seam.role`	`create`
`deleteRole()`	`seam.role`	`delete`
`enableUser()`	`seam.user`	`update`
`disableUser()`	`seam.user`	`update`
`changePassword()`	`seam.user`	`update`
`isUserEnabled()`	`seam.user`	`read`
`grantRole()`	`seam.user`	`update`
`revokeRole()`	`seam.user`	`update`
`userExists()`	`seam.user`	`read`
`listUsers()`	`seam.user`	`read`
`listRoles()`	`seam.role`	`read`
`addRoleToGroup()`	`seam.role`	`update`
`removeRoleFromGroup()`	`seam.role`	`update`

下列代码提供了一个例子，演示了一套给admin觉得的成员授权访问所有身份管理相关的方法的安全规则：

rule ManageUsers
  no-loop
  activation-group "permissions"
when
  check: PermissionCheck(name == "seam.user", granted == false)
  Role(name == "admin")
then
  check.grant();
end

rule ManageRoles
  no-loop
  activation-group "permissions"
when
  check: PermissionCheck(name == "seam.role", granted == false)
  Role(name == "admin")
then
  check.grant();
end