Improve the documentation, please

[mbunkus]

Hey,

I've tried to use your plugin, however, I'm pretty much stumped how it is supposed to work and how to integrate it with existing user accounts.

First, as a user I usually expect that I can somehow link an account to an existing OpenID. However, I couldn't find anything after having logged on on Trac with my user/password. I only see an "Login with OpenID" link when I'm logged off.

So I though "OK cool, let's try that one". I successfully logged in via myopenid.com and trac created a new account for me. This would be OK if I did not have an account on Trac already, however, I'd like to continue using my old account.

Making matters worse my existing account shares the same email address that the newly created account uses -- but they're different user names. Therefore Trac seems to have created a new account, and it has already sent me the activation email, but I cannot activate the new account because says that the email address has already been activated. Bummer.

I can also not see that newly created account on the Trac admin panel in the users list.

Therefore I'm really hoping you can write some more documentation on how both the admin and the user part of your plugin are supposed to work, which features should work and which shouldn't.

Thanks.

[dairiki]

I'll admit the documentation is less than ideal. I don't completely understand all the options either, and I am no trac guru. (I wrote neither the code nor the existing docs.)

I do use the plugin and it works for me. In my case, it is the only authentication method in use. Once someone logs in for the first time, you (the admin) need to somehow figure out his username ("session id"?). There are two ways I know of to do this:

1. trac-admin <path to env> session list. Look for the session with the auth flag set. The value in the first column (SID) is the "username" to which you want to grant priveleges.
2. Have the newly logged in user file a ticket. The ticket will show the username in the "reported by" field.

There is no logic in the plugin to identify users based on email address. Each openid identifier is treated as a unique user. There is a hook which purports to allow you to provide your own web service for mapping openid identifiers to local usernames (this uses the check_list and check_list_username config settings). I haven't used that feature myself.

Sorry for the lousy docs. Both the code and the docs could certainly use some cleanup. When/if I find some time I'll see what I can do. In the mean time, pull requests are welcome.

[chetanvaity]

I used this article to get over the "Trac environment needs to be upgraded" error - http://blog.119labs.com/2010/01/installing-auth-openid-on-trac-with-dreamhost/