USER_IDs, EIDs, Providers, Oh My!

I received feedback that the following notes on Sakai's LDAP provider behavior would be worthwhile archiving more visibly than on the Sakai dev list, so I'm reprinting them here. See here for the context of the entire thread.

...snip....

1. EID vs USER_ID -- Pre-populating SAKAI_USER_ID_MAP is not a problem. Changing EID values in that table is also mostly OK, but might not be respected by all tools. _Changing_ USER_ID values in that table _is_ a problem. USER_ID is a database artifact and is effectively used as a foreign key in other tables. So there's nothing wrong with using your employee IDs as USER_IDs, per se, as long as they are unique and immutable. You will be in for disappointment, though, if your process involves creating users via Sakai, then trying to change their USER_IDs in the database later. IMHO, you should treat employee IDs as user attributes (served from LDAP or stored locally in SAKAI_USER_PROPERTY) rather than as the user's database key.
2. Pre-Populating SAKAI_USER -- This is fine, but keep in mind that for the purposes of sourcing attributes, a user is either local or provided. There is no merging of attributes across the Sakai database and your LDAP tree. Also keep in mind that if you're using the vanilla LDAP provider, Sakai prefers local attributes (there are special cases where Sakai could be configured prefer provided attributes, but only at authentication time). So if a user is pre-loaded into SAKAI_USER, Sakai will not check LDAP for that user's attributes. It only makes sense to do so, then, if you only want to use the LDAP provider for authentication.
3. Authentication -- Hard to say why your users are not able to authenticate any longer. Sakai will attempt LDAP authN first, if the authenticateWithProviderFirst flag is set on the provider. If that flag is not set or provider authN fails, Sakai attempts local authN. Failing that, Sakai falls back to provider authN unless authenticateWithProviderFirst was set. There's not much logging in the UserDirectoryService to tell you what's going on, but your best bet is probably to turn up logging in both the service and provider to get an idea of whether or not it's even being invoked and when. In sakai.properties or local.properties:
   

   log.config.count=2
   log.config.1=DEBUG.edu.amc.sakai.user
   log.config.2=DEBUG.org.sakaiproject.user.impl

4. Strict Local Attributes with Provider AuthN -- I.e. do not allow authN or attribute lookup unless the user's account already exists in SAKAI_USER. It is awkward to do this, so the first question I think should be the classic: "Why?". But assuming you have a good reason, what you need to do is prevent the provider from responding positively to findUserByEmail(), getUser(), getUsers(), and getUserExists(). The easiest way to do this at the moment, I think, is to write a subclass of JLDAPDirectoryProvider which overrides those methods to return false/empty/null results

...snip...