From seam-commits at lists.jboss.org Mon Jan 28 23:04:35 2008 Content-Type: multipart/mixed; boundary="===============7266230270237131352==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r7277 - trunk/doc/reference/en/modules. Date: Mon, 28 Jan 2008 23:04:35 -0500 Message-ID: --===============7266230270237131352== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: shane.bryzak(a)jboss.com Date: 2008-01-28 23:04:35 -0500 (Mon, 28 Jan 2008) New Revision: 7277 Modified: trunk/doc/reference/en/modules/security.xml Log: describe security permissions for IdentityManager Modified: trunk/doc/reference/en/modules/security.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/doc/reference/en/modules/security.xml 2008-01-29 03:15:19 UTC (re= v 7276) +++ trunk/doc/reference/en/modules/security.xml 2008-01-29 04:04:35 UTC (re= v 7277) @@ -3,16 +3,16 @@ = The Seam Security API is an optional Seam feature that provides authen= tication and authorization features - for securing both domain and page resources within your Seam project. = + for securing both domain and page resources within your Seam project. - = + Overview - = + Seam Security provides two different modes of operation: - = + @@ -22,38 +22,38 @@ - advanced mode - this mode supports all the = same features as the simplified mode, = - plus it offers rule-based security checks using JBoss Rules. = = + advanced mode - this mode supports all the = same features as the simplified mode, + plus it offers rule-based security checks using JBoss Rules. - = + Which mode is right for my application? - = + That all depends on the requirements of your application. If you = have minimal security requirements, for example if you only wish to restrict certain pages and actions to users wh= o are logged in, or who belong to a certain role, - then the simplified mode will probably be sufficient. The advanta= ges of this is a more simplified configuration, = + then the simplified mode will probably be sufficient. The advanta= ges of this is a more simplified configuration, significantly less libraries to include, and a smaller memory foot= print. - = + - If on the other hand, your application requires security checks ba= sed on contextual state or complex business rules, = + If on the other hand, your application requires security checks ba= sed on contextual state or complex business rules, then you will require the features provided by the advanced mode. - = + Requirements - = + - If using the advanced mode features of Seam Security, the following = jar files are required to be configured as modules in = + If using the advanced mode features of Seam Security, the following = jar files are required to be configured as modules in application.xml. If you are using Seam Security = in simplified mode, these are not required: - = + drools-compiler.jar @@ -69,25 +69,25 @@ mvel14.jar - = - = - = + + + For web-based security, jboss-seam-ui.jar must al= so be included in the application's war file. - = - = + + - = + Disabling Security - = + In some situations it may be necessary to disable Seam Security, for= example during unit tests. This can be done by calling the static method Identity.setSecurityEnabled(false= ) to disable security checks. Doing this prevents any security checks being performed for the following: - = + Entity Security @@ -100,7 +100,7 @@ Page restrictions - = + = @@ -131,10 +131,10 @@ xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=3D "http://jboss.com/products/seam/components http://jboss.co= m/products/seam/components-2.0.xsd - http://jboss.com/products/seam/security http://jboss.com/= products/seam/security-2.0.xsd"> = - = + http://jboss.com/products/seam/security http://jboss.com/= products/seam/security-2.0.xsd"> + - = + ]]> = @@ -157,18 +157,18 @@ The authenticate-method property specified for = identity in components.xml specifies which method will be u= sed by SeamLoginModule - to authenticate users. This method takes no parameters, and is ex= pected to return a boolean indicating = + to authenticate users. This method takes no parameters, and is ex= pected to return a boolean indicating whether authentication is successful or not. The user's username = and password can be obtained from Identity.instance().getUsername() and = Identity.instance().getPassword(), respectively. Any roles that the user is a member of should be as= signed using - Identity.instance().addRole(). Here's a complet= e example of an authentication method = + Identity.instance().addRole(). Here's a complet= e example of an authentication method inside a JavaBean component: = = @@ -202,21 +202,21 @@ In this case, if the user record is not found and a NoRes= ultException thrown, the authentication method returns false to indicate= the authentication failed. - = + Identity.addRole() - = + The Identity.addRole() method behaves differe= ntly depending on whether the current - session is authenticated or not. If the session is not authenti= cated, then addRole() = + session is authenticated or not. If the session is not authenti= cated, then addRole() should only be called during the authentica= tion process. When called here, the role name is placed into a temporary list of pre-authenticated r= oles. Once authentication is successful, the pre-authenticated roles then become "real" roles, and callin= g Identity.hasRole() for those roles will then return true. The following sequence d= iagram represents the list of pre-authenticated roles as a first class object to show more clearly how it fits i= n to the authentication process. - = + - = + @@ -224,37 +224,37 @@ - = - = + + - = + Special Considerations - = + - When writing an authenticator method, it is important that it is= kept minimal and free from = - any side-effects. This is because there is no guarantee as to ho= w many times the authenticator = + When writing an authenticator method, it is important that it is= kept minimal and free from + any side-effects. This is because there is no guarantee as to ho= w many times the authenticator method will be called by the security API, and as such it may be= invoked multiple times during a single request. Because of this, any special code that should= execute upon a successful or failed authentication should be written by implementing an event= observer. See the section on Security Events further down in this chapter for more informatio= n about which events are raised by Seam Security. - = + To give an example, let's say that upon a successful login that = some user statistics must be - updated. We would do this by writing an event observer for the = + updated. We would do this by writing an event observer for the org.jboss.seam.security.loginSuccessful event= , like this: - = + = + userStats.incrementLoginCount(); + }]]> = @@ -265,8 +265,8 @@ The Identity component provides both u= sername and password properties, catering for the most common authentication scenario. = These properties can be bound directly to the - username and password fields on a login form. Once these properti= es are set, calling the = - identity.login() method will authenticate the u= ser using the provided credentials. = + username and password fields on a login form. Once these properti= es are set, calling the + identity.login() method will authenticate the u= ser using the provided credentials. Here's an example of a simple login form: = @@ -283,12 +283,12 @@
]]> - = + Similarly, logging out the user is done by calling #{iden= tity.logout}. Calling this action will clear the security state of the currently authenticate= d user. - = + = @@ -316,123 +316,123 @@ = - = + Handling Security Exceptions - = + - To prevent users from receiving the default error page in response= to a security error, it's recommended that = + To prevent users from receiving the default error page in response= to a security error, it's recommended that pages.xml is configured to redirect security er= rors to a more "pretty" page. The two main types of exceptions thrown by the security API are: - = + - NotLoggedInException - This exception is th= rown if the user attempts to access a = + NotLoggedInException - This exception is th= rown if the user attempts to access a restricted action or page when they are not logged in. - = + AuthorizationException - This exception is = only thrown if the user is already logged in, and they have attempted to access a restricted action or page = for which they do not have the necessary privileges. - = + - = + In the case of a NotLoggedInException, it is re= commended that the user is redirected to either a login or registration page so that they can log in. For = an AuthorizationException, - it may be useful to redirect the user to an error page. Here's an = example of a pages.xml = - file that redirects both of these security exceptions: = + it may be useful to redirect the user to an error page. Here's an = example of a pages.xml + file that redirects both of these security exceptions: - = + = ... - = + You must be logged in to perform this action - = + You do not have the necessary security privileges to = perform this action. - = + ]]> - = + Most web applications require even more sophisticated handling of = login redirection, so Seam includes some special functionality for handling this problem. - = + - = + Login Redirection - = + - You can ask Seam to redirect the user to a login screen when an un= authenticated user tries = + You can ask Seam to redirect the user to a login screen when an un= authenticated user tries to access a particular view (or wildcarded view id) as follows: - = + = - = + ... - = + ]]> = - (This is less of a blunt instrument than the exception handler sho= wn above, but should = + (This is less of a blunt instrument than the exception handler sho= wn above, but should probably be used in conjunction with it.) - = + After the user logs in, we want to automatically send them back wh= ere they came from, so - they can retry the action that required logging in. If you add the= following event listeners = - to components.xml, attempts to access a restric= ted view while not logged = - in will be remembered, so that upon the user successfully logging = in they will be redirected = + they can retry the action that required logging in. If you add the= following event listeners + to components.xml, attempts to access a restric= ted view while not logged + in will be remembered, so that upon the user successfully logging = in they will be redirected to the originally requested view, with any page parameters that ex= isted in the original request. - = + - = + ]]> - = + - Note that login redirection is implemented as a conversation-scope= d mechanism, so don't end = + Note that login redirection is implemented as a conversation-scope= d mechanism, so don't end the conversation in your authenticate() method. - = + - = + HTTP Authentication - = + - Although not recommended for use unless absolutely necessary, Seam= provides means for authenticating = - using either HTTP Basic or HTTP Digest (RFC 2617) methods. To use= either form of authentication, = + Although not recommended for use unless absolutely necessary, Seam= provides means for authenticating + using either HTTP Basic or HTTP Digest (RFC 2617) methods. To use= either form of authentication, the authentication-filter component must be ena= bled in components.xml: - = + ]]> - = + To enable the filter for basic authentication, set auth-t= ype to basic, or for digest authentication, set it to digest.= If using digest authentication, the @@ -442,55 +442,55 @@ ]]> - = + - The key can be any String value. The = realm is the name of the = + The key can be any String value. The = realm is the name of the authentication realm that is presented to the user when they authe= nticate. - = + Writing a Digest Authenticator - = + If using digest authentication, your authenticator class should = extend the abstract class org.jboss.seam.security.digest.DigestAuthenticator, and use the validatePassword() method to validate the use= r's plain text password against the digest request. Here is an example: - = + - = + - = + Advanced Authentication Features - = + This section explores some of the advanced features provided by th= e security API for addressing more complex security requirements. - = + Using your container's JAAS configuration - = + If you would rather not use the simplified JAAS configuration pr= ovided by the Seam Security API, you may instead delegate to the default system JAAS configuration by pro= viding a jaasConfigName @@ -498,33 +498,33 @@ the other policy (which uses the Use= rsRolesLoginModule login module provided by JBoss AS), then the entry in components.xml= would look like this: - = - ]]> - = + - = + = - = + Error Messages - = + - The security API produces a number of default faces messages for var= ious security-related events. = - The following table lists the message keys that can be used to overr= ide these messages by specifying = + The security API produces a number of default faces messages for var= ious security-related events. + The following table lists the message keys that can be used to overr= ide these messages by specifying them in a message.properties resource file. To s= uppress the message, just put the key with an empty value in the resource file. - = + Security Message Keys - = + - = + @@ -534,16 +534,16 @@ Description - = - = + + - = + org.jboss.seam.loginSuccessful - = + This message is produced when a user successfully logs in = via the security API. @@ -555,7 +555,7 @@ org.jboss.seam.loginFailed - = + This message is produced when the login process fails, eit= her because the user provided an @@ -568,14 +568,14 @@ org.jboss.seam.NotLoggedIn - = + This message is produced when a user attempts to perform a= n action or access a page that requires a security check, and the user is not currently authentica= ted. - = +
@@ -586,15 +586,15 @@ = There are a number of authorization features provided by the Seam Se= curity API for securing access to - components, component methods, and pages. This section describes ea= ch of these. An important thing to = - note is that if you wish to use any of the advanced features (such a= s rule-based permissions) then = + components, component methods, and pages. This section describes ea= ch of these. An important thing to + note is that if you wish to use any of the advanced features (such a= s rule-based permissions) then your components.xml must be configured to support= this - see the Configuration section above. = Core concepts - = + Each of the authorization mechanisms provided by the Seam Security= API are built upon the concept of a user being granted roles and/or permissions. A role is a gro= up, or type, @@ -614,7 +614,7 @@ = Securing components - = + Let's start by examining the simplest form of authorization, compo= nent security, starting with the @Restrict annotation. @@ -632,7 +632,7 @@ on just the component class itself is equivalent to adding @Restrict to each of its methods. - = + An empty @Restrict implies a permission check= of componentName:methodName. Take for example the following component method: @@ -657,7 +657,7 @@ public void insert() { ... } - @Restrict("#{s:hasRole('admin')}") = + @Restrict("#{s:hasRole('admin')}") public void delete() { ... } @@ -717,79 +717,79 @@ If the expression specified doesn't evaluate to true, either - = + - if the user is not logged in, a NotLoggedInEx= ception = + if the user is not logged in, a NotLoggedInEx= ception exception is thrown or - if the user is logged in, an AuthorizationExc= eption = + if the user is logged in, an AuthorizationExc= eption exception is thrown. - = + - It is also possible to call the hasRole() and= hasPermission() = + It is also possible to call the hasRole() and= hasPermission() methods directly from Java code: - = + = - = + - = + Security in the user interface - = + - One indication of a well designed user interface is that the user = is not presented with options for = - which they don't have the necessary privileges to use. Seam Secur= ity allows conditional rendering of = + One indication of a well designed user interface is that the user = is not presented with options for + which they don't have the necessary privileges to use. Seam Secur= ity allows conditional rendering of either 1) sections of a page or 2) individual controls, based upon= the privileges of the user, using the very same EL expressions that are used for component security. - = + - Let's take a look at some examples of interface security. First o= f all, let's pretend that we have a = - login form that should only be rendered if the user is not already= logged in. Using the = + Let's take a look at some examples of interface security. First o= f all, let's pretend that we have a + login form that should only be rendered if the user is not already= logged in. Using the identity.isLoggedIn() property, we can write th= is: - = + ]]> - = + - If the user isn't logged in, then the login form will be rendered = - very straight forward so far. = + If the user isn't logged in, then the login form will be rendered = - very straight forward so far. Now let's pretend there is a menu on the page that contains some a= ctions which should only be accessible to users in the manager role. Here's one way t= hat these could be written: - = + Manager Reports ]]> - = + This is also quite straight forward. If the user is not a member = of the manager role, then the outputLink will not be rendered. The rende= red attribute can - generally be used on the control itself, or on a surrounding <s:div> or = + generally be used on the control itself, or on a surrounding <s:div> or <s:span> control. - = + - Now for something more complex. Let's say you have a h:d= ataTable control on a = + Now for something more complex. Let's say you have a h:d= ataTable control on a page listing records for which you may or may not wish to render a= ction links depending on the user's privileges. The s:hasPermission EL func= tion allows us to pass in an - object parameter which can be used to determine whether the user h= as the requested permission = + object parameter which can be used to determine whether the user h= as the requested permission for that object or not. Here's how a dataTable with secured links = might look: - = + Name @@ -798,7 +798,7 @@ City #{cl.city} - = + Action ]]> = - = + - Securing pages = + Securing pages Page security requires that the application is using a pa= ges.xml file, however is extremely simple to configure. Simply include a <rest= rict/> element within - the page elements that you wish to secure. If = no explicit restriction is specified = - by the restrict element, an implied permission = of /viewId.xhtml:render = - will be checked when the page is accessed via a non-faces (GET) re= quest, and a permission of = + the page elements that you wish to secure. If = no explicit restriction is specified + by the restrict element, an implied permission = of /viewId.xhtml:render + will be checked when the page is accessed via a non-faces (GET) re= quest, and a permission of /viewId.xhtml:restore will be required when any= JSF postback (form submission) originates - from the page. Otherwise, the specified restriction will be evalu= ated as a standard security expression. = + from the page. Otherwise, the specified restriction will be evalu= ated as a standard security expression. Here's a couple of examples: - = + ]]> - = + - This page has an implied permission of /settings.xhtml:re= nder required for non-faces = + This page has an implied permission of /settings.xhtml:re= nder required for non-faces requests and an implied permission of /settings.xhtml:res= tore for faces requests. - = - = + + #{s:hasRole('admin')} ]]> - = + - Both faces and non-faces requests to this page require that the us= er is a member of the = + Both faces and non-faces requests to this page require that the us= er is a member of the admin role. - = + - = + Securing Entities - = - = - Seam security also makes it possible to apply security restriction= s to read, insert, update and = + + + Seam security also makes it possible to apply security restriction= s to read, insert, update and delete actions for entities. - = + To secure all actions for an entity class, add a @Restric= t annotation on the class itself: - = + = - If no expression is specified in the @Restrict = annotation, the default security check = + If no expression is specified in the @Restrict = annotation, the default security check that is performed is a permission check of entityName:act= ion, - where entityName is the Seam component name of = the entity (or the fully-qualified class name if no @Name is = - specified), and the action is either r= ead, = - insert, update or d= elete. = + where entityName is the Seam component name of = the entity (or the fully-qualified class name if no @Name is + specified), and the action is either r= ead, + insert, update or d= elete. - = + - It is also possible to only restrict certain actions, by placing a= @Restrict annotation = + It is also possible to only restrict certain actions, by placing a= @Restrict annotation on the relevent entity lifecycle method (annotated as follows): - = + @PostLoad - Called after an entity instance= is loaded from the database. Use this method to configure a read permission. - = + @PrePersist - Called before a new instance = of the entity is inserted. Use this method to configure an insert permission. - = + @PreUpdate - Called before an entity is upd= ated. Use this method to configure an update permission. - = + @PreRemove - Called before an entity is del= eted. Use this method to configure a delete permission. - = - = - = + + + Here's an example of how an entity would be configured to perform = a security check for any insert - operations. Please note that the method is not required to do any= thing, the only important thing in regard to = + operations. Please note that the method is not required to do any= thing, the only important thing in regard to security is how it is annotated: - = + - = + And here's an example of an entity permission rule that checks if = the authenticated user is allowed to insert a new MemberBlog record (from the seamspace exa= mple). The entity for which the security check is being made is automatically inserted into the working mem= ory (in this case MemberBlog): - = + Principal fact (and other places) is a variabl= e binding - it binds the name property of the Principal to a variable called= principalName. Variable bindings allow the value to be referred to in other places, such as the fo= llowing line which compares the member's username - to the Principal name. For more details, plea= se refer to the JBoss Rules documentation. = + to the Principal name. For more details, plea= se refer to the JBoss Rules documentation. = Finally, we need to install a listener class that integrates Seam= security with your JPA provider. - = + Entity security with JPA - = + Security checks for EJB3 entity beans are performed with an EntityListener. You can install this listener by using the following ME= TA-INF/orm.xml file: - = + - = + @@ -967,93 +967,93 @@ - = + ]]> = - = + Entity security with Hibernate - = + - If you are using a Hibernate SessionFactory c= onfigured via Seam, you don't = + If you are using a Hibernate SessionFactory c= onfigured via Seam, you don't need to do anything special to use entity security. - = + - = + = - = + Writing Security Rules - = + Up to this point there has been a lot of mention of permissions, but= no information about how permissions - are actually defined or granted. This section completes the picture= , by explaining how permission = + are actually defined or granted. This section completes the picture= , by explaining how permission checks are processed, and how to implement permission checks for a S= eam application. - = + Permissions Overview - = + - So how does the security API know whether a user has the = customer:modify permission = + So how does the security API know whether a user has the = customer:modify permission for a specific customer? Seam Security provides quite a novel met= hod for determining user permissions, - based on JBoss Rules. A couple of the advantages of using a rule = engine are 1) a centralized location = - for the business logic that is behind each user permission, and 2)= speed - JBoss Rules uses very efficient = + based on JBoss Rules. A couple of the advantages of using a rule = engine are 1) a centralized location + for the business logic that is behind each user permission, and 2)= speed - JBoss Rules uses very efficient algorithms for evaluating large numbers of complex rules involving= multiple conditions. - = - = + + - = + Configuring a rules file - = + Seam Security expects to find a RuleBase compon= ent called securityRules which it uses to evaluate permission checks. This is configured i= n components.xml as follows: - = + = - = + http://jboss.com/products/seam/security http://jboss.com/= products/seam/security-2.0.xsd"> + /META-INF/security.drl - = - = + + ]]> - = + Once the RuleBase component is configured, it's= time to write the security rules. - = + Creating a security rules file - For this step you need to create a file called security.d= rl in the = + For this step you need to create a file called security.d= rl in the /META-INF directory of your application's jar f= ile. In actual fact this file can be called anything you want, and exist in any location as long as it is conf= igured appropriately in components.xml. - = + - So what should the security rules file contain? At this stage it = might be a good idea to at least skim = + So what should the security rules file contain? At this stage it = might be a good idea to at least skim through the JBoss Rules documentation, however to get started here= 's an extremely simple example: - = + - = + Let's break this down. The first thing we see is the package decl= aration. A package in JBoss Rules is essentially a collection of rules. The package name can be any= thing you want - it doesn't relate to anything else outside the scope of the rule base. - = + The next thing we can notice is a couple of import statements for = the PermissionCheck - and Role classes. These imports inform the rule= s engine that we'll be referencing = + and Role classes. These imports inform the rule= s engine that we'll be referencing these classes within our rules. - = + - Finally we have the code for the rule. Each rule within a package= should be given a unique name (usually = - describing the purpose of the rule). In this case our rule is cal= led CanUserDeleteCustomers = + Finally we have the code for the rule. Each rule within a package= should be given a unique name (usually + describing the purpose of the rule). In this case our rule is cal= led CanUserDeleteCustomers and will be used to check whether a user is allowed to delete a cu= stomer record. - = + Looking at the body of the rule definition we can notice two disti= nct sections. Rules have what is known - as a left hand side (LHS) and a right hand side (RHS). The LHS co= nsists of the conditional part of the = - rule, i.e. a list of conditions which must be satisfied for the ru= le to fire. The LHS is represented by = + as a left hand side (LHS) and a right hand side (RHS). The LHS co= nsists of the conditional part of the + rule, i.e. a list of conditions which must be satisfied for the ru= le to fire. The LHS is represented by the when section. The RHS is the consequence, = or action section of the rule that will only be fired if all of the conditions in the LHS are met. The RH= S is represented by the then section. The end of the rule is denoted b= y the end; line. - = + If we look at the LHS of the rule, we see two conditions listed th= ere. Let's examine the first condition: - = + - = + - In plain english, this condition is stating that there must exist = a PermissionCheck object = + In plain english, this condition is stating that there must exist = a PermissionCheck object with a name property equal to "customer", and a= n action property equal - to "delete" within the working memory. What is the working memory= ? It is a session-scoped object that contains = + to "delete" within the working memory. What is the working memory= ? It is a session-scoped object that contains the contextual information that is required by the rules engine to= make a decision about a permission check. Each time the hasPermission() method is called,= a temporary PermissionCheck object, or Fact, is inserted into the working= memory. This PermissionCheck - corresponds exactly to the permission that is being checked, so fo= r example if you call = + corresponds exactly to the permission that is being checked, so fo= r example if you call hasPermission("account", "create", null) then a= PermissionCheck object with a name equal to "account" and action equal to "create" will be inserted into the working memory for the duration of the permissio= n check. - = + So what else is in the working memory? Besides the short-lived te= mporary facts inserted during a permission check, there are some longer-lived objects in the working memory t= hat stay there for the entire duration of a user being authenticated. These include any java.secur= ity.Principal objects that are created as part of the authentication process, plus a org.jboss.seam.security.Role - object for each of the roles that the user is a member of. It is = also possible to insert additional = + object for each of the roles that the user is a member of. It is = also possible to insert additional long-lived facts into the working memory by calling ((Rul= eBasedIdentity) RuleBasedIdentity.instance()).getSecurityContext().insert()= , passing the object as a parameter. - = + Getting back to our simple example, we can also notice that the fi= rst line of our LHS is prefixed with c:. This is a variable binding, and is used to= refer back to the object that is matched by the condition. Moving onto the second line of our LHS,= we see this: - = + - = + This condition simply states that there must be a Role object with - a name of "admin" within the working memory. A= s mentioned, user roles are inserted = - into the working memory as long-lived facts. So, putting both con= ditions together, this rule is essentially = + a name of "admin" within the working memory. A= s mentioned, user roles are inserted + into the working memory as long-lived facts. So, putting both con= ditions together, this rule is essentially saying "I will fire if you are checking for the customer:= delete permission and the user is a member of the admin role". - = + So what is the consequence of the rule firing? Let's take a look = at the RHS of the rule: - = + - = + - The RHS consists of Java code, and in this case is invoking the grant() = - method of the c object, which as already mentio= ned is a variable binding = + The RHS consists of Java code, and in this case is invoking the grant() + method of the c object, which as already mentio= ned is a variable binding for the PermissionCheck object. Besides the name and action properties of the PermissionChe= ck object, there is also a granted property which is initially s= et to false. - Calling grant() on a PermissionCheck sets the = + Calling grant() on a PermissionCheck sets the granted property to true, wh= ich means that the permission check was successful, allowing the user to carry out whatever acti= on the permission check was intended for. - = + Wildcard permission checks - = + - It is possible to implement a wildcard permission check (which a= llows all actions for a given permission = + It is possible to implement a wildcard permission check (which a= llows all actions for a given permission name), by omitting the action constraint for = the PermissionCheck in your rule, like this: - = + - = + This rule allows users with the admin role to= perform any action for any customer permission check. - = + - = + - = + SSL Security - = + Seam includes basic support for serving sensitive pages via the HTTP= S protocol. This is easily configured by specifying a scheme for the page in= pages.xml. The following example shows how the view /login.xhtml is configured to use HTTPS: - = + ]]> - = + - This configuration is automatically extended to both s:link= and = + This configuration is automatically extended to both s:link= and s:button JSF controls, which (when specifying the= view) - will also render the link using the correct protocol. Based on the = previous example, the following = + will also render the link using the correct protocol. Based on the = previous example, the following link will use the HTTPS protocol because /login.xhtml is configured to use it: - = + ]]> - = + - Browsing directly to a view when using the incorrect protocol will cause a = + Browsing directly to a view when using the incorrect protocol will cause a redirect to the same view using the correct pro= tocol. For example, browsing to a page that has scheme=3D"https" using HTTP wi= ll cause a redirect to the same page using HTTPS. - = + It is also possible to configure a default scheme for all pages. This is useful - if you wish to use HTTPS for a only few pages. If no default scheme = is specified then the normal = - behavior is to continue use the current scheme. So once the user acc= essed a page that required = + if you wish to use HTTPS for a only few pages. If no default scheme = is specified then the normal + behavior is to continue use the current scheme. So once the user acc= essed a page that required HTTPS, then HTTPS would continue to be used after the user navigated= away to other non-HTTPS pages. - (While this is good for security, it is not so great for performance= !). To define HTTP as the = + (While this is good for security, it is not so great for performance= !). To define HTTP as the default scheme, add this line to pages.x= ml: - = + ]]> - = + - Of course, if none of the pages in your applica= tion use HTTPS then it is not = + Of course, if none of the pages in your applica= tion use HTTPS then it is not required to specify a default scheme. - = + You may configure Seam to automatically invalidate the current HTTP = session each time the scheme changes. Just add this line to components.xml: - = + ]]> - = + - This option helps make your system less vulnerable to sniffing of th= e session id or leakage of = + This option helps make your system less vulnerable to sniffing of th= e session id or leakage of sensitive data from pages using HTTPS to other pages using HTTP. - = + - = + CAPTCHA - = + - Though strictly not part of the security API, Seam provides a built-= in CAPTCHA (Completely = - Automated Public Turing test to tell = - Computers and Humans Apart) algorithm to = + Though strictly not part of the security API, Seam provides a built-= in CAPTCHA (Completely + Automated Public Turing test to tell + Computers and Humans Apart) algorithm to prevent automated processes from interacting with your application. - = + Configuring the CAPTCHA Servlet - To get up and running, it is necessary to configure the Seam Resou= rce Servlet, which will provide the Captcha = + To get up and running, it is necessary to configure the Seam Resou= rce Servlet, which will provide the Captcha challenge images to your pages. This requires the following entry= in web.xml: - = + Seam Resource Servlet org.jboss.seam.servlet.SeamResourceServlet - = + Seam Resource Servlet /seam/resource/* ]]> - = + - = + Adding a CAPTCHA to a form - = + Adding a CAPTCHA challenge to a form is extremely easy. Here's an = example: - = + ]]> - = + That's all there is to it. The graphicImage co= ntrol displays the CAPTCHA challenge, - and the inputText receives the user's response.= The response is automatically = + and the inputText receives the user's response.= The response is automatically validated against the CAPTCHA when the form is submitted. - = + - = + Customising the CAPTCHA algorithm - = + You may customize the CAPTCHA algorithm by overriding the built-in= component: - = + = - = + - = + Security Events - = + The following table describes a number of events (see ) raised by Seam Security. - = + Security Events - = + - = + @@ -1347,16 +1347,16 @@ Description - = - = + + - = + org.jboss.seam.security.loginSuccessful - = + Raised when a login attempt is successful. @@ -1368,7 +1368,7 @@ org.jboss.seam.security.loginFailed - = + Raised when a login attempt fails. @@ -1380,109 +1380,109 @@ org.jboss.seam.security.notLoggedIn - = + Raised when a security check fails when the user is not lo= gged in. - = + org.jboss.seam.security.notAuthorized - = + Raised when a security check fails when the user is logged= in however doesn't have sufficient privileges. - = + org.jboss.seam.security.preAuthenticate - = + Raised just prior to user authentication. - = + org.jboss.seam.security.postAuthenticate - = + Raised just after user authentication. - = + org.jboss.seam.security.loggedOut - = + Raised after the user has logged out. - = + org.jboss.seam.security.credentialsUpdated - = + Raised when the user's credentials have been changed. - = + org.jboss.seam.security.rememberMe - = + Raised when the Identity's rememberMe property is changed. - = - = + + -
= - = + + - = + Extending the Identity component - = + Sometimes it might be necessary to extend the Identity component if = your application has special security requirements. For example, users might be required= to authenticate using a Company or Department ID, along with their usual username and pass= word. If permission-based security is required then RuleBasedIdentity should be extended, othe= rwise Identity should be extended. - = - = + + - The following example shows an extended Identity component with an a= dditional = + The following example shows an extended Identity component with an a= dditional companyCode field. The install precendence of APPLICATION ensures that this extended Identity gets installed in preference to = the built-in Identity. - = + = +}]]> = - = + Identity Management - = + Seam Security provides an optional identity management API, which of= fers the following features: - = + @@ -1536,7 +1536,7 @@ A hierarchical role/group membership structure, allowing roles t= o be members of other roles. - = + Pluggable identity store, allowing the developer to choose their= security provider, whether it be @@ -1544,14 +1544,14 @@ - = + The core of the identity management API is the IdentityMana= ger component. Before it can be - used however, it must be configured with an IdentityStore implementation. The = - IdentityStore does the actual work of interacting= with the underlying security provider, = + used however, it must be configured with an IdentityStore implementation. The + IdentityStore does the actual work of interacting= with the underlying security provider, whatever it may be. - = + @@ -1559,35 +1559,35 @@ - = - = + + Configuration - = + - Configuration of the IdentityManager is extreme= ly simple, requiring only an = + Configuration of the IdentityManager is extreme= ly simple, requiring only an IdentityStore to be configured in comp= onents.xml. The identity management namespace is http://jboss.com/pro= ducts/seam/security/management and its schema location is http://jboss.com/products/seam= /identity-management-2.0.xsd. Here's a simple example showing the configuration of a JP= AIdentityStore - for the IdentityManager to use it, it must be named identityStore: - = + = + ]]> - = + JPAIdentityStore - = + JPAIdentityStore is an IdentityStore implementation that uses JPA as its underlying security provider. User accounts and their = role memberships are stored in a - self-referencing database table, for which the corresponding entit= y bean must extend = + self-referencing database table, for which the corresponding entit= y bean must extend org.jboss.seam.security.management.UserAccount = to provide the following properties: - = + @@ -1596,11 +1596,11 @@ - = + To provide a complete example, here's what the actual database tab= les may look like: - = + @@ -1608,42 +1608,42 @@ - = - = + + And an example of the corresponding entity bean: - = + memberships; - = - @Id @GeneratedValue public Integer getAccountId() { return accountId; }= = + + @Id @GeneratedValue public Integer getAccountId() { return accountId; } public void setAccountId(Integer accountId) { this.accountId =3D accoun= tId; } - = - @NotNull @Override public String getUsername() { return username; } = + + @NotNull @Override public String getUsername() { return username; } @Override public void setUsername(String username) { this.username =3D = username; } - = - @Override public String getPasswordHash() { return passwordHash; } = - @Override public void setPasswordHash(String passwordHash) { this.passw= ordHash =3D passwordHash; } = - = - @Override public AccountType getAccountType() { return accountType; } = + + @Override public String getPasswordHash() { return passwordHash; } + @Override public void setPasswordHash(String passwordHash) { this.passw= ordHash =3D passwordHash; } + + @Override public AccountType getAccountType() { return accountType; } @Override public void setAccountType(AccountType accountType) { this.ac= countType =3D accountType; } - = + @Override public boolean isEnabled() { return enabled; } - @Override public void setEnabled(boolean enabled) { this.enabled =3D en= abled; } = + @Override public void setEnabled(boolean enabled) { this.enabled =3D en= abled; } = - @ManyToMany(targetEntity =3D MemberAccount.class) @JoinTable(name =3D "= ACCOUNT_MEMBERSHIP", = + @ManyToMany(targetEntity =3D MemberAccount.class) @JoinTable(name =3D "= ACCOUNT_MEMBERSHIP", joinColumns =3D @JoinColumn(name =3D "ACCOUNT_ID"), inverseJoinColumns =3D @JoinColumn(name =3D "MEMBER_OF")) - @Override public Set getMemberships() { return memberships= ; } = + @Override public Set getMemberships() { return memberships= ; } @Override public void setMemberships(Set memberships) { th= is.memberships =3D memberships; }}]]> = @@ -1654,64 +1654,64 @@ discriminator between the two. With this model, roles can be memb= ers of other roles, making it possible to define complex role membership hierarchies. - = + Once the UserAccount implementation has been cr= eated, the JPAIdentityStore - must be configured to use that implementation any time it performs= an identity management operation. = + must be configured to use that implementation any time it performs= an identity management operation. This is done by specifying the account-class pr= operty in components.xml. In the following example, it is configured as com.acme.Us= erAccount: - = + ]]> = - = + ]]> + Please note that this is a required parameter, and must always be = specified when using the JPAIdentityStore. - = + - = + Authentication with the Identity Management API - = + To authenticate using the Identity Management API, it is as simple= as not specifying the authenticate-method property for the I= dentity component. If no authenticate-method is specified, then by= default the authentication process (controlled by SeamLoginModule) will at= tempt to authenticate using IdentityManager's authenticate() method, and no - Authenticator component is necessary. = + Authenticator component is necessary. - = + Using the IdentityManager API - = + The IdentityManager can be accessed either by i= njecting it into your Seam component as follows: - = - = - = + + + or by accessing it through its static instance() method: = - = + - The following table describes each of the methods that the IdentityManager provides: + The following table describes each of the methods that Id= entityManager provides: - = + Identity Management API - = + - = + @@ -1719,106 +1719,106 @@ Returns - = + Description - = - = + + - = + createAccount(String name, String password) - = + boolean - = + Creates a new user account, with the specified name and = password. Returns true if successful, or false if not. - = - = + + deleteAccount(String name) - = + boolean - = + Deletes the user account with the specified name. Retur= ns true if successful, or false if not. - = - = + + enableAccount(String name) - = + boolean - = + Enables the user account with the specified name. Accou= nts that are not enabled are - not able to authenticate. Returns true if successful, or = + not able to authenticate. Returns true if successful, or false if not. - = - = + + disableAccount(String name) - = + boolean - = + - Disables the user account with the specified name. Retu= rns true if = + Disables the user account with the specified name. Retu= rns true if successful, or false if not. - = + = changePassword(String name, String password) - = + boolean - = + - Changes the password for the user account with the speci= fied name. Returns = + Changes the password for the user account with the speci= fied name. Returns true if successful, or false= if not. @@ -1829,35 +1829,35 @@ isEnabled(String name) - = + boolean - = + - Returns true if the specified user ac= count is enabled, or = + Returns true if the specified user ac= count is enabled, or false if it isn't. - = + = grantRole(String name, String role) - = + boolean - = + Grants the specified role to the specified user account.= The role must already exist for it to - be granted. Returns true if the role= is successfully granted, or = + be granted. Returns true if the role= is successfully granted, or false if it is already granted to the= user. @@ -1868,105 +1868,105 @@ revokeRole(String name, String role) - = + boolean - = + - Revokes the specified role from the specified user accou= nt. Returns true = - if the specified user is a member of the role and it is = successfully revoked, or = + Revokes the specified role from the specified user accou= nt. Returns true + if the specified user is a member of the role and it is = successfully revoked, or false if the user is not a member of = the role. - = + accountExists(String name) - = + boolean - = + Returns true if the specified user ex= ists, or false if it doesn't. - = - = + + listUsers() - = + List - = + Returns a list of all user names, sorted in alpha-numeri= c order. - = - = + + listUsers(String filter) - = + List - = + Returns a list of all user names filtered by the specifi= ed filter parameter, sorted in alpha-numeric order. - = - = + + listRoles() - = + List - = + Returns a list of all role names. - = - = + + getGrantedRoles(String name) - = + List - = + Returns a list of the names of all the roles explicitly = granted to the specified user name. @@ -1979,12 +1979,12 @@ getImpliedRoles(String name) - = + List - = + Returns a list of the names of all the roles implicitly = granted to the specified user name. @@ -2002,12 +2002,12 @@ authenticate(String name, String password) - = + boolean - = + Authenticates the specified username and password using = the configured Identity Store. Returns @@ -2017,25 +2017,282 @@ Identity.login() must be used instead. - = - = + +
- = + + + Using the Identity Management API requires that the calling user h= as the appropriate authorization to invoke + its methods. The following table describes the permission require= ments for each of the methods in + IdentityManager. + + + + Identity Management Security Permissions + + + + + + + + + Method + + + Permission Name + + + Permission Action + + + + + + + + + createAccount() + + + + + seam.account + + + + + create + + + + + + + + deleteAccount() + + + + + seam.account + + + + + delete + + + + + + + + enableAccount() + + + + + seam.account + + + + + update + + + + + + + + disableAccount() + + + + + seam.account + + + + + update + + + + + + + + changePassword() + + + + + seam.account + + + + + update + + + + + + + + isEnabled() + + + + + seam.account + + + + + read + + + + + + + + grantRole() + + + + + seam.account + + + + + update + + + + + + + + revokeRole() + + + + + seam.account + + + + + update + + + + + + + + accountExists() + + + + + seam.account + + + + + read + + + + + + + + listUsers() + + + + + seam.account + + + + + read + + + + + + +
+ + + The following code listing provides an example set of security rul= es that grants access to all + Identity Management-related methods to members of the adm= in role: + + + + - = + Seam-gen and Identity Management - = + - When creating a new project using seam-gen (see ), by default the = + When creating a new project using seam-gen (see ), by default the IdentityManager will be configured with a JPAIdentityStore and a UserAccount implementation will be genera= ted as part of the new project. In addition to this, the project will include the following user m= anagement screens, allowing new users to be created, roles assigned, etc: - = + @@ -2044,11 +2301,11 @@ - = + The user detail screen: - = + @@ -2056,9 +2313,9 @@ - = - = - = + + + = --===============7266230270237131352==--