File-based user service

User accounts are stored in the user file in the following format:

USERID:ENCRYPTED_PASSWORD[:<comma-delimited list of groups>]

The user service command is provided for creating and editing entries in the user file. You can use the user service command to:

• Create a user account in a user file. If a user file does not exist, it creates a new user file.
• Update a password in a user file.

The user file should be located in the <apphome>/config directory with the filename zero.users. The following sections of this article provide information about the file based user service:

For Eclipse users

Creating a user account

To create a user account with Eclipse, use the following steps:

1. Right click UserServiceCommand.class and from the context menu, select Run As > Java Application.
2. The user service command prompts you to specify a path to a user file and you have the following options:
   • If you are using the default (./config/zero.users), click Enter.
   • If you are not using this default, enter a path name on the Eclipse console and click Enter. The following example shows a path name as you would enter it:

     Jan 29, 2008 1:45:49 PM zero.core.security.userservice.UserServiceCommand getUserInput
     INFO: CWPZC2126I: Location of user file [default ./config/zero.users]:
     /Users/todd/workspace/zero.sample.app/config/zero.users
           

3. When the user service command prompts you for the task, type create on the Eclipse console, as shown in the following example, and click Enter.

   Jan 29, 2008 1:46:36 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2120I: Type 'create' to create user, 'update' to update user or 'exit' when done. 
   create
         

4. When prompted in the Eclipse console, type a user name, a password, and groups as shown in the following example:

   Jan 29, 2008 1:46:39 PM zero.core.security.userservice.UserServiceCommand readParametersFromStandardInput
   INFO: CWPZC2121I: Creating new user. 
   
   Jan 29, 2008 1:46:39 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2127I: Enter username:
   user1
   Jan 29, 2008 1:46:45 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2128I: Enter password:
   password1
   Jan 29, 2008 1:46:51 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2129I: Enter group (or enter when done):
   GROUP1
   Jan 29, 2008 1:46:58 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2129I: Enter group (or enter when done):
   
   Jan 29, 2008 1:47:00 PM zero.core.security.userservice.UserServiceCommand executeCommand
   INFO: CWPZC2115I: User 'user1' was successfully added to the user file.
         

   In this example, you would see the message User "user1" was successfully added to the user file. on the Eclipse console and you would also have a new user entry in the user file:

   user1: 7c6a180b36896a0a8c02787eeafb0e4c : GROUP1

   You can repeat step 3 and 4 to issue other command parameters to add or update users on the Eclipse console.

5. When you finish interaction with the command, type exit at step 3 on the console and click Enter.

Updating a user account

To update a user account with Eclipse, use the following steps:

1. Right click UserServiceCommand.class and, from the context menu, select Run As > Java Application.
2. The user service command prompts you to specify a path to a user file and you have the following options:
   • If you are using the default (./config/zero.users), click Enter.
   • If you are not using this default, enter a path name on the Eclipse console and click Enter. The following example shows a path name as you would enter it:

     Jan 29, 2008 1:45:49 PM zero.core.security.userservice.UserServiceCommand getUserInput
     INFO: CWPZC2126I: Location of user file [default ./config/zero.users]:
     /Users/todd/workspace/zero.sample.app/config/zero.users
           

3. When the user service command prompts you for the task, type update on the Eclipse console, as shown in the following example, and click Enter:

   Jan 29, 2008 1:47:00 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2120I: Type 'create' to create user, 'update' to update user or 'exit' when done. 
   update
         

4. When prompted in the Eclipse console, type a user name and a new password as shown in the following example:

   Jan 29, 2008 1:47:33 PM zero.core.security.userservice.UserServiceCommand readParametersFromStandardInput
   INFO: CWPZC2122I: Updating user. 
   
   Jan 29, 2008 1:47:33 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2127I: Enter username:
   user1
   Jan 29, 2008 1:47:36 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2128I: Enter password:
   pwd1
   Jan 29, 2008 1:47:40 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2123I: Hit enter to update user.
   
   Jan 29, 2008 1:47:42 PM zero.core.security.userservice.UserServiceCommand executeCommand
   INFO: CWPZC2117I: The password of the user 'user1' was successfully updated.
   
   Jan 29, 2008 1:47:42 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2120I: Type 'create' to create user, 'update' to update user or 'exit' when done. 
         

   In this example, you would see the message The password of the user "user1" was successfully updated. on the Eclipse console and you would have an updated entry in the user file.

   You can repeat step 3 and 4 to issue other command parameters to add or update users on the Eclipse console.

5. When you finish interaction with the command, type exit at step 3 on the console and click Enter.

For command line users

The user service is included in the zero.core, therefore you must resolve the zero.core with the following steps:

1. Change to the <zerohome> directory.
2. Add the <zerohome> directory to the path environment variable.
3. Create an application as shown in the following example:

   zero create SampleApp

4. From the <apphome> directory, resolve dependencies using the following command:

   zero resolve

Now you can issue the user service command with the command line. Before you enter any commands note that, by default, all commands expect the user file to be in the following directory: <CURRENT_DIRECTORY>/config/zero.users. Also, it is very important to note whether the commands work correctly for your user file (zero.users). You can specify the path of the user file using -f option in every command syntax.

Creating a user account

To create a user account on the command line, use the following steps:

1. Change to the <apphome>/config directory.
2. Run the user service command as follows:

   zero user

3. The user service command prompts you to specify a path to a user file and you have the following options:
   • If you are using the default (./config/zero.users), click Enter.
   • If you are not using this default, enter a path name and click Enter. The following example shows a path name as you would enter it:

     Jan 29, 2008 1:45:49 PM zero.core.security.userservice.UserServiceCommand getUserInput
     INFO: CWPZC2126I: Location of user file [default ./config/zero.users]:
     /Users/todd/zero/SampleApp/config/zero.users
           

4. When the user service command prompts you for the task, type create on the standard input, as shown in the following example, and click Enter:

   2007/07/25 4:49:33 zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: Type 'create' to create user, 'update' to update user or 'exit' when done. 
   create
         

5. When prompted, type a user name, a password, and groups on the standard input as shown in the following example:

   Jan 29, 2008 1:46:36 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2120I: Type 'create' to create user, 'update' to update user or 'exit' when done. 
   create
   Jan 29, 2008 1:46:39 PM zero.core.security.userservice.UserServiceCommand readParametersFromStandardInput
   INFO: CWPZC2121I: Creating new user. 
   
   Jan 29, 2008 1:46:39 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2127I: Enter username:
   user1
   Jan 29, 2008 1:46:45 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2128I: Enter password:
   password1
   Jan 29, 2008 1:46:51 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2129I: Enter group (or enter when done):
   GROUP1
   Jan 29, 2008 1:46:58 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2129I: Enter group (or enter when done):
   
   Jan 29, 2008 1:47:00 PM zero.core.security.userservice.UserServiceCommand executeCommand
   INFO: CWPZC2115I: User 'user1' was successfully added to the user file.
         

   In this example, you would see the message User "user1" was successfully added to the user file. on the standard output and you would also have a new user entry in the user file:

   user1: 7c6a180b36896a0a8c02787eeafb0e4c : GROUP1

   You can repeat step 3 and 4 to issue other command parameters to add or update users on the standard input.

6. When you finish interaction with the command, type exit at step 3 and click Enter.

Updating a user account

To update a user account on the command line, use the following steps:

1. Change to the <apphome>/config directory.
2. Run the user service command as follows:

   zero user

3. The user service command prompts you to specify a path to a user file and you have the following options:
   • If you are using the default (./config/zero.users), click Enter.
   • If you are not using this default, enter a path name on the standard input and click Enter. The following example shows a path name as you would enter it:

     Jan 29, 2008 1:45:49 PM zero.core.security.userservice.UserServiceCommand getUserInput
     INFO: CWPZC2126I: Location of user file [default ./config/zero.users]:
     /Users/todd/zero/SampleApp/config/zero.users
           

4. When the user service command prompts you for the task, type update on the standard input, as shown in the following example, and click Enter:

   Jan 29, 2008 1:47:00 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2120I: Type 'create' to create user, 'update' to update user or 'exit' when done. 
   update
         

5. When prompted on the standard output, type a user name and a new password as shown in the following example:

   Jan 29, 2008 1:47:33 PM zero.core.security.userservice.UserServiceCommand readParametersFromStandardInput
   INFO: CWPZC2122I: Updating user. 
   
   Jan 29, 2008 1:47:33 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2127I: Enter username:
   user1
   Jan 29, 2008 1:47:36 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2128I: Enter password:
   pwd1
   Jan 29, 2008 1:47:40 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2123I: Hit enter to update user.
   
   Jan 29, 2008 1:47:42 PM zero.core.security.userservice.UserServiceCommand executeCommand
   INFO: CWPZC2117I: The password of the user 'user1' was successfully updated.
   
   Jan 29, 2008 1:47:42 PM zero.core.security.userservice.UserServiceCommand getUserInput
   INFO: CWPZC2120I: Type 'create' to create user, 'update' to update user or 'exit' when done. 
         

   In this example, you would see the message The password of the user "user1" was successfully updated. on the standard output and you would have an updated entry in the user file.

   You can repeat step 3 and 4 to issue other command parameters to add or update users on the standard input.

6. When you finish interaction with the command, type exit at step 3 on the console and click Enter.

Advanced usage - non-interactive mode for command line users

The user service command directly accepts arguments with non-interactive fashion. You can make use of it with the command line.

Creating a user account

To create a user account in non-interactive mode, run the user service command as follows:

zero user [-f USER_FILE_PATH] create USERNAME PASSWORD "[GROUP]*"

For example:

zero user -f /Users/todd/zero/SampleApp/config/zero.users create user1 password1 "GROUP1,TEAM1" 

This adds the following entry to the user file:

user1: 7c6a180b36896a0a8c02787eeafb0e4c : GROUP1,TEAM1

Updating a user account

To update a password in non-interactive mode, run the user service command as follows:

zero user [-f USER_FILE_PATH] update USERNAME PASSWORD

For example:

zero user -f /Users/todd/zero/SampleApp/config/zero.users update user1 pwd1

The following message is returned:

The password of the user "user1" was successfully updated.

Advanced Topic File Base User Service user file.

• Project Zero uses the file based user service as the default. You don't need to configure the zero.config file for the file based user service.
• To delete user accounts and modify groups, you can use any editor because a user file is just a text file.
• If you want to specify zero.users in an arbitrary path and name, you can define it in the zero.config file as shown in the following example:

  
     /config/security/userservice/file/pathToUserfile="./a/b/c/config/zero.users"
     

Web based administration of file-based user service registry

See the Web based administration of file-based user service registry section of the Developer Web tools article on how to leverage this library.