Running the Custom Identity Store Example

The example described in this section demonstrates how to bundle and use a custom identity store in your application for credential validation.

Topics include:

Overview of the Custom Identity Store Example
Running the custom-identity-store Example

Overview of the Custom Identity Store Example

As an alternative to using a built-in identity store, an application can provide its own IdentityStore. When bundled with the application, this custom identity store can then be used for authentication and authorization.

This example demonstrates how to define a custom identity store, TestIdentityStore, and provide it as part of the application being deployed. The authentication mechanism used is BasicAuthenticationMechanism.

The source code for this example is in the tut-install/examples/security/security-api/custom-identity-store directory.

The following sections describe the high-level process for defining the TestIdentityStore. Note that the configuration described in these sections has already been completed in the application files, but is provided here to illustrate what you need to do to use a custom identity store.

Define the Users and Groups in the Identity Store
Specify the Authentication Mechanism
Declare Roles in the Servlet Container

When a request that includes credentials is sent to the application, the configured authentication mechanism comes into effect and authentication is performed against the TestIdentityStore as defined in the application.

Post authentication, the application also verifies the roles the caller is in and sends the details as part of the response.

Note that in GlassFish, if the user provides the wrong credentials when using BasicAuthenticationMechanism, then the realmName is presented to user, as a hint.

curl -I -u Joe http://localhost:8080/custom-identity-store/servlet
Enter host password for user 'Joe':
HTTP/1.1 401 Unauthorized
Server: GlassFish Server Open Source Edition  5.0
X-Powered-By: Servlet/3.1 JSP/2.3 (GlassFish Server Open Source Edition  5.0  Java/Oracle Corporation/1.8)
WWW-Authenticate: Basic realm="file"
Content-Length: 1090
Content-Language:
Content-Type: text/html

Define the Users and Groups in the Identity Store

The following table shows the user, password, and group used in this example.

User

Password

Group

Joe

secret1

foo, bar

The following code snippet shows how you define the credentials and the roles assigned to users in the TestIdentityStore.java file.

if (usernamePasswordCredential.compareTo("Joe", "secret1")) {
    return new CredentialValidationResult("Joe", new HashSet<>(asList("foo", "bar")));
}

Specify the Authentication Mechanism

In this application, credentials are validated using the BASIC authentication mechanism. Specify the @BasicAuthenticationMechanismDefinition annotation in the ApplicationConfig.java to ensure that the BasicAuthenticationMechanism is used to perform credential validation.

@BasicAuthenticationMechanismDefinition(
        realmName = "file"
)

@ApplicationScoped
@Named
public class ApplicationConfig {

}

Declare Roles in the Servlet Container

When a request is made to the application, the roles the user is in are returned as part of the response. Note that the container needs to be made aware of the supported roles, which are defined using the @Declareroles({ "foo", "bar", "kaz" }) annotation as shown below.

@DeclareRoles({ "foo", "bar", "kaz" })
@WebServlet("/servlet")
public class Servlet extends HttpServlet {

    private static final long serialVersionUID = 1L;

    @Override
    public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

        String webName = null;
        if (request.getUserPrincipal() != null) {
            webName = request.getUserPrincipal().getName();
        }

        response.getWriter().write("web username: " + webName + "\n");

        response.getWriter().write("web user has role \"foo\": " + request.isUserInRole("foo") + "\n");
        response.getWriter().write("web user has role \"bar\": " + request.isUserInRole("bar") + "\n");
        response.getWriter().write("web user has role \"kaz\": " + request.isUserInRole("kaz") + "\n");
    }

}

In GlassFish 5.0, group to role mapping is enabled by default. Therefore, you do not need to bundle web.xml with the application to provide mapping between roles and groups.

Running the custom-identity-store Example

You can use either NetBeans IDE or Maven to build, package, deploy, and run the custom-identity-store application as described in the following topics:

To Build, Package, and Deploy the custom-identity-store Example Using NetBeans IDE
To Build, Package, and Deploy the custom-identity-store Example Using Maven
To Run the custom-identity-store Example

To Build, Package, and Deploy the custom-identity-store Example Using NetBeans IDE

If you have not already done so, start the GlassFish server. See Starting and Stopping GlassFish Server.
From the File menu, choose Open Project.
In the Open Project dialog box, navigate to:
```
tut-install/examples/security/security-api
```
Select the custom-identity-store folder.
Click Open Project.
In the Projects tab, right-click the custom-identity-store project and select Build.

This command builds and deploys the example application to your GlassFish Server instance.

To Build, Package, and Deploy the custom-identity-store Example Using Maven

If you have not already done so, start the GlassFish server. See Starting and Stopping GlassFish Server..

In a terminal window, go to:

tut-install/examples/security/security-api/custom-identity-store

Enter the following command:
```
mvn install
```
This command builds and packages the application into a WAR file, custom-identity-store.war, that is located in the target directory, then deploys the WAR file.

To Run the custom-identity-store Example

In this example, use the credentials of user Joe to make a request and to validate the response according to the credentials defined in TestIdentityStore.

Make a request to the deployed application using valid credentials by entering the following request URL in your web browser:

Request URL:

http://localhost:8080/custom-identity-store/servlet?name=Joe&password=secret1

Response:

web username: Joe
web user has role "foo": true
web user has role "bar": true
web user has role "kaz": false

Test the authentication using invalid credentials. Make a request to the deployed application by entering the following request URL in your web browser:

Request URL:

http://localhost:8080/custom-identity-store/servlet?name=Joe&password=secret3

Response:

HTTP Status 401 - Unauthorized

type Status report

message Unauthorized

description This request requires HTTP authentication.

GlassFish Server Open Source Edition 5