
	Version 9.8	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— 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
Authentication Steps

Overview

Following is an overview of the authentication process in SIN:

An application instantiates a LoginContext
The LoginContext consults a Configuration to load all of the LoginModules configured for that application name.
The application invokes the LoginContext's login method
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.
The LoginContext returns the authentication status to the application
If authentication is successful, the application retrieves the Subject from the LoginContext, otherwise the LoginException will be thrown

Authentication Steps

To authenticate a user in SIN

Define the jaas.config file.

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

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.

Develop the JAAS client.
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:
- Inside the Common Runtime, the JAAS configuration file will be loaded from location that is pointed by the java.security.auth.login.config property in the profile's config.ini file. The location of the jaas.config file is specified in the value of the java.security.auth.login.config property.
- Outside of the Common Runtime, the JAAS configuration will be loaded from location that is pointed by java.security.auth.login.config Java system property. For this approach, a variable has to be set by the application either at start time as a parameter of a Java VM or programmatically.
  
  Set the variable as a Java VM system property:
```
-Djava.security.auth.login.config=<URL to configuration>
```
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:
- Domain name
- Password
- User name
- X.509 certificate chain including user certificate and the issuer certificate (excluding the root certificate)
- SAML artifact
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.
After the user is authenticated, the Subject is derived from the LoginContext.
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.

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT