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:
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
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 default configuration will be loaded
from the URL defined by the environment variable
java.security.auth.login.config. This variable has
to be set by the application, either at start time as a parameter to the Java
VM, or programmatically.
Set the variable like a Java VM system variable:
-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.