Reporting Errors and Warnings from Providers

Providers indicate errors and warnings in a variety of ways, including framework and stack trace logging to the logging system. Provider authors can customize exception handling and reporting.

Nearly all provider methods include SecException to indicate a failure. At a minimum, the framework logs the exception's message and stack trace to the logging system. The framework may propagate the message to the client, depending on the situation. Propagation makes exceptions accessible to the clients. The framework can add or log exceptions to the context warning list for troubleshooting purposes.

On the provider side, these interfaces enable adding warnings to the context that can be retrieved by the client:

package com.sybase.security.provider;

public interface WarningManager {
	void addWarning(SecProvider provider, SecWarning warning);
	void addWarning(javax.security.auth.spi.LoginModule provider, 
				SecWarning warning);
}

public interface ProviderConst {
	...
	public static final String WARNING_MANAGER = " CSI.warningManager ";
	public static final String PROVIDER_SERVICES = "CSI.providerServices";
}

A provider can add a warning to the context by retrieving the warning manager or provider services from the context map. This example shows how a login module can add a warning of you've been warned from the login method:

public class ExampleLoginModule implements javax.security.auth.spi.LoginModule {
	private Map context;

	public void initialize(Subject subject, 
				CallbackHandler callbackHandler,
				Map sharedState,
				Map options) {
		context = sharedState;
	}
	
	public boolean login()throws LoginException 
         {
         
		ProviderServices providerSvcs =
			(ProviderServices)context.get(ProviderConst. PROVIDER_SERVICES);
		
		providerSvcs.addWarning(this, 
         new SimpleWarning("you've been warned"));
		

		return true;
	}

	// ... other methods snipped for brevity
}

Use the same techniques from all other provider types, as well as the supplied context map. When a LoginException is thrown from the login method of an authentication provider, the framework automatically adds a warning to the warning list. If the LoginException instance already implements the SecWarning interface, the exception itself is added as a warning. Otherwise, the exception is wrapped in a lightweight wrapper (com.sybase.security.provider.SecLoginExceptionWarningImpl).

A provider can use the com.sybase.security.provider.SecLoginExceptionAuthenticationFailureWarningImplclass to simultaneously signify login failure and supply a more specific failure reason mapped from com.sybase.security.core.AuthenticationFailureReasons.

For more details, see the javadoc for these classes.