acs-authentication

This document aims to help you understand how it works and how you can use it for your own purpouses. By Rocael Hernández R.

Main functionality: It is used to authenticate any user in an openacs installations.

So far, you can use it to authenticate against LDAP & PAM, and of course, locally. You can implement your own based on your needs, processes, etc.

Definition: SC = service-contract

Authorities

acs-authentication can have multiple authorities, each one represent a specific configuration of authenticatication. For instance, in your openacs installation you can have users related to different authorities, some of them might authenticate locally since they are external or invited, others belongs to your corporate network and already have users, so might authenticate against LDAP and others in your own work office might use PAM for authentication because your local system authentication. Plus you might define a specific implementation (using the set of SC) to connect to your client DB, which is in another DB, and allow your clients login to certain parts of your website. Then, this is right way to handle all those set of users, that already might have an account in another place and you just want them to authenticate against that external system.

The idea is: each user belongs to a given authority, and just one .

To add an authority in your installation go to /acs-admin/auth/ and click on "Create new authority".

When adding the authority you need to configure:

• Authentication method (where to authenticate, i.e. check user/password)
• Password Management (where to update passwords)
• Account Registration (where to create new accounts)
• On-Demand Sync (to get user info from the source in real time)

Those configurations simply will perform the Tcl proc that is defined in the SC above described for the given SC implementation that you choose. In other words:

• For using LDAP, you need to install auth-ldap, on its installation, this package will create an implementation of the above mentioned SC definitions (look at "specs" that define which proc needs to be called for each alias).
• PAM package is auth-pam.
• Probably, for any new authentication method you'll need to create your own package in the same style of auth-ldap or auth-pam.

Note: "Batch Synchronization" will not be administered there anymore in the future, everything will go to ims-ent.

Also, depending on each implementation, it has a set of parameters that will require for the configuration to work. And those parameters are set independently by authority / authentication method, so for LDAP you'll be able to configure the next set of parameters:

• DNPattern
• UsernameAttribute
• Elements
• BaseDN
• Attributes
• PasswordHash

Then you can enter your specific values for your server, is likely that the recomemded ones will work fine.

Hint: nssha (SSHA) doesn't work well with LDAP use ns_passwd or another encryption method (MD5...)

You can make your users to logging using the email or username, by changing the parameter at the kernel named: UseEmailForLoginP under Security section. If username is used for logging, it will ask for the authority to use, since username is unique by authority but not for the entire openacs installation (can exists several identical usernames but each one belongs to a different authority).

acs-authentication defines a set of SC to interact with the different authentication implementations (LDAP or PAM):

1. auth_authentication "Authenticate users and retrieve their account status.", with the operations:
   • Authenticate
   • GetParameters
2. auth_password "Update, reset, and retrieve passwords for authentication.", with the operations:
   • CanChangePassword
   • ChangePassword
   • CanRetrievePassword
   • RetrievePassword
   • CanResetPassword
   • ResetPassword
   • GetParameters
3. auth_registration "Registering accounts for authentication", with the operations:
   • GetElements
   • Register
   • GetParameters
4. auth_sync_retrieve
5. auth_sync_process
6. auth_user_info
   • GetUserInfo
   • GetParameters

Note: #4 & #5 will be taken out from authentication and moved to the package ims-ent.

The SC definitions are quite straightforward, then worth to look at them for better understanding.

Login process

In an openacs site the login is managed through acs-authentication. It happens like this:

1. The user enters the email/user & password
2. It will search the user in the users table and return the authority_id
3. With that authority_id it will find the respective SC implementation which contains the adequate Tcl proc for the authentication process
4. That proc will check the identity of the user based on the password (right now could be locally, pam or ldap authenticated, though this model supports N methods of authentication)