Red Hat Training

A Red Hat training course is available for JBoss Enterprise SOA Platform

Chapter 6. Managing User Accounts

6.1. User Accounts

A user needs an account to be able to log in and use the JBoss Enterprise SOA Platform's various web-based consoles. The default security system reads plain text files (namely soa-users.properties and soa-roles.properties) to check a user's password and determine their level of access. SOA uses the Java Authentication and Authorization Service (JAAS) to authenticate user accounts.

Warning

Red Hat does not recommend that you run production servers configured with user passwords in clear text files as it compromises security.

6.2. Create User Accounts

Procedure 6.1. Add a New User

  1. Open the soa-users.properties file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/conf/props/soa-users.properties. Add the user's name and password on a new line, using this syntax: username=password.
    Here is an example for a user with the login name "Harold":
    harold=@dm1nU53r
    

    Note

    Any line in this file that begins with a hash (#) is ignored. (You can use this convention to temporarily disable a user account.)
  2. Save the changes to the file and exit the text editor.
  3. Open the soa-roles.properties file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/conf/props/soa-roles.properties. Add the user and the roles you wish to assign to them on a new line, using this syntax: username=role1,role2,role3.
    harold=JBossAdmin,HttpInvoker,user,admin
    

    Note

    You can assign any number of roles. Note that a user must be assigned the JBossAdmin, HttpInvoker, user and admin roles in order to be able to log into the server consoles.
    Any line in this file that begins with a hash (#) is ignored. You can use this convention to temporarily disable user roles.
  4. Save the changes to the file and exit the text editor.
Result

The user will now be able to log in to the server console at http://localhost:8080. You do not have to restart the server.

6.3. soa-users.properties

The soa-users.properties file is where the user accounts and passwords for accessing the SOA Web consoles are stored. Administrators control access to the system by editing this file. Note that the passwords are saved in clear text so for production systems, password encryption should be used instead.

6.4. soa-roles.properties

The soa-roles.properties file is where user access privileges are defined. This file uses the following syntax: username=role1,role2,role3. You can assign any number of roles. Note that a user must be assigned the JBossAdmin, HttpInvoker, user, and admin roles in order to be able to log into the server consoles.

6.5. Security Roles

Table 6.1. List of Security Permissions for JBoss Enterprise SOA Platform Console Users

Role Description
JBossAdmin The JBossAdmin role is required to log into the various management components of SOA. It is the primary role so all system administrators should be assigned this role.
HttpInvoker The HttpInvoker role is used by the Http Invoker to access JNDIs and EJBs from remote locations.
user This is used to grant user access to services deployed in SOA if they are configured to utilize the JAAS security domains. The jBPM Console relies on this one role only.
admin This is used to grant administrative access to services deployed in SOA if they are configured to utilize the JAAS security domains.

6.6. Disable a User's Account

Procedure 6.2. Disable a User's Account

  1. Open the soa-users.properties file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/conf/props/soa-users.properties. Either delete the entire line containing the user's name and password or simply put a hash (#) in front of it to "comment it out."
    Here is an example for a user with the login name "Harold":
    #harold=@dm1nU53r
    
  2. Save the changes to the file and exit the text editor.
Result

The user will no longer be able to log in to the server console. You do not have to restart the server.

6.7. Security Assertion Markup Language (SAML)

Security Assertion Markup Language (SAML) is a framework compiled in XML. It is used to sercurely pass information between services. It is most commonly used for authentication and identification. With SAML, users can login once and have their identity verified by SAML, thus negating the need to re-enter their credentials repeatedly.
The JBoss ESB uses the SAML provided by PicketLink Project via JAAS Login Modules. It provides users with the ability to assign and validate SAML security tokens.

6.8. Issuing a SAML Security Token

Procedure 6.3. Task

  1. Obtain the Login Module (LM) located in org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule
  2. Open the LM's configuration file.
  3. Enter the following code, inserting the names of the services you wish to use:
    <application-policy name="saml-issue-token">
         <authentication>
             <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule" flag="required">
                 <module-option name="configFile">picketlink-sts-client.properties</module-option>
                 <module-option name="endpointURI">http://security_saml/goodbyeworld</module-option>
             </login-module>
             <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSValidatingLoginModule" flag="required">
                 <module-option name="configFile">picketlink-sts-client.properties</module-option>
             </login-module>
         </authentication>
     </application-policy>
    
    This configuration uses a stacked LM. The security token from the first LM is later used by the second LM which will validate the security token. Having two separate LMs for this can be useful as there can be situations where you only need to validate a security token.
  4. Specify the picketlink-sts-client properties:
    serviceName=PicketLinkSTS
    portName=PicketLinkSTSPort
    endpointAddress=http://localhost:8080/picketlink-sts/PicketLinkSTS
    username=admin
    password=admin
    

    Note

    The username and password in this file are only used by the STSValidatingLoginModule. The username and password may also be stacked or provided by a callback.
  5. To use this LM in JBossESB you need to update your server's login-config.xml with the above application-policy. You must also point the ESB service to where you want this LM to be used.
    For example, this is how you could configure it in jboss-esb.xml:
    <service category="SamlSecurityQuickstart" name="issueTokenService" invmScope="GLOBAL"
        description="This service demonstrates how a service can be configured to issue and validate a security token">
    
     
    
        <security moduleName="saml-issue-token" callbackHandler="org.jboss.soa.esb.services.security.auth.login.JBossSTSIssueCallbackHandler">
            <!-- disable the security context timeout so that our security context is re-evaluated -->
            <property name="org.jboss.soa.esb.services.security.contextTimeout" value="0"/>
        </security>
        ...
    </service>
    
    The callbackHandler that is is specified is specific to the ESB. This is because it requires access to the authentication request in the ESB for retreiving the username and password of the user for whom a security token should be issued.

6.9. Validating a SAML Security Token

Procedure 6.4. Task

  1. Open the Login Module (LM) from org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule.
  2. Configure the properties file as shown in the example below:
            <application-policy name="saml-validate-token">
        <authentication>
            <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSValidatingLoginModule" flag="required">
                <module-option name="configFile">picketlink-sts-client.properties</module-option>
            </login-module>
        </authentication>
    </application-policy>
    
     
    
    And in jboss-esb.xml:
    <service category="SamlSecurityQuickstart" name="securedSamlService" invmScope="GLOBAL"
        description="This service demonstrates that an ESB service can be configured to only validate a security token.">
    
        <security moduleName="saml-validate-token" callbackHandler="org.jboss.soa.esb.services.security.auth.login.JBossSTSTokenCallbackHandler">
            <!-- disable the security context timeout so that our security context is re-evaluated -->
            <property name="org.jboss.soa.esb.services.security.contextTimeout" value="0"/>
        </security>
        ...
    </service>
    

    Note

    The callbackHandler that is specified is specific to the ESB. This is because it requires access to the authentication request in the ESB for retreiving the SAML Token which is to be validated.

    Note

    An example of SAML support in JBossESB can be found in the security_saml quickstart. More information about the Login Modules provied by PicketLink can be found at http://www.jboss.org/community/wiki/STSLoginModules