PicketLink Federation Core 2.1.6.Final-redhat-2

org.picketlink.identity.federation.core.wstrust.auth
Class AbstractSTSLoginModule

java.lang.Object
  extended by 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

    1. Callbackhandler 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>
         </login-module>
       </authentication>
     </application-policy>
     
     
    2. Login module options 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="useOptionsCredentials">true</module-option>
         </login-module>
       </authentication>
     </application-policy>
     
     
    3. Password stacking 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>
       </authentication>
     </application-policy>
     
     

    Password stacking

    Password stacking can be configured which means that a Login module configured with 'password-stacking' set to 'true' will set the username and password in the shared state map. Login modules that come after can set 'password-stacking' to 'useFirstPass' which means that that login module will use the username and password from the shared map.

    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

    Principal and Role mapping providers may be configured on subclasses of this login module and be leveraged to populate the JAAS Subject with appropriate user id and roles. The token is made available to the mapping providers so that identity information may be extracted.

    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
    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 static PicketLinkLogger logger
               
    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
    AbstractSTSLoginModule()
               
     
    Method Summary
     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()
               
    static void removeAllSamlCredentials(Subject subject)
               
    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

    logger

    protected static final PicketLinkLogger logger

    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()

    removeAllSamlCredentials

    public static void removeAllSamlCredentials(Subject subject)

    populateSubject

    protected void populateSubject()

    getMappingManager

    protected org.jboss.security.mapping.MappingManager getMappingManager()

    PicketLink Federation Core 2.1.6.Final-redhat-2

    Copyright © 2013 JBoss by Red Hat. All Rights Reserved.