Spring Security
  1. Spring Security
  2. SEC-1170

Improve documentation on how to use UserDetails

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 2.0.4
    • Fix Version/s: 3.0.0 M2
    • Component/s: Docs and Website
    • Labels:
      None

      Description

      UserDetails concept in Spring Security is nice, but not well documented. Docs say it is used for represent additional data, like user e-mail, but they say it must be immutable. What if user wants to change this e-mail? What it is the valid implementation of this? What is the correct approach for changing the password? How to plug the Hibernate-managed User entity (which is mutable) into immutable UserDetails? What's the role of Spring Security cache, how it integrates with Hibernate caches? etc.
      Those are very very basic questions. Documentation should explain clearly such basic cases.

        Activity

        Hide
        Luke Taylor added a comment -

        There isn't really a great deal to document - it's a very simple interface and if you have a stateless application you may want to use caching to prevent constantly hitting the database.

        I think the comment about immutability was probably just Ben being cautious when the code was first written. Obviously the object may be accessed from multiple threads and you might run into issues with ConcurrentModificationException if you updated the authorities list while iterating over it in another thread. These are standard threading issues though. There isn't anything in the framework which I'm aware of which would require that the object be immutable but it usually makes sense to program with immutable objects if you can. Your code will be much more robust. There may be some applications where the end users are able to edit velocity or freemarker templates (or even JSPs). Making the classes immutable also makes them less prone to being modified through technologies like these. But ultimately it's up to you to be fully aware of these possibilities and cater for them.

        I disagree that issues such as integration with Hibernate and its caching mechanisms are "very very basic" questions which should be in the documentation. Spring Security has nothing to say about whether you use Hibernate (or indeed any other ORM technology, object database or whatever). It just provides the interfaces and if you choose to implement them using Hibernate then its up to you to understand fully how Hibernate behaves.

        I'll update the Javadocs of the UserDetails class to state that immutability is advised but not essential.

        Show
        Luke Taylor added a comment - There isn't really a great deal to document - it's a very simple interface and if you have a stateless application you may want to use caching to prevent constantly hitting the database. I think the comment about immutability was probably just Ben being cautious when the code was first written. Obviously the object may be accessed from multiple threads and you might run into issues with ConcurrentModificationException if you updated the authorities list while iterating over it in another thread. These are standard threading issues though. There isn't anything in the framework which I'm aware of which would require that the object be immutable but it usually makes sense to program with immutable objects if you can. Your code will be much more robust. There may be some applications where the end users are able to edit velocity or freemarker templates (or even JSPs). Making the classes immutable also makes them less prone to being modified through technologies like these. But ultimately it's up to you to be fully aware of these possibilities and cater for them. I disagree that issues such as integration with Hibernate and its caching mechanisms are "very very basic" questions which should be in the documentation. Spring Security has nothing to say about whether you use Hibernate (or indeed any other ORM technology, object database or whatever). It just provides the interfaces and if you choose to implement them using Hibernate then its up to you to understand fully how Hibernate behaves. I'll update the Javadocs of the UserDetails class to state that immutability is advised but not essential.
        Hide
        Grzegorz Borkowski added a comment -

        Well, the "very very basic questions" relate to fact that UserDetails according to documentation is supposed to keep data that are typically stored in Hibernate/JPA entities, and at the same time its JavaDoc says it must be immutable. It's hard to me to imagine how to implement it using mutable Hibernate entities in immutable way. That's why it's so problematic.

        If you say immutability has nothing to do with actual framework implementation, it changes the picture significantly.
        Actually, all objects stored in session are advised to be immutable, because you can access them from different threads: but it is rather problem for application programmer, not framework author, to bother...

        Show
        Grzegorz Borkowski added a comment - Well, the "very very basic questions" relate to fact that UserDetails according to documentation is supposed to keep data that are typically stored in Hibernate/JPA entities, and at the same time its JavaDoc says it must be immutable. It's hard to me to imagine how to implement it using mutable Hibernate entities in immutable way. That's why it's so problematic. If you say immutability has nothing to do with actual framework implementation, it changes the picture significantly. Actually, all objects stored in session are advised to be immutable, because you can access them from different threads: but it is rather problem for application programmer, not framework author, to bother...
        Hide
        Luke Taylor added a comment -

        Well, there's no reason why you have to actually use your Hibernate entities as the UserDetails implementation. You can easily create a value object from something else that is mutable, so your UserDetails object can be independent from Hibernate if you want it to be. I don't really see why that should cause any major headaches. In practice, if you wanted to change a user's authorities or some other details at runtime and wanted to see an immediate effect, then you would probably do the update separately and force a reauthentication (possibly transparently) to replace the security context contents.

        Show
        Luke Taylor added a comment - Well, there's no reason why you have to actually use your Hibernate entities as the UserDetails implementation. You can easily create a value object from something else that is mutable, so your UserDetails object can be independent from Hibernate if you want it to be. I don't really see why that should cause any major headaches. In practice, if you wanted to change a user's authorities or some other details at runtime and wanted to see an immediate effect, then you would probably do the update separately and force a reauthentication (possibly transparently) to replace the security context contents.

          People

          • Assignee:
            Luke Taylor
            Reporter:
            Grzegorz Borkowski
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: