Getting Started - Five minutes Tutorial

Introduction

This tutorial will show you how to get started using PicketBox using only the default configuration.

This is the fastest way to get started. It is a very nice way to understand some basic concepts and get things working.

For more details about PicketBox configuration, take a look at the Configuration API documentation.

It will demonstrate how to:

Use PicketBox in a Java SE environment. In this case, using a JUnit Test Case.
Configure PicketBox using the default configuration provided by the Configuration API.
Manage users, roles, groups and related information using the Identity Management capabilities provided by the PicketLink IDM project.
Authenticate users using a Username and Password Credential.

requisites

Maven Dependencies

<dependency>
    <groupId>org.picketbox</groupId>
    <artifactId>picketbox-core</artifactId>
    <version>${picketbox.version}</version>
</dependency>

Usage

    private PicketBoxManager picketBoxManager;

    @Before
    public void onSetup() {
        // creates and starts the manager
        createPicketBoxManager();
        
        // populates the identity store with user information
        populateIdentityStore();
    }

    /**
     * Demonstrates how to authenticate users using the PicketBox default configuration.
     * 
     * @throws AuthenticationException
     */
    @Test
    public void testAuthentication() throws AuthenticationException {
        // creates a AUTHENTICATING context
        UserContext authenticatingContext = new UserContext();

        // sets the credential
        authenticatingContext.setCredential(new UsernamePasswordCredential("admin", "admin"));

        // authenticate the user context using the provided credentials
        UserContext authenticatedContext = picketBoxManager.authenticate(authenticatingContext);

        assertNotNull(authenticatedContext);
        assertTrue(authenticatedContext.isAuthenticated());
        assertTrue(authenticatedContext.hasRole("developer"));
        assertTrue(authenticatedContext.hasRole("admin"));
    }

    /**
     * Populates the identity store with user information.
     */
    private void populateIdentityStore() {
        IdentityManager identityManager = picketBoxManager.getIdentityManager();

        SimpleUser adminUser = new SimpleUser("admin");

        // sets some properties
        adminUser.setEmail("admin@picketbox.com");
        adminUser.setFirstName("The");
        adminUser.setLastName("Admin");
        // creates the user
        identityManager.add(adminUser);

        // updates the user credential. In this case a password credential.
        identityManager.updateCredential(adminUser, new PlainTextPassword("admin".toCharArray()));

        // creates some roles
        Role developerRole = new SimpleRole("developer");

        identityManager.add(developerRole);

        Role adminRole = new SimpleRole("admin");

        identityManager.add(adminRole);

        // creates a group
        Group picketBoxGroup = new SimpleGroup("The PicketBox Group");

        identityManager.add(picketBoxGroup);

        // grant the roles to the user and make him member of the group
        identityManager.grantRole(adminUser, developerRole);
        identityManager.grantRole(adminUser, adminRole);

        identityManager.addToGroup(adminUser, picketBoxGroup);
    }

    /**
     * Creates and starts the {@link PicketBoxManager}.
     */
    private void createPicketBoxManager() {
        // creates the configuration builder
        ConfigurationBuilder builder = new ConfigurationBuilder();

        // builds the configuration using the default configuration
        PicketBoxConfiguration configuration = builder.build();

        // instantiates a PicketBoxManager with the default configuration
        this.picketBoxManager = new DefaultPicketBoxManager(configuration);

        // starts the manager
        picketBoxManager.start();
    }

The code above is very simple. It is simple for two reasons:

We are using PicketBox default configuration. See Configuring PicketBox Programmatically for more details.
The default configuration uses a file-based *identity store *from where user, credentials, roles and groups information are stored.

The first thing you need to do is build a PicketBoxConfiguration instance to create and start the PicketBoxManager. In this case we are not defining any specific configuration just using the default one.

    /**
     * Creates and starts the {@link PicketBoxManager}.
     */
    private void createPicketBoxManager() {
        // creates the configuration builder
        ConfigurationBuilder builder = new ConfigurationBuilder();

        // builds the configuration using the default configuration
        PicketBoxConfiguration configuration = builder.build();

        // instantiates a PicketBoxManager with the default configuration
        this.picketBoxManager = new DefaultPicketBoxManager(configuration);

        // starts the manager
        picketBoxManager.start();
    }

Now that the manager is fully started we can use the IdentityManager to populate the configured identity store (in this case a file-based one) with the user information.

    /**
     * Populates the identity store with user information.
     */
    private void populateIdentityStore() {                
        IdentityManager identityManager = picketBoxManager.getIdentityManager();

        SimpleUser adminUser = new SimpleUser("admin");

        // sets some properties
        adminUser.setEmail("admin@picketbox.com");
        adminUser.setFirstName("The");
        adminUser.setLastName("Admin");
        // creates the user
        identityManager.add(adminUser);

        // updates the user credential. In this case a password credential.
        identityManager.updateCredential(adminUser, new PlainTextPassword("admin".toCharArray()));

        // creates some roles
        Role developerRole = new SimpleRole("developer");

        identityManager.add(developerRole);

        Role adminRole = new SimpleRole("admin");

        identityManager.add(adminRole);

        // creates a group
        Group picketBoxGroup = new SimpleGroup("The PicketBox Group");

        identityManager.add(picketBoxGroup);

        // grant the roles to the user and make him member of the group
        identityManager.grantRole(adminUser, developerRole);
        identityManager.grantRole(adminUser, adminRole);

        identityManager.addToGroup(adminUser, picketBoxGroup);
    }

Now that the user information is stored we can proceed with the authentication. To authenticate an user you need to create an empty/authenticating UserContext and set the credentials. In this case we are using a UsernamePasswordCredential.

UserContext authenticatingContext = new UserContext();

authenticatingContext.setCredential(new UsernamePasswordCredential("admin", "admin"));

Let's authenticate the user. If the user was successfully authenticated the PicketBoxManager will return an authenticated UserContext.

// authenticate the user context using the provided credentials
UserContext authenticatedContext = picketBoxManager.authenticate(authenticatingContext);

assertNotNull(authenticatedContext);
assertTrue(authenticatedContext.isAuthenticated()); // user admin was authenticated
assertTrue(authenticatedContext.hasRole("developer")); // user admin has role developer
assertTrue(authenticatedContext.hasRole("admin")); // user admin has role admin

That is it.