diff --git a/docs/src/main/docbook/en-US/security-authorization.xml b/docs/src/main/docbook/en-US/security-authorization.xml index 9eb3f32..89b913a 100755 --- a/docs/src/main/docbook/en-US/security-authorization.xml +++ b/docs/src/main/docbook/en-US/security-authorization.xml @@ -3,6 +3,20 @@ Security - Authorization + +
+ Configuration + + + Before using any of Seam's authorization features, you must enable the SecurityInterceptor + by adding the following code to your application's beans.xml: + + + org.jboss.seam.security.SecurityInterceptor + ]]> + + +
Basic Concepts diff --git a/docs/src/main/docbook/en-US/security-identitymanagement.xml b/docs/src/main/docbook/en-US/security-identitymanagement.xml index 7324b19..e4d087c 100755 --- a/docs/src/main/docbook/en-US/security-identitymanagement.xml +++ b/docs/src/main/docbook/en-US/security-identitymanagement.xml @@ -20,145 +20,14 @@ JpaIdentityStore, which allows you to store your identity data using JPA. - - - In a Seam-based application it probably makes more sense to use the standards-based JpaIdentityStore rather than - HibernateIdentityStore, as you will most likely be running in an Java EE container that supports JPA. - - - -
- -
- Configuring Seam to use Identity Management - - Like all authentication providers in Seam, Identity Management is supported via a concrete Authenticator - implementation called IdmAuthenticator. If you don't provide your own Authenticator - implementation then the IdmAuthenticator will be used automatically, however it is also possible (and doesn't hurt) to - configure it explicitly. For example, the following XML shows how it would be configured with the Seam Config module: - - - - - - - - org.jboss.seam.security.management.IdmAuthenticator - ]]> - - - Besides configuring the authenticatorClass property, you must also configure the identity store. - See the sections later in this chapter to find out how to configure the identity store for your application. - - -
- -
- Using the Identity Management Features - - - The Identity Management features are provided by a number of manager objects, which can be access from an - IdentitySession. The IdentitySession may be injected directly into your beans - like so: - - - - - - Once you have the IdentitySession object, you can use it to perform various identity management - operations. You should refer to the PicketLink documentation for a complete description of the available features, - however the following sections contain a brief overview. + In a Seam-based application it probably makes more sense to use the standards-based JpaIdentityStore rather than + HibernateIdentityStore, as you will most likely be running in an Java EE container that supports JPA. + JpaIdentityStore is an implementation of the PicketLink IdentityStore interface, provided by Seam Security. + This identity store allows you to store your identity model inside a relational database, accessible via JPA. It provides an immense + amount of flexibility in the way you define your identity model, and in most cases should be compatible with existing database schemas. -
- Managing Users and Groups - - - Users and groups are managed by a PersistenceManager, which can be obtained by calling - getPersistenceManager() on the IdentitySession object: - - - - - - Once you have the PersistenceManager object, you can create User objects with the - createUser() method: - - - - - - Similarly, you can create Group objects with the createGroup() method: - - - - - - You can also remove users and groups by calling the removeUser() or removeGroup() method. - -
- -
- Managing Relationships - - - Relationships are used to associate User objects with Group objects. Relationships can - be managed with the RelationshipManager object, which can be obtained by calling - getRelationshipManager() on the IdentitySession: - - - - - - Relationships are created by invoking the associateUser() method, and passing in the group and user - objects that should be associated: - - - -
- -
- Managing Roles - - - Roles are managed via the RoleManager object, which can be obtained by invoke the - getRoleManager() method on the IdentitySession object: - - - - - - Roles are an association between a user and a group, however they are slightly more complex than a simple - group membership as the association also has a role type. The role type is generally - used to describe a particular function of the user within the group. Role types are represented by the - RoleType object, and can be created with the createRoleType() method: - - - - - - Roles can be assigned to users by invoking the createRole() method, and passing in the - RoleType, User and Group: - - - -
-
- -
- JpaIdentityStore - See the idmconsole example application (included in the Seam distribution) for a demonstration of Seam's Identity Management @@ -166,17 +35,23 @@ public @Model class IdentityAction { - - JpaIdentityStore is an implementation of the PicketLink IdentityStore interface, provided by Seam Security. - This identity store allows you to store your identity model inside a relational database, accessible via JPA. It provides an immense - amount of flexibility in the way you define your identity model, and in most cases should be compatible with existing database schemas. - +
+ +
+ Configuring Seam to use Identity Management with JPA + + Like all authentication providers in Seam, Identity Management is supported via a concrete Authenticator + implementation called IdmAuthenticator. To use Identity Management in your own application, you don't + need to do anything! Simply don't configure any authenticator, and as long as you have an identity store + configured (see the next section), the Identity Management API will be used to authenticate automatically. + +
Recommended database schema - + - While JpaIdentityStore should be compatible with a large range of database schemas, the following diagram displays + While JpaIdentityStore should be compatible with a large variety of database schemas, the following diagram displays the recommended database schema to use: @@ -187,144 +62,97 @@ public @Model class IdentityAction { - +
- +
- Configuring JpaIdentityStore - - - Seam provides a configuration bean called JpaIdentityStoreConfiguration, which can be used - to configure which entity bean classes will be used by JpaIdentityStore to store identity-related - data. - - - - - - - Property - Description - - - - - identityClass - Entity class that contains identity objects such as users and groups - - - credentialClass - Entity class that contains credentials, such as passwords - - - relationshipClass - Entity class that contains relationships between identity objects - - - roleTypeClass - Entity class that contains the names of all role types - - - attributeClass - Entity class that contains additional identity object attributes - - - - - + The <code>@IdentityEntity</code> and <code>@IdentityProperty</code> annotations + - The following example shows how JpaIdentityStoreConfiguration may be configured using - the Seam Config module: + Seam Security provides two annotations for configuring your entity beans for use with JpaIdentityStore. + The first, @IdentityEntity is a class annotation used to mark an entity bean so that + JpaIdentityStore knows it contains identity-related data. It has a single member of type EntityType, + that tells JpaIdentityStore what type of identity data it contains. Possible values are: - - - - - - com.acme.model.IdentityObject - com.acme.model.IdentityObjectCredential - com.acme.model.IdentityObjectRelationship - com.acme.model.IdentityRoleName - com.acme.model.IdentityObjectAttribute - ]]> -
- -
- Configuring your Entities + + IDENTITY_OBJECT + IDENTITY_CREDENTIAL + IDENTITY_RELATIONSHIP + IDENTITY_ATTRIBUTE + IDENTITY_ROLE_NAME + - Seam Security provides a single annotation, IdentityProperty, which can be used to configure your - entity beans for use with JpaIdentityStore. This annotation declares two values, value + The second one, IdentityProperty, is a field or method annotation which is used to configure which + properties of the bean contain identity values. This annotation declares two values, value and attributeName: +
- - - The value() member is of type PropertyType, which is an enum that defines the following values: - + + The value() member is of type PropertyType, which is an enum that defines the following values: + - - - By placing the IdentityProperty annotation on various fields of your entity beans, JpaIdentityStore - can determine how identity-related data must be stored within your database tables. - + + By placing the IdentityProperty annotation on various fields of your entity beans, JpaIdentityStore + can determine how identity-related data must be stored within your database tables. + + + + In the following sections we'll look at how each of the main entities are configured. + +
+ Identity Object + - In the following sections we'll look at how each of the main entities are configured. + Let's start by looking at identity object. In the recommended database schema, the IDENTITY_OBJECT table + is responsible for storing objects such as users and groups. This table may be represented by the following entity + bean: - -
- Identity Object - - Let's start by looking at identity object. This entity class is configured as the identityClass property - of JpaIdentityStoreConfiguration. In the recommended database schema, the IDENTITY_OBJECT table - is responsible for storing objects such as users and groups. This table may be represented by the following entity - bean: - - + // snip getter and setter methods +}]]> - - In the above code both the name and type fields are annotated with @IdentityProperty. - This tells JpaIdentityStore that these two fields are significant in terms of identity management-related - state. By annotating the name field with @IdentityProperty(PropertyType.NAME), JpaIdentityStore - knows that this field is used to store the name of the identity object. Likewise, the - @IdentityProperty(PropertyType.TYPE) annotation on the type field indicates that the value of this - field is used to represent the type of identity object. - - - - The IdentityObjectType entity is simply a lookup table containing the names of the valid identity types. The - field representing the actual name of the type itself should be annotated with @IdentityProperty(PropertyType.NAME): - + + In the above code both the name and type fields are annotated with @IdentityProperty. + This tells JpaIdentityStore that these two fields are significant in terms of identity management-related + state. By annotating the name field with @IdentityProperty(PropertyType.NAME), JpaIdentityStore + knows that this field is used to store the name of the identity object. Likewise, the + @IdentityProperty(PropertyType.TYPE) annotation on the type field indicates that the value of this + field is used to represent the type of identity object. + + + + The IdentityObjectType entity is simply a lookup table containing the names of the valid identity types. The + field representing the actual name of the type itself should be annotated with @IdentityProperty(PropertyType.NAME): + - -
+
-
- Credential +
+ Credential - - The credentials table is used to store user credentials, such as passwords, and is configured as the credentialClass - property of JpaIdentityStoreConfiguration. Here's an example of an entity bean configured to store identity object - credentials: - + + The credentials table is used to store user credentials, such as passwords. Here's an example of an entity bean + configured to store identity object credentials: + - - - The IdentityObjectCredentialType entity is used to store a list of valid credential types. Like - IdentityObjectType, it is a simple lookup table with the field representing the credential type - name annotated with @IdentityProperty(PropertyType.NAME): - + + The IdentityObjectCredentialType entity is used to store a list of valid credential types. Like + IdentityObjectType, it is a simple lookup table with the field representing the credential type + name annotated with @IdentityProperty(PropertyType.NAME): + - -
- -
- Identity Object Relationship +
- - The relationship table stores associations between identity objects, and is configured as the relationshipClass - property of JpaIdentityStoreConfiguration. Here's an example of an entity bean that has been configured to - store identity object relationships: - +
+ Identity Object Relationship + + + The relationship table stores associations between identity objects. Here's an example of an entity bean that has been configured to + store identity object relationships: + - - - The name property is annotated with @IdentityProperty(PropertyType.NAME) to indicate that this - field contains the name value for named relationships. An example of a named relationship is a role, which uses the - name property to store the role type name. - - - - The relationshipType property is annotated with @IdentityProperty(PropertyType.TYPE) to indicate - that this field represents the type of relationship. This is typically a value in a lookup table. - - - - The from property is annotated with @IdentityProperty(PropertyType.RELATIONSHIP_FROM) to indicate - that this field represents the IdentityObject on the from side of the relationship. - - - - The to property is annotated with @IdentityProperty(PropertyType.RELATIONSHIP_TO) to indicate - that this field represents the IdentityObject on the to side of the relationship. - + + The name property is annotated with @IdentityProperty(PropertyType.NAME) to indicate that this + field contains the name value for named relationships. An example of a named relationship is a role, which uses the + name property to store the role type name. + + + + The relationshipType property is annotated with @IdentityProperty(PropertyType.TYPE) to indicate + that this field represents the type of relationship. This is typically a value in a lookup table. + + + + The from property is annotated with @IdentityProperty(PropertyType.RELATIONSHIP_FROM) to indicate + that this field represents the IdentityObject on the from side of the relationship. + - - The IdentityObjectRelationshipType entity is a lookup table containing the valid relationship types. The - @IdentityProperty(PropertyType.NAME) annotation is used to indicate the field containing the relationship - type names: - + + The to property is annotated with @IdentityProperty(PropertyType.RELATIONSHIP_TO) to indicate + that this field represents the IdentityObject on the to side of the relationship. + + + + The IdentityObjectRelationshipType entity is a lookup table containing the valid relationship types. The + @IdentityProperty(PropertyType.NAME) annotation is used to indicate the field containing the relationship + type names: + - -
+
-
- Attributes - - - The attribute table is used to store any additional information that is to be associated with identity objects. It is configured - as the attributeClass property of JpaIdentityStoreConfiguration. Here's an example of an entity bean - used to store attributes: - +
+ Attributes + + + The attribute table is used to store any additional information that is to be associated with identity objects. + Here's an example of an entity bean used to store attributes: + - - - The name field is annotated with @IdentityProperty(PropertyType.NAME) to indicate that this field - contains the attribute name. The value field is annotated with @IdentityProperty(PropertyType.VALUE) - to indicate that this field contains the attribute value. - -
+ + The name field is annotated with @IdentityProperty(PropertyType.NAME) to indicate that this field + contains the attribute name. The value field is annotated with @IdentityProperty(PropertyType.VALUE) + to indicate that this field contains the attribute value. +
- + +
+ +
+ Managing Users, Groups and Roles + + + The Identity Management features are provided by a number of manager objects, which can be access from an + IdentitySession. The IdentitySession may be injected directly into your beans + like so: + + + + + + Once you have the IdentitySession object, you can use it to perform various identity management + operations. You should refer to the PicketLink documentation for a complete description of the available features, + however the following sections contain a brief overview. + + +
+ Managing Users and Groups + + + Users and groups are managed by a PersistenceManager, which can be obtained by calling + getPersistenceManager() on the IdentitySession object: + + + + + + Once you have the PersistenceManager object, you can create User objects with the + createUser() method: + + + + + + Similarly, you can create Group objects with the createGroup() method: + + + + + + You can also remove users and groups by calling the removeUser() or removeGroup() method. + +
+ +
+ Managing Relationships + + + Relationships are used to associate User objects with Group objects. Relationships can + be managed with the RelationshipManager object, which can be obtained by calling + getRelationshipManager() on the IdentitySession: + + + + + + Relationships are created by invoking the associateUser() method, and passing in the group and user + objects that should be associated: + + + +
+ +
+ Managing Roles + + + Roles are managed via the RoleManager object, which can be obtained by invoke the + getRoleManager() method on the IdentitySession object: + + + + + + Roles are an association between a user and a group, however they are slightly more complex than a simple + group membership as the association also has a role type. The role type is generally + used to describe a particular function of the user within the group. Role types are represented by the + RoleType object, and can be created with the createRoleType() method: + + + + + + Roles can be assigned to users by invoking the createRole() method, and passing in the + RoleType, User and Group: + + + +
-