Implementing the Login Module Source Code (SAP Library - Developing Applications Using Java)

Show TOC

Implementing the Login Module Source Code

Procedure

Open the MyLoginModuleClass.java file. Implement the Java class:

...

1. Define the class package:

Syntax

package com.sap.example;

2. Import the classes and packages required for the compilation of the class:

Example

import java.util.Map;

import java.io.IOException;

import javax.security.auth.login.LoginException;

import javax.security.auth.Subject;

import javax.security.auth.callback.CallbackHandler;

import javax.security.auth.callback.Callback;

import javax.security.auth.callback.NameCallback;

import javax.security.auth.callback.UnsupportedCallbackException;

import com.sap.engine.interfaces.security.auth.AbstractLoginModule;

import com.sap.engine.lib.security.http.HttpGetterCallback;

import com.sap.engine.lib.security.http.HttpCallback;

import com.sap.engine.lib.security.LoginExceptionDetails;

import com.sap.engine.lib.security.Principal;

3. Use the following syntax to specify that the class MyLoginModuleClass extends AbstractLoginModule class:

Syntax

public class MyLoginModuleClass extends AbstractLoginModule {

...

a. Define the variables for the tutorials example. These are used only for the tutorial:

Example

// Define the variables that will be used later on

// in this example

private CallbackHandler callbackHandler = null;

private Subject subject = null;

private Map sharedState = null;

private Map options = null;

// This is the name of the user you have created on

// the AS Java so you can test the login module

private String userName = null;

private boolean successful;

private boolean nameSet;

b. Create the initialize() method to initialize the login module with the relevant authentication and state information:

Syntax

/**

* The method initialize the login module with the

* relevant authentication and state information.

public void initialize(

Subject subject,

CallbackHandler callbackHandler,

Map sharedState,

Map options) {

...

i. In the initialize() method, define the following obligatory source code:

Syntax

super.initialize(subject, callbackHandler, sharedState, options);

ii. Also initialize the values of the variables for the login module.

Example

// Initializing the values of the variables

this.callbackHandler = callbackHandler;

this.subject = subject;

this.sharedState = sharedState;

this.options = options;

this.successful = false;

this.nameSet = false;

c. Implement the login() method:

Example

/**

* Retrieves the user credentials and checks them. This is

* the first part of the authentication process.

public boolean login() throws LoginException {

...

i. In the login() method, retrieve the user’s credentials using a callback handler.

The type and the name specify which part of the HTTP request should be retrieved. For Web container authentication, the supported types are defined in the interface com.sap.engine.lib.security.http.HttpCallback. For programmatic authentication with a custom callback handler, the supported types depend on the callback handler used.

Example

// In this case we get the user name from the HTTP

// NameCallback.

NameCallback nameCallback = new NameCallback("User name: ");

/* The type and the name specify which part of the HTTP request

* should be retrieved. For Web container authentication, the

* supported types are defined in the interface

* com.sap.engine.lib.security.http.HttpCallback.

* For programmatic authentication with custom callback

* handler the supported types depend on the callback handler used.

try {

callbackHandler.handle(new Callback[] {nameCallback});

}

catch (UnsupportedCallbackException e) {

return false;

}

catch (IOException e) {

throwUserLoginException(e, LoginExceptionDetails.IO_EXCEPTION);

}

userName = nameCallback.getName();

if( userName == null || userName.length() == 0 ) {

return false;

}

ii. Update the user information using data from the persistence once the user name is available from the user. This operation must be done before the checks for the user credentials. This way the login() method verifies the existence of the user name. If the provided user name does not exist in the active user store, the method throws a java.lang.SecurityException:

Example

try {

refreshUserInfo(userName);

} catch (SecurityException e) {

throwUserLoginException(e);

}

iii. Perform a check of the user’s credentials.

Example

/* Checks if the given user name starts with the specified

* prefix in the login module options. If no prefix is specified,

* then all users are trusted.

String prefix = (String) options.get("user_name_prefix");

if ((prefix != null) && !userName.startsWith(prefix)) {

throwNewLoginException("The user is not trusted.");

}

iv. If the authentication is successful, put the user name in a shared state.

One and only one login module from the stack must put the user name in the shared state to represent the authenticated user. For example, if the login is successful, method getRemoteUser() of the HTTP request will retrieve this name. In the example shown below, we also set the variable successful to true and return the value true for the login module.

Example

if (sharedState.get(AbstractLoginModule.NAME) == null) {

sharedState.put(AbstractLoginModule.NAME, userName);

nameSet = true;

}

successful = true;

return true;

d. Implement the commit() method.

In this method you commit the log on. This is the second part of the authentication process. If a user’s name has been stored by the login() method, then this user name is added to the subject of a new principal.

Syntax

public boolean commit() throws LoginException {

...

i. The principals that are added to the subject should implement com.sap.engine.lib.security.Principal:

Example

if (successful) {

/* The principals that are added to the subject should

* implement java.security.Principal. You can use the class

* com.sap.engine.lib.security.Principal for this purpose.

Principal principal = new Principal(userName);

subject.getPrincipals().add(principal);

/* If the login is successful, then the principal corresponding

* to the <userName> (the same user name that has been added

* to the shared state) must be added in the shared state too.

* This principal is considered to be the main principal

* representing the user.

* For example, this principal will be retrieved from method

* getUserPrincipal() of the HTTP request.

if (nameSet) {

sharedState.put(AbstractLoginModule.PRINCIPAL, principal);

}

} else {

userName = null;

}

return true;

e. Implement the abort() method. This method is used for aborting the authentication process:

Example

public boolean abort() throws LoginException {

if (successful) {

userName = null;

successful = false;

}

return true;

}

f. Implement the logout() method: the method logs out the user and also removes the principals and destroys or removes the credentials that were associated with the user during the commit phase.

Example

public boolean logout() throws LoginException {

// Remove principals and credentials from subject

if (successful) {

subject.getPrincipals(Principal.class).clear();

successful = false;

}

return true;

}

Result

The login module class is implemented.

Example

Example Login Module.

More Information

More information about using SAP specific callbacks:

Using the HTTP Callback Classes

Next Step

Exporting the Login Module Class in a JAR File