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 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
SagCredential
s 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.