Version 9.8
 —  LoginModules Guide  —

Authentication Process

This document describes how the Software AG Security Infrastructure operates. The information is useful for developers who want to implement the LoginModules.

The information is organized under the following headings:


Overview

Following is an overview of the authentication process in SIN:

  1. An application instantiates a LoginContext

  2. The LoginContext consults a Configuration to load all of the LoginModules configured for that application name.

  3. The application invokes the LoginContext's login method

  4. The login method invokes all of the loaded LoginModules

    Each LoginModule attempts to authenticate the subject. Upon success, LoginModules associate relevant Principals and credentials with a Subject object that represents the subject being authenticated.

  5. The LoginContext returns the authentication status to the application

  6. If authentication is successful, the application retrieves the Subject from the LoginContext, otherwise the LoginException will be thrown

Top of page

Authentication Steps

Start of instruction setTo authenticate a user in SIN

  1. Define the jaas.config file.

    Each LoginModule has specific parameters that must be defined in the jaas.config file.

  2. Define the properties file for log4j.

    Following is an example of a properties file for log4j:

    # Set root logger level to INFO and its only appender to A1.
    log4j.rootLogger=INFO, A1
    
    # A1 is set to be a ConsoleAppender.
    log4j.appender.A1=org.apache.log4j.ConsoleAppender
    
    # A1 uses PatternLayout.
    log4j.appender.A1.layout=org.apache.log4j.PatternLayout
    log4j.appender.A1.layout.ConversionPattern=%d{ABSOLUTE} [%t] %-5p %c %x - %m%n

    See Troubleshooting for additional information on how to handle log4j.

  3. Develop the JAAS client.

  4. Load the JAAS configuration.

    There is one configuration available per JVM. This configuration can contain one or many application contexts, which in turn consist of one or many LoginModules. The JAAS configuration file can be loaded in two different ways depending on the environment:

  5. Set up the credentials.

    Software AG Security JAAS Stack provides the SagCredentials class. All LoginModules support only this type of credentials.

    SagCredentials are queried by SagCallbackHandler, which is the default callback handler for credentials. It supports SagCredentialCallback.

    Upon successful authentication, the SagCredentials can be stored as private credentials in the Subject, from where they can be retrieved by the application.

    Following is a list of user's attributes that SagCredentials sets and retrieves:

  6. Create the LoginContext.

    Following is an example of how to authenticate a user. In this case, you must instantiate a LoginContext:

    import javax.security.auth.login.LoginContext;
    . . .
    LoginContext loginContext = 
        new LoginContext(<configuration_entry_name>,
               <CallbackHandler_to_be_used_for_user_interaction>); 
    

    < configuration entry name > is the name used as the index into the jaas.config file.

  7. After the user is authenticated, the Subject is derived from the LoginContext.

  8. Different types of Principles are derived from an available Subject.

    The Principals architecture in SIN is based on an abstract class - AbstractSagPrincipal - and all other SAG Principals extend it. SIN provides some implemented classes for common use cases: SagUserPrincipal, SagGroupPrincipal, SagRolePrincipal, LightWeightPrincipal. SIN returns no or only one user principal for the authenticated user. It is configurable in the JAAS configuration.

Top of page