AbstractSTSLoginModule (JBoss Application Server: Build 7.1.2.Final API)

java.lang.Object
- org.picketlink.identity.federation.core.wstrust.auth.AbstractSTSLoginModule

All Implemented Interfaces:

LoginModule

Direct Known Subclasses:

STSIssuingLoginModule, STSValidatingLoginModule
```
public abstract class AbstractSTSLoginModule
extends Object
implements LoginModule
```
Abstract JAAS LoginModule for JBoss STS (Security Token Service).
Subclasses are required to implement invokeSTS(STSClient)() to perform their specific actions.
Configuration
Concrete implementations specify from where the username and credentials should be read from.
Callback handler, NameCallback and PasswordCallback.
From the login modules options configuration.
From the login modules earlier in the login modules stack.

Configuration example

 <application-policy name="saml-issue-token">
   <authentication>
     <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule" flag="required">
       <module-option name="configFile">/sts-client.properties</module-option>
     </login-module>
   </authentication>
 </application-policy>

 <application-policy name="saml-issue-token">
   <authentication>
     <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule" flag="required">
       <module-option name="configFile">/sts-client.properties</module-option>
       <module-option name="useOptionsCredentials">true</module-option>
     </login-module>
   </authentication>
 </application-policy>

 <application-policy name="saml-issue-token">
   <authentication>
     <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule" flag="required">
       <module-option name="configFile">/sts-client.properties</module-option>
       <module-option name="password-stacking">useFirstPass</module-option>
     </login-module>
   </authentication>
 </application-policy>

Password stacking

4. Mapping Provider configuration:

 <application-policy name="saml-issue-token">
   <authentication>
     <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule" flag="required">
       <module-option name="configFile">/sts-client.properties</module-option>
       <module-option name="password-stacking">useFirstPass</module-option>
     </login-module>
     <mapping>
       <mapping-module code="org.picketlink.identity.federation.bindings.jboss.auth.mapping.STSPrincipalMappingProvider" type="principal"/>
       <mapping-module code="org.picketlink.identity.federation.bindings.jboss.auth.mapping.STSGroupMappingProvider" type="role"/>
     </mapping>
   </authentication>
 </application-policy>

Mapping Providers

Subclasses can define more configuration options by overriding initialize. Also note that subclasses are not forced to put configuration options in a file. They can all be set as options just like the 'configFile' is specified above.

Additional Configuration

roleKey: By default, the saml attributes with key "Role" are assumed to represent user roles. You can configure a comma separated list of string values to represent the attribute names for user roles.

cache.invalidation: set it to true if you require invalidation of JBoss Auth Cache at SAML Principal expiration.

jboss.security.security_domain: name of the security domain where this login module is configured. This is only required if the cache.invalidation option is configured.

inject.callerprincipal: set it to true if you want to add a group principal called "CallerPrincipal" with the roles from the assertion, into the subject

Author:: Daniel Bevenius, Anil.Saldhana@redhat.com

Field Summary

Fields
Modifier and Type	Field and Description
`protected CallbackHandler`	`callbackHandler` Callback handler used to gather information from the caller.
`protected boolean`	`enableCacheInvalidation`
`static String`	`ENDPOINT_ADDRESS` Key to specify the end point address
`protected boolean`	`injectCallerPrincipalGroup` Should a separate Group Principal called "CallerPrincipal" be injected into subject with the roles from the assertion?
`static String`	`IS_BATCH` Key to specify whether this batch issue request
`protected boolean`	`isBatch` Value to indicate whether the RST is a batch request
`protected Map<String,?>`	`options` The options map passed into this login modules initalize method.
`static String`	`OPTIONS_CREDENTIALS` Options configuration name;
`static String`	`OPTIONS_PW_STACKING` Options configuration name;
`static String`	`PASSWORD_KEY` Key to specify the password
`protected boolean`	`passwordStacking` Indicates whether password stacking option was configured.
`static String`	`PORT_NAME` Key to specify the port name
`static String`	`ROLE_KEY` Attribute names indicating the user roles
`protected String`	`roleKey` Name of the saml attribute representing roles.
`protected Element`	`samlToken` WS-Trust SAML Assertion element.
`protected String`	`securityDomain`
`static String`	`SERVICE_NAME` Key to specify the service name
`static String`	`SHARED_TOKEN` Key used in share state map when LMs are stacked.
`protected Map`	`sharedState` The shared state map passed into this login modules initalize method.
`static String`	`STS_CONFIG_FILE` This is the required option that should identify the configuration file for WSTrustClient.
`protected Subject`	`subject` The subject to be populated.
`protected boolean`	`success` The outcome of the authentication process.
`protected boolean`	`useFirstPass` Indicates whether the password-stacking options was specifed as 'useFirstPass'.
`protected boolean`	`useOptionsCredentials` Indicates whether the 'useOptionsCredentials' was configured.
`static String`	`USERNAME_KEY` Key to specify the username

Constructor Summary

Constructors
Constructor and Description

AbstractSTSLoginModule()

Constructors
Constructor and Description
`AbstractSTSLoginModule()`

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`abort()` Called if the overall authentication failed (phase 2).
`boolean`	`commit()` Commit will package the samlToken set by the login method in a new `SamlCredential`.
`protected STSClientConfig.Builder`	`createBuilder()` Subclasses can override and create a preconfigured builder
`protected STSClient`	`createWSTrustClient(STSClientConfig config)`
`protected CallbackHandler`	`getCallbackHandler()`
`protected STSClientConfig`	`getConfiguration(Map<String,?> options)` This method gives users a chance to override how the `STSClientConfig` is created.
`protected org.jboss.security.mapping.MappingManager`	`getMappingManager()`
`protected Map<String,?>`	`getOptions()` Gets the options provided to this LM in it's `initialize(Subject, CallbackHandler, Map, Map)`.
`protected String`	`getRequiredOption(Map<String,?> options, String optionName)`
`protected char[]`	`getSharedPassword()`
`protected Object`	`getSharedToken()` Gets Security Token from the share state map if one was made available by a previous LM in the stack.
`protected String`	`getSharedUsername()`
`protected Subject`	`getSubject()`
`void`	`initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options)` Initialized this login module.
`abstract Element`	`invokeSTS(STSClient stsclient)`
`protected boolean`	`isSuccess()`
`protected boolean`	`isUseFirstPass()`
`protected boolean`	`isUseOptionsConfig()`
`protected boolean`	`isUsePasswordStacking()`
`boolean`	`login()` Subclasses must implement the login to perform their specific tasks.
`boolean`	`logout()`
`protected void`	`populateSubject()`
`protected void`	`setSamlToken(Element samlToken)`
`protected void`	`setSharedToken(Object token)`
`protected void`	`setSuccess(boolean success)`
`protected void`	`useCredentialsFromCallback(STSClientConfig.Builder builder)`
`protected void`	`useCredentialsFromOptions(STSClientConfig.Builder builder, Map<String,?> options2)` This method allows subclassed to retreive configuration options map and set on the builder.
`protected void`	`useCredentialsFromSharedState(STSClientConfig.Builder builder)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - SHARED_TOKEN
```
public static final String SHARED_TOKEN
```
    Key used in share state map when LMs are stacked.
    
    See Also:
    Constant Field Values
  - OPTIONS_CREDENTIALS
```
public static final String OPTIONS_CREDENTIALS
```
    Options configuration name;
    
    See Also:
    Constant Field Values
  - OPTIONS_PW_STACKING
```
public static final String OPTIONS_PW_STACKING
```
    Options configuration name;
    
    See Also:
    Constant Field Values
  - STS_CONFIG_FILE
```
public static final String STS_CONFIG_FILE
```
    This is the required option that should identify the configuration file for WSTrustClient.
    
    See Also:
    Constant Field Values
  - ROLE_KEY
```
public static final String ROLE_KEY
```
    Attribute names indicating the user roles
    
    See Also:
    Constant Field Values
  - ENDPOINT_ADDRESS
```
public static final String ENDPOINT_ADDRESS
```
    Key to specify the end point address
    
    See Also:
    Constant Field Values
  - PORT_NAME
```
public static final String PORT_NAME
```
    Key to specify the port name
    
    See Also:
    Constant Field Values
  - SERVICE_NAME
```
public static final String SERVICE_NAME
```
    Key to specify the service name
    
    See Also:
    Constant Field Values
  - USERNAME_KEY
```
public static final String USERNAME_KEY
```
    Key to specify the username
    
    See Also:
    Constant Field Values
  - PASSWORD_KEY
```
public static final String PASSWORD_KEY
```
    Key to specify the password
    
    See Also:
    Constant Field Values
  - IS_BATCH
```
public static final String IS_BATCH
```
    Key to specify whether this batch issue request
    
    See Also:
    Constant Field Values
  - subject
```
protected Subject subject
```
    The subject to be populated.
  - callbackHandler
```
protected CallbackHandler callbackHandler
```
    Callback handler used to gather information from the caller.
  - samlToken
```
protected Element samlToken
```
    WS-Trust SAML Assertion element.
  - success
```
protected boolean success
```
    The outcome of the authentication process.
  - options
```
protected Map<String,?> options
```
    The options map passed into this login modules initalize method.
  - sharedState
```
protected Map sharedState
```
    The shared state map passed into this login modules initalize method.
  - passwordStacking
```
protected boolean passwordStacking
```
    Indicates whether password stacking option was configured.
  - useFirstPass
```
protected boolean useFirstPass
```
    Indicates whether the password-stacking options was specifed as 'useFirstPass'.
  - useOptionsCredentials
```
protected boolean useOptionsCredentials
```
    Indicates whether the 'useOptionsCredentials' was configured.
  - roleKey
```
protected String roleKey
```
    Name of the saml attribute representing roles. Can be csv
  - enableCacheInvalidation
```
protected boolean enableCacheInvalidation
```
  - injectCallerPrincipalGroup
```
protected boolean injectCallerPrincipalGroup
```
    Should a separate Group Principal called "CallerPrincipal" be injected into subject with the roles from the assertion?
  - securityDomain
```
protected String securityDomain
```
  - isBatch
```
protected boolean isBatch
```
    Value to indicate whether the RST is a batch request
- Constructor Detail
  - AbstractSTSLoginModule
```
public AbstractSTSLoginModule()
```
- Method Detail
  - initialize
```
public void initialize(Subject subject,
              CallbackHandler callbackHandler,
              Map<String,?> sharedState,
              Map<String,?> options)
```
    Initialized this login module. Simple stores the passed in fields and also validates the options.
    
    Specified by:
    
    initialize in interface LoginModule
    
    Parameters:
    subject - The subject to authenticate/populate.
    callbackHandler - The callbackhandler that will gather information required by this login module.
    sharedState - State that is shared with other login modules. Used when modules are chained/stacked.
    options - The options that were specified for this login module.
  - login
```
public boolean login()
              throws LoginException
```
    Subclasses must implement the login to perform their specific tasks. The login module should call setSamlToken(Element) with the saml token element that should be added to the public credentials in commit().
    
    Specified by:
    
    login in interface LoginModule
    
    Returns:
    true If the login was successful otherwise false.
    
    Throws:
    
    LoginException - If an error occurs while trying to perform the authentication.
  - invokeSTS
```
public abstract Element invokeSTS(STSClient stsclient)
                           throws WSTrustException,
                                  LoginException
```
    Throws:
    
    WSTrustException
    
    LoginException
  - commit
```
public boolean commit()
               throws LoginException
```
    Commit will package the samlToken set by the login method in a new SamlCredential. This new SamlCredential will be put into the Subject public credentials set.
    
    Specified by:
    
    commit in interface LoginModule
    
    Throws:
    
    LoginException
  - abort
```
public boolean abort()
              throws LoginException
```
    Called if the overall authentication failed (phase 2).
    
    Specified by:
    
    abort in interface LoginModule
    
    Throws:
    
    LoginException
  - logout
```
public boolean logout()
               throws LoginException
```
    Specified by:
    
    logout in interface LoginModule
    
    Throws:
    
    LoginException
  - createBuilder
```
protected STSClientConfig.Builder createBuilder()
```
    Subclasses can override and create a preconfigured builder
    
    Returns:
  - useCredentialsFromCallback
```
protected void useCredentialsFromCallback(STSClientConfig.Builder builder)
                                   throws LoginException
```
    Throws:
    
    LoginException
  - useCredentialsFromSharedState
```
protected void useCredentialsFromSharedState(STSClientConfig.Builder builder)
```
  - useCredentialsFromOptions
```
protected void useCredentialsFromOptions(STSClientConfig.Builder builder,
                             Map<String,?> options2)
```
    This method allows subclassed to retreive configuration options map and set on the builder.
    
    Parameters:
    builder -
    options -
  - getConfiguration
```
protected STSClientConfig getConfiguration(Map<String,?> options)
```
    This method gives users a chance to override how the STSClientConfig is created. For example some users might perfer to not use a file containing the configuration properties, which is the default, but instead have the configuration options in the login modules configuration directly.
    
    Parameters:
    options - The options passed to the initialize method.
    
    Returns:
    STSClientConfig The configuration for STSClient.
  - createWSTrustClient
```
protected STSClient createWSTrustClient(STSClientConfig config)
```
  - getRequiredOption
```
protected String getRequiredOption(Map<String,?> options,
                       String optionName)
```
  - isSuccess
```
protected boolean isSuccess()
```
  - setSuccess
```
protected void setSuccess(boolean success)
```
  - getSubject
```
protected Subject getSubject()
```
  - getCallbackHandler
```
protected CallbackHandler getCallbackHandler()
```
  - setSamlToken
```
protected void setSamlToken(Element samlToken)
```
  - setSharedToken
```
protected void setSharedToken(Object token)
```
  - getSharedToken
```
protected Object getSharedToken()
```
    Gets Security Token from the share state map if one was made available by a previous LM in the stack.
    
    Returns:
    Object A security token if one was stored in the shared state map. Or null if one does not exist.
  - getOptions
```
protected Map<String,?> getOptions()
```
    Gets the options provided to this LM in it's initialize(Subject, CallbackHandler, Map, Map).
    
    Returns:
    Map The options map.
  - getSharedUsername
```
protected String getSharedUsername()
```
  - getSharedPassword
```
protected char[] getSharedPassword()
```
  - isUseFirstPass
```
protected boolean isUseFirstPass()
```
  - isUsePasswordStacking
```
protected boolean isUsePasswordStacking()
```
  - isUseOptionsConfig
```
protected boolean isUseOptionsConfig()
```
  - populateSubject
```
protected void populateSubject()
```
  - getMappingManager
```
protected org.jboss.security.mapping.MappingManager getMappingManager()
```

Class AbstractSTSLoginModule

Configuration

Configuration example

Password stacking

Mapping Providers

Additional Configuration

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SHARED_TOKEN

OPTIONS_CREDENTIALS

OPTIONS_PW_STACKING

STS_CONFIG_FILE

ROLE_KEY

ENDPOINT_ADDRESS

PORT_NAME

SERVICE_NAME

USERNAME_KEY

PASSWORD_KEY

IS_BATCH

subject

callbackHandler

samlToken

success

options

sharedState

passwordStacking

useFirstPass

useOptionsCredentials

roleKey

enableCacheInvalidation

injectCallerPrincipalGroup

securityDomain

isBatch

Constructor Detail

AbstractSTSLoginModule

Method Detail

initialize

login

invokeSTS

commit

abort

logout

createBuilder

useCredentialsFromCallback

useCredentialsFromSharedState

useCredentialsFromOptions

getConfiguration

createWSTrustClient

getRequiredOption

isSuccess

setSuccess

getSubject

getCallbackHandler

setSamlToken

setSharedToken

getSharedToken

getOptions

getSharedUsername

getSharedPassword

isUseFirstPass

isUsePasswordStacking

isUseOptionsConfig

populateSubject

getMappingManager