Red Hat JBoss Enterprise ApplicationPlatform 6.4

Security Guide

DEPRECATED. This book covers security concepts and procedures to harden theEAP server instance and to secure web applications.

Last Updated: 2017-12-12

Red Hat JBoss Enterprise Application Platform 6.4 Security Guide

DEPRECATED. This book covers security concepts and procedures to harden the EAP serverinstance and to secure web applications.

Legal Notice

Copyright © 2015 Red Hat, Inc..

This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0Unported License. If you distribute this document, or a modified version of it, you must provideattribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hattrademarks must be removed.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinitylogo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and othercountries.

Linux ® is the registered trademark of Linus Torvalds in the United States and other countries.

Java ® is a registered trademark of Oracle and/or its affiliates.

XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United Statesand/or other countries.

MySQL ® is a registered trademark of MySQL AB in the United States, the European Union andother countries.

Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not formally related toor endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marksor trademarks/service marks of the OpenStack Foundation, in the United States and other countriesand are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed orsponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Abstract

DEPRECATED. This book covers security concepts and procedures to harden the EAP serverinstance and to secure web applications.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Table of Contents

PART I. SECURITY FOR RED HAT JBOSS ENTERPRISE APPLICATION PLATFORM 6

CHAPTER 1. INTRODUCTION1.1. ABOUT RED HAT JBOSS ENTERPRISE APPLICATION PLATFORM 61.2. ABOUT SECURING JBOSS EAP 6

PART II. SECURING THE PLATFORM

CHAPTER 2. JAVA SECURITY MANAGER2.1. ABOUT THE JAVA SECURITY MANAGER2.2. ABOUT JAVA SECURITY POLICIES2.3. WRITE A JAVA SECURITY POLICY2.4. RUN JBOSS EAP 6 WITHIN THE JAVA SECURITY MANAGER2.5. IBM JDK AND THE JAVA SECURITY MANAGER2.6. DEBUG SECURITY MANAGER POLICIES

CHAPTER 3. SECURITY REALMS3.1. ABOUT SECURITY REALMS3.2. ADD A NEW SECURITY REALM3.3. ADD A USER TO A SECURITY REALM

CHAPTER 4. ENCRYPT NETWORK TRAFFIC4.1. SPECIFY WHICH NETWORK INTERFACE JBOSS EAP 6 USES4.2. CONFIGURE NETWORK FIREWALLS TO WORK WITH JBOSS EAP 64.3. NETWORK PORTS USED BY JBOSS EAP 64.4. ABOUT ENCRYPTION4.5. ABOUT SSL ENCRYPTION4.6. IMPLEMENT SSL ENCRYPTION FOR THE JBOSS EAP 6 WEB SERVER4.7. GENERATE A SSL ENCRYPTION KEY AND CERTIFICATE4.8. SSL CONNECTOR REFERENCE4.9. FIPS 140-2 COMPLIANT ENCRYPTION

4.9.1. About FIPS 140-2 Compliance4.9.2. FIPS 140-2 Compliant Cryptography on IBM JDK

Key storageExamine FIPS provider information

4.9.3. FIPS 140-2 Compliant Passwords4.9.4. Enable FIPS 140-2 Cryptography for SSL on Red Hat Enterprise Linux 6

CHAPTER 5. SECURE THE MANAGEMENT INTERFACES5.1. DEFAULT USER SECURITY CONFIGURATION5.2. OVERVIEW OF ADVANCED MANAGEMENT INTERFACE CONFIGURATION5.3. DISABLE THE HTTP MANAGEMENT INTERFACE5.4. REMOVE SILENT AUTHENTICATION FROM THE DEFAULT SECURITY REALM5.5. DISABLE REMOTE ACCESS TO THE JMX SUBSYSTEM5.6. CONFIGURE SECURITY REALMS FOR THE MANAGEMENT INTERFACES5.7. CONFIGURE THE MANAGEMENT CONSOLE FOR HTTPS5.8. USE DISTINCT INTERFACES FOR HTTP AND HTTPS CONNECTIONS TO THE MANAGEMENTINTERFACE5.9. USING 2-WAY SSL FOR THE MANAGEMENT INTERFACE AND THE CLI5.10. SECURE THE MANAGEMENT INTERFACES VIA JAAS5.11. LDAP

5.11.1. About LDAP5.11.2. Use LDAP to Authenticate to the Management Interfaces

7

888

9

10101010111313

15151516

17171821232424273137373737383838

4242434445474749

525355565656

Table of Contents

1

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.11.3. Using Outbound LDAP with 2-way SSL in the Management Interface and CLI

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL6.1. ABOUT ROLE-BASED ACCESS CONTROL (RBAC)6.2. ROLE-BASED ACCESS CONTROL IN THE MANAGEMENT CONSOLE AND CLI6.3. SUPPORTED AUTHENTICATION SCHEMES6.4. THE STANDARD ROLES6.5. ABOUT ROLE PERMISSIONS6.6. ABOUT CONSTRAINTS6.7. ABOUT JMX AND ROLE-BASED ACCESS CONTROL6.8. CONFIGURING ROLE-BASED ACCESS CONTROL

6.8.1. Overview of RBAC Configuration Tasks6.8.2. Enabling Role-Based Access Control6.8.3. Changing the Permission Combination Policy

6.9. MANAGING ROLES6.9.1. About Role Membership6.9.2. Configure User Role Assignment6.9.3. Configure User Role Assignment using the Management CLI6.9.4. About Roles and User Groups6.9.5. Configure Group Role Assignment6.9.6. Configure Group Role Assignment using the Management CLI6.9.7. About Authorization and Group Loading with LDAP

username-to-dnThe Group SearchGeneral Group Searching

6.9.8. About Scoped Roles6.9.9. Creating Scoped Roles

6.10. CONFIGURING CONSTRAINTS6.10.1. Configure Sensitivity Constraints6.10.2. Configure Application Resource Constraints6.10.3. Configure the Vault Expression Constraint

6.11. CONSTRAINTS REFERENCE6.11.1. Application Resource Constraints Reference6.11.2. Sensitivity Constraints Reference

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVE STRINGS WITH PASSWORD VAULT7.1. PASSWORD VAULT SYSTEM7.2. CONFIGURE AND USE PASSWORD VAULT7.3. CREATE A JAVA KEYSTORE TO STORE SENSITIVE STRINGS7.4. INITIALIZE THE PASSWORD VAULT7.5. OBTAIN KEYSTORE PASSWORD FROM EXTERNAL SOURCE7.6. CONFIGURE JBOSS EAP 6 TO USE THE PASSWORD VAULT7.7. CONFIGURE JBOSS EAP 6 TO USE A CUSTOM IMPLEMENTATION OF THE PASSWORD VAULT7.8. STORE A SENSITIVE STRING IN THE PASSWORD VAULT7.9. USE AN ENCRYPTED SENSITIVE STRING IN CONFIGURATION7.10. USE AN ENCRYPTED SENSITIVE STRING IN AN APPLICATION7.11. CHECK IF A SENSITIVE STRING IS IN THE PASSWORD VAULT7.12. REMOVE A SENSITIVE STRING FROM THE PASSWORD VAULT

PART III. DEVELOPING SECURE APPLICATIONS

CHAPTER 8. SECURITY OVERVIEW8.1. ABOUT APPLICATION SECURITY8.2. DECLARATIVE SECURITY

60

6161616262646566666667686969707377778084858688909192929495969698

107107107108110113114115116120121122124

128

129129129

Security Guide

2

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8.2.1. Java EE Declarative Security Overview8.2.2. Security References8.2.3. Security Identity8.2.4. Security Roles8.2.5. EJB Method Permissions8.2.6. Enterprise Beans Security Annotations8.2.7. Web Content Security Constraints8.2.8. Enable Form-based Authentication

CHAPTER 9. APPLICATION SECURITY9.1. DATASOURCE SECURITY

9.1.1. About Datasource Security9.2. EJB APPLICATION SECURITY

9.2.1. Security Identity9.2.1.1. About EJB Security Identity9.2.1.2. Set the Security Identity of an EJB

9.2.2. EJB Method Permissions9.2.2.1. About EJB Method Permissions9.2.2.2. Use EJB Method Permissions

9.2.3. EJB Security Annotations9.2.3.1. About EJB Security Annotations9.2.3.2. Use EJB Security Annotations

9.2.4. Remote Access to EJBs9.2.4.1. About Remote Method Access9.2.4.2. About Remoting Callbacks9.2.4.3. About Remoting Server Detection9.2.4.4. Configure the Remoting Subsystem9.2.4.5. Use Security Realms with Remote EJB Clients9.2.4.6. Add a New Security Realm9.2.4.7. Add a User to a Security Realm9.2.4.8. About Remote EJB Access Using SSL Encryption

9.3. JAX-RS APPLICATION SECURITY9.3.1. Enable Role-Based Security for a RESTEasy JAX-RS Web Service9.3.2. Secure a JAX-RS Web Service using Annotations

CHAPTER 10. THE SECURITY SUBSYSTEM10.1. ABOUT THE SECURITY SUBSYSTEM10.2. ABOUT THE STRUCTURE OF THE SECURITY SUBSYSTEM10.3. CONFIGURING THE SECURITY SUBSYSTEM

10.3.1. Configure the Security Subsystem10.3.2. Security Management

10.3.2.1. About Deep Copy Subject Mode10.3.2.2. Enable Deep Copy Subject Mode

10.3.3. Security Domains10.3.3.1. About Security Domains10.3.3.2. CLI Operations Related to Security Domains

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION11.1. KERBEROS AND SPNEGO INTEGRATION

11.1.1. About Kerberos and SPNEGO Integration11.1.2. Desktop SSO using SPNEGO11.1.3. Configure JBoss Negotiation for Microsoft Windows Domain11.1.4. Kerberos Authentication for PicketLink IDP11.1.5. Login with Certificate with PicketLink IDP

129129131133134137138140

142142142143143143143144144145147147148149149150151151160160161161162162164

165165165166166167167167168168168

170170170170173174178

Table of Contents

3

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11.1.5.1. JBoss EAP 6 SSL Configuration11.2. AUTHENTICATION

11.2.1. About Authentication11.2.2. Configure Authentication in a Security Domain

11.3. JAAS - JAVA AUTHENTICATION AND AUTHORIZATION SERVICE11.3.1. About JAAS11.3.2. JAAS Core Classes11.3.3. Subject and Principal classes11.3.4. Subject Authentication

11.4. JAVA AUTHENTICATION SPI FOR CONTAINERS (JASPI)11.4.1. About Java Authentication SPI for Containers (JASPI) Security11.4.2. Configure Java Authentication SPI for Containers (JASPI) Security

11.5. AUTHORIZATION11.5.1. About Authorization11.5.2. Configure Authorization in a Security Domain

11.6. JAVA AUTHORIZATION CONTRACT FOR CONTAINERS (JACC)11.6.1. About Java Authorization Contract for Containers (JACC)11.6.2. Configure Java Authorization Contract for Containers (JACC) Security11.6.3. Fine Grained Authorization Using XACML

11.6.3.1. About Fine Grained Authorization and XACML11.6.3.2. Configure XACML for Fine Grained Authorization

11.7. SECURITY AUDITING11.7.1. About Security Auditing11.7.2. Configure Security Auditing11.7.3. New Security Properties

11.8. SECURITY MAPPING11.8.1. About Security Mapping11.8.2. Configure Security Mapping in a Security Domain

11.9. USE A SECURITY DOMAIN IN YOUR APPLICATION

CHAPTER 12. SINGLE SIGN ON (SSO)12.1. ABOUT SINGLE SIGN ON (SSO) FOR WEB APPLICATIONS12.2. ABOUT CLUSTERED SINGLE SIGN ON (SSO) FOR WEB APPLICATIONS12.3. CHOOSE THE RIGHT SSO IMPLEMENTATION12.4. USE SINGLE SIGN ON (SSO) IN A WEB APPLICATION12.5. ABOUT KERBEROS12.6. ABOUT SPNEGO12.7. ABOUT MICROSOFT ACTIVE DIRECTORY12.8. CONFIGURE KERBEROS OR MICROSOFT ACTIVE DIRECTORY DESKTOP SSO FOR WEBAPPLICATIONS12.9. CONFIGURE SPNEGO FALL BACK TO FORM AUTHENTICATION

CHAPTER 13. SINGLE SIGN-ON WITH SAML13.1. ABOUT SECURITY TOKEN SERVICE (STS)13.2. CONFIGURE SECURITY TOKEN SERVICE (STS)13.3. ABOUT PICKETLINK STS LOGIN MODULES13.4. CONFIGURE STSISSUINGLOGINMODULE13.5. CONFIGURE STSVALIDATINGLOGINMODULE13.6. STS CLIENT POOLING

Using STSClientPoolFactory13.7. SAML WEB BROWSER BASED SSO

13.7.1. About SAML Web Browser Based SSO13.7.2. Setup SAML v2 based Web SSO

178180180181182182183183184187187187187188188189189190191191192199199200201201201202203

206206206206207209209210

210213

216216218220221222223223223223224

Security Guide

4

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13.7.3. Configure Identity Provider13.7.4. Configure Service Provider using HTTP/REDIRECT Binding13.7.5. Setup SAML v2 based Web SSO using HTTP/POST Binding13.7.6. Configure Dynamic Account Chooser at a Service Provider13.7.7. Configuration of IDP-initiated SSO

13.8. CONFIGURE SAML GLOBAL LOGOUT PROFILE

CHAPTER 14. LOGIN MODULES14.1. USING MODULES

14.1.1. Password Stacking14.1.2. Password Hashing14.1.3. Unauthenticated Identity14.1.4. Ldap Login Module14.1.5. LdapExtended Login Module14.1.6. UsersRoles Login Module14.1.7. Database Login Module14.1.8. Certificate Login Module14.1.9. Identity Login Module14.1.10. RunAs Login Module

14.1.10.1. RunAsIdentity Creation14.1.11. Client Login Module14.1.12. SPNEGO Login Module14.1.13. RoleMapping Login Module14.1.14. bindCredential Module Option

14.2. CUSTOM MODULES14.2.1. Subject Usage Pattern Support14.2.2. Custom LoginModule Example

CHAPTER 15. ROLE-BASED SECURITY IN APPLICATIONS15.1. JAVA AUTHENTICATION AND AUTHORIZATION SERVICE (JAAS)15.2. ABOUT JAVA AUTHENTICATION AND AUTHORIZATION SERVICE (JAAS)15.3. USE ROLE-BASED SECURITY IN SERVLETS15.4. USE A THIRD-PARTY AUTHENTICATION SYSTEM IN YOUR APPLICATION

CHAPTER 16. MIGRATION16.1. CONFIGURE APPLICATION SECURITY CHANGES

APPENDIX A. REFERENCEA.1. INCLUDED AUTHENTICATION MODULESA.2. INCLUDED AUTHORIZATION MODULESA.3. INCLUDED SECURITY MAPPING MODULESA.4. INCLUDED SECURITY AUDITING PROVIDER MODULESA.5. JBOSS-WEB.XML CONFIGURATION REFERENCEA.6. EJB SECURITY PARAMETER REFERENCE

APPENDIX B. REVISION HISTORY

224227230230232233

234234234235236237240249250251253254254256256257258259260265

269269269270272

280280

281281309310314314317

319

Table of Contents

5

Security Guide

6

PART I. SECURITY FOR RED HAT JBOSS ENTERPRISEAPPLICATION PLATFORM 6

PART I. SECURITY FOR RED HAT JBOSS ENTERPRISE APPLICATION PLATFORM 6

7

CHAPTER 1. INTRODUCTION

1.1. ABOUT RED HAT JBOSS ENTERPRISE APPLICATION PLATFORM6

Red Hat JBoss Enterprise Application Platform 6 (JBoss EAP 6) is a middleware platform built on openstandards and compliant with the Java Enterprise Edition 6 specification. It integrates JBoss ApplicationServer 7 with high-availability clustering, messaging, distributed caching, and other technologies.

JBoss EAP 6 includes a new, modular structure that allows service enabling only when required,improving start-up speed.

The Management Console and Management Command Line Interface make editing XML configurationfiles unnecessary and add the ability to script and automate tasks.

In addition, JBoss EAP 6 includes APIs and development frameworks for quickly developing secure andscalable Java EE applications.

Report a bug

1.2. ABOUT SECURING JBOSS EAP 6

Computer security is the all encompassing term given to the field of information technology that dealswith securing the virtual environments that power the digital age. This can include data protection andintegrity, application security, risk and vulnerability assessment and authentication and authorizationprotocols.

Computer data is an all important asset for most organizations. Data protection is vital and forms the coreof most businesses. JBoss EAP 6 provides a multi-layered approach to security to take care of data at allstages.

Truly secure systems are the ones that are designed from the ground up with security as the mainfeature. Such systems use the principle of Security by Design. In such systems, malicious attacks andinfiltration's are accepted as part and parcel of normal security apparatus and systems are designed towork around them.

Security can be applied at the operating system, middleware and application level. For more informationabout security at the operating system level as it applies to RHEL, refer to the Red Hat Enterprise LinuxSecurity Guide.

In the coming chapters, you will read about the different levels and layers of security within JBoss EAP 6.These layers provides the infrastructure for all security functionality within the platform.

Report a bug

Security Guide

8

PART II. SECURING THE PLATFORM

PART II. SECURING THE PLATFORM

9

CHAPTER 2. JAVA SECURITY MANAGER

2.1. ABOUT THE JAVA SECURITY MANAGER

The Java Security Manager is a class that manages the external boundary of the Java Virtual Machine(JVM) sandbox, controlling how code executing within the JVM can interact with resources outside theJVM. When the Java Security Manager is activated, the Java API checks with the security manager forapproval before executing a wide range of potentially unsafe operations. The Java Security Manageruses a security policy to determine whether a given action will be allowed or denied.

Report a bug

2.2. ABOUT JAVA SECURITY POLICIES

A Java Security policy is a set of defined permissions for different classes of code. The Java SecurityManager compares actions requested by applications against the security policy. If an action is allowedby the policy, the Security Manager will permit that action to take place. If the action is not allowed by thepolicy, the Security Manager will deny that action. The security policy can define permissions based onthe location of code, on the code's signature, or based on the subject's principals.

You can create a security policy using the policytool application, which is included with the JavaDevelopment Kit (JDK). A security policy entry consists of the following configuration elements, whichare configurable using policytool:

CodeBase

The URL location (excluding the host and domain information) where the code originates from. Thisparameter is optional.

SignedBy

The alias used in the keystore to reference the signer whose private key was used to sign the code.This can be a single value or a comma-separated list of values. This parameter is optional. If omitted,presence or lack of a signature has no impact on the Java Security Manager.

Principals

A list of principal_type/principal_name pairs, which must be present within the executingthread's principal set. The Principals entry is optional. If it is omitted, it signifies that the principals ofthe executing thread will have no impact on the Java Security Manager.

Permissions

A permission is the access which is granted to the code. Many permissions are provided as part ofthe Java Enterprise Edition 6 (Java EE 6) specification.

Report a bug

2.3. WRITE A JAVA SECURITY POLICY

An application called policytool is included with most JDK and JRE distributions, for the purpose ofcreating and editing Java security policies. Detailed information about policytool is linked fromhttp://docs.oracle.com/javase/6/docs/technotes/tools/. Alternatively, you can also write a security policyusing a text editor.

Security Guide

10

Procedure 2.1. Setup a new Java Security Manager Policy

1. Start policytool.Start the policytool tool in one of the following ways.

Red Hat Enterprise LinuxFrom your GUI or a command prompt, run /usr/bin/policytool.

Microsoft Windows ServerRun policytool.exe from your Start menu or from the bin\ of your Java installation. Thelocation can vary.

2. Create a policy.To create a policy, select Add Policy Entry. Add the parameters you need, then click Done.

NOTE

Use VFS to specify paths for applications deployed on JBoss EAP. On Linux thepath is: vfs:/content/application.war. On Microsoft Windows it is: vfs:/${user.dir}/content/application.war .

For example:

grant codeBase "vfs:/content/application.war/-" {permission java.util.PropertyPermission "*", "read";};

3. Edit an existing policySelect the policy from the list of existing policies, and select the Edit Policy Entry button.Edit the parameters as needed.

4. Delete an existing policy.Select the policy from the list of existing policies, and select the Remove Policy Entrybutton.

Report a bug

2.4. RUN JBOSS EAP 6 WITHIN THE JAVA SECURITY MANAGER

From JBoss EAP 6.4 and onwards, running JBoss EAP 6 within the Java Security Manager (JSM) isdone using the secmgr option.

IMPORTANT

Direct usage of the -Djava.security.manager Java system property is no longerpossible. This previous method used in older versions of JBoss EAP 6 to enable the JavaSecurity Manager is now only supported as a fallback mechanism in the JBoss EAPstartup scripts.

NOTE

From JBoss EAP 6.4 and onwards, custom security managers cannot be used.

CHAPTER 2. JAVA SECURITY MANAGER

11

The following procedure guides you through the steps of configuring your JBoss EAP 6 instance to runwithin the Java Security Manager using a specified security policy.

Prerequisites

Before you follow this procedure, you need to write a security policy using the policytoolapplication which is included in the Java Development Kit (JDK). Alternatively, you can write asecurity policy using a text editor.

Security policies will be needed for any user deployments that require permissions. Thisprocedure assumes that your policy is located at EAP_HOME/bin/server.policy.

The domain or standalone server must be completely stopped before you edit any configurationfiles.

If you are using JBoss EAP 6 in a Managed Domain, you must perform the following procedure on eachphysical host or instance in your domain.

Procedure 2.2. Configure the Java Security Manager for JBoss EAP 6

1. Open the Configuration FileOpen the configuration file for editing. The configuration file you need to edit depends onwhether you use a Managed Domain or standalone server, as well as your operating system.

Managed Domain

For Linux: EAP_HOME/bin/domain.conf

For Windows: EAP_HOME\bin\domain.conf.bat

Standalone Server

For Linux: EAP_HOME/bin/standalone.conf

For Windows: EAP_HOME\bin\standalone.conf.bat

2. Enable the Java Security ManagerUse one of the methods below to enable the Java Security Manager:

Use the -secmgr option with your JBoss EAP 6 server startup script.

Uncomment the SECMGR="true" line in the configuration file:

On Linux:

On Windows:

3. Specify the Java Security PolicyYou can use -Djava.security.policy to specify the exact location of your security policy. It

# Uncomment this to run with a security manager enabledSECMGR="true"

rem # Uncomment this to run with a security manager enabledset "SECMGR=true"

Security Guide

12

should go onto one line only, with no line break. Using == when setting -Djava.security.policy specifies that the security manager will use only the specified policyfile. Using = specifies that the security manager will use the specified policy combined with thepolicy set in the policy.url section of JAVA_HOME/lib/security/java.security.

In your relevant JBoss EAP 6 configuration file, add your security policy Java options. If you areusing a Managed Domain, ensure that this is inserted before where PROCESS_CONTROLLER_JAVA_OPTS and HOST_CONTROLLER_JAVA_OPTS are set.

On Linux:

On Windows:

4. Start the Domain or ServerStart the domain or server as normal.

Report a bug

2.5. IBM JDK AND THE JAVA SECURITY MANAGER

Some versions of the IBM JDK use a default policy provider which does not work correctly with a JBossEAP security policy. If you are having problems using an IBM JDK to host JBoss EAP with the JavaSecurity Manager enabled, you must change the JRE configuration to use the standard policy provider.

To modify the JRE configuration for the IBM JDK, edit the JAVA_HOME/jre/lib/security/java.security file, and set the policy.provider value to sun.security.provider.PolicyFile.

policy.provider=sun.security.provider.PolicyFile

Report a bug

2.6. DEBUG SECURITY MANAGER POLICIES

You can enable debugging information to help you troubleshoot security policy-related issues. The java.security.debug option configures the level of security-related information reported. Thecommand java -Djava.security.debug=help will produce help output with the full range ofdebugging options. Setting the debug level to all is useful when troubleshooting a security-relatedfailure whose cause is completely unknown, but for general use it will produce too much information. Asensible general default is access:failure.

Procedure 2.3. Enable general debugging

This procedure will enable a sensible general level of security-related debug information.Add the following line to the server configuration file.

JAVA_OPTS="$JAVA_OPTS -Djava.security.policy==$JBOSS_HOME/bin/server.policy -Djboss.home.dir=$JBOSS_HOME"

set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.policy==%JBOSS_HOME%\bin\server.policy -Djboss.home.dir=%JBOSS_HOME%"

CHAPTER 2. JAVA SECURITY MANAGER

13

If the JBoss EAP 6 instance is running in a managed domain, the line is added to the bin/domain.conf file for Linux or the bin\domain.conf.bat file for Windows.

If the JBoss EAP 6 instance is running as a standalone server, the line is added to the bin/standalone.conf file for Linux, or the bin\standalone.conf.bat file forWindows.

Linux

Windows

Result

A general level of security-related debug information has been enabled.

Report a bug

JAVA_OPTS="$JAVA_OPTS -Djava.security.debug=access:failure"

set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.debug=access:failure"

Security Guide

14

CHAPTER 3. SECURITY REALMS

3.1. ABOUT SECURITY REALMS

A security realm is a series of mappings between users and passwords, and users and roles. Securityrealms are a mechanism for adding authentication and authorization to your EJB and Web applications.JBoss EAP 6 provides two security realms by default:

ManagementRealm stores authentication information for the Management API, which providesthe functionality for the Management CLI and web-based Management Console. It provides anauthentication system for managing JBoss EAP 6 itself. You could also use the ManagementRealm if your application needed to authenticate with the same business rules youuse for the Management API.

ApplicationRealm stores user, password, and role information for Web Applications andEJBs.

Each realm is stored in a number of files on the filesystem:

REALM-users.properties stores usernames and hashed passwords.

REALM-roles.properties stores user-to-role mappings.

mgmt-groups.properties stores user-to-group mapping file for ManagementRealm. Onlyused when Role-based Access Control (RBAC) is enabled.

The properties files are stored in the domain/configuration/ and standalone/configuration/directories. The files are written simultaneously by the add-user.sh or add-user.bat command.When you run the command, the first decision you make is which realm to add your new user to.

Report a bug

3.2. ADD A NEW SECURITY REALM

1. Run the Management CLI.Start the jboss-cli.sh or jboss-cli.bat command and connect to the server.

2. Create the new security realm itself.Run the following command to create a new security realm named MyDomainRealm on adomain controller or a standalone server.

For a domain instance, use this command:

/host=master/core-service=management/security-realm=MyDomainRealm:add()

For a standalone instance, use this command:

/core-service=management/security-realm=MyDomainRealm:add()

3. Create the references to the properties file which will store information about the newrole.

CHAPTER 3. SECURITY REALMS

15

Run the following command to create a pointer a file named myfile.properties, which willcontain the properties pertaining to the new role.

NOTE

The newly created properties file is not managed by the included add-user.shand add-user.bat scripts. It must be managed externally.

For a domain instance, use this command:

/host=master/core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path=myfile.properties)

For a standalone instance, use this command:

/core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path=myfile.properties)

Result

Your new security realm is created. When you add users and roles to this new realm, the information willbe stored in a separate file from the default security realms. You can manage this new file using yourown applications or procedures.

Report a bug

3.3. ADD A USER TO A SECURITY REALM

1. Run the add-user.sh or add-user.bat command.Open a terminal and change directories to the EAP_HOME/bin/ directory. If you run Red HatEnterprise Linux or another UNIX-like operating system, run add-user.sh. If you run MicrosoftWindows Server, run add-user.bat.

2. Choose whether to add a Management User or Application User.For this procedure, type b to add an Application User.

3. Choose the realm the user will be added to.By default, the only available realm is ApplicationRealm. If you have added a custom realm,you can type its name instead.

4. Type the username, password, and roles, when prompted.Type the desired username, password, and optional roles when prompted. Verify your choice bytyping yes, or type no to cancel the changes. The changes are written to each of the propertiesfiles for the security realm.

Report a bug

Security Guide

16

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

4.1. SPECIFY WHICH NETWORK INTERFACE JBOSS EAP 6 USES

Overview

Isolating services so that they are accessible only to the clients who need them increases the security ofyour network. JBoss EAP 6 includes two interfaces in its default configuration, both of which bind to theIP address 127.0.0.1, or localhost, by default. One of the interfaces is called management, and isused by the Management Console, CLI, and API. The other is called public, and is used to deployapplications. These interfaces are not special or significant, but are provided as a starting point.

The management interface uses ports 9990 and 9999 by default, and the public interface uses port 8080, or port 8443 if you use HTTPS.

You can change the IP address of the management interface, public interface, or both.

WARNING

If you expose the management interfaces to other network interfaces which areaccessible from remote hosts, be aware of the security implications. Most of thetime, it is not advisable to provide remote access to the management interfaces.

1. Stop JBoss EAP 6.Stop JBoss EAP 6 by sending an interrupt in the appropriate way for your operating system. Ifyou are running JBoss EAP 6 as a foreground application, the typical way to do this is to press Ctrl+C.

2. Restart JBoss EAP 6, specifying the bind address.Use the -b command-line switch to start JBoss EAP 6 on a specific interface.

NOTE

In the following examples, the IP address used 10.1.1.1 must be available to you.To know the IP address, use the ifconfig command.

Example 4.1. Specify the public interface.

EAP_HOME/bin/domain.sh -b 10.1.1.1

Example 4.2. Specify the management interface.

EAP_HOME/bin/domain.sh -bmanagement=10.1.1.1

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

17

Example 4.3. Specify different addresses for each interface.

EAP_HOME/bin/domain.sh -bmanagement=127.0.0.1 -b 10.1.1.1

Example 4.4. Bind the public interface to all network interfaces.

EAP_HOME/bin/domain.sh -b 0.0.0.0

It is possible to edit your XML configuration file directly, to change the default bind addresses. However,if you do this, you will no longer be able to use the -b command-line switch to specify an IP address atruntime, so this is not recommended. If you do decide to do this, be sure to stop JBoss EAP 6 completelybefore editing the XML file.

Report a bug

4.2. CONFIGURE NETWORK FIREWALLS TO WORK WITH JBOSS EAP6

Summary

Most production environments use firewalls as part of an overall network security strategy. If you needmultiple server instances to communicate with each other or with external services such as web serversor databases, your firewall must take this into account. A well-managed firewall only opens the portswhich are necessary for operation, and limits access to the ports to specific IP addresses, subnets, andnetwork protocols.

A full discussion of firewalls is out of the scope of this documentation.

Prerequisites

Determine the ports you need to open.

An understanding of your firewall software is required. This procedure uses the system-config-firewall command in Red Hat Enterprise Linux 6. Microsoft Windows Serverincludes a built-in firewall, and several third-party firewall solutions are available for eachplatform. On Microsoft Windows Server, you can use PowerShell to configure the firewall.

Assumptions

This procedure configures a firewall in an environment with the following assumptions:

The operating system is Red Hat Enterprise Linux 6.

JBoss EAP 6 runs on host 10.1.1.2. Optionally, the server has its own firewall.

The network firewall server runs on host 10.1.1.1 on interface eth0, and has an externalinterface eth1.

You want traffic on port 5445 (a port used by JMS) forwarded to JBoss EAP 6. No other trafficshould be allowed through the network firewall.

Security Guide

18

Procedure 4.1. Manage Network Firewalls and JBoss EAP 6 to work together

1. Log into the Management Console.Log into the Management Console. By default, it runs on http://localhost:9990/console/.

2. Determine the socket bindings used by the socket binding group.

a. Click the Configuration label at the top of the Management Console.

b. Expand the General Configuration menu. Select the Socket Binding.

c. The Socket Binding Declarations screen appears. Initially, the standard-socketsgroup is shown. Choose a different group by selecting it from the combo box on the right-hand side.

NOTE

If you use a standalone server, it has only one socket binding group.

The list of socket names and ports is shown, eight values per page. You can go through thepages by using the arrow navigation below the table.

3. Determine the ports you need to open.Depending on the function of the particular port and the requirements of your environment, someports may need to be opened on your firewall.

4. Configure your firewall to forward traffic to JBoss EAP 6.Perform these steps to configure your network firewall to allow traffic on the desired port.

a. Log into your firewall machine and access a command prompt, as the root user.

b. Issue the command system-config-firewall to launch the firewall configuration utility.A GUI or command-line utility launches, depending on the way you are logged into thefirewall system. This task makes the assumption that you are logged in via SSH and usingthe command-line interface.

c. Use the TAB key on your keyboard to navigate to the Customize button, and press the ENTER key. The Trusted Services screen appears.

d. Do not change any values, but use the TAB key to navigate to the Forward button, andpress ENTER to advanced to the next screen. The Other Ports screen appears.

e. Use the TAB key to navigate to the <Add> button, and press ENTER. The Port and Protocol screen appears.

f. Enter 5445 in the Port / Port Range field, then use the TAB key to move to the Protocol field, and enter tcp. Use the TAB key to navigate to the OK button, and press ENTER.

g. Use the TAB key to navigate to the Forward button until you reach the Port Forwardingscreen.

h. Use the TAB key to navigate to the <Add> button, and press the ENTER key.

i. Fill in the following values to set up port forwarding for port 5445.

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

19

Source interface: eth1

Protocol: tcp

Port / Port Range: 5445

Destination IP address: 10.1.1.2

Port / Port Range: 5445

Use the TAB key to navigate to the OK button, and press ENTER.

j. Use the TAB key to navigate to the Close button, and press ENTER.

k. Use the TAB key to navigate to the OK button, and press ENTER. To apply the changes, readthe warning and click Yes.

5. Configure a firewall on your JBoss EAP 6 host.Some organizations choose to configure a firewall on the JBoss EAP 6 server itself, and close allports that are not necessary for its operation. See Section 4.3, “Network Ports Used By JBossEAP 6” and determine which ports to open, then close the rest. The default configuration of RedHat Enterprise Linux 6 closes all ports except 22 (used for Secure Shell (SSH) and 5353 (usedfor multicast DNS). While you are configuring ports, ensure you have physical access to yourserver so that you do not inadvertently lock yourself out.

Result

Your firewall is configured to forward traffic to your internal JBoss EAP 6 server in the way you specifiedin your firewall configuration. If you chose to enable a firewall on your server, all ports are closed exceptthe ones needed to run your applications.

Procedure 4.2. Configuring Firewall on Microsoft Windows using PowerShell

1. Switch off firewall for debug purpose to determine whether the current network behavior isrelated to the firewall configuration.

Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall set allprofiles state off"'

2. Allow UDP connections on port 23364. For example:

Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall firewall add rule name="UDP Port 23364" dir=in action=allow protocol=UDP localport=23364"'Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall firewall add rule name="UDP Port 23364" dir=out action=allow protocol=UDP localport=23364"'

Procedure 4.3. Configure the Firewall on Red Hat Enterprise Linux 7 to Allow mod_clusterAdvertising

To allow mod_cluster advertising on Red Hat Enterprise Linux 7, you must enable the UDP portin the firewall as follows:

firewall-cmd --permanent --zone=public --add-port=23364/udp

Security Guide

20

NOTE

224.0.1.105:23364 is the default address and port for mod_cluster balanceradvertising UDP multicast.

Report a bug

4.3. NETWORK PORTS USED BY JBOSS EAP 6

The ports used by the JBoss EAP 6 default configuration depend on several factors:

Whether your server groups use one of the default socket binding groups, or a custom group.

The requirements of your individual deployments.

NOTE

A numerical port offset can be configured, to alleviate port conflicts when you run multipleservers on the same physical server. If your server uses a numerical port offset, add theoffset to the default port number for its server group's socket binding group. For instance,if the HTTP port of the socket binding group is 8080, and your server uses a port offset of 100, its HTTP port is 8180.

Unless otherwise stated, the ports use the TCP protocol.

The default socket binding groups

full-ha-sockets

full-sockets

ha-sockets

standard-sockets

These socket binding groups are available only in domain.xml. The standalone server profiles containonly standard socket binding group. This group corresponds to standard-sockets in standalone.xml, ha-sockets for standalone-ha.xml, full-sockets for standalone-full.xml, and full-ha-sockets for standalone-full-ha.xml. Standalone profiles contain some more socket bindings, forexample, management-{native,http,https}.

Table 4.1. Reference of the default socket bindings

Name Port Multicast Port

Description full-ha-sockets

full-sockets

ha-socket

standard-socket

ajp 8009 Apache JServProtocol. Used forHTTP clustering andload balancing.

Yes Yes Yes Yes

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

21

http 8080 The default port fordeployed webapplications.

Yes Yes Yes Yes

https 8443 SSL-encryptedconnection betweendeployed webapplications andclients.

Yes Yes Yes Yes

jacorb 3528 CORBA services forJTS transactions andother ORB-dependent services.

Yes Yes No No

jacorb-ssl

3529 SSL-encryptedCORBA services.

Yes Yes No No

jgroups-diagnostics

7500 Multicast. Used forpeer discovery in HAclusters. Notconfigurable usingthe ManagementInterfaces.

Yes No Yes No

jgroups-mping

45700 Multicast. Used todiscover initialmembership in a HAcluster.

Yes No Yes No

jgroups-tcp

7600 Unicast peerdiscovery in HAclusters using TCP.

Yes No Yes No

jgroups-tcp-fd

57600 Used for HA failuredetection over TCP.

Yes No Yes No

jgroups-udp

55200 45688 Multicast peerdiscovery in HAclusters using UDP.

Yes No Yes No

jgroups-udp-fd

54200 Used for HA failuredetection over UDP.

Yes No Yes No

Name Port Multicast Port

Description full-ha-sockets

full-sockets

ha-socket

standard-socket

Security Guide

22

messaging

5445 JMS service. Yes Yes No No

messaging-group

Referenced byHornetQ JMSbroadcast anddiscovery groups.

Yes Yes No No

messaging-throughput

5455 Used by JMSRemoting.

Yes Yes No No

mod_cluster

23364 Multicast port forcommunicationbetween JBoss EAP6 and the HTTP loadbalancer.

Yes No Yes No

remoting

4447 Used for remote EJBinvocation.

Yes Yes Yes Yes

txn-recovery-environment

4712 The JTA transactionrecovery manager.

Yes Yes Yes Yes

txn-status-manager

4713 The JTA / JTStransaction manager.

Yes Yes Yes Yes

Name Port Multicast Port

Description full-ha-sockets

full-sockets

ha-socket

standard-socket

Management Ports

In addition to the socket binding groups, each host controller opens two more ports for managementpurposes:

9990 - The Web Management Console port

9999 - The port used by the Management Console and Management API

Additionally, if HTTPS is enabled for the Management Console, 9443 is also opened as the default port.

Report a bug

4.4. ABOUT ENCRYPTION

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

23

Encryption refers to obfuscating sensitive information by applying mathematical algorithms to it.Encryption is one of the foundations of securing your infrastructure from data breaches, system outages,and other risks.

Encryption can be applied to simple string data, such as passwords. It can also be applied to datacommunication streams. The HTTPS protocol, for instance, encrypts all data before transferring it fromone party to another. If you connect from one server to another using the Secure Shell (SSH) protocol, allof your communication is sent in an encrypted tunnel .

Report a bug

4.5. ABOUT SSL ENCRYPTION

Secure Sockets Layer (SSL) encrypts network traffic between two systems. Traffic between the twosystems is encrypted using a two-way key, generated during the handshake phase of the connection andknown only by those two systems.

For secure exchange of the two-way encryption key, SSL makes use of Public Key Infrastructure (PKI), amethod of encryption that utilizes a key pair. A key pair consists of two separate but matchingcryptographic keys - a public key and a private key. The public key is shared with others and is used toencrypt data, and the private key is kept secret and is used to decrypt data that has been encrypted usingthe public key.

When a client requests a secure connection, a handshake phase takes place before securecommunication can begin. During the SSL handshake the server passes its public key to the client in theform of a certificate. The certificate contains the identity of the server (its URL), the public key of theserver, and a digital signature that validates the certificate. The client then validates the certificate andmakes a decision about whether the certificate is trusted or not. If the certificate is trusted, the clientgenerates the two-way encryption key for the SSL connection, encrypts it using the public key of theserver, and sends it back to the server. The server decrypts the two-way encryption key, using its privatekey, and further communication between the two machines over this connection is encrypted using thetwo-way encryption key.

WARNING

Red Hat recommends that you explicitly disable SSL in favor of TLSv1.1 or TLSv1.2in all affected packages.

Report a bug

4.6. IMPLEMENT SSL ENCRYPTION FOR THE JBOSS EAP 6 WEBSERVER

Introduction

Many web applications require an SSL-encrypted connection between clients and server, also known asa HTTPS connection. You can use this procedure to enable HTTPS on your server or server group.

Security Guide

24

WARNING

Red Hat recommends that you explicitly disable SSL in favor of TLSv1.1 or TLSv1.2in all affected packages.

Prerequisites

A set of SSL encryption keys and an SSL encryption certificate. You may purchase these from acertificate-signing authority, or you can generate them yourself using command-line utilities. Togenerate encryption keys using utilities available on Red Hat Enterprise Linux, see Section 4.7,“Generate a SSL Encryption Key and Certificate”.

The following details about your specific environment and setup:

The full directory name where the certificate files are stored.

The encryption password for your encryption keys.

Management CLI running and connected to your domain controller or standalone server.

Select appropriate cipher suites.

Cipher Suites

There are a number of available cryptographic primitives used as building blocks to form cipher suites.The first table lists recommended cryptographic primitives. The second lists cryptographic primitiveswhich, while they may be used for compatibility with existing software, are not considered as secure asthose recommended.

WARNING

Red Hat recommends selectively whitelisting a set of strong ciphers to use for cipher-suite. Enabling weak ciphers is a significant security risk. Consult yourJDK vendor's documentation before deciding on particular cipher suites as theremay be compatibility issues.

Table 4.2. Recommended Cryptographic Primitives

RSA with 2048 bit keys and OAEP

AES-128 in CBC mode

SHA-256

HMAC-SHA-256

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

25

HMAC-SHA-1

Table 4.3. Other Cryptographic Primitives

RSA with key sizes larger than 1024 and legacy padding

AES-192

AES-256

3DES (triple DES, with two or three 56 bit keys)

RC4 (strongly discouraged)

SHA-1

HMAC-MD5

For a full listing of parameters you can set for the SSL properties of the connector, see Section 4.8, “SSLConnector Reference”.

NOTE

This procedure uses commands appropriate for a JBoss EAP 6 configuration that uses amanaged domain. If you use a standalone server, modify Management CLI commands byremoving the /profile=default from the beginning of any management CLIcommands and replace instances of the jboss.domain.config.dir property with jboss.server.config.dir (as jboss.domain.config.dir is not available instandalone mode).

WARNING

Red Hat recommends that you explicitly disable SSL in favor of TLSv1.1 or TLSv1.2in all affected packages.

Procedure 4.4. Configure the JBoss Web Server to use HTTPS

1. Add a new HTTPS connector.Create a secure connector, named HTTPS, which uses the https scheme, the https socketbinding (which defaults to 8443), and is set to be secure.

/profile=default/subsystem=web/connector=HTTPS/:add(socket-binding=https,scheme=https,protocol=HTTP/1.1,secure=true)

Security Guide

26

2. Configure the SSL encryption certificate and keys.Configure your SSL certificate, substituting your own values for the example ones. This exampleassumes that the keystore is copied to the server configuration directory, which is EAP_HOME/domain/configuration/ for a managed domain.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration:add(name=https,certificate-key-file="${jboss.domain.config.dir}/keystore.jks",password=SECRET, key-alias=KEY_ALIAS, cipher-suite=CIPHERS)

3. Set the protocol to TLSv1.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=protocol,value=TLSv1)

4. Deploy an application.Deploy an application to a server group which uses the profile you have configured. If you use astandalone server, deploy an application to your server. HTTPS requests to it use the new SSL-encrypted connection.

Report a bug

4.7. GENERATE A SSL ENCRYPTION KEY AND CERTIFICATE

To use a SSL-encrypted HTTP connection (HTTPS), as well as other types of SSL-encryptedcommunication, you need a signed encryption certificate. You can purchase a certificate from aCertificate Authority (CA), or you can use a self-signed certificate. Self-signed certificates are notconsidered trustworthy by many third parties, but are appropriate for internal testing purposes.

This procedure enables you to create a self-signed certificate using utilities which are available on RedHat Enterprise Linux.

Prerequisites

You need the keytool utility, which is provided by any Java Development Kit implementation.OpenJDK on Red Hat Enterprise Linux installs this command to /usr/bin/keytool.

Understand the syntax and parameters of the keytool command. This procedure usesextremely generic instructions, because further discussion of the specifics of SSL certificates orthe keytool command are out of scope for this documentation.

Procedure 4.5. Generate a SSL Encryption Key and Certificate

1. Generate a keystore with public and private keys.Run the following command to generate a keystore named server.keystore with the alias jboss in your current directory.

keytool -genkeypair -alias jboss -keyalg RSA -keystore server.keystore -storepass mykeystorepass --dname "CN=jsmith,OU=Engineering,O=mycompany.com,L=Raleigh,S=NC,C=US"

The following table describes the parameters used in the keytool command:

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

27

Parameter Description

-genkeypair The keytool command to generate a key paircontaining a public and private key.

-alias The alias for the keystore. This value is arbitrary,but the alias jboss is the default used by theJBoss Web server.

-keyalg The key pair generation algorithm. In this case itis RSA.

-keystore The name and location of the keystore file. Thedefault location is the current directory. Thename you choose is arbitrary. In this case, thefile will be named server.keystore.

-storepass This password is used to authenticate to thekeystore so that the key can be read. Thepassword must be at least 6 characters long andmust be provided when the keystore isaccessed. In this case, we used mykeystorepass. If you omit this parameter,you will be prompted to enter it when youexecute the command.

-keypass This is the password for the actual key.

NOTE

Due to an implementationlimitation this must be the sameas the store password.

Security Guide

28

--dname A quoted string describing the distinguishedname for the key, for example:"CN=jsmith,OU=Engineering,O=mycompany.com,L=Raleigh,C=US". This string is aconcatenation of the following components:

CN - The common name or host name. Ifthe hostname is "jsmith.mycompany.com",the CN is "jsmith".

OU - The organizational unit, for example"Engineering"

O - The organization name, for example"mycompany.com".

L - The locality, for example "Raleigh" or"London"

S - The state or province, for example "NC".This parameter is optional.

C - The 2 letter country code, for example"US" or "UK",

Parameter Description

When you execute the above command, you are prompted for the following information:

If you did not use the -storepass parameter on the command line, you are asked to enterthe keystore password. Re-enter the new password at the next prompt.

If you did not use the -keypass parameter on the command line, you are asked to enter thekey password. Press Enter to set this to the same value as the keystore password.

When the command completes, the file server.keystore now contains the single key with thealias jboss.

2. Verify the key.Verify that the key works properly by using the following command.

keytool -list -keystore server.keystore

You are prompted for the keystore password. The contents of the keystore are displayed (in thiscase, a single key called jboss). Notice the type of the jboss key, which is PrivateKeyEntry. This indicates that the keystore contains both a public and private entry forthis key.

3. Generate a certificate signing request.Run the following command to generate a certificate signing request using the public key fromthe keystore you created in step 1.

keytool -certreq -keyalg RSA -alias jboss -keystore server.keystore -file certreq.csr

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

29

You are prompted for the password in order to authenticate to the keystore. The keytoolcommand then creates a new certificate signing request called certreq.csr in the currentworking directory.

4. Test the newly generated certificate signing request.Test the contents of the certificate by using the following command.

openssl req -in certreq.csr -noout -text

The certificate details are shown.

5. Optional: Submit your certificate signing request to a Certificate Authority (CA).A Certificate Authority (CA) can authenticate your certificate so that it is considered trustworthyby third-party clients. The CA supplies you with a signed certificate, and optionally with one ormore intermediate certificates.

6. Optional: Export a self-signed certificate from the keystore.If you only need it for testing or internal purposes, you can use a self-signed certificate. You canexport one from the keystore you created in step 1 as follows:

keytool -export -alias jboss -keystore server.keystore -file server.crt

You are prompted for the password in order to authenticate to the keystore. A self-signedcertificate, named server.crt, is created in the current working directory.

7. Import the signed certificate, along with any intermediate certificates.Import each certificate, in the order that you are instructed by the CA. For each certificate toimport, replace intermediate.ca or server.crt with the actual file name. If yourcertificates are not provided as separate files, create a separate file for each certificate, andpaste its contents into the file.

NOTE

Your signed certificate and certificate keys are valuable assets. Be cautious withhow you transport them between servers.

keytool -import -keystore server.keystore -alias intermediateCA -file intermediate.ca

keytool -importcert -alias jboss -keystore server.keystore -file server.crt

8. Test that your certificates imported successfully.Run the following command, and enter the keystore password when prompted. The contents ofyour keystore are displayed, and the certificates are part of the list.

keytool -list -keystore server.keystore

Result

Your signed certificate is now included in your keystore and is ready to be used to encrypt SSLconnections, including HTTPS web server communications.

Security Guide

30

Report a bug

4.8. SSL CONNECTOR REFERENCE

JBoss Web connectors may include the following SSL configuration attributes. The CLI commandsprovided are designed for a managed domain using profile default. Change the profile name to theone you wish to configure, for a managed domain, or omit the /profile=default portion of thecommand, for a standalone server.

NOTE

Before using the write-attribute CLI command listed in the table, you need to add ssl=configuration.

Table 4.4. SSL Connector Attributes

Attribute Description CLI Command

name The display name of the SSLconnector.

Attribute name is read-only.

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

31

verify-client The possible values of verify-client differ, based uponwhether the HTTP/HTTPSconnector is used, or the nativeAPR connector is used.

HTTP/HTTPS Connector

Possible values are true, false, or want. Set to true torequire a valid certificate chainfrom the client before accepting aconnection. Set to want if youwant the SSL stack to request aclient Certificate, but not fail if oneis not presented. Set to false(the default) to not require acertificate chain unless the clientrequests a resource protected bya security constraint that uses CLIENT-CERT authentication.

Before using the write-attribute CLI command, youneed to add the APR connector.

Native APR Connector

Possible values are optional, require, optionalNoCA,and none (or any other string,which will have the same effect asnone). These values determinewhether a certification is optional,required, optional without aCertificate Authority, or notrequired at all. The default is none, meaning the client will nothave the opportunity to submit acertificate.

The first example command usesthe HTTPS connector.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=verify-client,value=want)

The second example commanduses the APR connector.

/profile=default/subsystem=web/connector=APR/ssl=configuration/:write-attribute(name=verify-client,value=require)

verify-depth The maximum number ofintermediate certificate issuerschecked before deciding that theclients do not have a validcertificate. The default value is 10.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=verify-depth,value=10)

Attribute Description CLI Command

Security Guide

32

certificate-key-file The full file path and file name ofthe keystore file where the signedserver certificate is stored. WithJSSE encryption, this certificatefile will be the only one, whileOpenSSL uses several files. Thedefault value is the .keystorefile in the home directory of theuser running JBoss EAP 6. If your keystoreType does not use afile, set the parameter to an emptystring.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=certificate-key-file,value=../domain/configuration/server.keystore)

certificate-file If you use OpenSSL encryption,set the value of this parameter tothe path to the file containing theserver certificate.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=certificate-file,value=server.crt)

password The password for both thetruststore and keystore. In thefollowing example, replacePASSWORD with your ownpassword.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=password,value=PASSWORD)

Attribute Description CLI Command

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

33

protocol The version of the SSL protocol touse. Supported values depend onthe underlying SSLimplementation (whether JSSE orOpenSSL). Refer to the Java SSEDocumentation.

You can also specify acombination of protocols, which iscomma separated. For example,TLSv1, TLSv1.1,TLSv1.2.

WARNING

Red Hatrecommends that youexplicitlydisableSSL infavor ofTLSv1.1 orTLSv1.2 inall affectedpackages.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=protocol,value=ALL)

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=protocol,value="TLSv1, TLSv1.1,TLSv1.2")

Attribute Description CLI Command

Security Guide

34

cipher-suite A list of the encryption cipherswhich are allowed. For JSSEsyntax, it must be a comma-separated list. For OpenSSLsyntax, it must be a colon-separated list. Ensure that youonly use one syntax.

The default is HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5.

The example only lists twopossible ciphers, but real-worldexamples will likely use more.

IMPORTANT

Using weakciphers is asignificantsecurity risk. Seehttp://www.nist.gov/manuscript-publication-search.cfm?pub_id=915295for NISTrecommendationson cipher suites.

For a list of available OpenSSLciphers, seehttps://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS. Note that the following are notsupported: @SECLEVEL, SUITEB128, SUITEB128ONLY, SUITEB192.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=cipher-suite, value="TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA")

key-alias The alias used to for the servercertificate in the keystore. In thefollowing example, replaceKEY_ALIAS with your certificate'salias.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=key-alias,value=KEY_ALIAS)

Attribute Description CLI Command

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

35

truststore-type The type of the truststore. Varioustypes of truststores are available,including PKCS12 and Java'sstandard JKS.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=truststore-type,value=jks)

keystore-type The type of the keystore, Varioustypes of keystores are available,including PKCS12 and Java'sstandard JKS.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=keystore-type,value=jks)

ca-certificate-file The file containing the CAcertificates. This is the truststoreFile, in the caseof JSSE, and uses the samepassword as the keystore. The ca-certificate-file file isused to validate client certificates.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=certificate-file,value=ca.crt)

ca-certificate-password The Certificate password for the ca-certificate-file. Inthe following example, replace theMASKED_PASSWORD with yourown masked password.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=ca-certificate-password,value=MASKED_PASSWORD)

ca-revocation-url A file or URL which contains therevocation list. It refers to the crlFile for JSSE or the SSLCARevocationFile forSSL.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=ca-revocation-url,value=ca.crl)

Attribute Description CLI Command

Security Guide

36

session-cache-size The size of the SSLSessioncache. This attribute applies onlyto JSSE connectors. The defaultis 0, which specifies an unlimitedcache size.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=session-cache-size,value=100)

session-timeout The number of seconds before acached SSLSession expires. Thisattribute applies only to JSSEconnectors. The default is 86400seconds, which is 24 hours.

/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=session-timeout,value=43200)

Attribute Description CLI Command

NOTE

For performance testing, you must set one explicit cipher and protocol.

Report a bug

4.9. FIPS 140-2 COMPLIANT ENCRYPTION

4.9.1. About FIPS 140-2 Compliance

The Federal Information Processing Standard 140-2 (FIPS 140-2) is a US government computer securitystandard for the accreditation of cryptographic software modules. FIPS 140-2 compliance is often arequirement of software systems used by government agencies and private sector business.

JBoss EAP 6 uses external modules encryption and can be configured to use a FIPS 140-2 compliantcryptography module.

Report a bug

4.9.2. FIPS 140-2 Compliant Cryptography on IBM JDK

On the IBM JDK, the IBM® JCE (Java™ Cryptographic Extension) IBMJCEFIPS provider and the IBMJSSE (Java Secure Sockets Extension) FIPS 140-2 Cryptographic Module (IBMJSSEFIPS) for Multi-platforms provide FIPS 140-2 compliant cryptography.

For more information on the IBMJCEFIPS provider, refer to the IBM Documentation for IBM JCEFIPS,and the NIST IBMJCEFIPS – Security Policy.

Key storageNote that the IBM JCE does not provide a keystore. The keys are stored on the computer and do notleave its physical boundary. If the keys are moved between computers they must be encrypted.

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

37

To run keytool in FIPS-compliant mode use the -providerClass option on each command like this:

keytool -list -storetype JCEKS -keystore mystore.jck -storepass mystorepass -providerClass com.ibm.crypto.fips.provider.IBMJCEFIPS

Examine FIPS provider informationTo examine information about the IBMJCEFIPS used by the server, enable debug-level logging byadding -Djavax.net.debug=true to standalone.conf or domain.conf. Information about theFIPS provider is logged to server.log, for example:

04:22:45,685 INFO [stdout] (http-/127.0.0.1:8443-1) JsseJCE: Using MessageDigest SHA from provider IBMJCEFIPS version 1.704:22:45,689 INFO [stdout] (http-/127.0.0.1:8443-1) DHCrypt: DH KeyPairGenerator from provider from init IBMJCEFIPS version 1.704:22:45,754 INFO [stdout] (http-/127.0.0.1:8443-1) JsseJCE: Using KeyFactory DiffieHellman from provider IBMJCEFIPS version 1.704:22:45,754 INFO [stdout] (http-/127.0.0.1:8443-1) JsseJCE: Using KeyAgreement DiffieHellman from provider IBMJCEFIPS version 1.704:22:45,754 INFO [stdout] (http-/127.0.0.1:8443-1) DHCrypt: DH KeyAgreement from provider IBMJCEFIPS version 1.704:22:45,754 INFO [stdout] (http-/127.0.0.1:8443-1) DHCrypt: DH KeyAgreement from provider from initIBMJCEFIPS version 1.7

Report a bug

4.9.3. FIPS 140-2 Compliant Passwords

A FIPS compliant password must have the following characteristics:

1. Must be at least seven (7) characters in length.

2. Must include characters from at least three (3) of the following character classes:

ASCII digits,

lowercase ASCII,

uppercase ASCII,

non-alphanumeric ASCII, and

non-ASCII.

If the first character of the password is an uppercase ASCII letter, then it is not counted as an uppercaseASCII letter for restriction 2.

If the last character of the password is an ASCII digit, then it does not count as an ASCII digit forrestriction 2.

Report a bug

4.9.4. Enable FIPS 140-2 Cryptography for SSL on Red Hat Enterprise Linux 6

This task describes how to configure the web container (JBoss Web) of JBoss EAP 6 to FIPS 140-2compliant cryptography for SSL. This task only covers the steps to do this on Red Hat Enterprise Linux 6.

Security Guide

38

This task uses the Mozilla NSS library in FIPS mode for this feature.

Prerequisites

Red Hat Enterprise Linux 6 must already be configured to be FIPS 140-2 compliant. Refer tohttps://access.redhat.com/knowledge/solutions/137833.

Procedure 4.6. Enable FIPS 140-2 Compliant Cryptography for SSL

1. Create the databaseCreate the NSS database in a directory own by the jboss user.

NOTE

The jboss user is only an example. You need to replace it with a user on youroperating system.

$ mkdir -p /usr/share/jboss-as/nssdb$ chown jboss /usr/share/jboss-as/nssdb $ modutil -create -dbdir /usr/share/jboss-as/nssdb

2. Create NSS configuration fileCreate a new text file with the name nss_pkcsll_fips.cfg in the /usr/share/jboss-asdirectory with the following contents:

The NSS configuration file must specify:

a name,

the directory where the NSS library is located, and

the directory where the NSS database was created as per step 1.

If you are not running a 64bit version of Red Hat Enterprise Linux 6 then set nssLibraryDirectory to /usr/lib instead of /usr/lib64.

3. Enable SunPKCS11 providerEdit the java.security configuration file for your JRE($JAVA_HOME/jre/lib/security/java.security) and add the following line:

Note that the configuration file specified in this line is the file created in step 2.

Any other security.provider.X lines in this file must have the value of their X increased byone to ensure that this provider is given priority.

name = nss-fipsnssLibraryDirectory=/usr/lib64nssSecmodDirectory=/usr/share/jboss-as/nssdbnssModule = fips

security.provider.1=sun.security.pkcs11.SunPKCS11 /usr/share/jboss-as/nss_pkcsll_fips.cfg

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

39

4. Enable FIPS mode for the NSS libraryRun the modutil command as shown to enable FIPS mode:

modutil -fips true -dbdir /usr/share/jboss-as/nssdb

Note that the directory specified here is the one created in step 1.

You may get a security library error at this point requiring you to regenerate the librarysignatures for some of the NSS shared objects.

5. Change the password on the FIPS tokenSet the password on the FIPS token using the following command. Note that the name of thetoken must be NSS FIPS 140-2 Certificate DB.

modutil -changepw "NSS FIPS 140-2 Certificate DB" -dbdir /usr/share/jboss-as/nssdb

The password used for the FIPS token must be a FIPS compliant password.

6. Create certificate using NSS toolsEnter the following command to create a certificate using the NSS tools.

certutil -S -k rsa -n jbossweb -t "u,u,u" -x -s "CN=localhost, OU=MYOU, O=MYORG, L=MYCITY, ST=MYSTATE, C=MY" -d /usr/share/jboss-as/nssdb

7. Configure the HTTPS connector to use the PKCS11 keystoreAdd a HTTPS connector using the following command in the JBoss CLI Tool:

/subsystem=web/connector=https/:add(socket-binding=https,scheme=https,protocol=HTTP/1.1,secure=true)

Then add the SSL configuration with the following command, replacing PASSWORD with theFIPS compliant password from step 5.

/subsystem=web/connector=https/ssl=configuration:add(name=https,password=PASSWORD,keystore-type=PKCS11,cipher-suite="SSL_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_DSS_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_DSS_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SH

Security Guide

40

A,TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_anon_WITH_AES_128_CBC_SHA,TLS_ECDH_anon_WITH_AES_256_CBC_SHA")

8. VerifyVerify that the JVM can read the private key from the PKCS11 keystore by running the followingcommand:

keytool -list -storetype pkcs11

Example 4.5. XML configuration for HTTPS connector using FIPS 140-2 compliance

Note that the cipher-suite attribute has linebreaks inserted to make it easier to read.

Report a bug

<connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true"> <ssl name="https" password="****" cipher-suite="SSL_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA, TLS_DHE_DSS_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA, TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_anon_WITH_AES_128_CBC_SHA, TLS_ECDH_anon_WITH_AES_256_CBC_SHA" keystore-type="PKCS11"/></connector>

CHAPTER 4. ENCRYPT NETWORK TRAFFIC

41

CHAPTER 5. SECURE THE MANAGEMENT INTERFACESA common development scenario is to run JBoss EAP 6 with no security on the management interfacesto allow rapid configuration changes.

In production deployment, secure the management interfaces by at least the following methods:

Section 4.1, “Specify Which Network Interface JBoss EAP 6 Uses”

Section 4.2, “Configure Network Firewalls to Work with JBoss EAP 6”

Additionally, the default silent local authentication mode allows local clients (on the server machine) toconnect to the Management CLI without requiring a username or password. This is a convenience forlocal users and Management CLI scripts. To disable this, refer to Section 5.4, “Remove SilentAuthentication from the Default Security Realm”.

Report a bug

5.1. DEFAULT USER SECURITY CONFIGURATION

Introduction

All management interfaces in JBoss EAP 6 are secured by default. This security takes two differentforms:

Local interfaces are secured by a SASL contract between local clients and the server theyconnect to. This security mechanism is based on the client's ability to access the local filesystem.This is because access to the local filesystem would allow the client to add a user or otherwisechange the configuration to thwart other security mechanisms. This adheres to the principle thatif physical access to the filesystem is achieved, other security mechanisms are superfluous. Themechanism happens in four steps:

NOTE

HTTP access is considered to be remote, even if you connect to the localhostusing HTTP.

1. The client sends a message to the server which includes a request to authenticate with thelocal SASL mechanism.

2. The server generates a one-time token, writes it to a unique file, and sends a message tothe client with the full path of the file.

3. The client reads the token from the file and sends it to the server, verifying that it has localaccess to the filesystem.

4. The server verifies the token and then deletes the file.

Remote clients, including local HTTP clients, use realm-based security. The default realm withthe permissions to configure the JBoss EAP 6 instance remotely using the managementinterfaces is ManagementRealm. A script is provided which allows you to add users to thisrealm (or realms you create). For more information on adding users, see the User Managementchapter of the JBoss EAP 6 Administration and Configuration Guide. For each user, theusername and a hashed password are stored in a file.

Security Guide

42

Managed domain

EAP_HOME/domain/configuration/mgmt-users.properties

Standalone server

EAP_HOME/standalone/configuration/mgmt-users.properties

Even though the contents of the mgmt-users.properties are masked, the file must still betreated as a sensitive file. It is recommended that it be set to the file mode of 600, which givesno access other than read and write access by the file owner.

Report a bug

5.2. OVERVIEW OF ADVANCED MANAGEMENT INTERFACECONFIGURATION

The Management interface configuration in the EAP_HOME/domain/configuration/host.xml or EAP_HOME/standalone/configuration/standalone.xml controls which network interfaces thehost controller process binds to, which types of management interfaces are available at all, and whichtype of authentication system is used to authenticate users on each interface. This topic discusses howto configure the Management Interfaces to suit your environment.

The Management subsystem consists of a <management> element that includes the following fourconfigurable child elements. The security realms and outbound connections are each first defined, andthen applied to the management interfaces as attributes.

<security-realms>

<outbound-connections>

<management-interfaces>

<audit-log>

NOTE

Refer to the Management Interface Audit Logging section of the Administration andConfiguration Guide for more information on audit logging.

Security Realms

The security realm is responsible for the authentication and authorization of users allowed to administerJBoss EAP 6 via the Management API, Management CLI, or web-based Management Console.

Two different file-based security realms are included in a default installation: ManagementRealm and ApplicationRealm. Each of these security realms uses a -users.properties file to store usersand hashed passwords, and a -roles.properties to store mappings between users and roles.Support is also included for an LDAP-enabled security realm.

NOTE

Security realms can also be used for your own applications. The security realmsdiscussed here are specific to the management interfaces.

CHAPTER 5. SECURE THE MANAGEMENT INTERFACES

43

Outbound Connections

Some security realms connect to external interfaces, such as an LDAP server. An outbound connectiondefines how to make this connection. A pre-defined connection type, ldap-connection, sets all of therequired and optional attributes to connect to the LDAP server and verify the credential.

For more information on how to configure LDAP authentication see Section 5.11.2, “Use LDAP toAuthenticate to the Management Interfaces”.

Management Interfaces

A management interface includes properties about how connect to and configure JBoss EAP. Suchinformation includes the named network interface, port, security realm, and other configurableinformation about the interface. Two interfaces are included in a default installation:

http-interface is the configuration for the web-based Management Console.

native-interface is the configuration for the command-line Management CLI and the REST-like Management API.

Each of the main configurable elements of the host management subsystem are interrelated. A securityrealm refers to an outbound connection, and a management interface refers to a security realm.

Associated information can be found in Chapter 5, Secure the Management Interfaces.

Report a bug

5.3. DISABLE THE HTTP MANAGEMENT INTERFACE

In a managed domain, you only need access to the HTTP interface on the domain controller, rather thanon domain member servers. In addition, on a production server, you may decide to disable the web-based Management Console altogether.

NOTE

Other clients, such as JBoss Operations Network, also operate using the HTTP interface.If you want to use these services, and simply disable the Management Console itself, youcan set the console-enabled attribute of the HTTP interface to false, instead ofdisabling the interface completely.

/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=console-enabled,value=false)

To disable access to the HTTP interface, which also disables access to the web-based ManagementConsole, you can delete the HTTP interface altogether.

The following JBoss CLI command allows you to read the current contents of your HTTP interface, incase you decide to add it again.

Example 5.1. Read the Configuration of the HTTP Interface

/host=master/core-service=management/management-interface=http-interface/:read-resource(recursive=true,proxies=false,include-runtime=false,include-defaults=true){

Security Guide

44

"outcome" => "success", "result" => { "console-enabled" => true, "interface" => "management", "port" => expression "${jboss.management.http.port:9990}", "secure-port" => undefined, "security-realm" => "ManagementRealm" }}

To remove the HTTP interface, issue the following command:

Example 5.2. Remove the HTTP Interface

/host=master/core-service=management/management-interface=http-interface/:remove

To re-enable access, issue the following commands to re-create the HTTP Interface with the defaultvalues.

Example 5.3. Re-Create the HTTP Interface

/host=master/core-service=management/management-interface=http-interface:add(console-enabled=true,interface=management,port="${jboss.management.http.port:9990}",security-realm=ManagementRealm)

Report a bug

5.4. REMOVE SILENT AUTHENTICATION FROM THE DEFAULTSECURITY REALM

Summary

The default installation of JBoss EAP 6 contains a method of silent authentication for a localManagement CLI user. This allows the local user the ability to access the Management CLI withoutusername or password authentication. This functionality is enabled as a convenience, and to assist localusers running Management CLI scripts without requiring authentication. It is considered a useful featuregiven that access to the local configuration typically also gives the user the ability to add their own userdetails or otherwise disable security checks.

The convenience of silent authentication for local users can be disabled where greater security control isrequired. This can be achieved by removing the local element within the security-realm section ofthe configuration file. This applies to both the standalone.xml for a Standalone Server instance, or host.xml for a Managed Domain. You should only consider the removal of the local element if youunderstand the impact that it might have on your particular server configuration.

The preferred method of removing silent authentication is by use of the Management CLI, which directlyremoves the local element visible in the following example.

CHAPTER 5. SECURE THE MANAGEMENT INTERFACES

45

Example 5.4. Example of the local element in the security-realm

Prerequisites

Start the JBoss EAP 6 instance.

Launch the Management CLI.

Procedure 5.1. Remove Silent Authentication from the Default Security Realm

Remove silent authentication with the Management CLIRemove the local element from the Management Realm and Application Realm as required.

a. Remove the local element from the Management Realm.

For Standalone Servers

/core-service=management/security-realm=ManagementRealm/authentication=local:remove

For Managed Domains

/host=HOST_NAME/core-service=management/security-realm=ManagementRealm/authentication=local:remove

b. Remove the local element from the Application Realm.

For Standalone Servers

/core-service=management/security-realm=ApplicationRealm/authentication=local:remove

<security-realms> <security-realm name="ManagementRealm"> <authentication> <local default-user="$local"/> <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/> </authentication> </security-realm> <security-realm name="ApplicationRealm"> <authentication> <local default-user="$local" allowed-users="*"/> <properties path="application-users.properties" relative-to="jboss.server.config.dir"/> </authentication> <authorization> <properties path="application-roles.properties" relative-to="jboss.server.config.dir"/> </authorization> </security-realm></security-realms>

Security Guide

46

For Managed Domains

/host=HOST_NAME/core-service=management/security-realm=ApplicationRealm/authentication=local:remove

Result

The silent authentication mode is removed from the ManagementRealm and the ApplicationRealm.

Report a bug

5.5. DISABLE REMOTE ACCESS TO THE JMX SUBSYSTEM

Remote access to the JMX subsystem allows you to trigger JDK and application management operationsremotely. In order to secure an installation, disable this function either by removing the remotingconnector or removing the JMX subsystem. The example Management CLI commands are suitable for amanaged domain. For a standalone server, remove the /profile=default prefix from thecommands.

NOTE

In a managed domain the remoting connector is removed from the JMX subsystem bydefault. This command is provided for your information, in case you add it duringdevelopment.

Example 5.5. Remove the Remoting Connector from the JMX Subsystem

/profile=default/subsystem=jmx/remoting-connector=jmx/:remove

Example 5.6. Remove the JMX Subsystem

For a managed domain, run this command for each profile.

/profile=default/subsystem=jmx/:remove

Report a bug

5.6. CONFIGURE SECURITY REALMS FOR THE MANAGEMENTINTERFACES

The management interfaces use security realms to control authentication and access to the configurationmechanisms of JBoss EAP 6. A Security Realm is similar to a Unix group. It is effectively a database ofusernames and passwords that can be use to authenticate users.

Default Management Realm

The management interfaces are configured to use the ManagementRealm security realm by default.The ManagementRealm stores its user password combinations in the file mgmt-users.properties.

CHAPTER 5. SECURE THE MANAGEMENT INTERFACES

47

Example 5.7. Default ManagementRealm

/host=master/core-service=management/security-realm=ManagementRealm/:read-resource(recursive=true,proxies=false,include-runtime=false,include-defaults=true){ "outcome" => "success", "result" => { "map-groups-to-roles" => false, "authentication" => { "local" => { "allowed-users" => undefined, "default-user" => "$local" }, "properties" => { "path" => "mgmt-users.properties", "plain-text" => false, "relative-to" => "jboss.domain.config.dir" } }, "authorization" => {"properties" => { "path" => "mgmt-groups.properties", "relative-to" => "jboss.domain.config.dir" }}, "plug-in" => undefined, "server-identity" => undefined }}

Create a new Security Realm

The following commands create a new security realm called TestRealm and set the directory for therelevant properties file.

Example 5.8. Create a new Security Realm

/host=master/core-service=management/security-realm=TestRealm/:add/host=master/core-service=management/security-realm=TestRealm/authentication=properties/:add(path=TestUsers.properties, relative-to=jboss.domain.config.dir)

Configure Security Realm authentication through an existing Security Domain

To use Security Domain to authenticate to the Management interfaces:

First, create a Security Realm. Then, set specify it as the value for the security-realm attribute of themanagement interface:

Example 5.9. Specify a Security Realm to use for the HTTP Management Interface

/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=TestRealm)

Security Guide

48

Report a bug

5.7. CONFIGURE THE MANAGEMENT CONSOLE FOR HTTPS

Configuring the JBoss EAP management console for communication only via HTTPS providesincreased security. All network traffic between the client (web browser) and management console isencrypted, which reduces the risk of security attacks such as a man-in-the-middle attack. Anyoneadministering a JBoss EAP instance has greater permissions on that instance than non-privileged users,and using HTTPS helps protect the integrity and availability of that instance.

In this procedure unencrypted communications with the JBoss EAP standalone instance or domain isdisabled. Passwords used in these communications are stored encrypted using the JBoss EAP vaultfeature, and passwords used in configuration files are masked.

This procedure applies to both standalone and domain mode configurations. For domain mode,prefix the management CLI commands with the name of the host, for example: /host=master.

Procedure 5.2.

1. Create a keystore to secure the management console.

NOTE

This keystore must be in JKS format as the management console is notcompatible with keystores in JCEKS format.

In a terminal emulator, enter the following command. For the parameters alias, keypass, keystore, storepass and dname, replace the example values with values of your choice.

The parameter validity specifies for how many days the key is valid. A value of 730 equalstwo years.

2. Ensure the Management Console Binds to HTTPS

Standalone ModeEnsure the management console binds to HTTPS for its interface by adding the management-https configuration and removing the management-http configuration.

Ensure the JBoss EAP instance is running, then enter the following management CLIcommands:

keytool -genkeypair -alias appserver -storetype jks -keyalg RSA -keysize 2048 -keypass password1 -keystore EAP_HOME/standalone/configuration/identity.jks -storepass password1 -dname "CN=appserver,OU=Sales,O=Systems Inc,L=Raleigh,ST=NC,C=US" -validity 730 -v

/core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https)

CHAPTER 5. SECURE THE MANAGEMENT INTERFACES

49

The expected output from these commands is:

{"outcome" => "success"}

NOTE

At this point the JBoss EAP log may display the following error message. Thisis to be expected because the SSL configuration is not yet completed.

JBAS015103: A secure port has been specified for the HTTP interface but no SSL configuration in the realm.

Domain ModeChange the socket element within the management-interface section by adding secure-portand removing port configuration.

Ensure the JBoss EAP instance is running, then enter the following management CLIcommands:

NOTE

At this point the JBoss EAP log may display the following error message. Thisis to be expected because the SSL configuration is not yet completed.

JBAS015103: A secure port has been specified for the HTTP interface but no SSL configuration in the realm.

3. Optional: Custom socket-binding groupIf you are using a custom socket-binding group, ensure the management-https binding isdefined (it is present by default, bound to port 9443). Edit the master configuration file - forexample standalone.xml - to match the following.

/core-service=management/management-interface=http-interface:undefine-attribute(name=socket-binding)

/host=master/core-service=management/management-interface=http-interface:write-attribute(name=secure-port,value=9443)/host=master/core-service=management/management-interface=http-interface:undefine-attribute(name=port)

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> <socket-binding name="management-native" interface="management" port="${jboss.management.native.port:9999}"/> <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/> <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9443}"/>

Security Guide

50

4. Create a new Security RealmEnter the following commands to create a new security realm named ManagementRealmHTTPS:

/host=master/core-service=management/security-realm=ManagementRealmHTTPS/:add/host=master/core-service=management/security-realm=ManagementRealmHTTPS/authentication=properties/:add(path=ManagementUsers.properties, relative-to=jboss.domain.config.dir)

5. Configure Management Interface to use the new security realmEnter the following commands:

/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=ManagementRealmHTTPS)

6. Configure the management console to use the keystore.Enter the following management CLI command. For the parameters file, password and alias their values must be copied from the step Create a keystore to secure the managementconsole.

The expected output from this command is:

{ "outcome" => "success", "response-headers" => { "operation-requires-reload" => true, "process-state" => "reload-required" }}

7. Restart the JBoss EAP server.On restarting the server the log should contain the following, just before the text which states thenumber of services that are started. The management console is now listening on port 9443,which confirms that the procedure was successful.

14:53:14,720 INFO [org.jboss.as] (Controller Boot Thread) JBAS015962: Http management interface listening on https://127.0.0.1:9443/management14:53:14,721 INFO [org.jboss.as] (Controller Boot Thread) JBAS015952: Admin console listening on https://127.0.0.1:9443

NOTE

For security reasons it is recommended that you mask the keystore password. For detailson how to do this see Section 7.1, “Password Vault System”.

/core-service=management/security-realm=ManagementRealmHTTPS/server-identity=ssl:add(keystore-path=identity.jks,keystore-relative-to=jboss.server.config.dir, keystore-password=password1, alias=appserver)

CHAPTER 5. SECURE THE MANAGEMENT INTERFACES

51

Report a bug

5.8. USE DISTINCT INTERFACES FOR HTTP AND HTTPSCONNECTIONS TO THE MANAGEMENT INTERFACE

The Management Interface can listen on distinct interfaces for HTTP and HTTPS connections. Onescenario for this is to listen for encrypted traffic on an external network, and use unencrypted traffic on aninternal network.

The secure-interface attribute specifies the network interface on which the host's socket for HTTPSmanagement communication should be opened, if a different interface should be used from that specifiedby the interface attribute. If it is not specified then the interface specified by the interface attributeis used.

The secure-interface attribute has no effect if the secure-port attribute is not set.

Note that when the server listens for HTTP and HTTPS traffic on the same interface, HTTPS requestsreceived by the HTTP listener are automatically redirected to the HTTPS port. When distinct interfacesare used for HTTP and HTTPS traffic, no redirection is performed when an HTTPS request is receivedby the HTTP listener.

Here is an example EAP_HOME/domain/configuration/host.xml configuration that sets the secure-interface attribute to listen for HTTPS traffic on a distinct interface from HTTP traffic:

<?xml version='1.0' encoding='UTF-8'?>

<host name="master" xmlns="urn:jboss:domain:3.0">

<management> <security-realms> <security-realm name="ManagementRealm"> <authentication> <local default-user="$local" /> <properties path="mgmt-users.properties" relative-to="jboss.domain.config.dir"/> </authentication> </security-realm> </security-realms> <management-interfaces> <native-interface security-realm="ManagementRealm"> <socket interface="management" port="${jboss.management.native.port:9999}"/> </native-interface> <http-interface security-realm="ManagementRealm"> <socket interface="management" port="${jboss.management.http.port:9990}" secure-port="${jboss.management.https.port:9943}" secure-interface="secure-management"/> </http-interface> </management-interfaces> </management>

<domain-controller> <local/> <!-- Alternative remote domain controller configuration with a

Security Guide

52

host and port --> <!-- <remote host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}" security-realm="ManagementRealm"/> --> </domain-controller>

<interfaces> <interface name="management"> <inet-address value="${jboss.bind.address.management:127.0.0.1}"/> </interface> <interface name="secure-management"> <inet-address value="${jboss.bind.address:10.10.64.1}"/> </interface> </interfaces></host>

Report a bug

5.9. USING 2-WAY SSL FOR THE MANAGEMENT INTERFACE AND THECLI

2-way SSL authentication, also known as client authentication, authenticates both the client and theserver using SSL certificates. This provides assurance that not only is the server who it says it is, but theclient is also who it says it is.

In this topic the following conventions are used:

HOST1

The JBoss server hostname. For example; jboss.redhat.com

HOST2

A suitable name for the client. For example: myclient. Note this is not necessarily an actualhostname.

CA_HOST1

The DN (distinguished name) to use for the HOST1 certificate. For example cn=jboss,dc=redhat,dc=com.

CA_HOST2

The DN (distinguished name) to use for the HOST2 certificate. For example cn=myclient,dc=redhat,dc=com.

Prerequisites

If you are going to use a password vault to store the keystore and truststore passwords(recommended), the password vault should already be created. Refer to Section 7.1, “PasswordVault System”.

Procedure 5.3.

CHAPTER 5. SECURE THE MANAGEMENT INTERFACES

53

1. Generate the stores:

2. Export the certificates:

3. Import the certificates into the opposing trust stores:

4. Define a CertificateRealm in the configuration for your installation (host.xml or standalone.xml) and point the interface to it:

This can be done by manually editing the configuration file (not recommended) or by using thefollowing commands:

IMPORTANT

The provided commands apply to standalone mode only. For domain mode, add /host=master before each command.

5. Change the security-realm of the native-interface to the new Certificate Realm.

keytool -genkeypair -alias HOST1_alias -keyalg RSA -keysize 1024 -validity 365 -keystore host1.keystore.jks -dname "CA_HOST1" -keypass secret -storepass secret

keytool -genkeypair -alias HOST2_alias -keyalg RSA -keysize 1024 -validity 365 -keystore host2.keystore.jks -dname "CA_HOST2" -keypass secret -storepass secret

keytool -exportcert -keystore HOST1.keystore.jks -alias HOST1_alias -keypass secret -storepass secret -file HOST1.cer

keytool -exportcert -keystore HOST2.keystore.jks -alias HOST2_alias -keypass secret -storepass secret -file HOST2.cer

keytool -importcert -keystore HOST1.truststore.jks -storepass secret -alias HOST2_alias -trustcacerts -file HOST2.cer

keytool -importcert -keystore HOST2.truststore.jks -storepass secret -alias HOST1_alias -trustcacerts -file HOST1.cer

/core-service=management/security-realm=CertificateRealm:add()

/core-service=management/security-realm=CertificateRealm/server-identity=ssl:add(keystore-path=/path/to/HOST1.keystore.jks,keystore-password=secret, alias=HOST1_alias)

/core-service=management/security-realm=CertificateRealm/authentication=truststore:add(keystore-path=/path/to/HOST1.truststore.jks,keystore-password=secret)

Security Guide

54

6. Add the SSL configuration for the CLI, which uses EAP_HOME/bin/jboss-cli.xml as asettings file. Either use a password vault to store the keystore and truststore passwords(recommended), or store them in plain text:

To store the keystore and truststore passwords in a password vault:

Edit EAP_HOME/bin/jboss-cli.xml and add the SSL configuration (using theappropriate values for the variables). Also add the vault configuration, replacing each valuewith those of your vault.

To store the keystore and truststore passwords in plain text:

Edit EAP_HOME/bin/jboss-cli.xml and add the SSL configuration (using theappropriate values for the variables):

Report a bug

5.10. SECURE THE MANAGEMENT INTERFACES VIA JAAS

/host=master/core-service=management/management-interface=native-interface:write-attribute(name=security-realm,value=CertificateRealm)

<ssl> <vault> <vault-option name="KEYSTORE_URL" value="path-to/vault/vault.keystore"/> <vault-option name="KEYSTORE_PASSWORD" value="MASK-5WNXs8oEbrs"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="12345678"/> <vault-option name="ITERATION_COUNT" value="50"/> <vault-option name="ENC_FILE_DIR" value="path-to/jboss-eap/vault/"/> </vault> <alias>$HOST2alias</alias> <key-store>/path/to/HOST2.keystore.jks</key-store> <key-store-password>VAULT::VB::cli_pass::1</key-store-password> <key-password>VAULT::VB::cli_pass::1</key-password> <trust-store>/path/to/HOST2.truststore.jks</trust-store> <trust-store-password>VAULT::VB::cli_pass::1</trust-store-password> <modify-trust-store>true</modify-trust-store></ssl>

<ssl> <alias>$HOST2alias</alias> <key-store>/path/to/HOST2.keystore.jks</key-store> <key-store-password>secret</key-store-password> <trust-store>/path/to/HOST2.truststore.jks</trust-store> <trust-store-password>secret</trust-store-password> <modify-trust-store>true</modify-trust-store></ssl>

CHAPTER 5. SECURE THE MANAGEMENT INTERFACES

55

To use JAAS to authenticate to the Management interfaces:

First, create a security domain with the UsersRoles login module:

/subsystem=security/security-domain=UsersLMDomain:add(cache-type=default)/subsystem=security/security-domain=UsersLMDomain/authentication=classic:add/subsystem=security/security-domain=UsersLMDomain/authentication=classic/login-module=UsersRoles:add()

Then, create a security realm with JAAS Authentication:

/core-service=management/security-realm=SecurityDomainAuthnRealm:add/core-service=management/security-realm=SecurityDomainAuthnRealm/authentication=jaas:add(name=UsersLMDomain)

The attribute assign-groups determines whether loaded user membership information from theSecurity Domain is used for group assignment in the Security Realm. When set to true this groupassignment is used for Role-Based Access Control (RBAC).

The assign-groups attribute can be set to true by this CLI command:

/core-service=management/security-realm=ManagementRealm/authentication=jaas:write-attribute(name=assign-groups,value=true)

Report a bug

5.11. LDAP

5.11.1. About LDAP

Lightweight Directory Access Protocol (LDAP) is a protocol for storing and distributing directoryinformation across a network. This directory information includes information about users, hardwaredevices, access roles and restrictions, and other information.

Some common implementations of LDAP include OpenLDAP, Microsoft Active Directory, IBM TivoliDirectory Server, Oracle Internet Directory, and others.

JBoss EAP 6 includes several authentication and authorization modules which allow you to use a LDAPserver as the authentication and authorization authority for your Web and EJB applications.

Report a bug

5.11.2. Use LDAP to Authenticate to the Management Interfaces

To use an LDAP directory server as the authentication source for the Management Console,Management CLI, or Management API, you need to perform the following procedures:

1. Create an outbound connection to the LDAP server.

2. Create an LDAP-enabled security realm.

3. Reference the new security domain in the Management Interface.

Security Guide

56

Create an Outbound Connection to an LDAP Server

The LDAP outbound connection allows the following attributes:

Table 5.1. Attributes of an LDAP Outbound Connection

Attribute Required Description

url yes The URL address of the directoryserver.

search-dn no The fully distinguished name (DN)of the user authorized to performsearches.

search-credentials no The password of the userauthorized to perform searches.

initial-context-factory no The initial context factory to usewhen establishing the connection.Defaults to com.sun.jndi.ldap.LdapCtxFactory.

security-realm no The security realm to reference toobtain a configured SSLContextto use when establishing theconnection.

Example 5.10. Add an LDAP Outbound Connection

This example adds an outbound connection with the following properties set:

Search DN: cn=search,dc=acme,dc=com

Search Credential: myPass

URL: ldap://127.0.0.1:389

The first command adds the security realm.

/host=master/core-service=management/security-realm=ldap_security_realm:add

The second command adds the LDAP connection.

/host=master/core-service=management/ldap-connection=ldap_connection/:add(search-credential=myPass,url=ldap://127.0.0.1:389,search-dn="cn=search,dc=acme,dc=com")

Create an LDAP-Enabled Security Realm

The Management Interfaces can authenticate against LDAP server instead of the property-file based

CHAPTER 5. SECURE THE MANAGEMENT INTERFACES

57

security realms configured by default. The LDAP authenticator operates by first establishing aconnection to the remote directory server. It then performs a search using the username which the userpassed to the authentication system, to find the fully-qualified distinguished name (DN) of the LDAPrecord. A new connection is established, using the DN of the user as the credential, and passwordsupplied by the user. If this authentication to the LDAP server is successful, the DN is verified to be valid.

The LDAP security realm uses the following configuration attributes:

connection

The name of the connection defined in outbound-connections to use to connect to the LDAPdirectory.

advanced-filter

The fully defined filter used to search for a user based on the supplied user ID. The filter must containa variable in the following format: {0}. This is later replaced with the user name supplied by the user.

base-dn

The distinguished name of the context to begin searching for the user.

recursive

Whether the search should be recursive throughout the LDAP directory tree, or only search thespecified context. Defaults to false.

user-dn

The attribute of the user that holds the distinguished name. This is subsequently used to testauthentication as the user can complete. Defaults to dn.

username-attribute

The name of the attribute to search for the user. This filter performs a simple search where the username entered by the user matches the specified attribute.

allow-empty-passwords

This attribute determines whether an empty password is accepted. The default value for this attributeis false.

Either username-filter or advanced-filter must be specified

The advanced-filter attribute contains a filter query in the standard LDAP syntax, for example:

Example 5.11. XML Representing an LDAP-enabled Security Realm

This example uses the following parameters:

connection - ldap_connection

base-dn - cn=users,dc=acme,dc=com.

username-filter - attribute="sambaAccountName"

(&(sAMAccountName={0})(memberOf=cn=admin,cn=users,dc=acme,dc=com))

Security Guide

58

WARNING

It is important to ensure that you do not allow empty LDAP passwords; unless youspecifically desire this in your environment, it is a serious security concern.

EAP 6.1 includes a patch for CVE-2012-5629, which sets the allowEmptyPasswordsoption for the LDAP login modules to false if the option is not already configured. Forolder versions, this option should be configured manually

Example 5.12. Add an LDAP Security Realm

The command below adds an LDAP authentication to a security realm and sets its attributes for ahost named master in the domain.

/host=master/core-service=management/security-realm=ldap_security_realm/authentication=ldap:add(base-dn="DC=mycompany,DC=org", recursive=true, username-attribute="MyAccountName", connection="ldap_connection")

Apply the New Security Realm to the Management Interface

After you create a security realm, you need to reference it in the configuration of your managementinterface. The management interface will use the security realm for HTTP digest authentication.

Example 5.13. Apply the Security Realm to the HTTP Interface

After this configuration is in place, and you restart the host controller, the web-based ManagementConsole will use LDAP to authenticate its users.

/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=ldap_security_realm)

Example 5.14. Apply the Security Realm to the Native Interface

Use the following command to apply the same settings to the native interface:

<security-realm name="ldap_security_realm"> <authentication> <ldap connection="ldap_connection" base-dn="cn=users,dc=acme,dc=com"> <username-filter attribute="sambaAccountName" /> </ldap> </authentication></security-realm>

CHAPTER 5. SECURE THE MANAGEMENT INTERFACES

59

/host=master/core-service=management/management-interface=native-interface/:write-attribute(name=security-realm,value=ldap_security_realm)

Report a bug

5.11.3. Using Outbound LDAP with 2-way SSL in the Management Interface andCLI

JBoss EAP 6 can be configured to use an outbound connection to a LDAP server using 2-way SSL forauthentication in the Management Interface and CLI.

Prerequisites

An LDAP-enabled security realm must be created. See Section 5.11.2, “Use LDAP toAuthenticate to the Management Interfaces” for details on creating the security realm.

Procedure 5.4. Configure Outbound LDAP with 2-way SSL

1. Configure the security realm keystore and truststore. The security realm must contain a keystoreconfigured with the key that the JBoss EAP 6 server will use to authenticate against the LDAPserver. The security realm must also contain a truststore configured with the LDAP server'scertificates. See Section 5.9, “Using 2-way SSL for the Management interface and the CLI” forinstructions on configuring keystores and truststores.

2. Add the outbound connection to the LDAP server, specifying the configured security realm:

/core-service=management/ldap-connection=LocalLdap:add(url="ldaps://LDAP_HOST:LDAP_PORT")

/core-service=management/ldap-connection=LocalLdap:write-attribute(name=security-realm,value="LdapSSLRealm")

3. Configure LDAP authentication within the security realm and the management interfaces asshown in Section 5.11.2, “Use LDAP to Authenticate to the Management Interfaces”.

Report a bug

Security Guide

60

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITHROLE-BASED ACCESS CONTROL

6.1. ABOUT ROLE-BASED ACCESS CONTROL (RBAC)

Role-Based Access Control (RBAC) is a mechanism for specifying a set of permissions for managementusers. It allows multiple users to share responsibility for managing JBoss EAP 6 servers without each ofthem requiring unrestricted access. By providing "separation of duties" for management users, JBossEAP 6 makes it easy for an organization to spread responsibility between individuals or groups withoutgranting unnecessary privileges. This ensures the maximum possible security of your servers and datawhile still providing flexibility for configuration, deployment, and management.

Role-Based Access Control in JBoss EAP 6 works through a combination of role permissions andconstraints.

Seven predefined roles are provided that each have different fixed permissions. The predefined rolesare: Monitor, Operator, Maintainer, Deployer, Auditor, Administrator, and SuperUser. Each managementuser is assigned one or more roles, which specify what the user is permitted to do when managing theserver.

IMPORTANT

Before changing the provider to rbac, be sure your configuration has a user who will bemapped to one of the RBAC roles, preferably with at least one in the Administrator orSuperUser role. Otherwise your installation will not be manageable unless it is shut downand the XML configuration is edited.

If you have started with one of the standard XML configurations shipped with JBoss EAP6, the $local user will be mapped to the SuperUser role and the local authenticationscheme will be enabled. This will allow a user running the CLI on the same system as theJBoss EAP 6 process to have full administrative permissions. Remote CLI users and web-based admin console users will have no permissions.

Map at least one user other than $local before switching the provider to rbac.

Report a bug

6.2. ROLE-BASED ACCESS CONTROL IN THE MANAGEMENTCONSOLE AND CLI

When Role-Based Access Control (RBAC) is enabled, the role assigned to a user determines theresources to which they have access and what operations they can conduct with a resource's attributes.

The Management Console

In the management console some controls and views are disabled (greyed out) or not visible at alldepending on the permissions of the role to which the user has been assigned.

If you do not have read permissions to a resource attribute, that attribute will appear blank in theconsole. For example, most roles cannot read the username and password fields for datasources.

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

61

If you do not have write permissions to a resource attribute, that attribute will be disabled (greyed-out)in the edit form for the resource. If you do not have write permissions to the resource, then the editbutton for the resource will not appear.

If a user does not have permissions to access a resource or attribute (it is "unaddressable" for thatrole), it will not appear in the console for that user. An example of that is the access control systemitself which is only visible to a few roles by default.

The Management CLI or API

Users of the Management CLI or management API will encounter slightly different behavior in the APIwhen RBAC is enabled.

Resources and attributes that cannot be read are filtered from results. If the filtered items areaddressable by the role, their names are listed as filtered-attributes in the response-headers section of the result. If a resource or attribute is not addressable by the role, it is not listed.

Attempting to access a resource that is not addressable will result in a resource not found error.

If a user attempts to write or read a resource that they can address but lack the appropriate write orread permissions, a Permission Denied error is returned.

Report a bug

6.3. SUPPORTED AUTHENTICATION SCHEMES

Role-Based Access Control works with the standard authentication providers that are included withJBoss EAP 6. The standard authentication providers are: username/password, client certificate, and local user.

Username/Password

Users are authenticated using a username and password combination which is verified against eitherthe mgmt-users.properties file, or an LDAP server.

Client Certificate

Using the Trust Store.

Local User

jboss-cli.sh authenticates automatically as Local User if the server that is running on the samemachine. By default Local User is a member of the SuperUser group.

Regardless of which provider is used, JBoss EAP is responsible for the assignment of roles to users.However when authenticating with the mgmt-users.properties file or an LDAP server, thosesystems can supply user group information. This information can also be used by JBoss EAP to assignroles to users.

Report a bug

6.4. THE STANDARD ROLES

Security Guide

62

JBoss EAP 6 provides seven predefined user roles: Monitor, Operator, Maintainer, Deployer, Auditor,Administrator, and SuperUser. Each of these roles has a different set of permissions and is designed forspecific use cases. The Monitor, Operator, Maintainer, Administrator, and SuperUser role each buildupon each other, with each having more permissions than the previous. The Auditor and Deployer rolesare similar to the Monitor and Maintainer roles respectively but have some additional special permissionsand restrictions.

Monitor

Users of the Monitor role have the fewest permissions and can only read the current configurationand state of the server. This role is intended for users who need to track and report on theperformance of the server.

Monitors cannot modify server configuration nor can they access sensitive data or operations.

Operator

The Operator role extends the Monitor role by adding the ability to modify the runtime state of theserver. This means that Operators can reload and shutdown the server as well as pause and resumeJMS destinations. The Operator role is ideal for users who are responsible for the physical or virtualhosts of the application server so they can ensure that servers can be shutdown and restartedcorrected when needed.

Operators cannot modify server configuration or access sensitive data or operations.

Maintainer

The Maintainer role has access to view and modify runtime state and all configuration exceptsensitive data and operations. The Maintainer role is the general purpose role that doesn't haveaccess to sensitive data and operation. The Maintainer role allows users to be granted almostcomplete access to administer the server without giving those users access to passwords and othersensitive information.

Maintainers cannot access sensitive data or operations.

Administrator

The Administrator role has unrestricted access to all resources and operations on the server exceptthe audit logging system. The Administrator role has access to sensitive data and operations. Thisrole can also configure the access control system. The Administrator role is only required whenhandling sensitive data or configuring users and roles.

Administrators cannot access the audit logging system and cannot change themselves to the Auditoror SuperUser role.

SuperUser

The SuperUser role has no restrictions and has complete access to all resources and operations ofthe server including the audit logging system. This role is equivalent to the administrator users ofearlier versions of JBoss EAP 6 (6.0 and 6.1). If RBAC is disabled, all management users havepermissions equivalent to the SuperUser role.

Deployer

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

63

The Deployer role has the same permissions as the Monitor, but can modify configuration and statefor deployments and any other resource type enabled as an application resource.

Auditor

The Auditor role has all the permissions of the Monitor role and can also view (but not modify)sensitive data, and has full access to the audit logging system. The Auditor role is the only role otherthan SuperUser that can access the audit logging system.

Auditors cannot modify sensitive data or resources. Only read access is permitted.

Report a bug

6.5. ABOUT ROLE PERMISSIONS

What each role is allowed to do is defined by what permissions it has. Not every role has everypermission. Notably SuperUser has every permission and Monitor has the least.

Each permission can grant read and/or write access for a single category of resources.

The categories are: runtime state, server configuration, sensitive data, the audit log, and the accesscontrol system.

Table 6.1, “Role Permissions Matrix” summarizes the permissions of each role.

Table 6.1. Role Permissions Matrix

Monitor Operator Maintainer

Deployer

Auditor Administrator

SuperUser

Read Config andState

X X X X X X X

Read Sensitive Data[2]

X X X

Modify Sensitive Data[2]

X X

Read/Modify AuditLog

X X

Modify Runtime State X X X[1] X X

Modify PersistentConfig

X X[1] X X

Security Guide

64

Read/Modify AccessControl

X X

[1] permissions are restricted to application resources.

[2] What resources are considered to be "sensitive data" are configured using Sensitivity Constraints.

Report a bug

6.6. ABOUT CONSTRAINTS

Constraints are named sets of access-control configuration for a specified list of resources. The RBACsystem uses the combination of constraints and role permissions to determine if any specific user canperform a management action.

Constraints are divided into three classifications: application, sensitivity and vault expression.

Application Constraints

Application Constraints define sets of resources and attributes that can be accessed by users of theDeployer role. By default the only enabled Application Constraint is core which includes deployments,deployment overlays. Application Constraints are also included (but not enabled by default) fordatasources, logging, mail, messaging, naming, resource-adapters and security. These constraintsallow Deployer users to not only deploy applications but also configure and maintain the resourcesthat are required by those applications.

Application constraint configuration is in the Management API at /core-service=management/access=authorization/constraint=application-classification.

Sensitivity Constraints

Sensitivity Constraints define sets of resources that are considered "sensitive". A sensitive resourceis generally one that is either secret, like a password, or one that will have serious impact on theoperation of the server, like networking, JVM configuration, or system properties. The access controlsystem itself is also considered sensitive.

The only roles permitted to write to sensitive resources are Administrator and SuperUser. The Auditorrole is only able to read sensitive resources. No other roles have access.

Sensitivity constraint configuration is in the Management API at /core-service=management/access=authorization/constraint=sensitivity-classification.

Vault Expression Constraint

The Vault Expression constraint defines if reading or writing vault expressions is consider a sensitiveoperation. By default both reading and writing vault expressions is a sensitive operation.

Vault Expression constraint configuration is in the Management API at /core-service=management/access=authorization/constraint=vault-expression.

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

65

Constraints can not be configured in the Management Console at this time.

Report a bug

6.7. ABOUT JMX AND ROLE-BASED ACCESS CONTROL

Role-Based Access Control applies to JMX in three ways:

1. The Management API of JBoss EAP 6 is exposed as JMX Management Beans. TheseManagement Beans are referred to as "core mbeans" and access to them is controlled andfiltered exactly the same as the underlying Management API itself.

2. The JMX subsystem is configured with write permissions being "sensitive". This means onlyusers of the Administrator and SuperUser roles can make changes to that subsystem. Users ofthe Auditor role can also read this subsystem configuration.

3. By default Management Beans registered by deployed applications and services (non-corembeans) can be accessed by all management users, but only users of the Maintainer, Operator,Administrator, SuperUser roles can write to them.

NOTE

Users can receive JMX notifications from a JMX client, such as jconsole. This feature islimited to local JMX connections. The JMX client must be connected either inside thesame JVM as the application server, or on the same machine and use the Attach agent toconnect to the application server (as jconsole does). JMX notifications for MBeanregistration/unregistration and attribute value changes are now also generated forMBeans in jboss.as and jboss.as.expr domains.

Report a bug

6.8. CONFIGURING ROLE-BASED ACCESS CONTROL

6.8.1. Overview of RBAC Configuration Tasks

When RBAC is enabled only users of the Administration or SuperUser role can view and make changesto the Access Control system.

The management console provides an interface for the following common RBAC tasks:

View and configure what roles are assigned to (or excluded from) each user

View and configure what roles are assigned to (or excluded from) each group

View group and user membership per role.

Configure default membership per role.

Create a scoped role

Security Guide

66

NOTE

The Management Console cannot be used to enable or disable RBAC. Those settingsare not exposed in the UI. Use the command line interface to perform these tasks.

The management CLI provides access to the complete access control system. This means thateverything that can be done in the management console can be done there, but a number of additionaltasks can be performed with the management CLI that cannot be done with the management console.

The following additional tasks can be performed in the CLI:

Enable and disable RBAC

Change permission combination policy

Configuring Application Resource and Resource Sensitivity Constraints

Report a bug

6.8.2. Enabling Role-Based Access Control

By default the Role-Based Access Control (RBAC) system is disabled. It is enabled by changing theprovider attribute from simple to rbac. This can be done using the Management CLI or by editing theserver configuration XML file if the server is offline. When RBAC is disabled or enabled on a runningserver, the server configuration must be reloaded before it takes effect.

Once enabled it can only be disabled by a user of the Administrator or SuperUser roles. By default theManagement CLI runs as the SuperUser role if it is run on the same machine as the server.

Procedure 6.1. Enabling RBAC

To enable RBAC with the Management CLI, use the write-attribute operation of theaccess authorization resource to set the provider attribute to rbac.

/core-service=management/access=authorization:write-attribute(name=provider, value=rbac)

[standalone@localhost:9999 /] /core-service=management/access=authorization:write-attribute(name=provider, value=rbac){ "outcome" => "success", "response-headers" => { "operation-requires-reload" => true, "process-state" => "reload-required" }}[standalone@localhost:9999 /] /:reload{ "outcome" => "success", "result" => undefined}

Procedure 6.2. Disabling RBAC

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

67

To disable RBAC with the Management CLI, use the write-attribute operation of theaccess authorization resource to set the provider attribute to simple.

/core-service=management/access=authorization:write-attribute(name=provider, value=simple)

[standalone@localhost:9999 /] /core-service=management/access=authorization:write-attribute(name=provider, value=simple){ "outcome" => "success", "response-headers" => { "operation-requires-reload" => true, "process-state" => "reload-required" }}[standalone@localhost:9999 /] /:reload{ "outcome" => "success", "result" => undefined}

If the server is offline the XML configuration can be edited to enabled or disable RBAC. To do this, editthe provider attribute of the access-control element of the management element. Set the value to rbac to enable, and simple to disable.

Report a bug

6.8.3. Changing the Permission Combination Policy

The Permission Combination Policy determines how permissions are determined if a user is assignedmore than one role. This can be set to permissive or rejecting. The default is permissive.

When set to permissive, if any role is assigned to the user that permits an action, then the action isallowed.

When set to rejecting, if multiple roles are assigned to a user, then no action is allowed. This meansthat when the policy is set to rejecting each user should only be assigned one role. Users withmultiple roles will not be able to use the Management Console or the Management CLI when the policy isset to rejecting.

<management>

<access-control provider="rbac"> <role-mapping> <role name="SuperUser"> <include> <user name="$local"/> </include> </role> </role-mapping> </access-control>

</management>

Security Guide

68

The Permission Combination Policy is configured by setting the permission-combination-policyattribute to either permissive or rejecting. This can be done using the Management CLI or byediting the server configuration XML file if the server is offline.

Procedure 6.3. Set the Permission Combination Policy

Use the write-attribute operation of the access authorization resource to set the permission-combination-policy attribute to the required policy name.

/core-service=management/access=authorization:write-attribute(name=permission-combination-policy, value=POLICYNAME)

The valid policy names are rejecting and permissive.

[standalone@localhost:9999 /] /core-service=management/access=authorization:write-attribute(name=permission-combination-policy, value=rejecting){"outcome" => "success"}[standalone@localhost:9999 access=authorization]

If the server is offline the XML configuration can be edited to change the permission combination policyvalue. To do this, edit the permission-combination-policy attribute of the access-control element.

Report a bug

6.9. MANAGING ROLES

6.9.1. About Role Membership

When Role-Based Access Control (RBAC) is enabled, what a management user is permitted to do isdetermined by the roles to which the user is assigned. JBoss EAP 6 uses a system of includes andexcludes based on both the user and group membership to determine to which role a user belongs.

A user is considered to be assigned to a role if:

1. The user is:

listed as a user to be included in the role, or

a member of a group that is listed to be included in the role.

2. The user is not:

<access-control provider="rbac" permission-combination-policy="rejecting"> <role-mapping> <role name="SuperUser"> <include> <user name="$local"/> </include> </role> </role-mapping></access-control>

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

69

listed as a user to exclude from the role, or

a member of a group that is listed to be excluded from the role.

Exclusions take priority over inclusions.

Role include and exclude settings for users and groups can be configured using both the managementconsole and the management CLI.

Only users of the SuperUser or Administrator roles can perform this configuration.

Report a bug

6.9.2. Configure User Role Assignment

Roles for a user to be included in and excluded from can be configured in the Management Console andthe Management CLI. This topic only shows using the Management Console.

Only users in the SuperUser or Administrator roles can perform this configuration.

The User roles configuration in the management console can be found by following these steps:

1. Login to the Management Console.

2. Click on the Administration tab.

3. Expand the Access Control menu and select Role Assignment.

4. Select the USERS tab.

Procedure 6.4. Create a new role assignment for a user

1. Login to the Management console.

2. Navigate to the Users tab of the Role Assignment section.

3. Click the Add button at the top right of the user list. Add User dialog appears.

Security Guide

70

Figure 6.1. Add User Dialog

4. Specify user name, and optionally realm.

5. Set the type menu to include or exclude.

6. Click the checkbox of the roles to include or exclude. To check multiple items, hold down theControl key (Command key on OSX).

7. Click Save to finish.

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

71

When successful, the Add User dialog closes, and the list of users is updated to reflect thechanges made. If unsuccessful a Failed to save role assignment message isdisplayed.

Procedure 6.5. Update the role assignment for a user

1. Login to the Management console.

2. Navigate to the Users tab of the Role Assignment section.

3. Select user from the list.

4. Click Edit. The selection panel enters edit mode.

Figure 6.2. Selection Edit View

Here you can add and remove assigned and excluded roles for the user.

1. To add an assigned role, select the required role from the list of available roles on the leftand click button with the right-facing arrow next to the assigned roles list. The role movesfrom the available list to the assigned list.

Security Guide

72

2. To remove an assigned role, selected the required role from the assigned roles list on theright and click the button with the left-facing arrow next to the assigned roles list. The rolemoves from the assigned list to the available list.

3. To add an excluded role, select the required role from the list of available roles on the leftand click button with the right-facing arrow next to the excluded roles list. The role movesfrom the available list to the excluded list.

4. To remove an excluded role, selected the required role from the excluded roles list on theright and click the button with the left-facing arrow next to the excluded roles list. The rolemoves from the excluded list to the available list.

5. Click Save to finish.

When successful, the edit view closes, and the list of users is updated to reflect the changesmade. If unsuccessful a Failed to save role assignment message is displayed.

Procedure 6.6. Remove role assignment for a user

1. Login to the Management console.

2. Navigate to the Users tab of the Role Assignment section.

3. Select the user from the list.

4. Click Remove. The Remove Role Assignment confirmation prompt appears.

5. Click Confirm.

When successful, the user will no longer appear in the list of user role assignments.

IMPORTANT

Removing the user from the list of role assignments does not remove the user from thesystem, nor does it guarantee that no roles will be assigned to the user. Roles might stillbe assigned from group membership.

Report a bug

6.9.3. Configure User Role Assignment using the Management CLI

Roles for a user to be included in and excluded from can be configured in the Management Console andthe Management CLI. This topic only shows using the Management CLI.

The configuration of mapping users and groups to roles is located in the management API at: /core-service=management/access=authorization as role-mapping elements.

Only users of the SuperUser or Administrator roles can perform this configuration.

For easier access to the commands, in the Management CLI change to the /core-service=management/access=authorization location:

[standalone@localhost:9999] cd /core-service=management/access=authorization

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

73

Procedure 6.7. Viewing Role Assignment Configuration

1. Use the :read-children-names operation to get a complete list of the configured roles:

/core-service=management/access=authorization:read-children-names(child-type=role-mapping)

[standalone@localhost:9999 access=authorization] :read-children-names(child-type=role-mapping){ "outcome" => "success", "result" => [ "Administrator", "Deployer", "Maintainer", "Monitor", "Operator", "SuperUser" ]}

2. Use the read-resource operation of a specified role-mapping to get the full details of aspecific role:

/core-service=management/access=authorization/role-mapping=ROLENAME:read-resource(recursive=true)

[standalone@localhost:9999 access=authorization] ./role-mapping=Administrator:read-resource(recursive=true){ "outcome" => "success", "result" => { "include-all" => false, "exclude" => undefined, "include" => { "user-theboss" => { "name" => "theboss", "realm" => undefined, "type" => "USER" }, "user-harold" => { "name" => "harold", "realm" => undefined, "type" => "USER" }, "group-SysOps" => { "name" => "SysOps", "realm" => undefined, "type" => "GROUP" } } }}[standalone@localhost:9999 access=authorization]

Security Guide

74

Procedure 6.8. Add a new role

This procedure shows how to add a role-mapping entry for a role. This must be done before the role canbe configured.

Use the add operation to add a new role configuration.

/core-service=management/access=authorization/role-mapping=ROLENAME:add

ROLENAME is the name of the role that the new mapping is for.

[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor:add {"outcome" => "success"}[standalone@localhost:9999 access=authorization]

Procedure 6.9. Add a user as included in a role

This procedure shows how to add a user to the included list of a role.

If no configuration for a role has been done, then a role-mapping entry for it must be done first.

Use the add operation to add a user entry to the includes list of the role.

/core-service=management/access=authorization/role-mapping=ROLENAME/include=ALIAS:add(name=USERNAME, type=USER)

ROLENAME is the name of the role being configured.

ALIAS is a unique name for this mapping. Red Hat recommends that you use a namingconvention for your aliases such as user-USERNAME.

USERNAME is the name of the user being added to the include list.

[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/include=user-max:add(name=max, type=USER){"outcome" => "success"}[standalone@localhost:9999 access=authorization]

Procedure 6.10. Add a user as excluded in a role

This procedure shows how to add a user to the excluded list of a role.

If no configuration for a role has been done, then a role-mapping entry for it must be done first.

Use the add operation to add a user entry to the excludes list of the role.

/core-service=management/access=authorization/role-mapping=ROLENAME/exclude=ALIAS:add(name=USERNAME, type=USER)

ROLENAME is the name of the role being configured.

USERNAME is the name of the user being added to the exclude list.

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

75

ALIAS is a unique name for this mapping. Red Hat recommends that you use a namingconvention for your aliases such as user-USERNAME.

[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/exclude=user-max:add(name=max, type=USER){"outcome" => "success"}[standalone@localhost:9999 access=authorization]

Procedure 6.11. Remove user role include configuration

This procedure shows how to remove a user include entry from a role mapping.

Use the remove operation to remove the entry.

/core-service=management/access=authorization/role-mapping=ROLENAME/include=ALIAS:remove

ROLENAME is the name of the role being configured

ALIAS is a unique name for this mapping. Red Hat recommends that you use a namingconvention for your aliases such as user-USERNAME.

[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/include=user-max:remove{"outcome" => "success"}[standalone@localhost:9999 access=authorization]

Removing the user from the list of includes does not remove the user from the system, nor doesit guarantee that the role won't be assigned to the user. The role might still be assigned based ongroup membership.

Procedure 6.12. Remove user role exclude configuration

This procedure shows how to remove an user exclude entry from a role mapping.

Use the remove operation to remove the entry.

/core-service=management/access=authorization/role-mapping=ROLENAME/exclude=ALIAS:remove

ROLENAME is the name of the role being configured.

ALIAS is a unique name for this mapping. Red Hat recommends that you use a namingconvention for your aliases such as user-USERNAME.

[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/exclude=user-max:remove{"outcome" => "success"}[standalone@localhost:9999 access=authorization]

Removing the user from the list of excludes does not remove the user from the system, nor doesit guarantee the role will be assigned to the user. Roles might still be excluded based on groupmembership.

Security Guide

76

Report a bug

6.9.4. About Roles and User Groups

Users authenticated using either the mgmt-users.properties file or an LDAP server, can bemembers of user groups. A user group is an arbitrary label that can be assigned to one or more users.

The RBAC system can be configured to automatically assign roles to users depending on what usergroups they are members of. It can also exclude users from roles based on group membership.

When using the mgmt-users.properties file, group information is stored in the mgmt-groups.properties file. When using LDAP the group information is stored in the LDAP sever andmaintained by those responsible for the LDAP server.

Report a bug

6.9.5. Configure Group Role Assignment

Roles can be assigned to a user based on the user's membership of a user group.

Groups to be included or excluded from a role can be configured in the Management Console and theManagement CLI. This topic only shows using the Management Console.

Only users in the SuperUser or Administrator roles can perform this configuration.

The Group roles configuration in the management console can be found by following these steps:

1. Login to the Management Console.

2. Click on the Administration tab.

3. Expand the Access Control menu and select Role Assignment.

4. Select the GROUPS tab.

Procedure 6.13. Create a new role assignment for a group

1. Login to the Management console

2. Navigate to the GROUPS tab of the Role Assignment section.

3. Click the Add button at the top right of the user list. Add Group dialog appears.

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

77

Figure 6.3. Add Group Dialog

4. Specify the group name, and optionally the realm.

5. Set the type menu to include or exclude.

6. Click the checkbox of the roles to include or exclude. To check multiple items, hold down theControl key (Command key on OSX).

7. Click Save to finish.

Security Guide

78

When successful, the Add Group dialog closes, and the list of groups is updated to reflect thechanges made. If unsuccessful a Failed to save role assignment message isdisplayed.

Procedure 6.14. Update a role assignment for a group

1. Login to the Management console.

2. Navigate to the GROUPS tab of the Role Assignment section.

3. Select the group from the list.

4. Click Edit. The Selection view enters Edit mode.

Figure 6.4. Selection View Edit Mode

Here you can add and remove assigned and excluded roles from the group:

To add assigned role, select the required role from the list of available roles on the left andclick button with the right-facing arrow next to the assigned roles list. The role moves fromthe available list to the assigned list.

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

79

To remove an assigned role, selected the required role from the assigned roles list on theright and click the button with the left-facing arrow next to the assigned roles list. The rolemoves from the assigned list to the available list.

To add an excluded role, select the required role from the list of available roles on the leftand click button with the right-facing arrow next to the excluded roles list. The role movesfrom the available list to the excluded list.

To remove an excluded role, selected the required role from the excluded roles list on theright and click the button with the left-facing arrow next to the excluded roles list. The rolemoves from the excluded list to the available list.

5. Click Save to finish.

When successful, the edit view closes, and the list of groups is updated to reflect the changesmade. If unsuccessful a Failed to save role assignment message is displayed.

Procedure 6.15. Remove role assignment for a group

1. Login to the Management console.

2. Navigate to the GROUPS tab of the Role Assignment section.

3. Select the group from the list.

4. Click Remove. The Remove Role Assignment confirmation prompt appears.

5. Click Confirm.

When successful, the role will no longer appear in the list of group role assignments.

Removing the group from the list of role assignments does not remove the user group from thesystem, nor does it guarantee that no roles will be assigned to members of that group. Eachgroup member might still have a role assigned to them directly.

Report a bug

6.9.6. Configure Group Role Assignment using the Management CLI

Groups to be included or excluded from a role can be configured in the Management Console and theManagement CLI. This topic only shows using the Management CLI.

The configuration of mapping users and groups to roles is located in the management API at: /core-service=management/access=authorization as role-mapping elements.

Only users in the SuperUser or Administrator roles can perform this configuration.

For easier access to the commands, in the Management CLI change to the /core-service=management/access=authorization location:

[standalone@localhost:9999] cd /core-service=management/access=authorization

Procedure 6.16. Viewing Group Role Assignment Configuration

Security Guide

80

1. Use the read-children-names operation to get a complete list of the configured roles:

/core-service=management/access=authorization:read-children-names(child-type=role-mapping)

[standalone@localhost:9999 access=authorization] :read-children-names(child-type=role-mapping){ "outcome" => "success", "result" => [ "Administrator", "Deployer", "Maintainer", "Monitor", "Operator", "SuperUser" ]}

2. Use the read-resource operation of a specified role-mapping to get the full details of aspecific role:

/core-service=management/access=authorization/role-mapping=ROLENAME:read-resource(recursive=true)

[standalone@localhost:9999 access=authorization] ./role-mapping=Administrator:read-resource(recursive=true){ "outcome" => "success", "result" => { "include-all" => false, "exclude" => undefined, "include" => { "user-theboss" => { "name" => "theboss", "realm" => undefined, "type" => "USER" }, "user-harold" => { "name" => "harold", "realm" => undefined, "type" => "USER" }, "group-SysOps" => { "name" => "SysOps", "realm" => undefined, "type" => "GROUP" } } }}[standalone@localhost:9999 access=authorization]

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

81

Procedure 6.17. Add a new role

This procedure shows how to add a role-mapping entry for a role. This must be done before the role canbe configured.

Use the add operation to add a new role configuration.

/core-service=management/access=authorization/role-mapping=ROLENAME:add

[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor:add {"outcome" => "success"}[standalone@localhost:9999 access=authorization]

Procedure 6.18. Add a Group as included in a role

This procedure shows how to add a Group to the included list of a role.

If no configuration for a role has been done, then a role-mapping entry for it must be done first.

Use the add operation to add a Group entry to the includes list of the role.

/core-service=management/access=authorization/role-mapping=ROLENAME/include=ALIAS:add(name=GROUPNAME, type=GROUP)

ROLENAME is the name of the role being configured.

GROUPNAME is the name of the group being added to the include list.

ALIAS is a unique name for this mapping. Red Hat recommends that you use a namingconvention for your aliases such as group-GROUPNAME.

[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/include=group-investigators:add(name=investigators, type=GROUP){"outcome" => "success"}[standalone@localhost:9999 access=authorization]

Procedure 6.19. Add a group as excluded in a role

This procedure shows how to add a group to the excluded list of a role.

If no configuration for a role has been done, then a role-mapping entry for it must be created first.

Use the add operation to add a group entry to the excludes list of the role.

/core-service=management/access=authorization/role-mapping=ROLENAME/exclude=ALIAS:add(name=GROUPNAME, type=GROUP)

ROLENAME is the name of the role being configured

GROUPNAME is the name of the group being added to the include list

Security Guide

82

ALIAS is a unique name for this mapping. Red Hat recommends that you use a namingconvention for your aliases such as group-GROUPNAME.

[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/exclude=group-supervisors:add(name=supervisors, type=GROUP){"outcome" => "success"}[standalone@localhost:9999 access=authorization]

Procedure 6.20. Remove group role include configuration

This procedure shows how to remove a group include entry from a role mapping.

Use the remove operation to remove the entry.

/core-service=management/access=authorization/role-mapping=ROLENAME/include=ALIAS:remove

ROLENAME is the name of the role being configured

ALIAS is a unique name for this mapping. Red Hat recommends that you use a namingconvention for your aliases such as group-GROUPNAME.

[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/include=group-investigators:remove{"outcome" => "success"}[standalone@localhost:9999 access=authorization]

Removing the group from the list of includes does not remove the group from the system, nordoes it guarantee that the role won't be assigned to users in this group. The role might still beassigned to users in the group individually.

Procedure 6.21. Remove a user group exclude entry

This procedure shows how to remove a group exclude entry from a role mapping.

Use the remove operation to remove the entry.

/core-service=management/access=authorization/role-mapping=ROLENAME/exclude=ALIAS:remove

ROLENAME is the name of the role being configured.

ALIAS is a unique name for this mapping. Red Hat recommends that you use a namingconvention for your aliases such as group-GROUPNAME.

[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/exclude=group-supervisors:remove{"outcome" => "success"}[standalone@localhost:9999 access=authorization]

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

83

Removing the group from the list of excludes does not remove the group from the system. It alsodoes not guarantee the role will be assigned to members of the group. Roles might still beexcluded based on group membership.

Report a bug

6.9.7. About Authorization and Group Loading with LDAP

An LDAP directory contains entries for user accounts and groups, cross referenced by attributes.Depending on the LDAP server configuration, a user entity may map the groups the user belongs tothrough memberOf attributes; a group entity may map which users belong to it through uniqueMemberattributes; or both mappings may be maintained by the LDAP server.

Users generally authenticate against the server using a simple user name. When searching for groupmembership information, depending on the directory server in use, searches could be performed usingthis simple name or using the distinguished name of the user's entry in the directory.

The authentication step of a user connecting to the server always happens first. Once the user issuccessfully authenticated the server loads the user's groups. The authentication step and theauthorization step each require a connection to the LDAP server. The realm optimizes this process byreusing the authentication connection for the group loading step. As will be shown within theconfiguration steps below it is possible to define rules within the authorization section to convert a user'ssimple user name to their distinguished name. The result of a "user name to distinguished namemapping" search during authentication is cached and reused during the authorization query when the force attribute is set to "false". When force is true, the search is performed again during authorization(while loading groups). This is typically done when different servers perform authentication andauthorization.

<authorization> <ldap connection="..."> <!-- OPTIONAL --> <username-to-dn force="true"> <!-- Only one of the following. --> <username-is-dn /> <username-filter base-dn="..." recursive="..." user-dn-attribute="..." attribute="..." /> <advanced-filter base-dn="..." recursive="..." user-dn-attribute="..." filter="..." /> </username-to-dn> <group-search group-name="..." iterative="..." group-dn-attribute="..." group-name-attribute="..." > <!-- One of the following --> <group-to-principal base-dn="..." recursive="..." search-by="..."> <membership-filter principal-attribute="..." /> </group-to-principal> <principal-to-group group-attribute="..." /> </group-search> </ldap></authorization>

Security Guide

84

IMPORTANT

These examples specify some attributes with their default values. This is done fordemonstration. Attributes that specify their default values are removed from theconfiguration when it is persisted by the server. The exception is the force attribute. It isrequired, even when set to the default value of false.

username-to-dnThe username-to-dn element specifies how to map the user name to the distinguished name of theirentry in the LDAP directory. This element is only required when both of the following are true:

The authentication and authorization steps are against different LDAP servers.

The group search uses the distinguished name.

1:1 username-to-dn

This specifies that the user name entered by the remote user is the user's distinguished name.

This defines a 1:1 mapping and there is no additional configuration.

username-filter

The next option is very similar to the simple option described above for the authentication step. Aspecified attribute is searched for a match against the supplied user name.

The attributes that can be set here are:

base-dn: The distinguished name of the context to begin the search.

recursive: Whether the search will extend to sub contexts. Defaults to false.

attribute: The attribute of the users entry to try and match against the supplied user name.Defaults to uid.

user-dn-attribute: The attribute to read to obtain the users distinguished name.Defaults to dn.

advanced-filter

The final option is to specify an advanced filter, as in the authentication section this is an opportunityto use a custom filter to locate the users distinguished name.

<username-to-dn force="false"> <username-is-dn /></username-to-dn>

<username-to-dn force="true"> <username-filter base-dn="dc=people,dc=harold,dc=example,dc=com" recursive="false" attribute="sn" user-dn-attribute="dn" /></username-to-dn>

<username-to-dn force="true"> <advanced-filter base-dn="dc=people,dc=harold,dc=example,dc=com"

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

85

For the attributes that match those in the username-filter example, the meaning and default valuesare the same. There is one new attribute:

filter: Custom filter used to search for a user's entry where the user name will besubstituted in the {0} place holder.

IMPORTANT

The XML must remain valid after the filter is defined so if any special characters areused such as & ensure the proper form is used. For example &amp; for the &character.

The Group Search

There are two different styles that can be used when searching for group membership information. Thefirst style is where the user's entry contains an attribute that references the groups the user is a memberof. The second style is where the group contains an attribute referencing the users entry.

When there is a choice of which style to use Red Hat recommends that the configuration for a user'sentry referencing the group is used. This is because with this method group information can be loadedby reading attributes of known distinguished names without having to perform any searches. The otherapproach requires extensive searches to identify the groups that reference the user.

Before describing the configuration here are some LDIF examples to illustrate this.

Example 6.1. Principal to Group - LDIF example.

This example illustrates where we have a user TestUserOne who is a member of GroupOne, GroupOne is in turn a member of GroupFive. The group membership is shown by the use of a memberOf attribute which is set to the distinguished name of the group of which the user (or group) isa member.

It is not shown here but a user could potentially have multiple memberOf attributes set, one for eachgroup of which the user is directly a member.

recursive="false" filter="sAMAccountName={0}" user-dn-attribute="dn" /></username-to-dn>

dn: uid=TestUserOne,ou=users,dc=principal-to-group,dc=example,dc=orgobjectClass: extensibleObjectobjectClass: topobjectClass: groupMemberobjectClass: inetOrgPersonobjectClass: uidObjectobjectClass: personobjectClass: organizationalPersoncn: Test User Onesn: Test User Oneuid: TestUserOnedistinguishedName: uid=TestUserOne,ou=users,dc=principal-to-group,dc=example,dc=orgmemberOf: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=orgmemberOf: uid=Slashy/Group,ou=groups,dc=principal-to-

Security Guide

86

Example 6.2. Group to Principal - LDIF Example

This example shows the same user TestUserOne who is a member of GroupOne which is in turn amember of GroupFive - however in this case it is an attribute uniqueMember from the group to theuser being used for the cross reference.

Again the attribute used for the group membership cross reference can be repeated, if you look atGroupFive there is also a reference to another user TestUserFive which is not shown here.

group,dc=example,dc=orguserPassword:: e1NTSEF9WFpURzhLVjc4WVZBQUJNbEI3Ym96UVAva0RTNlFNWUpLOTdTMUE9PQ==

dn: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=orgobjectClass: extensibleObjectobjectClass: topobjectClass: groupMemberobjectClass: groupobjectClass: uidObjectuid: GroupOnedistinguishedName: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=orgmemberOf: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-to-group,dc=example,dc=org

dn: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-to-group,dc=example,dc=orgobjectClass: extensibleObjectobjectClass: topobjectClass: groupMemberobjectClass: groupobjectClass: uidObjectuid: GroupFivedistinguishedName: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-to-group,dc=example,dc=org

dn: uid=TestUserOne,ou=users,dc=group-to-principal,dc=example,dc=orgobjectClass: topobjectClass: inetOrgPersonobjectClass: uidObjectobjectClass: personobjectClass: organizationalPersoncn: Test User Onesn: Test User Oneuid: TestUserOneuserPassword:: e1NTSEF9SjR0OTRDR1ltaHc1VVZQOEJvbXhUYjl1dkFVd1lQTmRLSEdzaWc9PQ==

dn: uid=GroupOne,ou=groups,dc=group-to-principal,dc=example,dc=orgobjectClass: topobjectClass: groupOfUniqueNamesobjectClass: uidObjectcn: Group Oneuid: GroupOne

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

87

General Group Searching

Before looking at the examples for the two approaches shown above we first need to define the attributescommon to both of these.

group-name: This attribute is used to specify the form that should be used for the group namereturned as the list of groups of which the user is a member. This can either be the simple formof the group name or the group's distinguished name. If the distinguished name is required thisattribute can be set to DISTINGUISHED_NAME. Defaults to SIMPLE.

iterative: This attribute is used to indicate if, after identifying the groups a user is a memberof, we should also iteratively search based on the groups to identify which groups the groups area member of. If iterative searching is enabled we keep going until either we reach a group that isnot a member if any other groups or a cycle is detected. Defaults to false.

Cyclic group membership is not a problem. A record of each search is kept to prevent groups that havealready been searched from being searched again.

IMPORTANT

For iterative searching to work the group entries need to look the same as user entries.The same approach used to identify the groups a user is a member of is then used toidentify the groups of which the group is a member. This would not be possible if for groupto group membership the name of the attribute used for the cross reference changes or ifthe direction of the reference changes.

group-dn-attribute: On an entry for a group which attribute is its distinguished name.Defaults to dn.

group-name-attribute: On an entry for a group which attribute is its simple name. Defaultsto uid.

uniqueMember: uid=TestUserOne,ou=users,dc=group-to-principal,dc=example,dc=org

dn: uid=GroupFive,ou=subgroups,ou=groups,dc=group-to-principal,dc=example,dc=orgobjectClass: topobjectClass: groupOfUniqueNamesobjectClass: uidObjectcn: Group Fiveuid: GroupFiveuniqueMember: uid=TestUserFive,ou=users,dc=group-to-principal,dc=example,dc=orguniqueMember: uid=GroupOne,ou=groups,dc=group-to-principal,dc=example,dc=org

<group-search group-name="..." iterative="..." group-dn-attribute="..." group-name-attribute="..." > ...</group-search>

Security Guide

88

Example 6.3. Principal to Group Example Configuration

Based on the example LDIF from above here is an example configuration iteratively loading a user'sgroups where the attribute used to cross reference is the memberOf attribute on the user.

The most important aspect of this configuration is that the principal-to-group element has beenadded with a single attribute.

group-attribute: The name of the attribute on the user entry that matches the distinguishedname of the group the user is a member of. Defaults to memberOf.

Example 6.4. Group to Principal Example Configuration

This example shows an iterative search for the group to principal LDIF example shown above.

Here an element group-to-principal is added. This element is used to define how searches forgroups that reference the user entry will be performed. The following attributes are set:

base-dn: The distinguished name of the context to use to begin the search.

<authorization> <ldap connection="LocalLdap"> <username-to-dn> <username-filter base-dn="ou=users,dc=principal-to-group,dc=example,dc=org" recursive="false" attribute="uid" user-dn-attribute="dn" /> </username-to-dn> <group-search group-name="SIMPLE" iterative="true" group-dn-attribute="dn" group-name-attribute="uid"> <principal-to-group group-attribute="memberOf" /> </group-search> </ldap></authorization>

<authorization> <ldap connection="LocalLdap"> <username-to-dn> <username-filter base-dn="ou=users,dc=group-to-principal,dc=example,dc=org" recursive="false" attribute="uid" user-dn-attribute="dn" /> </username-to-dn> <group-search group-name="SIMPLE" iterative="true" group-dn-attribute="dn" group-name-attribute="uid"> <group-to-principal base-dn="ou=groups,dc=group-to-principal,dc=example,dc=org" recursive="true" search-by="DISTINGUISHED_NAME"> <membership-filter principal-attribute="uniqueMember" /> </group-to-principal> </group-search> </ldap> </authorization>

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

89

recursive: Whether sub-contexts also be searched. Defaults to false.

search-by: The form of the role name used in searches. Valid values are SIMPLE and DISTINGUISHED_NAME. Defaults to DISTINGUISHED_NAME.

Within the group-to-principal element there is a membership-filter element to define the cross reference.

principal-attribute: The name of the attribute on the group entry that references the userentry. Defaults to member.

Report a bug

6.9.8. About Scoped Roles

Scoped Roles are user-defined roles that grant the permissions of one of the standard roles but only forone or more specified server groups or hosts. Scoped roles allow for management users to be grantedpermissions that are limited to only those server groups or hosts that are required.

Scoped roles can be created by users assigned the Administrator or SuperUser roles.

They are defined by five characteristics:

1. A unique name.

2. Which of the standard roles it is based on.

3. If it applies to Server Groups or Hosts

4. The list of server groups or hosts that it is restricted to.

5. If all users are automatically include. This defaults to false.

Once created a scoped role can be assigned to users and groups the same way that the standard rolesare.

Creating a scoped role does not let you define new permissions. Scoped roles can only be used to applythe permissions of an existing role in a limited scope. For example, you could create a scoped role basedon the Deployer role which is restricted to a single server group.

There are only two scopes that roles can be limited to, host and server group.

Host-scoped roles

A role that is host-scoped restricts the permissions of that role to one or more hosts. This meansaccess is provided to the relevant /host=*/ resource trees but resources that are specific to otherhosts are hidden.

Server-Group-scoped roles

A role that is server-group-scoped restricts the permissions of that role to one or more server groups.Additionally the role permissions will also apply to the profile, socket binding group, server config andserver resources that are associated with the specified server-groups. Any sub-resources within anyof those that are not logically related to the server-group will not be visible to the user.

Security Guide

90

Both host and server-group scoped roles have permissions of the Monitor role for the remainder of themanaged domain configuration.

Report a bug

6.9.9. Creating Scoped Roles

Scoped Roles are user-defined roles that grant the permissions of one of the standard roles but only forone or more specified server groups or hosts. This topic shows how to create scoped roles.

Only users in the SuperUser or Administrator roles can perform this configuration.

Scoped Role configuration in the management console can be found by following these steps:

1. Login to the Management Console

2. Click on the Administration tab

3. Expand the Access Control menu and select Role Assignment.

4. Select ROLES tab, and then the Scoped Roles tab within it.

The Scoped Roles section of the Management Console consists of two main areas, a table containinga list of the currently configured scoped roles, and the Selection panel which displays the details of therole currently selected in the table.

The following procedures show how to perform configuration tasks for Scoped Roles.

Procedure 6.22. Add a New Scoped Role

1. Login to the Management Console

2. Navigate to the Scoped Roles area of the Roles tab.

3. Click Add. The Add Scoped Role dialog appears.

4. Specify the following details:

Name, the unique name for the new scoped role.

Base Role, the role which this role will base its permissions on.

Type, whether this role will be restricted to hosts or server groups.

Scope, the list of hosts or server groups that the role is restricted to. Multiple entries can beselected.

Include All, should this role automatically include all users. Defaults to no.

5. Click Save and the dialog will close and the newly created role will appear in the table.

Procedure 6.23. Edit a Scoped Role

1. Login to the Management Console

2. Navigate to the Scoped Roles area of the Roles tab.

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

91

3. Click on the scoped role you want to edit in the table. The details of that role appears in the Selection panel below the table.

4. Click Edit in the Selection panel. The Selection panel enters edit mode.

5. Update the details you need to change and click the Save button. The Selection panel returnsto its previous state. Both the Selection panel and table show the newly updated details.

Procedure 6.24. View Scoped Role Members

1. Login to the Management Console

2. Navigate to the Scoped Roles area of the Roles tab.

3. Click on the scoped role in the table that you want to view the Members of, then click Members.The Members of role dialog appears. It shows users and groups that are included or excludedfrom the role.

4. Click Done when you have finished reviewing this information.

Procedure 6.25. Delete a Scoped Role

IMPORTANT

A Scoped Role cannot be deleted if users or groups are assigned to it. Remove the roleassignments first, and then delete it.

1. Login to the Management Console

2. Navigate to the Scoped Roles area of the Roles tab.

3. Select the scoped role to be removed in the table.

4. Click the Remove button. The Remove Scoped Role dialog appears.

5. Click Confirm.The dialog closes and the role is removed.

Report a bug

6.10. CONFIGURING CONSTRAINTS

6.10.1. Configure Sensitivity Constraints

Each Sensitivity Constraint defines a set of resources that are considered "sensitive". A sensitiveresource is generally one that either should be secret, like passwords, or one that will have seriousimpact on the server, like networking, JVM configuration, or system properties. The access controlsystem itself is also considered sensitive. Resource sensitivity limits which roles are able to read, writeor address a specific resource.

Sensitivity constraint configuration is in the Management API at /core-service=management/access=authorization/constraint=sensitivity-classification.

Security Guide

92

Within the management model each Sensitivity Constraint is identified as a classification. Theclassifications are then grouped into types. There are 39 included classifications that are arranged into13 types.

To configure a sensitivity constraint, use the write-attribute operation to set the configured-requires-read, configured-requires-write, or configured-requires-addressableattribute. To make that type of operation sensitive set the value of the attribute to true, otherwise tomake it nonsensitive set it to false. By default these attributes are not set and the values of default-requires-read, default-requires-write, and default-requires-addressable are used.Once the configured attribute is set it is that value that is used instead of the default. The default valuescannot be changed.

Example 6.5. Make reading system properties a sensitive operation

[domain@localhost:9999 /] cd /core-service=management/access=authorization/constraint=sensitivity-classification/type=core/classification=system-property[domain@localhost:9999 classification=system-property] :write-attribute(name=configured-requires-read, value=true){ "outcome" => "success", "result" => undefined, "server-groups" => {"main-server-group" => {"host" => {"master" => { "server-one" => {"response" => {"outcome" => "success"}}, "server-two" => {"response" => {"outcome" => "success"}} }}}}}[domain@localhost:9999 classification=system-property] :read-resource{ "outcome" => "success", "result" => { "configured-requires-addressable" => undefined, "configured-requires-read" => true, "configured-requires-write" => undefined, "default-requires-addressable" => false, "default-requires-read" => false, "default-requires-write" => true, "applies-to" => { "/host=master/system-property=*" => undefined, "/host=master/core-service=platform-mbean/type=runtime" => undefined, "/server-group=*/system-property=*" => undefined, "/host=master/server-config=*/system-property=*" => undefined, "/host=master" => undefined, "/system-property=*" => undefined, "/" => undefined } }}[domain@localhost:9999 classification=system-property]

What roles will be able to perform what operations depending on the configuration of these attributes issummarized in Table 6.2, “Sensitivity Constraint Configuration outcomes”.

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

93

Table 6.2. Sensitivity Constraint Configuration outcomes

Value requires-read requires-write requires-addressable

true Read is sensitive.

Only Auditor, Administrator, SuperUser can read.

Write is sensitive.

Only Administrator and SuperUser can write

Addressing is sensitive.

Only Auditor, Administrator, SuperUser can address.

false Read is not sensitive.

Any management user canread.

Write is not sensitive.

Only Maintainer, Administrator and SuperUser can write. Deployers can also writethe resource is an applicationresource.

Addressing is not sensitive.

Any management user canaddress.

Report a bug

6.10.2. Configure Application Resource Constraints

Each Application Resource Constraint defines a set of resources, attributes and operations that areusually associated with the deployment of applications and services. When an application resourceconstraint is enabled management users of the Deployer role are granted access to the resources that itapplies to.

Application constraint configuration is in the Management Model at /core-service=management/access=authorization/constraint=application-classification/.

Within the management model each Application Resource Constraint is identified as a classification. The classifications are then grouped into types. There are 14 includedclassifications that are arranged into 8 types. Each classification has an applies-to element which is alist of resource path patterns to which the classifications configuration applies.

By default the only Application Resource classification that is enabled is core. Core includesdeployments, deployment overlays, and the deployment operations.

To enable an Application Resource, use the write-attribute operation to set the configured-application attribute of the classification to true. To disable an Application Resource, set thisattribute to false. By default these attributes are not set and the value of default-application attribute is used. The default value cannot be changed.

Example 6.6. Enabling the logger-profile application resource classification

[domain@localhost:9999 /] cd /core-service=management/access=authorization/constraint=application-classification/type=logging/classification=logging-profile[domain@localhost:9999 classification=logging-profile] :write-attribute(name=configured-application, value=true){

Security Guide

94

"outcome" => "success", "result" => undefined, "server-groups" => {"main-server-group" => {"host" => {"master" => { "server-one" => {"response" => {"outcome" => "success"}}, "server-two" => {"response" => {"outcome" => "success"}} }}}}}[domain@localhost:9999 classification=logging-profile] :read-resource { "outcome" => "success", "result" => { "configured-application" => true, "default-application" => false, "applies-to" => {"/profile=*/subsystem=logging/logging-profile=*" => undefined} }}[domain@localhost:9999 classification=logging-profile]

IMPORTANT

Application Resource Constraints apply to all resources that match its configuration. Forexample, It is not possible to grant a Deployer user access to one datasource resourcebut not another. If this level of separation is required then it is recommended to configurethe resources in different server groups and create different scoped Deployer roles foreach group.

Report a bug

6.10.3. Configure the Vault Expression Constraint

By default, reading and writing vault expressions are sensitive operations. Configuring the VaultExpression Constraint allows you to set either or both of those operations to being nonsensitive.Changing this constraint allows a greater number of roles to read and write vault expressions.

The vault expression constraint is found in the management model at /core-service=management/access=authorization/constraint=vault-expression.

To configure the vault expression constraint, use the write-attribute operation to set the attributesof configured-requires-write and configured-requires-read to true or false. By defaultthese are not set and the values of default-requires-read and default-requires-write areused. The default values cannot be changed.

Example 6.7. Making writing to vault expressions a nonsensitive operation

[domain@localhost:9999 /] cd /core-service=management/access=authorization/constraint=vault-expression[domain@localhost:9999 constraint=vault-expression] :write-attribute(name=configured-requires-write, value=false){ "outcome" => "success", "result" => undefined,

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

95

"server-groups" => {"main-server-group" => {"host" => {"master" => { "server-one" => {"response" => {"outcome" => "success"}}, "server-two" => {"response" => {"outcome" => "success"}} }}}}}[domain@localhost:9999 constraint=vault-expression] :read-resource{ "outcome" => "success", "result" => { "configured-requires-read" => undefined, "configured-requires-write" => false, "default-requires-read" => true, "default-requires-write" => true }}[domain@localhost:9999 constraint=vault-expression]

What roles will be able to read and write to vault expressions depending on this configuration issummarized in Table 6.3, “Vault Expression Constraint Configuration outcomes”.

Table 6.3. Vault Expression Constraint Configuration outcomes

Value requires-read requires-write

true Read operation is sensitive.

Only Auditor, Administrator, and SuperUser can read.

Write operation is sensitive.

Only Administrator, and SuperUsercan write.

false Read operation is not sensitive.

All management users can read.

Write operation is not sensitive.

Monitor, Administrator, and SuperUser can write. Deployers can alsowrite if the vault expression is in an ApplicationResource.

Report a bug

6.11. CONSTRAINTS REFERENCE

6.11.1. Application Resource Constraints Reference

Type: core

Classification: deployment-overlay

default: true

PATH: /deployment-overlay=*

PATH: /deployment=*

Security Guide

96

PATH: /

Operation:

upload-deployment-stream, full-replace-deployment, upload-deployment-url, upload-deployment-bytes

Type: datasources

Classification: datasource

default: false

PATH: /deployment=*/subdeployment=*/subsystem=datasources/data-source=*

PATH: /subsystem=datasources/data-source=*

PATH: /subsystem=datasources/data-source=ExampleDS

PATH: /deployment=*/subsystem=datasources/data-source=*

Classification: jdbc-driver

default: false

PATH: /subsystem=datasources/jdbc-driver=*

Classification: xa-data-source

default: false

PATH: /subsystem=datasources/xa-data-source=*

PATH: /deployment=*/subsystem=datasources/xa-data-source=*

PATH: /deployment=*/subdeployment=*/subsystem=datasources/xa-data-source=*

Type: logging

Classification: logger

default: false

PATH: /subsystem=logging/logger=*

PATH: /subsystem=logging/logging-profile=*/logger=*

Classification: logging-profile

default: false

PATH: /subsystem=logging/logging-profile=*

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

97

Type: mail

Classification: mail-session

default: false

PATH: /subsystem=mail/mail-session=*

Type: naming

Classification: binding

default: false

PATH: /subsystem=naming/binding=*

Type: resource-adapters

Classification: resource-adapters

default: false

PATH: /subsystem=resource-adapters/resource-adapter=*

Type: security

Classification: security-domain

default: false

PATH: /subsystem=security/security-domain=*

Report a bug

6.11.2. Sensitivity Constraints Reference

Type: core

Classification: access-control

requires-addressable: true

requires-read: true

requires-write: true

PATH: /core-service=management/access=authorization

PATH: /subsystem=jmx ATTRIBUTE: non-core-mbean-sensitivity

Classification: credential

Security Guide

98

requires-addressable: false

requires-read: true

requires-write: true

PATH: /subsystem=mail/mail-session=*/server=pop3 ATTRIBUTE: username , password

PATH: /subsystem=mail/mail-session=*/server=imap ATTRIBUTE: username , password

PATH: /subsystem=datasources/xa-data-source=* ATTRIBUTE: user-name, recovery-username, password, recovery-password

PATH: /subsystem=mail/mail-session=*/custom=* ATTRIBUTE: username, password

PATH: /subsystem=datasources/data-source=*" ATTRIBUTE: user-name, password

PATH: /subsystem=remoting/remote-outbound-connection=*" ATTRIBUTE: username

PATH: /subsystem=mail/mail-session=*/server=smtp ATTRIBUTE: username, password

PATH: /subsystem=web/connector=*/configuration=ssl ATTRIBUTE: key-alias, password

PATH: /subsystem=resource-adapters/resource-adapter=*/connection-definitions=*"ATTRIBUTE: recovery-username, recovery-password

Classification: domain-controller

requires-addressable: false

requires-read: false

requires-write: true

Classification: domain-names

requires-addressable: false

requires-read: false

requires-write: true

Classification: extensions

requires-addressable: false

requires-read: false

requires-write: true

PATH: /extension=*

Classification: jvm

requires-addressable: false

requires-read: false

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

99

requires-write: true

PATH: /core-service=platform-mbean/type=runtime ATTRIBUTE: input-arguments, boot-class-path, class-path, boot-class-path-supported, library-path

Classification: management-interfaces

requires-addressable: false

requires-read: false

requires-write: true

/core-service=management/management-interface=native-interface

/core-service=management/management-interface=http-interface

Classification: module-loading

requires-addressable: false

requires-read: false

requires-write: true

PATH: /core-service=module-loading

Classification: patching

requires-addressable: false

requires-read: false

requires-write: true

PATH: /core-service=patching/addon=*

PATH: /core-service=patching/layer=*"

PATH: /core-service=patching

Classification: read-whole-config

requires-addressable: false

requires-read: true

requires-write: true

PATH: / OPERATION: read-config-as-xml

Classification: security-domain

requires-addressable: true

requires-read: true

Security Guide

100

requires-write: true

PATH: /subsystem=security/security-domain=*

Classification: security-domain-ref

requires-addressable: true

requires-read: true

requires-write: true

PATH: /subsystem=datasources/xa-data-source=* ATTRIBUTE: security-domain

PATH: /subsystem=datasources/data-source=* ATTRIBUTE: security-domain

PATH: /subsystem=ejb3 ATTRIBUTE: default-security-domain

PATH: /subsystem=resource-adapters/resource-adapter=*/connection-definitions=*ATTRIBUTE: security-domain, recovery-security-domain, security-application, security-domain-and-application

Classification: security-realm

requires-addressable: true

requires-read: true

requires-write: true

PATH: /core-service=management/security-realm=*

Classification: security-realm-ref

requires-addressable: true

requires-read: true

requires-write: true

PATH: /subsystem=remoting/connector=* ATTRIBUTE: security-realm

PATH: /core-service=management/management-interface=native-interface ATTRIBUTE:security-realm

PATH: /core-service=management/management-interface=http-interface ATTRIBUTE:security-realm

PATH: /subsystem=remoting/remote-outbound-connection=* ATTRIBUTE: security-realm

Classification: security-vault

requires-addressable: false

requires-read: false

requires-write: true

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

101

PATH: /core-service=vault

Classification: service-container

requires-addressable: false

requires-read: false

requires-write: true

PATH: /core-service=service-container

Classification: snapshots

requires-addressable: false

requires-read: false

requires-write: false

PATH: / ATTRIBUTE: take-snapshot, list-snapshots, delete-snapshot

Classification: socket-binding-ref

requires-addressable: false

requires-read: false

requires-write: false

PATH: /subsystem=mail/mail-session=*/server=pop3 ATTRIBUTE: outbound-socket-binding-ref

PATH: /subsystem=mail/mail-session=*/server=imap ATTRIBUTE: outbound-socket-binding-ref

PATH: /subsystem=remoting/connector=* ATTRIBUTE: socket-binding

PATH: /subsystem=web/connector=* ATTRIBUTE: socket-binding

PATH: /subsystem=remoting/local-outbound-connection=* ATTRIBUTE: outbound-socket-binding-ref

PATH: /socket-binding-group=*/local-destination-outbound-socket-binding=* ATTRIBUTE:socket-binding-ref

PATH: /subsystem=remoting/remote-outbound-connection=* ATTRIBUTE: outbound-socket-binding-ref

PATH: /subsystem=mail/mail-session=*/server=smtp ATTRIBUTE: outbound-socket-binding-ref

PATH: /subsystem=transactions ATTRIBUTE: process-id-socket-binding, status-socket-binding, socket-binding

Classification: socket-config

Security Guide

102

requires-addressable: false

requires-read: false

requires-write: true

PATH: /interface=* OPERATION: resolve-internet-address

PATH: /core-service=management/management-interface=native-interface ATTRIBUTE:port, interface, socket-binding

PATH: /socket-binding-group=*

PATH: /core-service=management/management-interface=http-interface ATTRIBUTE: port,secure-port, interface, secure-socket-binding, socket-binding

PATH: / OPERATION: resolve-internet-address

PATH: /subsystem=transactions ATTRIBUTE: process-id-socket-max-ports

Classification: system-property

requires-addressable: false

requires-read: false

requires-write: true

PATH: /core-service=platform-mbean/type=runtime ATTRIBUTE: system-properties

PATH: /system-property=*

PATH: / OPERATION: resolve-expression

Type: datasources

Classification: data-source-security

requires-addressable: false

requires-read: true

requires-write: true

PATH: /subsystem=datasources/xa-data-source=* ATTRIBUTE: user-name, security-domain, password

PATH: /subsystem=datasources/data-source=* ATTRIBUTE: user-name, security-domain,password

Type: jdr

Classification: jdr

requires-addressable: false

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

103

requires-read: false

requires-write: true

PATH: /subsystem=jdr OPERATION: generate-jdr-report

Type: jmx

Classification: jmx

requires-addressable: false

requires-read: false

requires-write: true

PATH: /subsystem=jmx

Type: mail

Classification: mail-server-security

requires-addressable: false

requires-read: false

requires-write: true

PATH: /subsystem=mail/mail-session=*/server=pop3 ATTRIBUTE: username, tls, ssl,password

PATH: /subsystem=mail/mail-session=*/server=imap ATTRIBUTE: username, tls, ssl,password

PATH: /subsystem=mail/mail-session=*/custom=* ATTRIBUTE: username, tls, ssl, password

PATH: /subsystem=mail/mail-session=*/server=smtp ATTRIBUTE: username, tls, ssl,password

Type: naming

Classification: jndi-view

requires-addressable: false

requires-read: true

requires-write: true

PATH: /subsystem=naming OPERATION: jndi-view

Classification: naming-binding

requires-addressable: false

Security Guide

104

requires-read: false

requires-write: false

PATH: /subsystem=naming/binding=*

Type: remoting

Classification: remoting-security

requires-addressable: false

requires-read: true

requires-write: true

PATH: /subsystem=remoting/connector=* ATTRIBUTE: authentication-provider, security-realm

PATH: /subsystem=remoting/remote-outbound-connection=* ATTRIBUTE: username,security-realm

PATH: /subsystem=remoting/connector=*/security=sasl

Type: resource-adapters

Classification: resource-adapter-security

requires-addressable: false

requires-read: true

requires-write: true

PATH: /subsystem=resource-adapters/resource-adapter=*/connection-definitions=*ATTRIBUTE: security-domain, recovery-username, recovery-security-domain, security-application, security-domain-and-application, recovery-password

Type: security

Classification: misc-security

requires-addressable: false

requires-read: true

requires-write: true

PATH: /subsystem=security ATTRIBUTE: deep-copy-subject-mode

Type: web

Classification: web-access-log

CHAPTER 6. SECURE THE MANAGEMENT INTERFACES WITH ROLE-BASED ACCESS CONTROL

105

requires-addressable: false

requires-read: false

requires-write: false

PATH: /subsystem=web/virtual-server=*/configuration=access-log

Classification: web-connector

requires-addressable: false

requires-read: false

requires-write: false

PATH: /subsystem=web/connector=*

Classification: web-ssl

requires-addressable: false

requires-read: true

requires-write: true

PATH: /subsystem=web/connector=*/configuration=ssl

Classification: web-sso

requires-addressable: false

requires-read: true

requires-write: true

PATH: /subsystem=web/virtual-server=*/configuration=sso

Classification: web-valve

requires-addressable: false

requires-read: false

requires-write: false

PATH: /subsystem=web/valve=*

Report a bug

Security Guide

106

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVESTRINGS WITH PASSWORD VAULT

7.1. PASSWORD VAULT SYSTEM

Configuration of JBoss EAP and associated applications requires potentially sensitive information, suchas usernames and passwords. Instead of storing this sensitive information as plain text in configurationfiles, use the Password Vault feature to mask this information and store it in an encrypted keystore.

Instead of storing the password as plain text in configuration files, you can use the Password Vaultfeature to mask the password information and store it in an encrypted keystore. Once the password isstored, you can include references in Management CLI commands or your own applications. ThePassword Vault uses the Java Keystore as its storage mechanism. Password Vault consists of two parts:storage and key storage. Java Keystore is used to store the key, which is used to encrypt or decryptsensitive strings in Vault storage.

Report a bug

7.2. CONFIGURE AND USE PASSWORD VAULT

The masked keystore password feature provided in Password Vault provides the option to obtain themasked keystore password from Password Vault, which is stored on the JBoss EAP server. ThePassword Vault uses the Java Keystore as its storage mechanism.

Procedure 7.1. Basic steps to configure and use Password Vault

1. Setup a Java Keystore to store key for password encryption.

For information on creating a keystore, refer Section 7.3, “Create a Java Keystore to StoreSensitive Strings”.

2. Initialize the Password Vault.

For information on masking the password and initialize the password value, refer Section 7.4,“Initialize the Password Vault”.

3. Configure JBoss EAP 6 to use the Password Vault.

For information on configuring EAP 6 to use Password Vault, refer Section 7.6, “Configure JBossEAP 6 to Use the Password Vault”.

4. Store a Sensitive String in the Password Vault.

For information on storing sensitive string in Password Vault, refer Section 7.8, “Store aSensitive String in the Password Vault”.

5. Configure JBoss EAP 6 to use the Password Vault.

For information on configuring JBoss EAP 6 to use the Password Vault, refer Section 7.6,“Configure JBoss EAP 6 to Use the Password Vault”. For custom implementation, referSection 7.7, “Configure JBoss EAP 6 to Use a Custom Implementation of the Password Vault”.

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVE STRINGS WITH PASSWORD VAULT

107

NOTE

To use an encrypted sensitive string in configuration, refer Section 7.9, “Use anEncrypted Sensitive String in Configuration”.

To use an encrypted sensitive string in an application, refer Section 7.10, “Use anEncrypted Sensitive String in an Application”.

To verify a sensitive string in Password Vault, refer Section 7.11, “Check if aSensitive String is in the Password Vault”.

To remove a sensitive string from Password Vault, refer Section 7.12, “Remove aSensitive String from the Password Vault”.

Report a bug

7.3. CREATE A JAVA KEYSTORE TO STORE SENSITIVE STRINGS

Prerequisites

The keytool utility, provided by the Java Runtime Environment (JRE). Locate the path for thefile, which on Red Hat Enterprise Linux is /usr/bin/keytool.

WARNING

JCEKS keystore implementations differ between Java vendors so you mustgenerate the keystore using the keytool utility from the same vendor as the JDKyou use.

Using a keystore generated by the keytool from one vendor's JDK in a JBoss EAPinstance running on a JDK from a different vendor results in the following exception:

java.io.IOException: com.sun.crypto.provider.SealedObjectForKeyProtector

Procedure 7.2. Set up a Java Keystore

1. Create a directory to store your keystore and other encrypted information.Create a directory to store your keystore and other important information. The rest of thisprocedure assumes that the directory is EAP_HOME/vault/. Since this directory will containsensitive information it should be accessible to only limited users. At a minimum the useraccount under which JBoss EAP is running requires read-write access.

2. Determine the parameters to use with keytool utility.Decide on values for the following parameters:

alias

Security Guide

108

The alias is a unique identifier for the vault or other data stored in the keystore. Aliases arecase-insensitive.

storetype

The storetype specifies the keystore type. The value jceks is recommended.

keyalg

The algorithm to use for encryption. Use the documentation for your JRE and operatingsystem to see which other choices may be available to you.

keysize

The size of an encryption key impacts how difficult it is to decrypt through brute force. Forinformation on appropriate values, see the documentation distributed with the keytoolutility.

storepass

The value of storepass is the password is used to authenticate to the keystore so that thekey can be read. The password must be at least 6 characters long and must be providedwhen the keystore is accessed. If you omit this parameter, you will be prompted to enter itwhen you execute the command.

keypass

The value of keypass is the password used to access the specific key and must match thevalue of the storepass parameter.

validity

The value of validity is the period (in days) for which the key will be valid.

keystore

The value of keystore is the filepath and filename in which the keystore's values are to bestored. The keystore file is created when data is first added to it.

Ensure you use the correct file path separator: / (forward slash) for Red Hat Enterprise Linuxand similar operating systems, \ (backslash) for Microsoft Windows Server.

The keytool utility has many other options. See the documentation for your JRE or youroperating system for more details.

3. Run the keytool commandLaunch your operating system's command line interface and run the keytool utility, supplyingthe information that you gathered.

Example 7.1. Create a Java Keystore

$ keytool -genseckey -alias vault -storetype jceks -keyalg AES -keysize 128 -storepass vault22 -keypass vault22 -validity 730 -keystore EAP_HOME/vault/vault.keystore

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVE STRINGS WITH PASSWORD VAULT

109

Result

In this a keystore has been created in the file EAP_HOME/vault/vault.keystore. It stores a singlekey, with the alias vault, which will be used to store encrypted strings, such as passwords, for JBossEAP.

Report a bug

7.4. INITIALIZE THE PASSWORD VAULT

Prerequisites

Section 7.3, “Create a Java Keystore to Store Sensitive Strings”

Overview

The Password Vault can be initialized either interactively, where you are prompted for each parameter'svalue, or non-interactively, where you provide all parameters' values on the commmand line. Eachmethod gives the same result, so choose whichever method you prefer.

Refer to the following list when using either method.

Keystore URL (KEYSTORE_URL)

The file system path or URI of the keystore file. The examples use EAP_HOME/vault/vault.keystore.

Keystore password (KEYSTORE_PASSWORD)

The password used to access the keystore.

Salt (SALT)

The salt value is a random string of eight characters used, together with the iteration count, toencrypt the content of the keystore.

Keystore Alias (KEYSTORE_ALIAS)

The alias by which the keystore is known.

Iteration Count (ITERATION_COUNT)

The number of times the encryption algorithm is run.

Directory to store encrypted files (ENC_FILE_DIR)

The path in which the encrypted files are to be stored. This is typically the directory containing thepassword vault.

It is convenient but not mandatory to store all of your encrypted information in the same place as thekey store. This directory should be only accessible to limited users. At a minimum the user accountunder which JBoss EAP is running requires read-write access. If you followed Section 7.3, “Create aJava Keystore to Store Sensitive Strings”, your keystore is in a directory called EAP_HOME/vault/.

Security Guide

110

NOTE

The trailing backslash or forward slash on the directory name is required. Ensure youuse the correct file path separator: / (forward slash) for Red Hat Enterprise Linux andsimilar operating systems, \ (backslash) for Microsoft Windows Server.

Vault Block (VAULT_BLOCK)

The name to be given to this block in the password vault. Choose a value which is significant to you.

Attribute (ATTRIBUTE)

The name to be given to the attribute being stored. Choose a value which is significant to you. Forexample, you could choose a name which you associate with a datasource.

Security Attribute (SEC-ATTR)

The password which is being stored in the password vault.

Procedure 7.3. Run the Password Vault Command Interactively

Use this method if you would prefer to be prompted for the value of each parameter.

1. Launch the Password Vault command interactively.Launch your operating system's command line interface and run EAP_HOME/bin/vault.sh(on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat(on Microsoft Windows Server). Start a new interactive session by typing 0 (zero).

2. Complete the prompted parameters.Follow the prompts to input the required parameters.

3. Make a note of the masked password information.The masked password, salt, and iteration count are printed to standard output. Make a note ofthem in a secure location. They are required to add entries to the Password Vault. Access to thekeystore file and these values could allow an attacker access to obtain access to sensitiveinformation in the Password Vault.

4. Exit the interactive console.Type 3 (three) to exit the interactive console.

Example 7.2. Run the Password Vault command interactively

Please enter a Digit:: 0: Start Interactive Session 1: Remove Interactive Session 2: Exit0Starting an interactive sessionEnter directory to store encrypted files:EAP_HOME/vault/ Enter Keystore URL:EAP_HOME/vault/vault.keystoreEnter Keystore password: vault22Enter Keystore password again: vault22Values matchEnter 8 character salt:1234abcdEnter iteration count as a number (Eg: 44):120Enter Keystore Alias:vaultInitializing Vault

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVE STRINGS WITH PASSWORD VAULT

111

Oct 17, 2014 12:58:11 PM org.picketbox.plugins.vault.PicketBoxSecurityVault initINFO: PBOX000361: Default Security Vault Implementation Initialized and ReadyVault Configuration in AS7 config file:********************************************...</extensions><vault> <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/> <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="1234abcd"/> <vault-option name="ITERATION_COUNT" value="120"/> <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/></vault><management> ...********************************************Vault is initialized and ready for useHandshake with Vault complete

Procedure 7.4. Run the Password Vault Command Non-interactively

Use this method if you would prefer to provide all parameters' values at once.

Launch your operating system's command line interface and run the Password Vault command.Refer to the list in the Overview, substituting the placeholder values with your preferred values.

Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems)or EAP_HOME\bin\vault.bat (on Microsoft Windows Server).

vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --vault-block VAULT_BLOCK --attribute ATTRIBUTE --sec-attr SEC-ATTR --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT

Example 7.3. Run the Password Vault command non-interactively

vault.sh --keystore EAP_HOME/vault/vault.keystore --keystore-password vault22 --alias vault --vault-block vb --attribute password --sec-attr 0penS3sam3 --enc-dir EAP_HOME/vault/ --iteration 120 --salt 1234abcd

Command output

=========================================================================

JBoss Vault

JBOSS_HOME: EAP_HOME

JAVA: java

Security Guide

112

=========================================================================

Oct 17, 2014 2:23:43 PM org.picketbox.plugins.vault.PicketBoxSecurityVault initINFO: PBOX000361: Default Security Vault Implementation Initialized and ReadySecured attribute value has been stored in vault. Please make note of the following:********************************************Vault Block:vbAttribute Name:passwordConfiguration should be done as follows:VAULT::vb::password::1********************************************Vault Configuration in AS7 config file:********************************************...</extensions><vault> <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/> <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="1234abcd"/> <vault-option name="ITERATION_COUNT" value="120"/> <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/></vault><management> ...********************************************

Result

Your keystore password has been masked for use in configuration files and deployments. In addition,your vault is initialized and ready to use.

Report a bug

7.5. OBTAIN KEYSTORE PASSWORD FROM EXTERNAL SOURCE

You can also the use the EXT, EXTC, CMD, CMDC or CLASS methods in Vault configuration forobtaining the Java keystore password.

The description for the methods are listed as:

{EXT}...: Refers to the exact command, where ‘…’ is the exact command. For example: {EXT}/usr/bin/getmypassword --section 1 --query company, run the /usr/bin/getmypassword command, which displays the password on standard output anduse it as password for Security Vault's keystore. In this example, the command is using twooptions: --section 1 and --query company.

<vault-option name="KEYSTORE_PASSWORD" value="[here]"

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVE STRINGS WITH PASSWORD VAULT

113

{EXTC[:expiration_in_millis]}...: Refers to the exact command, where the '...' is theexact command line that is passed to the Runtime.exec(String) method to execute a platformcommand. The first line of the command output is used as the password. EXTC variant cachesthe passwords for expiration_in_millis milliseconds. Default cache expiration is 0 (zero),meaning items in the cache never expire. For example: {EXTC:120000}/usr/bin/getmypassword --section 1 --query company Verify ifcache contains /usr/bin/getmypassword output, if it contains the output then use it. If itdoes not contain the output, run the command to output it to cache and use it. In this example,the cache expires in 2 minute (120000 milliseconds).

{CMD}... or {CMDC[:expiration_in_millis]}...: The general command is a stringdelimited by ',' where the first part is the actual command and further parts represents theparameters. The comma can be backslashed to keep it as a part of the parameter. For example,{CMD}/usr/bin/getmypassword,--section,1,--query,company

{CLASS[@jboss_module_spec]}classname[:ctorargs]: Where the '[:ctorargs]' is anoptional string delimited by the ':' from the classname is passed to the classname ctor. Thectorargs is a comma delimited list of strings. For example, {CLASS@org.test.passwd}org.test.passwd.ExternamPassworProvider. In thisexample, we load org.test.passwd.ExternamPassworProvider class from org.test.passwd module and use the toCharArray() method to get the password. If toCharArray() is not available use toString() method. The org.test.passwd.ExternamPassworProvider class must have the default constructor.

Report a bug

7.6. CONFIGURE JBOSS EAP 6 TO USE THE PASSWORD VAULT

Overview

Before you can mask passwords and other sensitive attributes in configuration files, you need to makeJBoss EAP 6 aware of the password vault which stores and decrypts them.

Prerequisites

Section 7.4, “Initialize the Password Vault”

Procedure 7.5. Enable the Password Vault

Run the following Management CLI command, substituting the placeholder values with thosefrom the output of the Password Vault command in Section 7.4, “Initialize the Password Vault”.

NOTE

If you use Microsoft Windows Server, use two backslashes (\\) in the file pathwhere you would normally use one. For example, C:\\data\\vault\\vault.keystore. This is because a single backslashcharacter (\) is used for character escaping.

/core-service=vault:add(vault-options=[("KEYSTORE_URL" => "PATH_TO_KEYSTORE"), ("KEYSTORE_PASSWORD" => "MASKED_PASSWORD"), ("KEYSTORE_ALIAS" => "ALIAS"), ("SALT" => "SALT"),("ITERATION_COUNT" => "ITERATION_COUNT"), ("ENC_FILE_DIR" => "ENC_FILE_DIR")])

Security Guide

114

Example 7.4. Enable the Password Vault

/core-service=vault:add(vault-options=[("KEYSTORE_URL" => "EAP_HOME/vault/vault.keystore"), ("KEYSTORE_PASSWORD" => "MASK-5dOaAVafCSd"), ("KEYSTORE_ALIAS" => "vault"), ("SALT" => "1234abcd"),("ITERATION_COUNT" => "120"), ("ENC_FILE_DIR" => "EAP_HOME/vault/")])

Result

JBoss EAP 6 is configured to decrypt masked strings stored in the Password Vault. To add strings to thePassword Vault and use them in your configuration, see Section 7.8, “Store a Sensitive String in thePassword Vault”.

Report a bug

7.7. CONFIGURE JBOSS EAP 6 TO USE A CUSTOM IMPLEMENTATIONOF THE PASSWORD VAULT

Overview

You can use your own implementation of SecurityVault to mask passwords and other sensitiveattributes in configuration files.

Prerequisites

Section 7.4, “Initialize the Password Vault”

Procedure 7.6. Use a Custom Implementation of the Password Vault

1. Create a class that implements the interface SecurityVault.

2. Create a module containing the class from the previous step, and specify a dependency on org.picketbox where the interface is SecurityVault.

3. Enable the custom Password Vault in the JBoss EAP server configuration by adding the vaultelement with the following attributes:

code

The fully qualified name of class that implements SecurityVault.

module

The name of the module that contains the custom class.

Optionally, you can use vault-options parameters to initialize the custom class for aPassword Vault.

Example 7.5. Use vault-options Parameters to Initialize the Custom Class

/core-service=vault:add(code="custom.vault.implementation.CustomSecurityVault", module="custom.vault.module", vault-options=

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVE STRINGS WITH PASSWORD VAULT

115

[("KEYSTORE_URL" => "PATH_TO_KEYSTORE"), ("KEYSTORE_PASSWORD" => "MASKED_PASSWORD"), ("KEYSTORE_ALIAS" => "ALIAS"), ("SALT" => "SALT"),("ITERATION_COUNT" => "ITERATION_COUNT"), ("ENC_FILE_DIR" => "ENC_FILE_DIR")])

Result

JBoss EAP 6 is configured to decrypt masked strings using a custom implementation of the passwordvault.

Report a bug

7.8. STORE A SENSITIVE STRING IN THE PASSWORD VAULT

Overview

Including passwords and other sensitive strings in plaintext configuration files is a security risk. Storethese strings instead in the Password Vault for improved security, where they can then be referenced inconfiguration files, Management CLI commands and applications in their masked form.

Sensitive strings can be store in the Password Vault either interactively, where you are prompted foreach parameter's value, or non-interactively, where you provide all parameters' values on thecommmand line. Each method gives the same result, so choose whichever method you prefer. For adescription of all parameters, see Section 7.4, “Initialize the Password Vault”.

Prerequisites

Section 7.6, “Configure JBoss EAP 6 to Use the Password Vault”

Procedure 7.7. Store a Sensitive String Interactively

Use this method if you would prefer to be prompted for the value of each parameter.

1. Run the Password Vault commandLaunch your operating system's command line interface and run the Password Vault command.Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems)or EAP_HOME\bin\vault.bat (on Microsoft Windows Server). Start a new interactive sessionby typing 0 (zero).

2. Complete the prompted parameters about the Password VaultFollow the prompts to input the required authentication parameters. These values must matchthose provided when the Password Vault was created.

NOTE

The keystore password must be given in plaintext form, not masked form.

3. Complete the prompted parameters about the sensitive stringEnter 0 (zero) to start storing the sensitive string. Follow the prompts to input the requiredparameters.

4. Make note of the information about the masked string

Security Guide

116

A message prints to standard output, showing the vault block, attribute name, masked string,and advice about using the string in your configuration. Make note of this information in a securelocation. An extract of sample output is as follows:

Vault Block:ds_Example1Attribute Name:passwordConfiguration should be done as follows:VAULT::ds_Example1::password::1

5. Exit the interactive consoleEnter 3 (three) to exit the interactive console.

Example 7.6. Store a Sensitive String Interactively

=========================================================================

JBoss Vault

JBOSS_HOME: EAP_HOME/jboss-eap-6.4

JAVA: java

=========================================================================

************************************** JBoss Vault *************************************************Please enter a Digit:: 0: Start Interactive Session 1: Remove Interactive Session 2: Exit0Starting an interactive sessionEnter directory to store encrypted files:11:18:46,086 INFO [org.jboss.security] (management-handler-thread - 4) PBOX0 Enter directory to store encrypted files:EAP_HOME/vault/ Enter Keystore URL:EAP_HOME/vault/vault.keystoreEnter Keystore password: Enter Keystore password again: Values matchEnter 8 character salt:1234abcdEnter iteration count as a number (Eg: 44):120Enter Keystore Alias:vaultInitializing VaultOct 21, 2014 11:20:49 AM org.picketbox.plugins.vault.PicketBoxSecurityVault initINFO: PBOX000361: Default Security Vault Implementation Initialized and ReadyVault Configuration in AS7 config file:********************************************...</extensions><vault> <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/>

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVE STRINGS WITH PASSWORD VAULT

117

<vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="1234abcd"/> <vault-option name="ITERATION_COUNT" value="120"/> <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/></vault><management> ...********************************************Vault is initialized and ready for useHandshake with Vault completePlease enter a Digit:: 0: Store a secured attribute 1: Check whether a secured attribute exists 2: Remove secured attribute 3: Exit0Task: Store a secured attributePlease enter secured attribute value (such as password):Please enter secured attribute value (such as password) again: Values matchEnter Vault Block:ds_Example1Enter Attribute Name:passwordSecured attribute value has been stored in vault. Please make note of the following:********************************************Vault Block:ds_Example1Attribute Name:passwordConfiguration should be done as follows:VAULT::ds_Example1::password::1********************************************Please enter a Digit:: 0: Store a secured attribute 1: Check whether a secured attribute exists 2: Remove secured attribute 3: Exit

Procedure 7.8. Store a Sensitive String Non-interactively

Use this method if you would prefer to provide all parameters' values at once.

1. Launch your operating system's command line interface and run the Password Vault command.Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems)or EAP_HOME\bin\vault.bat (on Microsoft Windows Server).

Substitute the placeholder values with your own values. The values for parameters KEYSTORE_URL, KEYSTORE_PASSWORD and KEYSTORE_ALIAS must match those providedwhen the Password Vault was created.

NOTE

The keystore password must be given in plaintext form, not masked form.

EAP_HOME/bin/vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --vault-block VAULT_BLOCK --attribute ATTRIBUTE --sec-attr SEC-ATTR --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT

2. Make note of the information about the masked string

Security Guide

118

A message prints to standard output, showing the vault block, attribute name, masked string,and advice about using the string in your configuration. Make note of this information in a securelocation. An extract of sample output is as follows:

Vault Block:vbAttribute Name:passwordConfiguration should be done as follows:VAULT::vb::password::1

Example 7.7. Run the Password Vault command non-interactively

EAP_HOME/bin/vault.sh --keystore EAP_HOME/vault/vault.keystore --keystore-password vault22 --alias vault --vault-block vb --attribute password --sec-attr 0penS3sam3 --enc-dir EAP_HOME/vault/ --iteration 120 --salt 1234abcd

Command output

=========================================================================

JBoss Vault

JBOSS_HOME: EAP_HOME

JAVA: java

=========================================================================

Oct 22, 2014 9:24:43 AM org.picketbox.plugins.vault.PicketBoxSecurityVault initINFO: PBOX000361: Default Security Vault Implementation Initialized and ReadySecured attribute value has been stored in vault. Please make note of the following:********************************************Vault Block:vbAttribute Name:passwordConfiguration should be done as follows:VAULT::vb::password::1********************************************Vault Configuration in AS7 config file:********************************************...</extensions><vault> <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/> <vault-option name="KEYSTORE_PASSWORD" value="vault22"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="1234abcd"/> <vault-option name="ITERATION_COUNT" value="120"/>

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVE STRINGS WITH PASSWORD VAULT

119

<vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/vault/"/></vault><management> ...********************************************

Result

The sensitive string has now been stored in the Password Vault and can be used in configuration files,Management CLI commands and applications in its masked form.

Report a bug

7.9. USE AN ENCRYPTED SENSITIVE STRING IN CONFIGURATION

Prerequisites

Section 7.8, “Store a Sensitive String in the Password Vault”

Any sensitive string which has been encrypted can be used in a configuration file or Management CLIcommand in its masked form, providing expressions are allowed.

To confirm if expressions are allowed within a particular subsystem, run the following Management CLIcommand against that subsystem.

NOTE

Add the prefix /host=HOST_NAME to the command for a managed domain.

Example 7.8. List the Description of all Resources in the Management Subsystem

/core-service=management:read-resource-description(recursive=true)

From the output of running this command, look for the value of the expressions-allowed parameter.If this is true, then you can use expressions within the configuration of this subsystem.

Use the following syntax to replace any plaintext string with the masked form.

${VAULT::VAULT_BLOCK::ATTRIBUTE_NAME::MASKED_STRING}

Example 7.9. Datasource Definition Using a Password in Masked Form

In this example the vault block is ds_ExampleDS and the attribute is password.

... <subsystem xmlns="urn:jboss:domain:datasources:1.0"> <datasources> <datasource jndi-name="java:jboss/datasources/ExampleDS" enabled="true" use-java-context="true" pool-name="H2DS"> <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-

/core-service=SUBSYSTEM:read-resource-description(recursive=true)

Security Guide

120

url> <driver>h2</driver> <pool></pool> <security> <user-name>sa</user-name> <password>${VAULT::ds_ExampleDS::password::1}</password> </security> </datasource> <drivers> <driver name="h2" module="com.h2database.h2"> <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class> </driver> </drivers> </datasources> </subsystem>...

Report a bug

7.10. USE AN ENCRYPTED SENSITIVE STRING IN AN APPLICATION

Prerequisites

Section 7.8, “Store a Sensitive String in the Password Vault”

Encrypted strings stored in the Password Vault can be used in your application's source code.

Example 7.10. Servlet Using a Vaulted Password

This example is an extract of a servlet's source code, illustrating the use of a masked password in adatasource definition, instead of the plaintext password. The plaintext version is commented out sothat you can see the difference.

Report a bug

/*@DataSourceDefinition( name = "java:jboss/datasources/LoginDS", user = "sa", password = "sa", className = "org.h2.jdbcx.JdbcDataSource", url = "jdbc:h2:tcp://localhost/mem:test")*/@DataSourceDefinition( name = "java:jboss/datasources/LoginDS", user = "sa", password = "VAULT::DS::thePass::1", className = "org.h2.jdbcx.JdbcDataSource", url = "jdbc:h2:tcp://localhost/mem:test")

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVE STRINGS WITH PASSWORD VAULT

121

7.11. CHECK IF A SENSITIVE STRING IS IN THE PASSWORD VAULT

Overview

Before attempting to store or use a sensitive string in the Password Vault it can be useful to first confirmif it is already stored.

This check can be done either interactively, where you are prompted for each parameter's value, or non-interactively, where you provide all parameters' values on the commmand line. Each method gives thesame result, so choose whichever method you prefer.

Procedure 7.9. Check For a Sensitive String Interactively

Use this method if you would prefer to be prompted for the value of each parameter.

1. Run the Password Vault commandLaunch your operating system's command line interface and run the Password Vault command.Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems)or EAP_HOME\bin\vault.bat (on Microsoft Windows Server). Start a new interactive sessionby typing 0 (zero).

2. Complete the prompted parameters about the Password VaultFollow the prompts to input the required authentication parameters. These values must matchthose provided when the Password Vault was created.

NOTE

The keystore password must be given in plaintext form, not masked form.

3. Enter 1 (one) to select “Check whether a secured attribute exists”.

4. Enter the name of the vault block in which the sensitive string is stored.

5. Enter the name of the sensitive string to be checked.

Result

If the sensitive string is stored in the vault block specified, a confirmation message like the following willbe output.

A value exists for (VAULT_BLOCK, ATTRIBUTE)

If the sensitive string is not stored in the specified block, a message like the following will be output.

No value has been store for (VAULT_BLOCK, ATTRIBUTE)

Example 7.11. Check For a Sensitive String Interactively

=========================================================================

JBoss Vault

JBOSS_HOME: EAP_HOME

Security Guide

122

JAVA: java

=========================================================================

************************************** JBoss Vault *************************************************Please enter a Digit:: 0: Start Interactive Session 1: Remove Interactive Session 2: Exit0Starting an interactive sessionEnter directory to store encrypted files:EAP_HOME/vaultEnter Keystore URL:EAP_HOME/vault/vault.keystoreEnter Keystore password:Enter Keystore password again:Values matchEnter 8 character salt:1234abcdEnter iteration count as a number (Eg: 44):120Enter Keystore Alias:vaultInitializing VaultOct 22, 2014 12:53:56 PM org.picketbox.plugins.vault.PicketBoxSecurityVault initINFO: PBOX000361: Default Security Vault Implementation Initialized and ReadyVault Configuration in AS7 config file:********************************************...</extensions><vault> <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/> <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="1234abcd"/> <vault-option name="ITERATION_COUNT" value="120"/> <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/></vault><management> ...********************************************Vault is initialized and ready for useHandshake with Vault completePlease enter a Digit:: 0: Store a secured attribute 1: Check whether a secured attribute exists 2: Remove secured attribute 3: Exit1Task: Verify whether a secured attribute existsEnter Vault Block:vbEnter Attribute Name:passwordA value exists for (vb, password)Please enter a Digit:: 0: Store a secured attribute 1: Check whether a secured attribute exists 2: Remove secured attribute 3: Exit

Procedure 7.10. Check For a Sensitive String Non-Interactively

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVE STRINGS WITH PASSWORD VAULT

123

Use this method if you would prefer to provide all parameters' values at once. For a description of allparameters, see Section 7.4, “Initialize the Password Vault”.

Launch your operating system's command line interface and run the Password Vault command.Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems)or EAP_HOME\bin\vault.bat (on Microsoft Windows Server).

Substitute the placeholder values with your own values. The values for parameters KEYSTORE_URL, KEYSTORE_PASSWORD-password and KEYSTORE_ALIAS must match thoseprovided when the Password Vault was created.

NOTE

The keystore password must be given in plaintext form, not masked form.

EAP_HOME/bin/vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --check-sec-attr --vault-block VAULT_BLOCK --attribute ATTRIBUTE --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT

Result

If the sensitive string is stored in the vault block specified, the following message will be output.

Password already exists.

If the value is not stored in the specified block, the following message will be output.

Password doesn't exist.

Report a bug

7.12. REMOVE A SENSITIVE STRING FROM THE PASSWORD VAULT

Overview

For security reasons it is best to remove sensitive strings from the Password Vault when they are nolonger required. For example, if you are decommissioning an application, any sensitive strings used indatasource definitions should be removed at the same time.

Prerequisite

Before removing a sensitive string from the Password Vault, confirm if it is used in the configuration ofJBoss EAP. One method of doing this is to use the ‘grep’ utility to search configuration files for instancesof the masked string. On Red Hat Enterprise Linux (and similar operating systems), grep is installed bydefault but for Microsoft Windows Server it must be installed manually.

The Password Vault utility provides two modes: interactive and non-interactive. Interactive modeprompts you for each parameter’s value, where non-interactive mode requires you to provide allparameters’ values in a single command.

Procedure 7.11. Remove a Sensitive String Interactively

Use this method if you would prefer to be prompted for the value of each parameter.

Security Guide

124

1. Run the Password Vault commandLaunch your operating system's command line interface and run EAP_HOME/bin/vault.sh(on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat(on Microsoft Windows Server). Start a new interactive session by typing 0 (zero).

2. Provide Authentication DetailsFollow the prompts to input the required authentication parameters. These values must matchthose provided when the Password Vault was created.

NOTE

The keystore password must be given in plaintext form, not masked form.

3. Enter 2 (two) to choose option Remove secured attribute.

4. Enter the name of the vault block in which the sensitive string is stored.

5. Enter the name of the sensitive string to be removed.

Result

If the sensitive string is successfully removed, a confirmation message like the following will be output.

Secured attribute [VAULT_BLOCK::ATTRIBUTE] has been successfully removed from vault

If the sensitive string is not removed, a message like the following will be output.

Secured attribute [VAULT_BLOCK::ATTRIBUTE] was not removed from vault, check whether it exist

Example 7.12. Remove a Sensitive String Interactively

************************************** JBoss Vault *************************************************Please enter a Digit:: 0: Start Interactive Session 1: Remove Interactive Session 2: Exit0Starting an interactive sessionEnter directory to store encrypted files:EAP_HOME/vault/Enter Keystore URL:EAP_HOME/vault/vault.keystoreEnter Keystore password: Enter Keystore password again: Values matchEnter 8 character salt:1234abcdEnter iteration count as a number (Eg: 44):120Enter Keystore Alias:vaultInitializing VaultDec 23, 2014 1:40:56 PM org.picketbox.plugins.vault.PicketBoxSecurityVault initINFO: PBOX000361: Default Security Vault Implementation Initialized and ReadyVault Configuration in configuration file:

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVE STRINGS WITH PASSWORD VAULT

125

********************************************...</extensions><vault> <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/> <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="1234abcd"/> <vault-option name="ITERATION_COUNT" value="120"/> <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/></vault><management> ...********************************************Vault is initialized and ready for useHandshake with Vault completePlease enter a Digit:: 0: Store a secured attribute 1: Check whether a secured attribute exists 2: Remove secured attribute 3: Exit2Task: Remove secured attributeEnter Vault Block:craftEnter Attribute Name:passwordSecured attribute [craft::password] has been successfully removed from vault

Procedure 7.12. Remove a Sensitive String Non-interactively

Use this method if you would prefer to provide all parameters' values at once. For a description of allparameters, see Section 7.4, “Initialize the Password Vault”.

Launch your operating system's command line interface and run the Password Vault command.Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems)or EAP_HOME\bin\vault.bat (on Microsoft Windows Server).

Substitute the placeholder values with your own values. The values for parameters KEYSTORE_URL, KEYSTORE_PASSWORD and KEYSTORE_ALIAS must match those providedwhen the Password Vault was created.

NOTE

The keystore password must be given in plaintext form, not masked form.

EAP_HOME/bin/vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --remove-sec-attr --vault-block VAULT_BLOCK --attribute ATTRIBUTE --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT

Result

If the sensitive string is successfully removed, a confirmation message like the following will be output.

Secured attribute [VAULT_BLOCK::ATTRIBUTE] has been successfully removed from vault

Security Guide

126

If the sensitive string is not removed, a message like the following will be output.

Secured attribute [VAULT_BLOCK::ATTRIBUTE] was not removed from vault, check whether it exist

Example 7.13. Remove a Sensitive String Non-interactively

./vault.sh --keystore EAP_HOME/vault/vault.keystore --keystore-password vault22 --alias vault --remove-sec-attr --vault-block craft --attribute password --enc-dir ../vault/ --iteration 120 --salt 1234abcd=========================================================================

JBoss Vault

JBOSS_HOME: EAP_HOME

JAVA: java

=========================================================================

Dec 23, 2014 1:54:24 PM org.picketbox.plugins.vault.PicketBoxSecurityVault initINFO: PBOX000361: Default Security Vault Implementation Initialized and ReadySecured attribute [craft::password] has been successfully removed from vault

Report a bug

CHAPTER 7. SECURE PASSWORDS AND OTHER SENSITIVE STRINGS WITH PASSWORD VAULT

127

PART III. DEVELOPING SECURE APPLICATIONS

Security Guide

128

CHAPTER 8. SECURITY OVERVIEW

8.1. ABOUT APPLICATION SECURITY

Securing your applications is a multi-faceted and important concern for every application developer.JBoss EAP 6 provides all the tools you need to write secure applications, including the following abilities:

Section 11.2.1, “About Authentication”

Section 11.5.1, “About Authorization”

Section 11.7.1, “About Security Auditing”

Section 11.8.1, “About Security Mapping”

Section 8.2, “Declarative Security”

Section 9.2.2.1, “About EJB Method Permissions”

Section 9.2.3.1, “About EJB Security Annotations”

See also Section 11.9, “Use a Security Domain in Your Application”.

Report a bug

8.2. DECLARATIVE SECURITY

Declarative security is a method to separate security concerns from your application code by using thecontainer to manage security. The container provides an authorization system based on either filepermissions or users, groups, and roles. This approach is usually superior to programmatic security,which gives the application itself all of the responsibility for security.

JBoss EAP 6 provides declarative security via security domains.

Report a bug

8.2.1. Java EE Declarative Security Overview

The Java EE security model is declarative in that you describe the security roles and permissions in astandard XML descriptor rather than embedding security into your business component. This isolatessecurity from business-level code because security tends to be more a function of where the componentis deployed than an inherent aspect of the component's business logic. For example, consider anAutomated Teller Machine (ATM) that is to be used to access a bank account. The securityrequirements, roles and permissions will vary independent of how you access the bank account, basedon what bank is managing the account, where the ATM is located, and so on.

Securing a Java EE application is based on the specification of the application security requirements viathe standard Java EE deployment descriptors. You secure access to EJBs and web components in anenterprise application by using the ejb-jar.xml and web.xml deployment descriptors.

Report a bug

8.2.2. Security References

Both Enterprise Java Beans (EJBs) and servlets can declare one or more <security-role-ref> elements.

CHAPTER 8. SECURITY OVERVIEW

129

Figure 8.1. Security Roles Reference Model

This element declares that a component is using the <role-name> element's role-nameType attributevalue as an argument to the isCallerInRole(String) method. By using the isCallerInRolemethod, a component can verify whether the caller is in a role that has been declared with a <security-role-ref> or <role-name> element. The <role-name> element value must link to a <security-role> elementthrough the <role-link> element. The typical use of isCallerInRole is to perform a security check thatcannot be defined by using the role-based <method-permissions> elements.

Example 8.1. ejb-jar.xml descriptor fragment

NOTE

This fragment is an example only. In deployments, the elements in this section mustcontain role names and links relevant to the EJB deployment.

Example 8.2. web.xml descriptor fragment

<!-- A sample ejb-jar.xml fragment --> <ejb-jar> <enterprise-beans> <session> <ejb-name>ASessionBean</ejb-name> ... <security-role-ref> <role-name>TheRoleICheck<role-name> <role-link>TheApplicationRole</role-link> </security-role-ref> </session> </enterprise-beans> ... </ejb-jar>

Security Guide

130

Report a bug

8.2.3. Security Identity

An Enterprise Java Bean (EJB) can specify the identity another EJB must use when it invokes methodson components using the <security-identity> element.

Figure 8.2. Java EE Security Identity Data Model

The invocation identity can be that of the current caller, or it can be a specific role. The applicationassembler uses the <security-identity> element with a <use-caller-identity> child element. This indicatethat the current caller's identity should be propagated as the security identity for method invocationsmade by the EJB. Propagation of the caller's identity is the default used in the absence of an explicit<security-identity> element declaration.

Alternatively, the application assembler can use the <run-as> or <role-name> child element to specifythat a specific security role supplied by the <role-name> element value must be used as the securityidentity for method invocations made by the EJB.

Note that this does not change the caller's identity as seen by the EJBContext.getCallerPrincipal() method. Rather, the caller's security roles are set to the singlerole specified by the <run-as> or <role-name> element value.

One use case for the <run-as> element is to prevent external clients from accessing internal EJBs. Youconfigure this behavior by assigning the internal EJB <method-permission> elements, which restrictaccess to a role never assigned to an external client. EJBs that must in turn use internal EJBs are then

<web-app> <servlet> <servlet-name>AServlet</servlet-name> ... <security-role-ref> <role-name>TheServletRole</role-name> <role-link>TheApplicationRole</role-link> </security-role-ref> </servlet> ...</web-app>

CHAPTER 8. SECURITY OVERVIEW

131

configured with a <run-as> or <role-name> equal to the restricted role. The following descriptor fragmentdescribes an example<security-identity> element usage.

When you use <run-as> to assign a specific role to outgoing calls, a principal named anonymous isassigned to all outgoing calls. If you want another principal to be associated with the call, you mustassociate a <run-as-principal> with the bean in the jboss-ejb3.xml file. The following fragmentassociates a principal named internal with RunAsBean from the prior example.

The <run-as> element is also available in servlet definitions in a web.xml file. The following exampleshows how to assign the role InternalRole to a servlet:

<ejb-jar> <enterprise-beans> <session> <ejb-name>ASessionBean</ejb-name> <!-- ... --> <security-identity> <use-caller-identity/> </security-identity> </session> <session> <ejb-name>RunAsBean</ejb-name> <!-- ... --> <security-identity> <run-as> <description>A private internal role</description> <role-name>InternalRole</role-name> </run-as> </security-identity> </session> </enterprise-beans> <!-- ... --></ejb-jar>

<session> <ejb-name>RunAsBean</ejb-name> <security-identity> <run-as-principal>internal</run-as-principal> </security-identity></session>

<servlet> <servlet-name>AServlet</servlet-name> <!-- ... --> <run-as> <role-name>InternalRole</role-name> </run-as> </servlet>

Security Guide

132

Calls from this servlet are associated with the anonymous principal. The <run-as-principal> elementis available in the jboss-web.xml file to assign a specific principal to go along with the run-as role.The following fragment shows how to associate a principal named internal to the servlet above.

Report a bug

8.2.4. Security Roles

The security role name referenced by either the security-role-ref or security-identityelement needs to map to one of the application's declared roles. An application assembler defines logicalsecurity roles by declaring security-role elements. The role-name value is a logical applicationrole name like Administrator, Architect, SalesManager, etc.

The Java EE specifications note that it is important to keep in mind that the security roles in thedeployment descriptor are used to define the logical security view of an application. Roles defined in theJava EE deployment descriptors should not be confused with the user groups, users, principals, andother concepts that exist in the target enterprise's operational environment. The deployment descriptorroles are application constructs with application domain-specific names. For example, a bankingapplication might use role names such as BankManager, Teller, or Customer.

In JBoss EAP, a security-role element is only used to map security-role-ref/role-namevalues to the logical role that the component role references. The user's assigned roles are a dynamicfunction of the application's security manager. JBoss does not require the definition of security-roleelements in order to declare method permissions. However, the specification of security-roleelements is still a recommended practice to ensure portability across application servers and fordeployment descriptor maintenance.

Example 8.3. An ejb-jar.xml descriptor fragment that illustrates the security-role elementusage.

Example 8.4. An example web.xml descriptor fragment that illustrates the security-roleelement usage.

<servlet> <servlet-name>AServlet</servlet-name> <run-as-principal>internal</run-as-principal> </servlet>

<!-- A sample ejb-jar.xml fragment --><ejb-jar> <assembly-descriptor> <security-role> <description>The single application role</description> <role-name>TheApplicationRole</role-name> </security-role> </assembly-descriptor></ejb-jar>

<!-- A sample web.xml fragment --><web-app> <security-role>

CHAPTER 8. SECURITY OVERVIEW

133

Report a bug

8.2.5. EJB Method Permissions

An application assembler can set the roles that are allowed to invoke an EJB's home and remoteinterface methods through method-permission element declarations.

Figure 8.3. Java EE Method Permissions Element

Each method-permission element contains one or more role-name child elements that define thelogical roles that are allowed to access the EJB methods as identified by method child elements. Youcan also specify an unchecked element instead of the role-name element to declare that anyauthenticated user can access the methods identified by method child elements. In addition, you candeclare that no one should have access to a method that has the exclude-list element. If an EJB hasmethods that have not been declared as accessible by a role using a method-permission element,the EJB methods default to being excluded from use. This is equivalent to defaulting the methods intothe exclude-list.

<description>The single application role</description> <role-name>TheApplicationRole</role-name> </security-role></web-app>

Security Guide

134

Figure 8.4. Java EE Method Element

There are three supported styles of method element declarations.

The first is used for referring to all the home and component interface methods of the named enterprisebean:

The second style is used for referring to a specified method of the home or component interface of thenamed enterprise bean:

If there are multiple methods with the same overloaded name, this style refers to all of the overloadedmethods.

The third style is used to refer to a specified method within a set of methods with an overloaded name:

<method> <ejb-name>EJBNAME</ejb-name> <method-name>*</method-name></method>

<method> <ejb-name>EJBNAME</ejb-name> <method-name>METHOD</method-name> </method>

<method> <ejb-name>EJBNAME</ejb-name> <method-name>METHOD</method-name> <method-params> <method-param>PARAMETER_1</method-param>

CHAPTER 8. SECURITY OVERVIEW

135

The method must be defined in the specified enterprise bean's home or remote interface. The method-param element values are the fully qualified name of the corresponding method parameter type. If thereare multiple methods with the same overloaded signature, the permission applies to all of the matchingoverloaded methods.

The optional method-intf element can be used to differentiate methods with the same name andsignature that are defined in both the home and remote interfaces of an enterprise bean.

Example 8.5, “An ejb-jar.xml descriptor fragment that illustrates the method-permission element usage.”provides complete examples of the method-permission element usage.

Example 8.5. An ejb-jar.xml descriptor fragment that illustrates the method-permissionelement usage.

<!-- ... --> <method-param>PARAMETER_N</method-param> </method-params></method>

<ejb-jar> <assembly-descriptor> <method-permission> <description>The employee and temp-employee roles may access any method of the EmployeeService bean </description> <role-name>employee</role-name> <role-name>temp-employee</role-name> <method> <ejb-name>EmployeeService</ejb-name> <method-name>*</method-name> </method> </method-permission> <method-permission> <description>The employee role may access the findByPrimaryKey, getEmployeeInfo, and the updateEmployeeInfo(String) method of the AardvarkPayroll bean </description> <role-name>employee</role-name> <method> <ejb-name>AardvarkPayroll</ejb-name> <method-name>findByPrimaryKey</method-name> </method> <method> <ejb-name>AardvarkPayroll</ejb-name> <method-name>getEmployeeInfo</method-name> </method> <method> <ejb-name>AardvarkPayroll</ejb-name> <method-name>updateEmployeeInfo</method-name> <method-params> <method-param>java.lang.String</method-param> </method-params> </method> </method-permission> <method-permission>

Security Guide

136

Report a bug

8.2.6. Enterprise Beans Security Annotations

Enterprise beans use Annotations to pass information to the deployer about security and other aspects ofthe application. The deployer can set up the appropriate enterprise bean security policy for theapplication if specified in annotations, or the deployment descriptor.

Any method values explicitly specified in the deployment descriptor override annotation values. If amethod value is not specified in the deployment descriptor, those values set using annotations are used.The overriding granularity is on a per-method basis

Those annotations that address security and can be used in an enterprise beans include the following:

@DeclareRoles

Declares each security role declared in the code. For information about configuring roles, refer to theJava EE 6 Tutorial Specifying Authorized Users by Declaring Security Roles.

@RolesAllowed, @PermitAll, and @DenyAll

Specifies method permissions for annotations. For information about configuring annotation methodpermissions, refer to the Java EE 6 Tutorial Specifying Authorized Users by Declaring SecurityRoles.

<description>The admin role may access any method of the EmployeeServiceAdmin bean </description> <role-name>admin</role-name> <method> <ejb-name>EmployeeServiceAdmin</ejb-name> <method-name>*</method-name> </method> </method-permission> <method-permission> <description>Any authenticated user may access any method of the EmployeeServiceHelp bean</description> <unchecked/> <method> <ejb-name>EmployeeServiceHelp</ejb-name> <method-name>*</method-name> </method> </method-permission> <exclude-list> <description>No fireTheCTO methods of the EmployeeFiring bean may be used in this deployment</description> <method> <ejb-name>EmployeeFiring</ejb-name> <method-name>fireTheCTO</method-name> </method> </exclude-list> </assembly-descriptor></ejb-jar>

CHAPTER 8. SECURITY OVERVIEW

137

@RunAs

Configures the propagated security identity of a component. For information about configuringpropagated security identities using annotations, refer to the Java EE 6 Tutorial Propagating aSecurity Identity (Run-As).

Report a bug

8.2.7. Web Content Security Constraints

In a web application, security is defined by the roles that are allowed access to content by a URL patternthat identifies the protected content. This set of information is declared by using the web.xml security-constraint element.

Figure 8.5. Web Content Security Constraints

The content to be secured is declared using one or more <web-resource-collection> elements. Each<web-resource-collection> element contains an optional series of <url-pattern> elements followed by anoptional series of <http-method> elements. The <url-pattern> element value specifies a URL patternagainst which a request URL must match for the request to correspond to an attempt to access securedcontent. The <http-method> element value specifies a type of HTTP request to allow.

Security Guide

138

The optional <user-data-constraint> element specifies the requirements for the transport layer of theclient to server connection. The requirement may be for content integrity (preventing data tampering inthe communication process) or for confidentiality (preventing reading while in transit). The <transport-guarantee> element value specifies the degree to which communication between the client and servershould be protected. Its values are NONE, INTEGRAL, and CONFIDENTIAL. A value of NONE means thatthe application does not require any transport guarantees. A value of INTEGRAL means that theapplication requires the data sent between the client and server to be sent in such a way that it can notbe changed in transit. A value of CONFIDENTIAL means that the application requires the data to betransmitted in a fashion that prevents other entities from observing the contents of the transmission. Inmost cases, the presence of the INTEGRAL or CONFIDENTIAL flag indicates that the use of SSL isrequired.

The optional <login-config> element is used to configure the authentication method that should be used,the realm name that should be used for the application, and the attributes that are needed by the formlogin mechanism.

Figure 8.6. Web Login Configuration

The <auth-method> child element specifies the authentication mechanism for the web application. As aprerequisite to gaining access to any web resources that are protected by an authorization constraint, auser must have authenticated using the configured mechanism. Legal <auth-method> values are BASIC,DIGEST, FORM, SPNEGO, and CLIENT-CERT. The <realm-name> child element specifies the realmname to use in HTTP basic and digest authorization. The <form-login-config> child element specifies thelog in as well as error pages that should be used in form-based log in. If the <auth-method> value is not FORM, then form-login-config and its child elements are ignored.

The following configuration example indicates that any URL lying under the web application's /restricted path requires an AuthorizedUser role. There is no required transport guarantee andthe authentication method used for obtaining the user identity is BASIC HTTP authentication.

Example 8.6. web.xml Descriptor Fragment

<web-app> <security-constraint> <web-resource-collection>

CHAPTER 8. SECURITY OVERVIEW

139

Report a bug

8.2.8. Enable Form-based Authentication

Form-based authentication provides flexibility in defining a custom JSP/HTML page for log in, and aseparate page to which users are directed if an error occurs during login.

Form-based authentication is defined by including <auth-method>FORM</auth-method> in the<login-config> element of the deployment descriptor, web.xml. The login and error pages are alsodefined in <login-config>, as follows:

When a web application with form-based authentication is deployed, the web container uses FormAuthenticator to direct users to the appropriate page. JBoss EAP maintains a session pool sothat authentication information does not need to be present for each request. When FormAuthenticator receives a request, it queries org.apache.catalina.session.Manager foran existing session. If no session exists, a new session is created. FormAuthenticator then verifiesthe credentials of the session.

<web-resource-name>Secure Content</web-resource-name> <url-pattern>/restricted/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>AuthorizedUser</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </security-constraint> <!-- ... --> <login-config> <auth-method>BASIC</auth-method> <realm-name>The Restricted Zone</realm-name> </login-config> <!-- ... --> <security-role> <description>The role required to access restricted content </description> <role-name>AuthorizedUser</role-name> </security-role></web-app>

<login-config> <auth-method>FORM</auth-method> <form-login-config> <form-login-page>/login.html</form-login-page> <form-error-page>/error.html</form-error-page> </form-login-config></login-config>

Security Guide

140

NOTE

Each session is identified by a session ID, a 16 byte string generated from randomvalues. These values are retrieved from /dev/urandom (Linux) by default, and hashedwith MD5. Checks are performed at session ID creation to ensure that the ID created isunique.

Once verified, the session ID is assigned as part of a cookie, and then returned to the client. This cookieis expected in subsequent client requests and is used to identify the user session.

The cookie passed to the client is a name value pair with several optional attributes. The identifierattribute is called JSESSIONID . Its value is a hex-string of the session ID. This cookie is configured tobe non-persistent. This means that on the client side it will be deleted when the browser exits. On theserver side, sessions expire after 30 minutes of inactivity, at which time session objects and theircredential information are deleted.

Say a user attempts to access a web application that is protected with form-based authentication. FormAuthenticator caches the request, creates a new session if necessary, and redirects the user tothe login page defined in login-config. (In the previous example code, the login page is login.html.) The user then enters their user name and password in the HTML form provided. Username and password are passed to FormAuthenticator via the j_security_check form action.

The FormAuthenticator then authenticates the user name and password against the realm attachedto the web application context. In JBoss Enterprise Application Platform, the realm is JBossWebRealm.When authentication is successful, FormAuthenticator retrieves the saved request from the cacheand redirects the user to their original request.

NOTE

The server recognizes form authentication requests only when the URI ends with /j_security_check and at least the j_username and j_password parameters exist.

Report a bug

CHAPTER 8. SECURITY OVERVIEW

141

CHAPTER 9. APPLICATION SECURITY

9.1. DATASOURCE SECURITY

9.1.1. About Datasource Security

Datasource security refers to encrypting or obscuring passwords for datasource connections. Thesepasswords can be stored in plain text in configuration files, however this represents a security risk.

The preferred solution for datasource security is the use of either security domains or password vaults.Examples of each are included below. For more information, refer to the Security Architecture and otherJBoss EAP security documentation.

Example 9.1. Security Domain Example

The DsRealm domain is referenced by a datasource like so:

Example 9.2. Password Vault Example

Report a bug

<security-domain name="DsRealm" cache-type="default"> <authentication> <login-module code="ConfiguredIdentity" flag="required"> <module-option name="userName" value="sa"/> <module-option name="principal" value="sa"/> <module-option name="password" value="sa"/> </login-module> </authentication> </security-domain>

<datasources> <datasource jndi-name="java:jboss/datasources/securityDs" pool-name="securityDs"> <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url> <driver>h2</driver> <new-connection-sql>select current_user()</new-connection-sql> <security> <security-domain>DsRealm</security-domain> </security> </datasource></datasources>

<security> <user-name>admin</user-name> <password>${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}</password></security>

Security Guide

142

9.2. EJB APPLICATION SECURITY

9.2.1. Security Identity

9.2.1.1. About EJB Security Identity

An EJB can specify an identity to use when invoking methods on other components. This is the EJB'ssecurity identity (also known as invocation identity).

By default, the EJB uses its own caller identity. The identity can alternatively be set to a specific securityrole. Using specific security roles is useful when you want to construct a segmented security model - forexample, restricting access to a set of components to internal EJBs only.

Report a bug

9.2.1.2. Set the Security Identity of an EJB

The security identity of the EJB is specified through the <security-identity> tag in the securityconfiguration.

By default - if no <security-identity> tag is present - the EJB's own caller identity is used.

Example 9.3. Set the security identity of an EJB to be the same as its caller

This example sets the security identity for method invocations made by an EJB to be the same as thecurrent caller's identity. This behavior is the default if you do not specify a <security-identity>element declaration.

Example 9.4. Set the security identity of an EJB to a specific role

To set the security identity to a specific role, use the <run-as> and <role-name> tags inside the <security-identity> tag.

<ejb-jar> <enterprise-beans> <session> <ejb-name>ASessionBean</ejb-name> <!-- ... --> <security-identity> <use-caller-identity/> </security-identity> </session> <!-- ... --> </enterprise-beans></ejb-jar>

<ejb-jar> <enterprise-beans> <session> <ejb-name>RunAsBean</ejb-name> <!-- ... -->

CHAPTER 9. APPLICATION SECURITY

143

By default, when you use <run-as>, a principal named anonymous is assigned to outgoing calls. Toassign a different principal, uses the <run-as-principal>.

NOTE

You can also use the <run-as> and <run-as-principal> elements inside a servletelement.

See also:

Section 9.2.1.1, “About EJB Security Identity”

Section A.6, “EJB Security Parameter Reference”

Report a bug

9.2.2. EJB Method Permissions

9.2.2.1. About EJB Method Permissions

EJBs can restrict access to their methods to specific security roles.

The EJB <method-permission> element declaration specifies the roles that can invoke the EJB'sinterface methods. You can specify permissions for the following combinations:

All home and component interface methods of the named EJB

A specified method of the home or component interface of the named EJB

A specified method within a set of methods with an overloaded name

Report a bug

<security-identity> <run-as> <description>A private internal role</description> <role-name>InternalRole</role-name> </run-as> </security-identity> </session> </enterprise-beans> <!-- ... --></ejb-jar>

<session> <ejb-name>RunAsBean</ejb-name> <security-identity> <run-as-principal>internal</run-as-principal> </security-identity></session>

Security Guide

144

9.2.2.2. Use EJB Method Permissions

Overview

The <method-permission> element defines the logical roles that are allowed to access the EJBmethods defined by <method> elements. Several examples demonstrate the syntax of the XML.Multiple method permission statements may be present, and they have a cumulative effect. The <method-permission> element is a child of the <assembly-descriptor> element of the <ejb-jar> descriptor.

The XML syntax is an alternative to using annotations for EJB method permissions.

Example 9.5. Allow roles to access all methods of an EJB

Example 9.6. Allow roles to access only specific methods of an EJB, and limiting whichmethod parameters can be passed.

<method-permission> <description>The employee and temp-employee roles may access any method of the EmployeeService bean </description> <role-name>employee</role-name> <role-name>temp-employee</role-name> <method> <ejb-name>EmployeeService</ejb-name> <method-name>*</method-name> </method></method-permission>

<method-permission> <description>The employee role may access the findByPrimaryKey, getEmployeeInfo, and the updateEmployeeInfo(String) method of the AcmePayroll bean </description> <role-name>employee</role-name> <method> <ejb-name>AcmePayroll</ejb-name> <method-name>findByPrimaryKey</method-name> </method> <method> <ejb-name>AcmePayroll</ejb-name> <method-name>getEmployeeInfo</method-name> </method> <method> <ejb-name>AcmePayroll</ejb-name> <method-name>updateEmployeeInfo</method-name> <method-params> <method-param>java.lang.String</method-param> </method-params> </method></method-permission>

CHAPTER 9. APPLICATION SECURITY

145

Example 9.7. Allow any authenticated user to access methods of EJBs

Using the <unchecked/> element allows any authenticated user to use the specified methods.

Example 9.8. Completely exclude specific EJB methods from being used

Example 9.9. A complete <assembly-descriptor> containing several <method-permission> blocks

<method-permission> <description>Any authenticated user may access any method of the EmployeeServiceHelp bean</description> <unchecked/> <method> <ejb-name>EmployeeServiceHelp</ejb-name> <method-name>*</method-name> </method></method-permission>

<exclude-list> <description>No fireTheCTO methods of the EmployeeFiring bean may be used in this deployment</description> <method> <ejb-name>EmployeeFiring</ejb-name> <method-name>fireTheCTO</method-name> </method></exclude-list>

<ejb-jar> <assembly-descriptor> <method-permission> <description>The employee and temp-employee roles may access any method of the EmployeeService bean </description> <role-name>employee</role-name> <role-name>temp-employee</role-name> <method> <ejb-name>EmployeeService</ejb-name> <method-name>*</method-name> </method> </method-permission> <method-permission> <description>The employee role may access the findByPrimaryKey, getEmployeeInfo, and the updateEmployeeInfo(String) method of the AcmePayroll bean </description> <role-name>employee</role-name> <method>

Security Guide

146

Report a bug

9.2.3. EJB Security Annotations

9.2.3.1. About EJB Security Annotations

EJB javax.annotation.security annotations are defined in JSR250.

<ejb-name>AcmePayroll</ejb-name> <method-name>findByPrimaryKey</method-name> </method> <method> <ejb-name>AcmePayroll</ejb-name> <method-name>getEmployeeInfo</method-name> </method> <method> <ejb-name>AcmePayroll</ejb-name> <method-name>updateEmployeeInfo</method-name> <method-params> <method-param>java.lang.String</method-param> </method-params> </method> </method-permission> <method-permission> <description>The admin role may access any method of the EmployeeServiceAdmin bean </description> <role-name>admin</role-name> <method> <ejb-name>EmployeeServiceAdmin</ejb-name> <method-name>*</method-name> </method> </method-permission> <method-permission> <description>Any authenticated user may access any method of the EmployeeServiceHelp bean</description> <unchecked/> <method> <ejb-name>EmployeeServiceHelp</ejb-name> <method-name>*</method-name> </method> </method-permission> <exclude-list> <description>No fireTheCTO methods of the EmployeeFiring bean may be used in this deployment</description> <method> <ejb-name>EmployeeFiring</ejb-name> <method-name>fireTheCTO</method-name> </method> </exclude-list> </assembly-descriptor></ejb-jar>

CHAPTER 9. APPLICATION SECURITY

147

EJBs use security annotations to pass information about security to the deployer. These include:

@DeclareRoles

Declares which roles are available.

@RunAs

Configures the propagated security identity of a component.

Report a bug

9.2.3.2. Use EJB Security Annotations

Overview

You can use either XML descriptors or annotations to control which security roles are able to callmethods in your Enterprise JavaBeans (EJBs). For information on using XML descriptors, refer toSection 9.2.2.2, “Use EJB Method Permissions”.

Any method values explicitly specified in the deployment descriptor override annotation values. If amethod value is not specified in the deployment descriptor, those values set using annotations are used.The overriding granularity is on a per-method basis.

Annotations for Controlling Security Permissions of EJBs

@DeclareRoles

Use @DeclareRoles to define which security roles to check permissions against. If no@DeclareRoles is present, the list is built automatically from the @RolesAllowed annotation. Forinformation about configuring roles, refer to the Java EE 6 Tutorial Specifying Authorized Users byDeclaring Security Roles.

@RolesAllowed, @PermitAll, @DenyAll

Use @RolesAllowed to list which roles are allowed to access a method or methods. Use @PermitAll or @DenyAll to either permit or deny all roles from using a method or methods. Forinformation about configuring annotation method permissions, refer to the Java EE 6 TutorialSpecifying Authorized Users by Declaring Security Roles.

@RunAs

Use @RunAs to specify a role a method uses when making calls from the annotated method. Forinformation about configuring propagated security identities using annotations, refer to the Java EE 6Tutorial Propagating a Security Identity (Run-As).

Example 9.10. Security Annotations Example

@Stateless@RolesAllowed({"admin"})@SecurityDomain("other")public class WelcomeEJB implements Welcome { @PermitAll public String WelcomeEveryone(String msg) { return "Welcome to " + msg; }

Security Guide

148

In this code, all roles can access method WelcomeEveryone. The GoodBye method uses the tempemployee role when making calls. Only the admin role can access method GoodbyeAdmin,and any other methods with no security annotation.

Report a bug

9.2.4. Remote Access to EJBs

9.2.4.1. About Remote Method Access

JBoss Remoting is the framework which provides remote access to EJBs, JMX MBeans, and othersimilar services. It works within the following transport types, with or without SSL:

Supported Transport Types

Socket / Secure Socket

RMI / RMI over SSL

HTTP / HTTPS

Servlet / Secure Servlet

Bisocket / Secure Bisocket

WARNING

Red Hat recommends that you explicitly disable SSL in favor of TLSv1.1 or TLSv1.2in all affected packages.

JBoss Remoting also provides automatic discovery via Multicast or JNDI.

It is used by many of the subsystems within JBoss EAP 6, and also enables you to design, implement,and deploy services that can be remotely invoked by clients over several different transport mechanisms.It also allows you to access existing services in JBoss EAP 6.

Data Marshalling

The Remoting system also provides data marshalling and unmarshalling services. Data marshallingrefers to the ability to safely move data across network and platform boundaries, so that a separate

@RunAs("tempemployee") public String GoodBye(String msg) { return "Goodbye, " + msg; } public String GoodbyeAdmin(String msg) { return "See you later, " + msg; }}

CHAPTER 9. APPLICATION SECURITY

149

system can perform work on it. The work is then sent back to the original system and behaves as thoughit were handled locally.

Architecture Overview

When you design a client application which uses Remoting, you direct your application to communicatewith the server by configuring it to use a special type of resource locator called an InvokerLocator,which is a simple String with a URL-type format. The server listens for requests for remote resources ona connector, which is configured as part of the remoting subsystem. The connector hands therequest off to a configured ServerInvocationHandler. Each ServerInvocationHandlerimplements a method invoke(InvocationRequest), which knows how to handle the request.

The JBoss Remoting framework contains three layers that mirror each other on the client and serverside.

JBoss Remoting Framework Layers

The user interacts with the outer layer. On the client side, the outer layer is the Client class,which sends invocation requests. On the server side, it is the InvocationHandler, which isimplemented by the user and receives invocation requests.

The transport is controlled by the invoker layer.

The lowest layer contains the marshaller and unmarshaller, which convert data formats to wireformats.

Report a bug

9.2.4.2. About Remoting Callbacks

When a Remoting client requests information from the server, it can block and wait for the server toreply, but this is often not the ideal behavior. To allow the client to listen for asynchronous events on theserver, and continue doing other work while waiting for the server to finish the request, your applicationcan ask the server to send a notification when it has finished. This is referred to as a callback. One clientcan add itself as a listener for asynchronous events generated on behalf of another client, as well. Thereare two different choices for how to receive callbacks: pull callbacks or push callbacks. Clients check forpull callbacks synchronously, but passively listen for push callbacks.

In essence, a callback works by the server sending an InvocationRequest to the client. Your server-side code works the same regardless of whether the callback is synchronous or asynchronous. Only theclient needs to know the difference. The server's InvocationRequest sends a responseObject to theclient. This is the payload that the client has requested. This may be a direct response to a request or anevent notification.

Your server also tracks listeners using an m_listeners object. It contains a list of all listeners that havebeen added to your server handler. The ServerInvocationHandler interface includes methods thatallow you to manage this list.

The client handles pull and push callback in different ways. In either case, it must implement a callbackhandler. A callback handler is an implementation of interface org.jboss.remoting.InvokerCallbackHandler, which processes the callback data. Afterimplementing the callback handler, you either add yourself as a listener for a pull callback, or implementa callback server for a push callback.

Pull Callbacks

Security Guide

150

For a pull callback, your client adds itself to the server's list of listeners using the Client.addListener() method. It then polls the server periodically for synchronous delivery ofcallback data. This poll is performed using the Client.getCallbacks().

Push Callback

A push callback requires your client application to run its own InvocationHandler. To do this, you need torun a Remoting service on the client itself. This is referred to as a callback server. The callback serveraccepts incoming requests asynchronously and processes them for the requester (in this case, theserver). To register your client's callback server with the main server, pass the callback server's InvokerLocator as the second argument to the addListener method.

Report a bug

9.2.4.3. About Remoting Server Detection

Remoting servers and clients can automatically detect each other using JNDI or Multicast. A RemotingDetector is added to both the client and server, and a NetworkRegistry is added to the client.

The Detector on the server side periodically scans the InvokerRegistry and pulls all server invokers ithas created. It uses this information to publish a detection message which contains the locator andsubsystems supported by each server invoker. It publishes this message via a multicast broadcast or abinding into a JNDI server.

On the client side, the Detector receives the multicast message or periodically polls the JNDI server toretrieve detection messages. If the Detector notices that a detection message is for a newly-detectedremoting server, it registers it into the NetworkRegistry. The Detector also updates the NetworkRegistryif it detects that a server is no longer available.

Report a bug

9.2.4.4. Configure the Remoting Subsystem

Overview

JBoss Remoting has three top-level configurable elements: the worker thread pool, one or moreconnectors, and a series of local and remote connection URIs. This topic presents an explanation ofeach configurable item, example CLI commands for how to configure each item, and an XML example ofa fully-configured subsystem. This configuration only applies to the server. Most people will not need toconfigure the Remoting subsystem at all, unless they use custom connectors for their own applications.Applications which act as Remoting clients, such as EJBs, need separate configuration to connect to aspecific connector.

NOTE

The Remoting subsystem configuration is not exposed to the web-based ManagementConsole, but it is fully configurable from the command-line based Management CLI.Editing the XML by hand is not recommended.

Adapting the CLI Commands

The CLI commands are formulated for a managed domain, when configuring the default profile. Toconfigure a different profile, substitute its name. For a standalone server, omit the /profile=defaultpart of the command.

Configuration Outside the Remoting Subsystem

CHAPTER 9. APPLICATION SECURITY

151

There are a few configuration aspects which are outside of the remoting subsystem:

Network Interface

The network interface used by the remoting subsystem is the public interface defined in the domain/configuration/domain.xml or standalone/configuration/standalone.xml.

The per-host definition of the public interface is defined in the host.xml in the same directory asthe domain.xml or standalone.xml. This interface is also used by several other subsystems.Exercise caution when modifying it.

socket-binding

The default socket-binding used by the remoting subsystem binds to TCP port 4447. Refer to thedocumentation about socket bindings and socket binding groups for more information if you need tochange this.

Remoting Connector Reference for EJB

The EJB subsystem contains a reference to the remoting connector for remote method invocations.The following is the default configuration:

Secure Transport Configuration

Remoting transports use StartTLS to use a secure (HTTPS, Secure Servlet, etc) connection if theclient requests it. The same socket binding (network port) is used for secured and unsecuredconnections, so no additional server-side configuration is necessary. The client requests the secure

<interfaces> <interface name="management"/> <interface name="public"/> <interface name="unsecure"/></interfaces>

<interfaces> <interface name="management"> <inet-address value="${jboss.bind.address.management:127.0.0.1}"/> </interface> <interface name="public"> <inet-address value="${jboss.bind.address:127.0.0.1}"/> </interface> <interface name="unsecure"> <!-- Used for IIOP sockets in the standard configuration. To secure JacORB you need to setup SSL --> <inet-address value="${jboss.bind.address.unsecure:127.0.0.1}"/> </interface></interfaces>

<remote connector-ref="remoting-connector" thread-pool-name="default"/>

Security Guide

152

or unsecured transport, as its needs dictate. JBoss EAP 6 components which use Remoting, such asEJBs, the ORB, and the JMS provider, request secured interfaces by default.

WARNING

StartTLS works by activating a secure connection if the client requests it, andotherwise defaulting to an unsecured connection. It is inherently susceptible to aMan in the Middle style exploit, wherein an attacker intercepts the client's requestand modifies it to request an unsecured connection. Clients must be written to failappropriately if they do not receive a secure connection, unless an unsecuredconnection actually is an appropriate fall-back.

Worker Thread Pool

The worker thread pool is the group of threads which are available to process work which comes inthrough the Remoting connectors. It is a single element <worker-thread-pool>, and takes severalattributes. Tune these attributes if you get network timeouts, run out of threads, or need to limit memoryusage. Specific recommendations depend on your specific situation. Contact Red Hat Global SupportServices for more information.

Table 9.1. Worker Thread Pool Attributes

Attribute Description CLI Command

read-threads The number of read threads tocreate for the remoting worker.Defaults to 1.

/profile=default/subsystem=remoting/:write-attribute(name=worker-read-threads,value=1)

write-threads The number of write threads tocreate for the remoting worker.Defaults to 1.

/profile=default/subsystem=remoting/:write-attribute(name=worker-write-threads,value=1)

task-keepalive The number of milliseconds tokeep non-core remoting workertask threads alive. Defaults to 60.

/profile=default/subsystem=remoting/:write-attribute(name=worker-task-keepalive,value=60)

task-max-threads The maximum number of threadsfor the remoting worker taskthread pool. Defaults to 16.

/profile=default/subsystem=remoting/:write-attribute(name=worker-task-max-threads,value=16)

CHAPTER 9. APPLICATION SECURITY

153

task-core-threads The number of core threads forthe remoting worker task threadpool. Defaults to 4.

/profile=default/subsystem=remoting/:write-attribute(name=worker-task-core-threads,value=4)

task-limit The maximum number ofremoting worker tasks to allowbefore rejecting. Defaults to 16384.

/profile=default/subsystem=remoting/:write-attribute(name=worker-task-limit,value=16384)

Attribute Description CLI Command

Connector

The connector is the main Remoting configuration element. Multiple connectors are allowed. Eachconsists of a element <connector> element with several sub-elements, as well as a few possibleattributes. The default connector is used by several subsystems of JBoss EAP 6. Specific settings for theelements and attributes of your custom connectors depend on your applications, so contact Red HatGlobal Support Services for more information.

Table 9.2. Connector Attributes

Attribute Description CLI Command

socket-binding The name of the socket binding touse for this connector.

/profile=default/subsystem=remoting/connector=remoting-connector/:write-attribute(name=socket-binding,value=remoting)

authentication-provider The Java Authentication ServiceProvider Interface for Containers(JASPIC) module to use with thisconnector. The module must be inthe classpath.

/profile=default/subsystem=remoting/connector=remoting-connector/:write-attribute(name=authentication-provider,value=myProvider)

security-realm Optional. The security realmwhich contains your application'susers, passwords, and roles. AnEJB or Web Application canauthenticate against a securityrealm. ApplicationRealm isavailable in a default JBoss EAP 6installation.

/profile=default/subsystem=remoting/connector=remoting-connector/:write-attribute(name=security-realm,value=ApplicationRealm)

Table 9.3. Connector Elements

Security Guide

154

Attribute Description CLI Command

sasl Enclosing element for SimpleAuthentication and Security Layer(SASL) authenticationmechanisms

N/A

properties Contains one or more <property> elements, eachwith a name attribute and anoptional value attribute.

/profile=default/subsystem=remoting/connector=remoting-connector/property=myProp/:add(value=myPropValue)

Outbound Connections

You can specify three different types of outbound connection:

Outbound connection to a URI.

Local outbound connection – connects to a local resource such as a socket.

Remote outbound connection – connects to a remote resource and authenticates using asecurity realm.

All of the outbound connections are enclosed in an <outbound-connections> element. Each of theseconnection types takes an outbound-socket-binding-ref attribute. The outbound-connectiontakes a uri attribute. The remote outbound connection takes optional username and security-realm attributes to use for authorization.

Table 9.4. Outbound Connection Elements

Attribute Description CLI Command

outbound-connection Generic outbound connection. /profile=default/subsystem=remoting/outbound-connection=my-connection/:add(uri=http://my-connection)

local-outbound-connection Outbound connection with aimplicit local:// URI scheme.

/profile=default/subsystem=remoting/local-outbound-connection=my-connection/:add(outbound-socket-binding-ref=remoting2)

remote-outbound-connection Outbound connections forremote:// URI scheme, usingbasic/digest authentication with asecurity realm.

/profile=default/subsystem=remoting/remote-outbound-connection=my-connection/:add(outbound-socket-binding-ref=remoting,username=myUser,security-realm=ApplicationRealm)

CHAPTER 9. APPLICATION SECURITY

155

SASL Elements

Before defining the SASL child elements, you need to create the initial SASL element. Use the followingcommand:

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:add

The child elements of the SASL element are described in the table below.

Table 9.5. SASL child elements

Attribute Description CLI Command

include-mechanisms Contains a value attribute,which is a list of SASLmechanisms.

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=include-mechanisms,value=["DIGEST","PLAIN","GSSAPI"])

qop Contains a value attribute,which is a list of SASL Quality ofprotection values, in decreasingorder of preference.

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=qop,value=["auth"])

strength Contains a value attribute,which is a list of SASL cipherstrength values, in decreasingorder of preference.

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=strength,value=["medium"])

Security Guide

156

reuse-session Contains a value attribute whichis a boolean value. If true, attemptto reuse sessions.

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=reuse-session,value=false)

server-auth Contains a value attribute whichis a boolean value. If true, theserver authenticates to the client.

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=server-auth,value=false)

policy An enclosing element whichcontains zero or more of thefollowing elements, which eachtake a single value.

forward-secrecy –whether mechanisms arerequired to implementforward secrecy(breaking into onesession will notautomatically provideinformation for breakinginto future sessions)

no-active – whethermechanisms susceptibleto non-dictionary attacksare permitted. A value of false permits, and true denies.

no-anonymous – whethermechanisms that acceptanonymous login arepermitted. A value of false permits, and true denies.

no-dictionary – whethermechanisms susceptibleto passive dictionaryattacks are allowed. Avalue of false permits,and true denies.

no-plain-text – whether

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:add

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=forward-secrecy,value=true)

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=no-active,value=false)

/profile=default/subsystem=remoting/connector=remoting-connector/security=s

Attribute Description CLI Command

CHAPTER 9. APPLICATION SECURITY

157

mechanisms which aresusceptible to simpleplain passive attacks areallowed. A value of false permits, and true denies.

pass-credentials –whether mechanismswhich pass clientcredentials are allowed.

asl/sasl-policy=policy:write-attribute(name=no-anonymous,value=false)

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=no-dictionary,value=true)

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=no-plain-text,value=false)

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=pass-credentials,value=true)

properties Contains one or more <property> elements, eachwith a name attribute and anoptional value attribute.

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/property=myprop:add(value=1)

/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/property=myprop2:add(value=2)

Attribute Description CLI Command

Security Guide

158

Example 9.11. Example Configurations

This example shows the default remoting subsystem that ships with JBoss EAP 6.

This example contains many hypothetical values, and is presented to put the elements and attributesdiscussed previously into context.

<subsystem xmlns="urn:jboss:domain:remoting:1.1"> <connector name="remoting-connector" socket-binding="remoting" security-realm="ApplicationRealm"/></subsystem>

<subsystem xmlns="urn:jboss:domain:remoting:1.1"> <worker-thread-pool read-threads="1" task-keepalive="60" task-max-threads="16" task-core-thread="4" task-limit="16384" write-threads="1" /> <connector name="remoting-connector" socket-binding="remoting" security-realm="ApplicationRealm"> <sasl> <include-mechanisms value="GSSAPI PLAIN DIGEST-MD5" /> <qop value="auth" /> <strength value="medium" /> <reuse-session value="false" /> <server-auth value="false" /> <policy> <forward-secrecy value="true" /> <no-active value="false" /> <no-anonymous value="false" /> <no-dictionary value="true" /> <no-plain-text value="false" /> <pass-credentials value="true" /> </policy> <properties> <property name="myprop1" value="1" /> <property name="myprop2" value="2" /> </properties> </sasl> <authentication-provider name="myprovider" /> <properties> <property name="myprop3" value="propValue" /> </properties> </connector> <outbound-connections> <outbound-connection name="my-outbound-connection" uri="http://myhost:7777/"/> <remote-outbound-connection name="my-remote-connection" outbound-socket-binding-ref="my-remote-socket" username="myUser" security-realm="ApplicationRealm"/> <local-outbound-connection name="myLocalConnection" outbound-socket-binding-ref="my-outbound-socket"/> </outbound-connections>

CHAPTER 9. APPLICATION SECURITY

159

Configuration Aspects Not Yet Documented

JNDI and Multicast Automatic Detection

Report a bug

9.2.4.5. Use Security Realms with Remote EJB Clients

One way to add security to clients which invoke EJBs remotely is to use security realms. A securityrealm is a simple database of username/password pairs and username/role pairs. The terminology isalso used in the context of web containers, with a slightly different meaning.

To authenticate a specific username/password pair that exists in a security realm against an EJB, followthese steps:

Add a new security realm to the domain controller or standalone server.

Add the following parameters to the jboss-ejb-client.properties file, which is in theclasspath of the application. This example assumes the connection is referred to as default bythe other parameters in the file.

Create a custom Remoting connector on the domain or standalone server, which uses your newsecurity realm.

Deploy your EJB to the server group which is configured to use the profile with the customRemoting connector, or to your standalone server if you are not using a managed domain.

Report a bug

9.2.4.6. Add a New Security Realm

1. Run the Management CLI.Start the jboss-cli.sh or jboss-cli.bat command and connect to the server.

2. Create the new security realm itself.Run the following command to create a new security realm named MyDomainRealm on adomain controller or a standalone server.

For a domain instance, use this command:

/host=master/core-service=management/security-realm=MyDomainRealm:add()

For a standalone instance, use this command:

/core-service=management/security-realm=MyDomainRealm:add()

</subsystem>

remote.connection.default.username=appuserremote.connection.default.password=apppassword

Security Guide

160

3. Create the references to the properties file which will store information about the newrole.Run the following command to create a pointer a file named myfile.properties, which willcontain the properties pertaining to the new role.

NOTE

The newly created properties file is not managed by the included add-user.shand add-user.bat scripts. It must be managed externally.

For a domain instance, use this command:

/host=master/core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path=myfile.properties)

For a standalone instance, use this command:

/core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path=myfile.properties)

Result

Your new security realm is created. When you add users and roles to this new realm, the information willbe stored in a separate file from the default security realms. You can manage this new file using yourown applications or procedures.

Report a bug

9.2.4.7. Add a User to a Security Realm

1. Run the add-user.sh or add-user.bat command.Open a terminal and change directories to the EAP_HOME/bin/ directory. If you run Red HatEnterprise Linux or another UNIX-like operating system, run add-user.sh. If you run MicrosoftWindows Server, run add-user.bat.

2. Choose whether to add a Management User or Application User.For this procedure, type b to add an Application User.

3. Choose the realm the user will be added to.By default, the only available realm is ApplicationRealm. If you have added a custom realm,you can type its name instead.

4. Type the username, password, and roles, when prompted.Type the desired username, password, and optional roles when prompted. Verify your choice bytyping yes, or type no to cancel the changes. The changes are written to each of the propertiesfiles for the security realm.

Report a bug

9.2.4.8. About Remote EJB Access Using SSL Encryption

CHAPTER 9. APPLICATION SECURITY

161

By default, the network traffic for Remote Method Invocation (RMI) of EJB2 and EJB3 Beans is notencrypted. In instances where encryption is required, Secure Sockets Layer (SSL) can be utilized so thatthe connection between the client and server is encrypted. Using SSL also has the added benefit ofallowing the network traffic to traverse some firewalls, depending on the firewall configuration.

WARNING

Red Hat recommends that you explicitly disable SSL in favor of TLSv1.1 or TLSv1.2in all affected packages.

Report a bug

9.3. JAX-RS APPLICATION SECURITY

9.3.1. Enable Role-Based Security for a RESTEasy JAX-RS Web Service

Summary

RESTEasy supports the @RolesAllowed, @PermitAll, and @DenyAll annotations on JAX-RS methods.However, it does not recognize these annotations by default. Follow these steps to configure the web.xml file and enable role-based security.

WARNING

Do not activate role-based security if the application uses EJBs. The EJB containerwill provide the functionality, instead of RESTEasy.

Procedure 9.1. Enable Role-Based Security for a RESTEasy JAX-RS Web Service

1. Open the web.xml file for the application in a text editor.

2. Add the following <context-param> to the file, within the web-app tags:

<context-param> <param-name>resteasy.role.based.security</param-name> <param-value>true</param-value></context-param>

3. Declare all roles used within the RESTEasy JAX-RS WAR file, using the <security-role> tags:

<security-role> <role-name>ROLE_NAME</role-name></security-role>

Security Guide

162

<security-role> <role-name>ROLE_NAME</role-name></security-role>

4. Authorize access to all URLs handled by the JAX-RS runtime for all roles:

<security-constraint> <web-resource-collection> <web-resource-name>Resteasy</web-resource-name> <url-pattern>/PATH</url-pattern> </web-resource-collection> <auth-constraint> <role-name>ROLE_NAME</role-name> <role-name>ROLE_NAME</role-name> </auth-constraint></security-constraint>

Result

Role-based security has been enabled within the application, with a set of defined roles.

Example 9.12. Example Role-Based Security Configuration

<web-app>

<context-param> <param-name>resteasy.role.based.security</param-name> <param-value>true</param-value> </context-param>

<servlet-mapping> <servlet-name>Resteasy</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping>

<security-constraint> <web-resource-collection> <web-resource-name>Resteasy</web-resource-name> <url-pattern>/security</url-pattern> </web-resource-collection> <auth-constraint> <role-name>admin</role-name> <role-name>user</role-name> </auth-constraint> </security-constraint>

<security-role> <role-name>admin</role-name> </security-role> <security-role> <role-name>user</role-name> </security-role> </web-app>

CHAPTER 9. APPLICATION SECURITY

163

Report a bug

9.3.2. Secure a JAX-RS Web Service using Annotations

Summary

This topic covers the steps to secure a JAX-RS web service using the supported security annotations

Procedure 9.2. Secure a JAX-RS Web Service using Supported Security Annotations

1. Enable role-based security. For more information, refer to: Section 9.3.1, “Enable Role-BasedSecurity for a RESTEasy JAX-RS Web Service”

2. Add security annotations to the JAX-RS web service. RESTEasy supports the followingannotations:

@RolesAllowed

Defines which roles can access the method. All roles should be defined in the web.xml file.

@PermitAll

Allows all roles defined in the web.xml file to access the method.

@DenyAll

Denies all access to the method.

Report a bug

Security Guide

164

CHAPTER 10. THE SECURITY SUBSYSTEM

10.1. ABOUT THE SECURITY SUBSYSTEM

The security subsystem provides security infrastructure for applications. The subsystem uses asecurity context associated with the current request to expose the capabilities of the authenticationmanager, authorization manager, audit manager, and mapping manager to the relevant container.

The security subsystem is preconfigured by default, so security elements rarely need to be changed.The only security element that may need to be changed is whether to use deep-copy-subject-mode. Inmost cases, administrators will focus on the configuration of security domains.

Deep Copy Mode

See Section 10.3.2.1, “About Deep Copy Subject Mode” for details about deep copy subject mode.

Security Domain

A security domain is a set of Java Authentication and Authorization Service (JAAS) declarative securityconfigurations which one or more applications use to control authentication, authorization, auditing, andmapping. Three security domains are included by default: jboss-ejb-policy, jboss-web-policy,and other. You can create as many security domains as you need to accommodate your applicationrequirements.

Report a bug

10.2. ABOUT THE STRUCTURE OF THE SECURITY SUBSYSTEM

The security subsystem is configured in the managed domain or standalone configuration file. Most ofthe configuration elements can be configured using the web-based management console or the console-based management CLI. The following is the XML representing an example security subsystem.

Example 10.1. Example Security Subsystem Configuration

<subsystem xmlns="urn:jboss:domain:security:1.2"> <security-management> ... </security-management> <security-domains> <security-domain name="other" cache-type="default"> <authentication> <login-module code="Remoting" flag="optional"> <module-option name="password-stacking" value="useFirstPass"/> </login-module> <login-module code="RealmUsersRoles" flag="required"> <module-option name="usersProperties" value="${jboss.domain.config.dir}/application-users.properties"/> <module-option name="rolesProperties" value="${jboss.domain.config.dir}/application-roles.properties"/> <module-option name="realm" value="ApplicationRealm"/> <module-option name="password-stacking" value="useFirstPass"/> </login-module>

CHAPTER 10. THE SECURITY SUBSYSTEM

165

The <security-management>, <subject-factory>, <security-properties>, and <vault> elements are not present in the default configuration. The <subject-factory> and <security-properties> elements have been deprecated in JBoss EAP 6.1 onwards.

Report a bug

10.3. CONFIGURING THE SECURITY SUBSYSTEM

10.3.1. Configure the Security Subsystem

You can configure the security subsystem using the Management CLI or web-based ManagementConsole.

Each top-level element within the security subsystem contains information about a different aspect of thesecurity configuration. Refer to Section 10.2, “About the Structure of the Security Subsystem” for anexample of security subsystem configuration.

<security-management>

This section overrides high-level behaviors of the security subsystem. It contains an optional setting deep-copy-subject-mode, that specifies whether to copy or link to security tokens, for additionalthread safety.

<security-domains>

A container element which holds multiple security domains. A security domain may containinformation about authentication, authorization, mapping, and auditing modules, as well as JASPIauthentication and JSSE configuration. Your application would specify a security domain to manageits security information.

<security-properties>

Contains names and values of properties which are set on the java.security.Security class.

</authentication> </security-domain> <security-domain name="jboss-web-policy" cache-type="default"> <authorization> <policy-module code="Delegating" flag="required"/> </authorization> </security-domain> <security-domain name="jboss-ejb-policy" cache-type="default"> <authorization> <policy-module code="Delegating" flag="required"/> </authorization> </security-domain> </security-domains> <vault> ... </vault></subsystem>

Security Guide

166

Report a bug

10.3.2. Security Management

10.3.2.1. About Deep Copy Subject Mode

If deep copy subject mode is disabled (the default), copying a security data structure makes a referenceto the original, rather than copying the entire data structure. This behavior is more efficient, but is proneto data corruption if multiple threads with the same identity clear the subject by means of a flush orlogout operation.

Deep copy subject mode causes a complete copy of the data structure and all its associated data to bemade, as long as they are marked cloneable. This is more thread-safe, but less efficient.

Deep copy subject mode is configured as part of the security subsystem.

Report a bug

10.3.2.2. Enable Deep Copy Subject Mode

You can enable deep copy security mode from the web-based management console or the managementCLI.

Procedure 10.1. Enable Deep Copy Security Mode from the Management Console

1. Log into the Management Console.For detailed instructions, see the section entitled The Management Console in theAdministration and Configuration Guide for JBoss Enterprise Application Platform 6.x located onthe Customer Portal athttps://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

2. Managed Domain: Select the appropriate profile.In a managed domain, the security subsystem is configured per profile, and you can enable ordisable the deep copy security mode independently in each profile.

To select a profile, click Configuration at the top of the screen, and then select a profile fromthe Profile drop down box at the top left.

3. Open the Security Subsystem configuration menu.Expand the Security menu, then select Security Subsystem.

4. Enable Deep Copy Subject mode.Click Edit. Check the box beside Deep Copy Subjects to enable deep copy subject mode.

Enable Deep Copy Subject Mode Using the Management CLI

If you prefer to use the management CLI to enable this option, use one of the following commands.

Example 10.2. Managed Domain

/profile=full/subsystem=security/:write-attribute(name=deep-copy-subject-mode,value=TRUE)

CHAPTER 10. THE SECURITY SUBSYSTEM

167

Example 10.3. Standalone Server

/subsystem=security/:write-attribute(name=deep-copy-subject-mode,value=TRUE)

Report a bug

10.3.3. Security Domains

10.3.3.1. About Security Domains

Security domains are part of the JBoss EAP 6 security subsystem. All security configuration is nowmanaged centrally, by the domain controller of a managed domain, or by the standalone server.

A security domain consists of configurations for authentication, authorization, security mapping, andauditing. It implements Java Authentication and Authorization Service (JAAS) declarative security.

Authentication refers to verifying the identity of a user. In security terminology, this user is referred to asa principal. Although authentication and authorization are different, many of the included authenticationmodules also handle authorization.

Authorization is a process by which the server determines if an authenticated user has permission orprivileges to access specific resources in the system or operation.

Security mapping refers to the ability to add, modify, or delete information from a principal, role, orattribute before passing the information to your application.

The auditing manager allows you to configure provider modules to control the way that security eventsare reported.

If you use security domains, you can remove all specific security configuration from your applicationitself. This allows you to change security parameters centrally. One common scenario that benefits fromthis type of configuration structure is the process of moving applications between testing and productionenvironments.

Report a bug

10.3.3.2. CLI Operations Related to Security Domains

Example 10.4. flush-cache

This CLI command removes entries stored in the authentication cache for a security domain. A singleentry can be flushed by using the principal argument with the username as the value. If no argumentis passed to the operation, all entries are flushed. For more details about this operation, use the CLIcommand:

/subsystem=security/security-domain=other:read-operation-description(name=flush-cache)

Example 10.5. list-cached-principals

Security Guide

168

This CLI command lists the principals stored in the authentication cache for this security domain. Formore details about this operation, use the CLI command:

/subsystem=security/security-domain=other:read-operation-description(name=list-cached-principals)

Report a bug

CHAPTER 10. THE SECURITY SUBSYSTEM

169

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

11.1. KERBEROS AND SPNEGO INTEGRATION

11.1.1. About Kerberos and SPNEGO Integration

Kerberos is an authentication method that is designed for open network computing environments. Itworks on the basis of a ticket and authenticator to establish the identity of both the user and the server. Ithelps the two nodes communicating over a non secure environment to establish their identity to eachother in a secured manner.

SPNEGO is an authentication method used by a client application to authenticate itself to the server.This technology is used when the client application and the server trying to communicate with each otherare not sure of the authentication protocol the other supports. SPNEGO determines the common GSSAPImechanisms between the client application and the server and then dispatches all further securityoperations to it.

Kerberos and SPNEGO Integration

In a typical setup, the user logs into a desktop which is governed by the Active Directory domain. Theuser then uses the web browser, either Firebox or Internet Explorer, to access a web application thatuses JBoss Negotiation hosted on the JBoss EAP. The web browser transfers the desktop sign oninformation to the web application. JBoss EAP uses background GSS messages with the ActiveDirectory or any Kerberos Server to validate the user. This enables the user to achieve a seamless SSOinto the web application.

Report a bug

11.1.2. Desktop SSO using SPNEGO

To configure the desktop SSO using SPNEGO configure the following:

Security Domain

System Properties

Web Application

Procedure 11.1. Configure Desktop SSO using SPNEGO

1. Configure Security DomainConfigure the security domains to represent the identity of the server and to secure the webapplication.

Example 11.1. Security Domain Configuration

<security-domains>

<security-domain name="host" cache-type="default">

<authentication>

<login-module code="Kerberos" flag="required">

Security Guide

170

2. Setup the System PropertiesIf required, the system properties can be set in the domain model.

Example 11.2. Configure System Properties

<module-option name="storeKey" value="true"/>

<module-option name="useKeyTab" value="true"/>

<module-option name="principal" value="host/testserver@MY_REALM"/>

<module-option name="keyTab" value="/home/username/service.keytab"/>

<module-option name="doNotPrompt" value="true"/>

<module-option name="debug" value="false"/>

</login-module>

</authentication>

</security-domain>

<security-domain name="SPNEGO" cache-type="default">

<authentication>

<login-module code="SPNEGO" flag="requisite">

<module-option name="password-stacking" value="useFirstPass"/>

<module-option name="serverSecurityDomain" value="host"/>

</login-module>

<!-- Login Module For Roles Search -->

</security-domain>

<system-properties>

<property name="java.security.krb5.kdc" value="mykdc.mydomain"/>

<property name="java.security.krb5.realm" value="MY_REALM"/>

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

171

3. Configure Web ApplicationIt is not possible to override the authenticators, but it is possible to add the NegotiationAuthenticator as a valve to your jboss-web.xml descriptor to configure theweb application.

NOTE

The valve requires the security-constraint and login-config to bedefined in the web.xml file as this is used to decide which resources are secured.However, the chosen auth-method is overridden by this authenticator.

Example 11.3. Configure Web Application

The web application also requires a dependency defining in META-INF/MANIFEST.MF so thatthe JBoss Negotiation classes can be located.

Example 11.4. Define Dependency in META-INF/MANIFEST.MF

Report a bug

</system-properties>

<!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 2.4//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_4_0.dtd">

<jboss-web>

<security-domain>SPNEGO</security-domain>

<valve>

<class-name>org.jboss.security.negotiation.NegotiationAuthenticator</class-name>

</valve>

</jboss-web>

Manifest-Version: 1.0

Build-Jdk: 1.6.0_24

Dependencies: org.jboss.security.negotiation

Security Guide

172

11.1.3. Configure JBoss Negotiation for Microsoft Windows Domain

This section describes how to configure the accounts required for JBoss Negotiation to be used whenJBoss EAP is running on a Microsoft Windows server, which is a part of the Active Directory domain.

In this section, the hostname that is used to access the server as is referred to as {hostname}, realm isreferred to as {realm}, domain is referred to as {domain}, and the server hosting the JBoss EAPinstance is referred to as {machine_name}.

Procedure 11.2. Configure JBoss Negotiation for Microsoft Windows Domain

1. Clear Existing Service Principal MappingsOn a Microsoft Windows network some mappings are created automatically. Delete theautomatically created mappings to map the identity of the server to the service principal fornegotiation to take place correctly. The mapping enables the web browser on the clientcomputer to trust the server and attempt SPNEGO. The client computer verifies with the domaincontroller for a mapping in the form of HTTP{hostname}.

The following are the steps to delete the existing mappings:

List the mapping registered with the domain for the computer using the command, setspn -L {machine_name}.

Delete the existing mappings using the commands, setspn -D HTTP/{hostname} {machine_name} and setspn -D host/{hostname} {machine_name}.

2. Create a host user account.

NOTE

Ensure the host user name is different from the {machine_name}.

In the rest of the section the host user name is referred to as {user_name}.

3. Define the mapping between the {user_name} and {hostname}.

Run the following command to configure the Service Principal Mapping, ktpass -princ HTTP/{hostname}@{realm} -pass * -mapuser {domain}\{user_name}.

Enter the password for the user name when prompted.

NOTE

Reset the password for the user name as it is a prerequisite for exporting thekeytab.

Verify the mapping by running the following command, setspn -L {user_name}

4. Export the keytab of the user to the server on which EAP JBoss is installed.Run the following command to export the keytab, ktab -k service.keytab -a HTTP/{hostname}@{realm}.

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

173

NOTE

This command exports the ticket for the HTTP/{hostname} principal to the keytab service.keytab, which is used to configure the host security domain on JBoss.

5. Define the principal within the security domain as follows:

Report a bug

11.1.4. Kerberos Authentication for PicketLink IDP

The following sections explain how to set up Kerberos authentication for PicketLink IDP.

Procedure 11.3. Install JBoss EAP 6 and setup Kerberos

1. Download and install JBoss EAP 6. Refer to installation instructions in the Installation Guide.

2. Whether you are using Oracle Java or IBM Java, you must use unlimited JCE. Without unlimitedJCE, the JBoss server cannot negotiate on the proper SPNEGO mechanism type (using1.3.6.1.5.2.5, which is GSS_IAKERB_MECHANISM).

3. Use the example below to configure JBoss to use your desired Java version.

Procedure 11.4. Test your Kerberos setup using JBoss Negotiation Toolkit

1. Use the JBoss Negotiation Toolkit available at Github

2. Modify the configuration files and use the mvn clean install command to build the project.

3. Copy the file jboss-negotiation-toolkit/target/jboss-negotiation-toolkit.war to $JBOSS_HOME/standalone/deployments/.

4. Verify that all the three sections pass through the JBoss Negotiation Toolkit.

Procedure 11.5. Set up PicketLink IDP

Changes to idp.war

The example provided uses the idp.war and employee.war archives, which can be located in thePicketLink Quickstarts repository. Modify the files in idp.war as described below.

1. Add org.jboss.security.negotiation module to $JBOSS_HOME/standalone/deployments/idp.war/META-INF/jboss-deployment-structure.xml because IDP is using the JBoss Negotiation module.

<module-option name="principal">HTTP/{hostname}@{realm}</module-option>

export JAVA_HOME=JDK/JRE_directory

<jboss-deployment-structure> <deployment>

Security Guide

174

2. Add an additional valve org.jboss.security.negotiation.NegotiationAuthenticator for SPNEGO to $JBOSS_HOME/standalone/deployments/idp.war/WEB-INF/jboss-web.xml.

3. Change security-domain from idp to SPNEGO in $JBOSS_HOME/standalone/deployments/idp.war/WEB-INF/jboss-web.xml asfollows:

4. Add or change the security-role added to your principal by Kerberos server setup to $JBOSS_HOME/standalone/deployments/idp.war/WEB-INF/web.xml.

5. Modify the file $JBOSS_HOME/standalone/deployments/idp.war/WEB-INF/picketlink.xml as follows:

<!-- Add picketlink module dependency --> <dependencies> <module name="org.picketlink" /> <module name="org.jboss.security.negotiation" /> </dependencies> </deployment> </jboss-deployment-structure>

<jboss-web> <security-domain>SPNEGO</security-domain> <context-root>idp</context-root> <valve> <class-name>org.picketlink.identity.federation.bindings.tomcat.idp.IDPWebBrowserSSOValve</class-name> <param> <param-name>passUserPrincipalToAttributeManager</param-name> <param-value>true</param-value> </param> </valve> <valve> <class-name>org.jboss.security.negotiation.NegotiationAuthenticator</class-name> </valve></jboss-web>

<PicketLink xmlns="urn:picketlink:identity-federation:config:2.1"> <PicketLinkIDP xmlns="urn:picketlink:identity-federation:config:2.1"> <IdentityURL>${idp.url::http://localhost:8080/idp/}</IdentityURL> <Trust> <Domains>redhat.com,localhost,amazonaws.com</Domains> </Trust> </PicketLinkIDP> <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1"> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler" />

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

175

6. Change IdentityURL to match the host name of server you are running IDP on.

7. Change Trust to contain the domain names trusted by the Identity Provider.

8. Modify the employee.war. Add or change security-roles added to your principal by Kerberosserver setup to $JBOSS_HOME/standalone/deployments/employee.war/WEB-INF/web.xml.

9. Modify the security domain configuration in the file $JBOSS_HOME/standalone/configuration/standalone.xml. Role mappingconfiguration is the same as that in normal security domain configurations.

<Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" /> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" /> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" /> </Handlers> <!-- The configuration bellow defines a token timeout and a clock skew. Both configurations will be used during the SAML Assertion creation. This configuration is optional. It is defined only to show you how to set the token timeout and clock skew configuration. --> <PicketLinkSTS xmlns="urn:picketlink:identity-federation:config:1.0" TokenTimeout="5000" ClockSkew="0"> <TokenProviders> <TokenProvider ProviderClass="org.picketlink.identity.federation.core.saml.v1.providers.SAML11AssertionTokenProvider" TokenType="urn:oasis:names:tc:SAML:1.0:assertion" TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:1.0:assertion" /> <TokenProvider ProviderClass="org.picketlink.identity.federation.core.saml.v2.providers.SAML20AssertionTokenProvider" TokenType="urn:oasis:names:tc:SAML:2.0:assertion" TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:2.0:assertion" /> </TokenProviders> </PicketLinkSTS></PicketLink>

<security-domain name="host" cache-type="default"> <authentication> <login-module code="Kerberos" flag="required"> <module-option name="principal" value="HTTP/something.com@yourdomain.COM"/> <module-option name="storeKey" value="true"/> <module-option name="useKeyTab" value="true"/> <module-option name="doNotPrompt" value="true"/>

Security Guide

176

NOTE

In case of using IBM JDK, options for Kerberos module are different. You must set thesystem property jboss.security.disable.secdomain.option to true. Refer toSection 11.2.2, “Configure Authentication in a Security Domain” for details. Update thelogin module to the following:

Procedure 11.6. Verify Kerberos authentication setup for PicketLink IDP

1. Start JBoss EAP server using $JBOSS_HOME/bin/standalone.sh.

2. Setup your Kerberos system. There are a number of ways to do so. For example, using one ofthe following options:

FreeIPA: there are multiple configuration options. You must choose the one that is suitableto your setup.

ApacheDS

3. Setup your browser, for example Firefox, to use Kerberos. Follow the instructions provided here:https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/5/html/Deployment_Guide/sso-config-firefox.html

<module-option name="keyTab" value="/root/keytab"/> </login-module> </authentication> </security-domain> <security-domain name="SPNEGO" cache-type="default"> <authentication> <login-module code="SPNEGO" flag="required"> <module-option name="serverSecurityDomain" value="host"/> </login-module> </authentication></security-domain> <security-domain name="sp" cache-type="default"> <authentication> <login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required" /> </authentication> </security-domain>

<login-module code="Kerberos" flag="required"> <module-option name="principal" value="HTTP/something.com@yourdomain.COM"/> <module-option name="credsType" value="acceptor"/> <module-option name="useKeytab" value="file:///root/keytab"/></login-module>

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

177

4. Verify that you are able to access the http://YOUR_DOMAIN:8080/employee from Firefoxconfigured as mentioned above.

Report a bug

11.1.5. Login with Certificate with PicketLink IDP

Configure IDP to Support SSL

You can configure the PicketLink IDP to support SSL. The following procedure is an exampledemonstrating how to configure a web application as an IDP supporting SSL client authentication. Thereare two ways to configure the IDP to authenticate users:

If SSL is being used, the server will ask the client for a certificate and use this certificate toauthenticate the user.

If no certificate is provided by the client, a form-based authentication is performed.

Report a bug

11.1.5.1. JBoss EAP 6 SSL Configuration

The first thing you must do is create the certificates - the keystore and truststore that will be used duringthe entire configuration procedure.

Procedure 11.7. Create the certificate, keystore, and truststore for your server

1. Create a Certificate for Your ServerUse the following command to create a certificate for your server:

The system prompts you for additional information. You must provide the values as required.The CN name of the certificate must be the same as your DNS server name. For example, incase of localhost you could use the following command:

2. Create the Client CertificateYou will use this client certificate to authenticate against the server when accessing a resourcethrough SSL.

3. Create the TruststoreExport the client's certificate and create a truststore by importing this certificate:

keytool -genkey -alias server -keyalg RSA -keystore server.keystore -storepass change_it -validity 365

keytool -genkey -alias server -keystore server.keystore -storepass change_it -keypass password -dname"CN=localhost,OU=QE,O=example.com,L=Brno,C=CZ"

keytool -genkey -alias client -keystore client.keystore -storepass change_it -validity 365 -keyalg RSA -keysize 2048 -storetype pkcs12

keytool -exportcert -keystore client.keystore -storetype pkcs12 -storepass change_it -alias client -keypass change_it -file client.keystorekeytool -import -file client.keystore -alias client -keystore

Security Guide

178

4. Change the JBoss EAP 6 Server Installation to Enable SSLAdd the following connector to the web subsystem to enable SSL:

5. Restart the ServerRestart the server and verify that it is responding on: https://localhost:8443

6. Trust the CertificateYou will be prompted to trust the server certificate.

Configure the Client Certificate in your Browser

Before accessing the application, you must import the client.keystore to your browser. This fileholds the client certificate. When you access the application, the browser prompts you to select thecertificate you need to use to authenticate with the server. Select the desired certificate.

Security Domain Configuration

Add the following security domain to your server installation. If you're in standalone mode, you must addit to the JBOSS_HOME/standalone/configuration/standalone.xml:

client.truststore

<connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" enable-lookups="false" secure="true"> <ssl name="localhost-ssl" key-alias="server" password="change_it" certificate-key-file="${jboss.server.config.dir}/server.keystore" protocol="TLSv1" verify-client="want" ca-certificate-file="${jboss.server.config.dir}/client.truststore"/></connector>

<security-domain name="idp" cache-type="default"> <authentication> <login-module code="CertificateRoles" flag="optional"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="securityDomain" value="idp"/> <module-option name="verifier" value="org.jboss.security.auth.certs.AnyCertVerifier"/> </login-module> <login-module code="org.picketlink.identity.federation.bindings.jboss.auth.RegExUserNameLoginModule" flag="optional"> <module-option name="regex" value="CN=(.*?),"/> </login-module> <login-module code="UsersRoles" flag="required"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="usersProperties" value="users.properties"/> <module-option name="rolesProperties" value="roles.properties"/> </login-module> </authentication>

<jsse keystore-password="change_it" keystore-url="${jboss.server.config.dir}" truststore-password="change_it"

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

179

The configuration example above validates any provided certificate. If no certificate is provided or if theauthentication fails, the procedure falls back to a user/password based authentication.

Regular Expression User Name Login Module

The Regular Expression User Name Login module can be used after Certificate Login Modules to extracta username, UID or other field from the principal name so that roles can be obtained from LDAP. Themodule has an option named regex which specifies the regular expression to be applied to the principalname, the result of which is passed on to the subsequent login module.

In this example, an input principal name of UID=007, EMAILADDRESS=something@something, CN=James Bond, O=SpyAgency would result in the output UID=007.

Example 11.5. Example of Regular Expression User Name Login Module

For further details about regular expressions, see java.util.regex.Pattern class documentationat http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html.

Report a bug

11.2. AUTHENTICATION

11.2.1. About Authentication

Authentication refers to identifying a subject and verifying the authenticity of the identification. The mostcommon authentication mechanism is a username and password combination. Other commonauthentication mechanisms use shared keys, smart cards, or fingerprints. The outcome of a successfulauthentication is referred to as a principal, in terms of Java Enterprise Edition declarative security.

JBoss EAP 6 uses a pluggable system of authentication modules to provide flexibility and integrationwith the authentication systems you already use in your organization. Each security domain may containone or more configured authentication modules. Each module includes additional configurationparameters to customize its behavior. The easiest way to configure the authentication subsystem iswithin the web-based management console.

Authentication is not the same as authorization, although they are often linked. Many of the includedauthentication modules can also handle authorization.

Report a bug

truststore-url="${jboss.server.config.dir}" client-auth="true"/></security-domain>

<login-module code="org.picketlink.identity.federation.bindings.jboss.auth.RegExUserNameLoginModule" flag="required"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="regex" value="UID=(.*?),"/></login-module>

Security Guide

180

11.2.2. Configure Authentication in a Security Domain

To configure authentication settings for a security domain, log into the management console and followthis procedure.

Procedure 11.8. Setup Authentication Settings for a Security Domain

1. Open the security domain's detailed view.

a. Click the Configuration label at the top of the management console.

b. Select the profile to modify from the Profile selection box at the top left of the Profile view.

c. Expand the Security menu, and select Security Domains.

d. Click the View link for the security domain you want to edit.

2. Navigate to the Authentication subsystem configuration.Select the Authentication label at the top of the view if it is not already selected.

The configuration area is divided into two areas: Login Modules and Details. The loginmodule is the basic unit of configuration. A security domain can include several login modules,each of which can include several attributes and options.

3. Add an authentication module.Click Add to add a JAAS authentication module. Fill in the details for your module.

The Code is the class name of the module. The Flag setting controls how the module relates toother authentication modules within the same security domain.

Explanation of the Flags

The Java Enterprise Edition 6 specification provides the following explanation of the flags forsecurity modules. The following list is taken fromhttp://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html#AppendixARefer to that document for more detailed information.

Flag Details

required The LoginModule is required to succeed. If itsucceeds or fails, authentication still continues toproceed down the LoginModule list.

requisite LoginModule is required to succeed. If itsucceeds, authentication continues down theLoginModule list. If it fails, control immediatelyreturns to the application (authentication doesnot proceed down the LoginModule list).

sufficient The LoginModule is not required to succeed. If itdoes succeed, control immediately returns to theapplication (authentication does not proceeddown the LoginModule list). If it fails,authentication continues down the LoginModulelist.

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

181

optional The LoginModule is not required to succeed. If itsucceeds or fails, authentication still continues toproceed down the LoginModule list.

Flag Details

4. Edit authentication settingsAfter you have added your module, you can modify its Code or Flags by clicking Edit in the Details section of the screen. Be sure the Attributes tab is selected.

5. Optional: Add or remove module options.If you need to add options to your module, click its entry in the Login Modules list, and selectthe Module Options tab in the Details section of the page. Click the Add button, andprovide the key and value for the option. Use the Remove button to remove an option.

Result

Your authentication module is added to the security domain, and is immediately available to applicationswhich use the security domain.

The jboss.security.security_domain Module Option

By default, each login module defined in a security domain has the jboss.security.security_domain module option added to it automatically. This option causesproblems with login modules which check to make sure that only known options are defined. The IBMKerberos login module, com.ibm.security.auth.module.Krb5LoginModule is one of these.

You can disable the behavior of adding this module option by setting the system property to true whenstarting JBoss EAP 6. Add the following to your start-up parameters.

-Djboss.security.disable.secdomain.option=true

You can also set this property using the web-based Management Console. In a standalone server, youcan set system properties in the Profile section of the configuration. In a managed domain, you canset system properties for each server group.

Report a bug

11.3. JAAS - JAVA AUTHENTICATION AND AUTHORIZATION SERVICE

11.3.1. About JAAS

JAAS is the Java Authentication and Authorization Service. It is part of the Java EE Spec, and allows forpluggable authentication and authorization to abstract applications from security providers.

The JAAS 1.0 API consists of a set of Java packages designed for user authentication and authorization.The API implements a Java version of the standard Pluggable Authentication Modules (PAM) frameworkand extends the Java 2 Platform access control architecture to support user-based authorization.

JAAS authentication is performed in a pluggable fashion. This permits Java applications to remainindependent from underlying authentication technologies, and allows the security manager to work indifferent security infrastructures. Integration with a security infrastructure is achievable without changingthe security manager implementation. You need only change the configuration of the authentication stackJAAS uses.

Security Guide

182

Refer to the Java EE JAAS Documentation for further information on JAAS.

The JBoss Enterprise Application Platform 6 security subsystem is based on the JAAS API.

Report a bug

11.3.2. JAAS Core Classes

The JAAS core classes can be broken down into three categories: common, authentication, andauthorization. The following list presents only the common and authentication classes because these arethe specific classes used to implement the functionality of the EAP security subsystem covered in thischapter.

These are the common classes:

Subject (javax.security.auth.Subject)

These are the authentication classes:

Configuration (javax.security.auth.login.Configuration)

LoginContext (javax.security.auth.login.LoginContext)

These are the associated interfaces:

Principal (java.security.Principal)

Callback (javax.security.auth.callback.Callback)

CallbackHandler (javax.security.auth.callback.CallbackHandler)

LoginModule (javax.security.auth.spi.LoginModule)

Report a bug

11.3.3. Subject and Principal classes

To authorize access to resources, applications must first authenticate the request's source. The JAASframework defines the term subject to represent a request's source. The Subject class is the centralclass in JAAS. A Subject represents information for a single entity, such as a person or service. Itencompasses the entity's principals, public credentials, and private credentials. The JAAS API uses theexisting Java 2 java.security.Principal interface to represent a principal, which is essentially atyped name.

During the authentication process, a subject is populated with associated identities, or principals. Asubject may have many principals. For example, a person may have a name principal (John Doe), asocial security number principal (123-45-6789), and a user name principal (johnd), all of which helpdistinguish the subject from other subjects. To retrieve the principals associated with a subject, twomethods are available:

public Set getPrincipals() {...}public Set getPrincipals(Class c) {...}

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

183

getPrincipals() returns all principals contained in the subject. getPrincipals(Class c) returnsonly those principals that are instances of class c or one of its subclasses. An empty set is returned if thesubject has no matching principals.

Note that the java.security.acl.Group interface is a sub-interface of java.security.Principal, so an instance in the principals set may represent a logical grouping ofother principals or groups of principals.

Report a bug

11.3.4. Subject Authentication

Subject Authentication requires a JAAS login. For a description of the JAAS Login Configuration file,refer to JAAS Login Configuration File in the Java documentation.

The login process consists of the following points:

1. An application instantiates a LoginContext and passes in the name of the login configurationand a CallbackHandler to populate the Callback objects, as required by the configuration LoginModules.

2. The LoginContext consults a Configuration to load all the LoginModules included in thenamed login configuration. If no such named configuration exists the other configuration isused as a default.

3. The application invokes the LoginContext.login method.

4. The login method invokes each loaded LoginModule. As each LoginModule attempts toauthenticate the subject, it invokes the handle method on the associated CallbackHandler toobtain the information required for the authentication process. The required information is passedto the handle method in the form of an array of Callback objects. Upon success, the LoginModules associate relevant principals and credentials with the subject.

5. The LoginContext returns the authentication status to the application. Success is representedby a return from the login method. Failure is represented through a LoginException being thrownby the login method.

6. If authentication succeeds, the application retrieves the authenticated subject using the LoginContext.getSubject method.

7. After the scope of the subject authentication is complete, all principals and related informationassociated with the subject by the login method can be removed by invoking the LoginContext.logout method.

The LoginContext class provides the basic methods for authenticating subjects and offers a way todevelop an application that is independent of the underlying authentication technology. The LoginContext consults a Configuration to determine the authentication services configured for aparticular application. LoginModule classes represent the authentication services. Therefore, you canplug different login modules into an application without changing the application itself. The followingcode shows the steps required by an application to authenticate a subject.

CallbackHandler handler = new MyHandler();LoginContext lc = new LoginContext("some-config", handler);

try {

Security Guide

184

Developers integrate with an authentication technology by creating an implementation of the LoginModule interface. This allows an administrator to plug different authentication technologies intoan application. You can chain together multiple LoginModules to allow for more than one authenticationtechnology to participate in the authentication process. For example, one LoginModule may performuser name/password-based authentication, while another may interface to hardware devices such assmart card readers or biometric authenticators.

The life cycle of a LoginModule is driven by the LoginContext object against which the client createsand issues the login method. The process consists of two phases. The steps of the process are asfollows:

The LoginContext creates each configured LoginModule using its public no-arg constructor.

Each LoginModule is initialized with a call to its initialize method. The Subject argument isguaranteed to be non-null. The signature of the initialize method is: public void

lc.login(); Subject subject = lc.getSubject();} catch(LoginException e) { System.out.println("authentication failed"); e.printStackTrace();} // Perform work as authenticated Subject// ...

// Scope of work complete, logout to remove authentication infotry { lc.logout();} catch(LoginException e) { System.out.println("logout failed"); e.printStackTrace();} // A sample MyHandler classclass MyHandler implements CallbackHandler{ public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException { for (int i = 0; i < callbacks.length; i++) { if (callbacks[i] instanceof NameCallback) { NameCallback nc = (NameCallback)callbacks[i]; nc.setName(username); } else if (callbacks[i] instanceof PasswordCallback) { PasswordCallback pc = (PasswordCallback)callbacks[i]; pc.setPassword(password); } else { throw new UnsupportedCallbackException(callbacks[i], "Unrecognized Callback"); } } }}

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

185

initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options)

The login method is called to start the authentication process. For example, a methodimplementation might prompt the user for a user name and password and then verify theinformation against data stored in a naming service such as NIS or LDAP. Alternativeimplementations might interface to smart cards and biometric devices, or simply extract userinformation from the underlying operating system. The validation of user identity by each LoginModule is considered phase 1 of JAAS authentication. The signature of the loginmethod is boolean login() throws LoginException . A LoginException indicatesfailure. A return value of true indicates that the method succeeded, whereas a return value offalse indicates that the login module should be ignored.

If the LoginContext's overall authentication succeeds, commit is invoked on each LoginModule. If phase 1 succeeds for a LoginModule, then the commit method continueswith phase 2 and associates the relevant principals, public credentials, and/or private credentialswith the subject. If phase 1 fails for a LoginModule, then commit removes any previouslystored authentication state, such as user names or passwords. The signature of the commitmethod is: boolean commit() throws LoginException . Failure to complete the commitphase is indicated by throwing a LoginException. A return of true indicates that the methodsucceeded, whereas a return of false indicates that the login module should be ignored.

If the LoginContext's overall authentication fails, then the abort method is invoked on each LoginModule. The abort method removes or destroys any authentication state created by thelogin or initialize methods. The signature of the abort method is boolean abort() throws LoginException . Failure to complete the abort phase is indicated by throwing a LoginException. A return of true indicates that the method succeeded, whereas a return offalse indicates that the login module should be ignored.

To remove the authentication state after a successful login, the application invokes logout onthe LoginContext. This in turn results in a logout method invocation on each LoginModule. The logout method removes the principals and credentials originallyassociated with the subject during the commit operation. Credentials should be destroyed uponremoval. The signature of the logout method is: boolean logout() throws LoginException . Failure to complete the logout process is indicated by throwing a LoginException. A return of true indicates that the method succeeded, whereas a return offalse indicates that the login module should be ignored.

When a LoginModule must communicate with the user to obtain authentication information, it uses a CallbackHandler object. Applications implement the CallbackHandler interface and pass it to the LoginContext, which send the authentication information directly to the underlying login modules.

Login modules use the CallbackHandler both to gather input from users, such as a password orsmart card PIN, and to supply information to users, such as status information. By allowing theapplication to specify the CallbackHandler, underlying LoginModules remain independent from thedifferent ways applications interact with users. For example, a CallbackHandler's implementation fora GUI application might display a window to solicit user input. On the other hand, a CallbackHandlerimplementation for a non-GUI environment, such as an application server, might simply obtain credentialinformation by using an application server API. The CallbackHandler interface has one method toimplement:

void handle(Callback[] callbacks) throws java.io.IOException, UnsupportedCallbackException;

Security Guide

186

The Callback interface is the last authentication class we will look at. This is a tagging interface forwhich several default implementations are provided, including the NameCallback and PasswordCallback used in an earlier example. A LoginModule uses a Callback to requestinformation required by the authentication mechanism. LoginModules pass an array of Callbacksdirectly to the CallbackHandler.handle method during the authentication's login phase. If a callbackhandler does not understand how to use a Callback object passed into the handlemethod, it throws an UnsupportedCallbackException to abort the login call.

Report a bug

11.4. JAVA AUTHENTICATION SPI FOR CONTAINERS (JASPI)

11.4.1. About Java Authentication SPI for Containers (JASPI) Security

Java Authentication SPI for Containers (JASPI or JASPIC) is a pluggable interface for Java applications.It is defined in JSR-196 of the Java Community Process. Refer to http://www.jcp.org/en/jsr/detail?id=196for details about the specification.

Report a bug

11.4.2. Configure Java Authentication SPI for Containers (JASPI) Security

To authenticate against a JASPI provider, add a <authentication-jaspi> element to your securitydomain. The configuration is similar to a standard authentication module, but login module elements areenclosed in a <login-module-stack> element. The structure of the configuration is:

Example 11.6. Structure of the authentication-jaspi element

The login module itself is configured in exactly the same way as a standard authentication module.

Because the web-based management console does not expose the configuration of JASPIauthentication modules, you need to stop JBoss EAP 6 completely before adding the configurationdirectly to EAP_HOME/domain/configuration/domain.xml or EAP_HOME/standalone/configuration/standalone.xml.

Report a bug

11.5. AUTHORIZATION

<authentication-jaspi> <login-module-stack name="..."> <login-module code="..." flag="..."> <module-option name="..." value="..."/> </login-module> </login-module-stack> <auth-module code="..." login-module-stack-ref="..."> <module-option name="..." value="..."/> </auth-module></authentication-jaspi>

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

187

11.5.1. About Authorization

Authorization is a mechanism for granting or denying access to a resource based on identity. It isimplemented as a set of declarative security roles which can be added to principals.

JBoss EAP 6 uses a modular system to configure authorization. Each security domain may contain oneor more authorization policies. Each policy has a basic module which defines its behavior. It is configuredthrough specific flags and attributes. The easiest way to configure the authorization subsystem is byusing the web-based management console.

Authorization is different from authentication, and usually happens after authentication. Many of theauthentication modules also handle authorization.

Report a bug

11.5.2. Configure Authorization in a Security Domain

To configure authorization settings for a security domain, log into the management console and followthis procedure.

Procedure 11.9. Setup Authorization in a Security Domain

1. Open the security domain's detailed view.

a. Click the Configuration label at the top of the management console.

b. In a managed domain, select the profile to modify from the Profile drop down box at thetop left.

c. Expand the Security menu item, and select Security Domains.

d. Click the View link for the security domain you want to edit.

2. Navigate to the Authorization subsystem configuration.Select the Authorization label at the top of the screen.

The configuration area is divided into two areas: Policies and Details. The login module isthe basic unit of configuration. A security domain can include several authorization policies, eachof which can include several attributes and options.

3. Add a policy.Click Add to add a JAAS authorization policy module. Fill in the details for your module.

The Code is the class name of the module. The Flag controls how the module relates to otherauthorization policy modules within the same security domain.

Explanation of the Flags

The Java Enterprise Edition 6 specification provides the following explanation of the flags forsecurity modules. The following list is taken fromhttp://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html#AppendixARefer to that document for more detailed information.

Security Guide

188

Flag Details

required The LoginModule is required to succeed. If itsucceeds or fails, authorization still continues toproceed down the LoginModule list.

requisite LoginModule is required to succeed. If itsucceeds, authorization continues down theLoginModule list. If it fails, control immediatelyreturns to the application (authorization does notproceed down the LoginModule list).

sufficient The LoginModule is not required to succeed. If itdoes succeed, control immediately returns to theapplication (authorization does not proceeddown the LoginModule list). If it fails,authorization continues down the LoginModulelist.

optional The LoginModule is not required to succeed. If itsucceeds or fails, authorization still continues toproceed down the LoginModule list.

4. Edit authorization settingsAfter you have added your module, you can modify its Code or Flags by clicking Edit in the Details section of the screen. Be sure the Attributes tab is selected.

5. Optional: Add or remove module options.If you need to add options to your module, click its entry in the Policies list, and select the Module Options tab in the Details section of the page. Click Add and provide the key andvalue for the option. Use the Remove button to remove an option.

Result

Your authorization policy module is added to the security domain, and is immediately available toapplications which use the security domain.

Report a bug

11.6. JAVA AUTHORIZATION CONTRACT FOR CONTAINERS (JACC)

11.6.1. About Java Authorization Contract for Containers (JACC)

Java Authorization Contract for Containers (JACC) is a standard which defines a contract betweencontainers and authorization service providers, which results in the implementation of providers for useby containers. It was defined in JSR-115, which can be found on the Java Community Process websiteat http://jcp.org/en/jsr/detail?id=115. It has been part of the core Java Enterprise Edition (Java EE)specification since Java EE version 1.3.

JBoss EAP 6 implements support for JACC within the security functionality of the security subsystem.

Report a bug

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

189

11.6.2. Configure Java Authorization Contract for Containers (JACC) Security

To configure Java Authorization Contract for Containers (JACC), you need to configure your securitydomain with the correct module, and then modify your jboss-web.xml to include the correctparameters.

Add JACC Support to the Security Domain

To add JACC support to the security domain, add the JACC authorization policy to the authorization stackof the security domain, with the required flag set. The following is an example of a security domainwith JACC support. However, the security domain is configured in the Management Console orManagement CLI, rather than directly in the XML.

Configure a Web Application to Use JACC

The jboss-web.xml is located in the WEB-INF/ directory of your deployment, and contains overridesand additional JBoss-specific configuration for the web container. To use your JACC-enabled securitydomain, you need to include the <security-domain> element, and also set the <use-jboss-authorization> element to true. The following application is properly configured to use the JACCsecurity domain above.

Configure an EJB Application to Use JACC

Configuring EJBs to use a security domain and to use JACC differs from Web Applications. For an EJB,you can declare method permissions on a method or group of methods, in the ejb-jar.xml descriptor.Within the <ejb-jar> element, any child <method-permission> elements contain information aboutJACC roles. Refer to the example configuration for more details. The EJBMethodPermission class ispart of the Java Enterprise Edition 6 API, and is documented athttp://docs.oracle.com/javaee/6/api/javax/security/jacc/EJBMethodPermission.html.

Example 11.7. Example JACC Method Permissions in an EJB

<security-domain name="jacc" cache-type="default"> <authentication> <login-module code="UsersRoles" flag="required"> </login-module> </authentication> <authorization> <policy-module code="JACC" flag="required"/> </authorization></security-domain>

<jboss-web> <security-domain>jacc</security-domain> <use-jboss-authorization>true</use-jboss-authorization></jboss-web>

<ejb-jar> <assembly-descriptor> <method-permission> <description>The employee and temp-employee roles may access any method of the EmployeeService bean </description> <role-name>employee</role-name> <role-name>temp-employee</role-name>

Security Guide

190

You can also constrain the authentication and authorization mechanisms for an EJB by using a securitydomain, just as you can do for a web application. Security domains are declared in the jboss-ejb3.xml descriptor, in the <security> child element. In addition to the security domain, you can alsospecify the <run-as-principal>, which changes the principal the EJB runs as.

Example 11.8. Example Security Domain Declaration in an EJB

Report a bug

11.6.3. Fine Grained Authorization Using XACML

11.6.3.1. About Fine Grained Authorization and XACML

Fine Grained Authorization caters to the changing requirements and multiple variables involved in thedecision making process, which becomes the basis of providing authorization for accessing a module.Hence, the process of Fine Grained Authorization is complex in itself.

JBoss uses XACML as a medium to achieve Fine Grained Authorization. XACML provides standardsbased solution to the complex nature of achieving Fine Grained Authorization. XACML defines a policylanguage and an architecture for decision making. The XACML architecture includes a PolicyEnforcement Point (PEP), which intercepts any requests in a normal program flow, then asks a PolicyDecision Point (PDP) to make an access decision based on the policies associated with the PDP. ThePDP evaluates the XACML request created by the PEP and runs through the policies to make one of thefollowing access decisions:

PERMIT - The access is approved.

DENY - The access is denied.

INDETERMINATE - There is an error at the PDP.

NOTAPPLICABLE - There is some attribute missing in the request or there is no policy match.

<method> <ejb-name>EmployeeService</ejb-name> <method-name>*</method-name> </method> </method-permission> </assembly-descriptor></ejb-jar>

<ejb-jar> <assembly-descriptor> <security> <ejb-name>*</ejb-name> <security-domain>myDomain</security-domain> <run-as-principal>myPrincipal</run-as-principal> </security> </assembly-descriptor></ejb-jar>

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

191

The following are the features of the XACML:

Oasis XACML v2.0 library

JAXB v2.0 based object model

ExistDB Integration for storing/retrieving XACML Policies and Attributes

Report a bug

11.6.3.2. Configure XACML for Fine Grained Authorization

The following is the procedure to configure XACML.

Procedure 11.10. Configure XACML

1. Download the library which is a single jar file.

2. Create one or more policy files for XACML

Under the WEB-INF/classes, create a policies directory to save all your policies.

Create a policyConfig.xml under WEB-INF/classes directory.

The following are the two types of policy sets can be defined:

Role Permission Policy Sets (RPS)

Permission Policy Sets (PPS)

Example 11.9. Role Permission Policy Sets (RPS)

Employee

<PolicySet xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" PolicySetId="RPS:employee:role" PolicyCombiningAlgId="urn:oasis:names:tc:xacml:1.0:policy-combining-algorithm:permit-overrides"> <Target> <Subjects> <Subject> <SubjectMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:anyURI-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">employee</AttributeValue> <SubjectAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI"/> </SubjectMatch> </Subject> </Subjects> </Target> <!-- Use permissions associated with the employee role -->

Security Guide

192

Manager

Example 11.10. Permission Policy Sets (PPS)

Employee

<PolicySetIdReference>PPS:employee:role</PolicySetIdReference> </PolicySet>

<PolicySet xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" PolicySetId="RPS:manager:role" PolicyCombiningAlgId="urn:oasis:names:tc:xacml:1.0:policy-combining-algorithm:permit-overrides"> <Target> <Subjects> <Subject> <SubjectMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:anyURI-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">manager</AttributeValue> <SubjectAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI"/> </SubjectMatch> </Subject> </Subjects> </Target> <!-- Use permissions associated with the manager role --> <PolicySetIdReference>PPS:manager:role</PolicySetIdReference> </PolicySet>

<PolicySet xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" PolicySetId="PPS:employee:role" PolicyCombiningAlgId="urn:oasis:names:tc:xacml:1.0:policy-combining-algorithm:permit-overrides"> <Target /> <!-- Permissions specifically for the employee role --> <Policy PolicyId="Permissions:specifically:for:the:employee:role" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:permit-overrides"> <Target /> <!-- Permission to create a purchase order --> <Rule RuleId="Permission:to:create:a:purchase:order" Effect="Permit"> <Target> <Resources> <Resource>

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

193

<ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">purchase order </AttributeValue> <ResourceAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" DataType="http://www.w3.org/2001/XMLSchema#string" /> </ResourceMatch> </Resource> </Resources> <Actions> <Action> <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">create</AttributeValue> <ActionAttributeDesignator AttributeId="urn:action-id" DataType="http://www.w3.org/2001/XMLSchema#string" /> </ActionMatch> </Action> </Actions> </Target> </Rule> </Policy> <!-- HasPrivilegesOfRole Policy for employee role --> <Policy PolicyId="Permission:to:have:employee:role:permissions" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:permit-overrides"> <Target /> <!-- Permission to have employee role permissions --> <Rule RuleId="Permission:to:have:employee:permissions" Effect="Permit"> <Condition> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:and"> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:anyURI-is-in"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">employee</AttributeValue> <ResourceAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI" /> </Apply> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:anyURI-is-in"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">urn:oasis:names

Security Guide

194

Manager

:tc:xacml:2.0:actions:hasPrivilegesOfRole </AttributeValue> <ActionAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#anyURI" /> </Apply> </Apply> </Condition> </Rule> </Policy> </PolicySet>

<PolicySet xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" PolicySetId="PPS:manager:role" PolicyCombiningAlgId="urn:oasis:names:tc:xacml:1.0:policy-combining-algorithm:permit-overrides"> <Target /> <!-- Permissions specifically for the manager role --> <Policy PolicyId="Permissions:specifically:for:the:manager:role" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:permit-overrides"> <Target /> <!-- Permission to sign a purchase order --> <Rule RuleId="Permission:to:sign:a:purchase:order" Effect="Permit"> <Target> <Resources> <Resource> <ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">purchase order </AttributeValue> <ResourceAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" DataType="http://www.w3.org/2001/XMLSchema#string" /> </ResourceMatch> </Resource> </Resources> <Actions> <Action> <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">sign</AttributeValue> <ActionAttributeDesignator

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

195

3. Create a configuration file for the XACML engine.A configuration file is created to configure the locators and mention the directories where thepolicies are saved.

AttributeId="urn:action-id" DataType="http://www.w3.org/2001/XMLSchema#string" /> </ActionMatch> </Action> </Actions> </Target> </Rule> </Policy> <!-- HasPrivilegesOfRole Policy for manager role --> <Policy PolicyId="Permission:to:have:manager:role:permissions" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:permit-overrides"> <Target /> <!-- Permission to have manager role permissions --> <Rule RuleId="Permission:to:have:manager:permissions" Effect="Permit"> <Condition> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:and"> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:anyURI-is-in"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">manager</AttributeValue> <ResourceAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI" /> </Apply> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:anyURI-is-in"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">urn:oasis:names:tc:xacml:2.0:actions:hasPrivilegesOfRole </AttributeValue> <ActionAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#anyURI" /> </Apply> </Apply> </Condition> </Rule> </Policy> <!-- Include permissions associated with employee role --> <PolicySetIdReference>PPS:employee:role</PolicySetIdReference> </PolicySet>

Security Guide

196

Example 11.11. Configuration File

Configuration File Only Indicating The Directory Of The Policy Files.

Configuration File Defining the Policy Set

4. Create a Policy Decision Point (PDP) and pass it in the Configuration File.

5. In the Policy Enforcement Point (PEP), create an XACML request based on the context. Pass theXACML request to the PDP to get one of the following access decisions:

Permit

<ns:jbosspdp xmlns:ns="urn:jboss:xacml:2.0"> <ns:Policies> <ns:PolicySet> <ns:Location>test/policies/rbac/</ns:Location> </ns:PolicySet> </ns:Policies> <ns:Locators> <ns:Locator Name="org.jboss.security.xacml.locators.JBossRBACPolicySetLocator"/> </ns:Locators> </ns:jbosspdp>

<ns:jbosspdp xmlns:ns="urn:jboss:xacml:2.0"> <ns:Policies> <ns:PolicySet> <ns:Location>test/policies/rbac/employee-PPS-policyset.xml</ns:Location> </ns:PolicySet> <ns:PolicySet> <ns:Location>test/policies/rbac/manager-PPS-policyset.xml</ns:Location> </ns:PolicySet> <ns:PolicySet> <ns:Location>test/policies/rbac/employee-RPS-policyset.xml</ns:Location> </ns:PolicySet> <ns:PolicySet> <ns:Location>test/policies/rbac/manager-RPS-policyset.xml</ns:Location> </ns:PolicySet> </ns:Policies> <ns:Locators> <ns:Locator Name="org.jboss.security.xacml.locators.JBossRBACPolicySetLocator"/> </ns:Locators> </ns:jbosspdp>

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

197

Deny

Indeterminate

Not Applicable

Example 11.12. Access Decisions

Permit condition

Deny Permission

<Request xmlns="urn:oasis:names:tc:xacml:2.0:context:schema:os" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:xacml:2.0:context:schema:os

access_control-xacml-2.0-context-schema-os.xsd"> <Subject> <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" DataType="http://www.w3.org/2001/XMLSchema#string"> <AttributeValue>Anne</AttributeValue> </Attribute> <Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI"> <AttributeValue>manager</AttributeValue> </Attribute> </Subject> <Resource> <Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI"> <AttributeValue>manager</AttributeValue> </Attribute> </Resource> <Action> <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#anyURI"> <AttributeValue>urn:oasis:names:tc:xacml:2.0:actions:hasPrivilegesOfRole</AttributeValue> </Attribute> </Action> </Request>

<Request xmlns="urn:oasis:names:tc:xacml:2.0:context:schema:os"

Security Guide

198

Report a bug

11.7. SECURITY AUDITING

11.7.1. About Security Auditing

Security auditing refers to triggering events, such as writing to a log, in response to an event thathappens within the security subsystem. Auditing mechanisms are configured as part of a securitydomain, along with authentication, authorization, and security mapping details.

Auditing uses provider modules. You can use one of the included ones, or implement your own.

Report a bug

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:xacml:2.0:context:schema:os

access_control-xacml-2.0-context-schema-os.xsd"> <Subject> <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" DataType="http://www.w3.org/2001/XMLSchema#string"> <AttributeValue>Anne</AttributeValue> </Attribute> <Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI"> <AttributeValue>manager</AttributeValue> </Attribute> </Subject> <Resource> <Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI"> <AttributeValue>manager</AttributeValue> </Attribute> </Resource> <Action> <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#anyURI"> <AttributeValue>urn:nobody</AttributeValue> </Attribute> </Action> </Request>

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

199

11.7.2. Configure Security Auditing

To configure security auditing settings for a security domain, log into the management console andfollow this procedure.

Procedure 11.11. Setup Security Auditing for a Security Domain

1. Open the security domain's detailed view.

a. Click Configuration at the top of the screen.

b. In a managed domain, select a profile to modify from the Profile selection box at the topleft.

c. Expand the Security menu and select Security Domains.

d. Click View for the security domain you want to edit.

2. Navigate to the Auditing subsystem configuration.Select the Audit tab at the top of the screen.

The configuration area is divided into two areas: Provider Modules and Details. Theprovider module is the basic unit of configuration. A security domain can include several providermodules each of which can include attributes and options.

3. Add a provider module.Click Add. Fill in the Code section with the classname of the provider module.

4. Verify if your module is workingThe goal of an audit module is to provide a way to monitor the events in the security subsystem.This monitoring can be done by means of writing to a log file, email notifications or any othermeasurable auditing mechanism.

For example, JBoss EAP 6 includes the LogAuditProvider module by default. If enabledfollowing the steps above, this audit module writes security notifications to a audit.log file inthe log subfolder within the EAP_HOME directory.

To verify if the steps above have worked in the context of the LogAuditProvider, perform anaction that is likely to trigger a notification and then check the audit log file.

For a full list of included security auditing provider modules, see here: Section A.4, “IncludedSecurity Auditing Provider Modules”

5. Optional: Add, edit, or remove module options.To add options to your module, click its entry in the Modules list, and select the Module Options tab in the Details section of the page. Click Add, and provide the key and value forthe option.

To edit an option that already exists, click Remove to remove it, and click Add to add it againwith the correct options.

Result

Your security auditing module is added to the security domain, and is immediately available toapplications which use the security domain.

Security Guide

200

Report a bug

11.7.3. New Security Properties

New system properties have been added to the security audit functionality for JBoss EAP versions 6.2.2and later. These new properties mitigate security concerns surrounding plain text logging of web requestcomponents, particularly in scenarios involving BASIC or FORM based authentication.

The new properties allow greater control over which components of a web request are captured in auditlogs (parameters, cookies, headers or attributes). These components can also be masked using the newproperties.

The new properties are:

Table 11.1. New Security Properties

Name Description Possible values Behavior Default

org.jboss.security.web.audit

This propertycontrols thegranularity of thesecurity auditing ofweb requests.

off, headers, cookies, parameters, attributes

Any component (orcomma-separatedgroup ofcomponents)specified will beaudited out of webrequests.

headers,parameters

org.jboss.security.web.audit.mask

This property canbe used to specifya list of strings tobe matchedagainst headers,parameters,cookies, andattributes of webrequests. Anyelement matchingthe specifiedmasks will beexcluded fromsecurity auditlogging.

Any commaseparated stringindicating keys ofheaders,parameters,cookies, andattributes.

Currently, thematching of themasks is fuzzyrather than strict.For example, amask of authorization will mask boththe header calledauthorization andthe parametercalledcustom_authorization. A futurerelease mayintroduce strictmasks.

j_password,authorization

Report a bug

11.8. SECURITY MAPPING

11.8.1. About Security Mapping

Security mapping allows you to combine authentication and authorization information after theauthentication or authorization happens, but before the information is passed to your application.

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

201

You can map principals (authentication), roles (authorization), or credentials (attributes which are notprincipals or roles).

Role Mapping is used to add, replace, or remove roles to the subject after authentication.

Principal mapping is used to modify a principal after authentication.

Attribute mapping is used to convert attributes from an external system to be used by your application,and vice versa.

Report a bug

11.8.2. Configure Security Mapping in a Security Domain

To configure security mapping settings for a security domain, log into the management console andfollow this procedure.

Procedure 11.12. Setup Security Mapping Settings in a Security Domain

1. Open the security domain's detailed view.

a. Click the Configuration label at the top of the management console.

b. In a managed domain, select a profile from the Profile selection box at the top left.

c. Expand the Security menu, and select Security Domains.

d. Click View for the security domain you want to edit.

2. Navigate to the Mapping subsystem configuration.Select the Mapping label at the top of the screen.

The configuration area is divided into two areas: Modules and Details. The mapping moduleis the basic unit of configuration. A security domain can include several mapping modules, eachof which can include several attributes and options.

3. Add a security mapping module.Click Add.

Fill in the details for your module. The Code is the class name of the module. The Type fieldrefers to the type of mapping this module performs. Allowed values are principal, role, attributeor credential.

4. Edit a security mapping moduleAfter you have added your module, you can modify its Code or Type.

a. Select the Attributes tab.

b. Click Edit in the Details section of the screen.

5. Optional: Add, edit, or remove module options.To add options to your module, click its entry in the Modules list, and select the Module Options tab in the Details section of the page. Click Add, and provide the key and value forthe option.

Security Guide

202

To edit an option that already exists, click Remove to remove it, and add it again with the newvalue.

Use the Remove button to remove an option.

Result

Your security mapping module is added to the security domain, and is immediately available toapplications which use the security domain.

Report a bug

11.9. USE A SECURITY DOMAIN IN YOUR APPLICATION

Overview

To use a security domain in your application, first you need to define the security domain in the server'sconfiguration and then enable it for an application in the application's deployment descriptor. Then youmust add the required annotations to the EJB that uses it. This topic covers the steps required to use asecurity domain in your application.

WARNING

If an application is part of a security domain that uses an authentication cache, userauthentications for that application will also be available to other applications in thatsecurity domain.

Procedure 11.13. Configure Your Application to Use a Security Domain

1. Define the Security DomainYou need to define the security domain in the server's configuration file, and then enable it for anapplication in the application's descriptor file.

a. Configure the security domain in the server's configuration fileThe security domain is configured in the security subsystem of the server's configurationfile. If the JBoss EAP 6 instance is running in a managed domain, this is the domain/configuration/domain.xml file. If the JBoss EAP 6 instance is running as astandalone server, this is the standalone/configuration/standalone.xml file.

The other, jboss-web-policy, and jboss-ejb-policy security domains areprovided by default in JBoss EAP 6. The following XML example was copied from the security subsystem in the server's configuration file.

The cache-type attribute of a security domain specifies a cache for faster authenticationchecks. Allowed values are default to use a simple map as the cache, or infinispan touse an Infinispan cache.

<subsystem xmlns="urn:jboss:domain:security:1.2"> <security-domains> <security-domain name="other" cache-type="default"> <authentication>

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

203

You can configure additional security domains as needed using the Management Consoleor CLI.

b. Enable the security domain in the application's descriptor fileThe security domain is specified in the <security-domain> child element of the <jboss-web> element in the application's WEB-INF/jboss-web.xml file. The following exampleconfigures a security domain named my-domain.

This is only one of many settings which you can specify in the WEB-INF/jboss-web.xmldescriptor.

2. Add the Required Annotation to the EJBYou configure security in the EJB using the @SecurityDomain and @RolesAllowedannotations. The following EJB code example limits access to the other security domain byusers in the guest role.

<login-module code="Remoting" flag="optional"> <module-option name="password-stacking" value="useFirstPass"/> </login-module> <login-module code="RealmDirect" flag="required"> <module-option name="password-stacking" value="useFirstPass"/> </login-module> </authentication> </security-domain> <security-domain name="jboss-web-policy" cache-type="default"> <authorization> <policy-module code="Delegating" flag="required"/> </authorization> </security-domain> <security-domain name="jboss-ejb-policy" cache-type="default"> <authorization> <policy-module code="Delegating" flag="required"/> </authorization> </security-domain> </security-domains></subsystem>

<jboss-web> <security-domain>my-domain</security-domain></jboss-web>

package example.ejb3;

import java.security.Principal;

import javax.annotation.Resource;import javax.annotation.security.RolesAllowed;import javax.ejb.SessionContext;

Security Guide

204

For more code examples, see the ejb-security quickstart in the JBoss EAP 6 Quickstartsbundle, which is available from the Red Hat Customer Portal.

Report a bug

import javax.ejb.Stateless;

import org.jboss.ejb3.annotation.SecurityDomain;

/** * Simple secured EJB using EJB security annotations * Allow access to "other" security domain by users in a "guest" role. */@Stateless@RolesAllowed({ "guest" })@SecurityDomain("other")public class SecuredEJB {

// Inject the Session Context @Resource private SessionContext ctx;

/** * Secured EJB method using security annotations */ public String getSecurityInfo() { // Session context injected using the resource annotation Principal principal = ctx.getCallerPrincipal(); return principal.toString(); }}

CHAPTER 11. AUTHENTICATION AND AUTHORIZATION

205

CHAPTER 12. SINGLE SIGN ON (SSO)

12.1. ABOUT SINGLE SIGN ON (SSO) FOR WEB APPLICATIONS

Overview

Single Sign On (SSO) allows authentication to one resource to implicitly allow access to other resources.

Clustered and Non-Clustered SSO

Non-clustered SSO limits the sharing of access information to applications on the same virtual host. Inaddition, there is no resiliency in the event of a host failure. Clustered SSO data can be shared betweenapplications in multiple hosts, and is resilient to failover. In addition, clustered SSO is able to receiverequests from a load balancer.

How SSO Works

If a resource is unprotected, a user is not challenged to authenticate at all. If a user accesses a protectedresource, the user is required to authenticate.

Upon successful authentication, the roles associated with the user are stored and used for authenticationof all other associated resources.

If the user logs out of an application, or an application invalidates the session programmatically, allpersisted authentication data is removed, and the process starts over.

A session timeout does not invalidate the SSO session if other sessions are still valid.

Report a bug

12.2. ABOUT CLUSTERED SINGLE SIGN ON (SSO) FOR WEBAPPLICATIONS

Single Sign On (SSO) is the ability for users to authenticate to a single web application, and by means ofa successful authentication, will successfully authenticate to multiple other applications without needingto be prompted at each one. Clustered SSO stores the authentication information in a clustered cache.This allows for applications on multiple different servers to share the information, and also makes theinformation resilient to a failure of one of the hosts.

Some of the supported SSO mechanisms (for example, Kerberos, PicketLink SAML) need valves towork correctly. Valves have a similar function as the servlet filters, but they are processed before thecontainer managed authentication. Valves for web applications can be defined in the jboss-web.xmldeployment descriptor.

Report a bug

12.3. CHOOSE THE RIGHT SSO IMPLEMENTATION

JBoss EAP 6 runs Java Enterprise Edition (EE) applications, which may be web applications, EJBapplications, web services, or other types. Single Sign On (SSO) allows you to propagate securitycontext and identity information between these applications. Several SSO solutions are available butchoosing the right solution depends on your requirements.

Note that there is a distinct difference between a clustered web application and clustered SSO. Aclustered web application is one which is distributed across the nodes of a cluster to spread the load ofhosting that application. If marked as distributable, all new sessions, and changes to existing sessions

Security Guide

206

are replicated to other members of the cluster. An application is marked as able to be distributed acrosscluster nodes with the <distributable/> tag in the web.xml deployment descriptor. Clustered SSO allowsfor replication of security context and identity information, regardless of whether or not the applicationsare themselves clustered. Although these technologies may be used together they are separateconcepts.

Kerberos-Based Desktop SSO

If your organization already uses a Kerberos-based authentication and authorization system, such asMicrosoft Active Directory, you can use the same systems to transparently authenticate to yourenterprise applications running on JBoss EAP 6.

Non-Clustered Web Application SSO

If you are running multiple applications on a single instance and need to enable SSO session replicationfor those applications, non-clustered SSO will meet your requirements.

Clustered Web Application SSO

If you are running either a single application, or multiple applications, across a cluster and need toenable SSO session replication for those applications, clustered SSO will meet your requirements.

Report a bug

12.4. USE SINGLE SIGN ON (SSO) IN A WEB APPLICATION

Overview

Single Sign On (SSO) capabilities are provided by the web and Infinispan subsystems. Use thisprocedure to configure SSO in web applications.

Prerequisites

A configured security domain which handles authentication and access.

The infinispan subsystem. By default, it is present in all the profiles for managed domain andstandalone server.

The web cache-container and SSO replicated-cache. The initial configuration files alreadycontain the web cache-container, and some of the configurations already contain the SSOreplicated-cache as well. Use the following commands to check for and enable the SSOreplicated-cache. Note that these commands modify the ha profile of a managed domain. Youcan change the commands to use a different profile, or remove the /profile=ha portion of thecommand, for a standalone server.

Example 12.1. Check for the web cache-container

The profiles and configurations mentioned above include the web cache-container by default.Use the following command to verify its presence. If you use a different profile, substitute itsname instead of ha.

/profile=ha/subsystem=infinispan/cache-container=web/:read-resource(recursive=false,proxies=false,include-runtime=false,include-defaults=true)

If the result is success the subsystem is present. Otherwise, you need to add it.

CHAPTER 12. SINGLE SIGN ON (SSO)

207

Example 12.2. Add the web cache-container

Use the following three commands to enable the web cache-container to your configuration.Modify the name of the profile as appropriate, as well as the other parameters. Theparameters here are the ones used in a default configuration.

/profile=ha/subsystem=infinispan/cache-container=web:add(aliases=["standard-session-cache"],default-cache="repl",module="org.jboss.as.clustering.web.infinispan")

/profile=ha/subsystem=infinispan/cache-container=web/transport=TRANSPORT:add(lock-timeout=60000)

/profile=ha/subsystem=infinispan/cache-container=web/replicated-cache=repl:add(mode="ASYNC",batching=true)

Example 12.3. Check for the SSO replicated-cache

Run the following Management CLI command:

/profile=ha/subsystem=infinispan/cache-container=web/:read-resource(recursive=true,proxies=false,include-runtime=false,include-defaults=true)

Look for output like the following: "sso" => {

If you do not find it, the SSO replicated-cache is not present in your configuration.

Example 12.4. Add the SSO replicated-cache

/profile=ha/subsystem=infinispan/cache-container=web/replicated-cache=sso:add(mode="SYNC", batching=true)

Configure Clustered SSO for a Managed Domain

The web subsystem needs to be configured to use SSO. The following command enables SSO on thevirtual server called default-host, and the cookie domain domain.com. The cache name is sso, andreauthentication is disabled.

/profile=ha/subsystem=web/virtual-server=default-host/sso=configuration:add(cache-container="web",cache-name="sso",reauthenticate="false",domain="domain.com")

Each application which will share the SSO information must be configured to use the same <security-domain> in its jboss-web.xml deployment descriptor and the same Realm in its web.xmlconfiguration file.

Security Guide

208

Configure Clustered or Non-Clustered SSO for a Standalone Server

Configure sso under the web subsystem in the server profile. The ClusteredSingleSignOn versionis used when attribute cache-container is present, otherwise standard SingleSignOn class isused.

Example 12.5. Example Non-Clustered SSO Configuration

/subsystem=web/virtual-server=default-host/sso=configuration:add(reauthenticate="false")

Invalidate a Session

An application can programmatically invalidate a session by invoking method javax.servlet.http.HttpSession.invalidate().

Report a bug

12.5. ABOUT KERBEROS

Kerberos is a network authentication protocol for client/server applications. It allows authenticationacross a non-secure network in a secure way, using secret-key symmetric cryptography.

Kerberos uses security tokens called tickets. To use a secured service, you need to obtain a ticket fromthe Ticket Granting Service (TGS), which is a service running on a server on the network. After obtainingthe ticket, you request a Service Ticket (ST) from an Authentication Service (AS), which is anotherservice running on the network. You then use the ST to authenticate to the service you want to use. TheTGS and the AS both run inside an enclosing service called the Key Distribution Center (KDC).

Kerberos is designed to be used in a client-server environment, and is rarely used in Web applicationsor thin client environments. However, many organizations already use a Kerberos system for desktopauthentication, and prefer to reuse their existing system rather than create a second one for their WebApplications. Kerberos is an integral part of Microsoft Active Directory, and is also used in many Red HatEnterprise Linux environments.

Report a bug

12.6. ABOUT SPNEGO

Simple and Protected GSS_API Negotiation Mechanism (SPNEGO) provides a mechanism forextending a Kerberos-based Single Sign On (SSO) environment for use in Web applications.

When an application on a client computer, such as a web browser, attempts to access a protect page onthe web server, the server responds that authorization is required. The application then requests aservice ticket from the Kerberos Key Distribution Center (KDC). After the ticket is obtained, theapplication wraps it in a request formatted for SPNEGO, and sends it back to the Web application, viathe browser. The web container running the deployed Web application unpacks the request andauthenticates the ticket. Upon successful authentication, access is granted.

SPNEGO works with all types of Kerberos providers, including the Kerberos service included in Red HatEnterprise Linux and the Kerberos server which is an integral part of Microsoft Active Directory.

Report a bug

CHAPTER 12. SINGLE SIGN ON (SSO)

209

12.7. ABOUT MICROSOFT ACTIVE DIRECTORY

Microsoft Active Directory is a directory service developed by Microsoft to authenticate users andcomputers in a Microsoft Windows domain. It is included as part of Microsoft Windows Server. Thecomputer in the Microsoft Windows Server is referred to as the domain controller. Red Hat EnterpriseLinux servers running the Samba service can also act as the domain controller in this type of network.

Active Directory relies on three core technologies which work together:

Lightweight Directory Access Protocol (LDAP), for storing information about users, computers,passwords, and other resources.

Kerberos, for providing secure authentication over the network.

Domain Name Service (DNS) for providing mappings between IP addresses and host names ofcomputers and other devices on the network.

Report a bug

12.8. CONFIGURE KERBEROS OR MICROSOFT ACTIVE DIRECTORYDESKTOP SSO FOR WEB APPLICATIONS

Introduction

To authenticate your web or EJB applications using your organization's existing Kerberos-basedauthentication and authorization infrastructure, such as Microsoft Active Directory, you can use theJBoss Negotiation capabilities built into JBoss EAP 6. If you configure your web application properly, asuccessful desktop or network login is sufficient to transparently authenticate against your webapplication, so no additional login prompt is required.

Difference from Previous Versions of the Platform

There are a few noticeable differences between JBoss EAP 6 and earlier versions:

Security domains are configured for each profile of a managed domain, or for each standaloneserver. They are not part of the deployment itself. The security domain a deployment should useis named in the deployment's jboss-web.xml or jboss-ejb3.xml file.

Security properties are configured as part of a security domain. They are not part of thedeployment.

You can no longer override the authenticators as part of your deployment. However, you canadd a NegotiationAuthenticator valve to your jboss-web.xml descriptor to achieve the sameeffect. The valve still requires the <security-constraint> and <login-config> elementsto be defined in the web.xml. These are used to decide which resources are secured. However,the chosen auth-method will be overridden by the NegotiationAuthenticator valve in the jboss-web.xml.

The CODE attributes in security domains now use a simple name instead of a fully-qualified classname. The following table shows the mappings between the classes used for JBossNegotiation, and their classes.

Table 12.1. Login Module Codes and Class Names

Security Guide

210

Simple Name Class Name Purpose

Kerberos com.sun.security.auth.module.Krb5LoginModule

com.ibm.security.auth.module.Krb5LoginModule

Kerberos login module when using theOracle JDK

Kerberos login module when using theIBM JDK

SPNEGO org.jboss.security.negotiation.spnego.SPNEGOLoginModule

The mechanism which enables your Webapplications to authenticate to yourKerberos authentication server.

AdvancedLdap org.jboss.security.negotiation.AdvancedLdapLoginModule

Used with LDAP servers other thanMicrosoft Active Directory.

AdvancedAdLdap org.jboss.security.negotiation.AdvancedADLoginModule

Used with Microsoft Active DirectoryLDAP servers.

JBoss Negotiation Toolkit

The JBoss Negotiation Toolkit is a debugging tool which is available for download fromhttps://community.jboss.org/servlet/JiveServlet/download/16876-2-34629/jboss-negotiation-toolkit.war. Itis provided as an extra tool to help you to debug and test the authentication mechanisms beforeintroducing your application into production. It is an unsupported tool, but is considered to be veryhelpful, as SPNEGO can be difficult to configure for web applications.

Procedure 12.1. Setup SSO Authentication for your Web or EJB Applications

1. Configure one security domain to represent the identity of the server. Set systemproperties if necessary.The first security domain authenticates the container itself to the directory service. It needs touse a login module which accepts some type of static login mechanism, because a real user isnot involved. This example uses a static principal and references a keytab file which contains thecredential.

The XML code is given here for clarity, but you should use the Management Console orManagement CLI to configure your security domains.

<security-domain name="host" cache-type="default"> <authentication> <login-module code="Kerberos" flag="required"> <module-option name="storeKey" value="true"/> <module-option name="useKeyTab" value="true"/> <module-option name="principal" value="host/testserver@MY_REALM"/> <module-option name="keyTab" value="/home/username/service.keytab"/> <module-option name="doNotPrompt" value="true"/> <module-option name="debug" value="false"/> </login-module> </authentication></security-domain>

CHAPTER 12. SINGLE SIGN ON (SSO)

211

2. Configure a second security domain to secure the web application or applications. Setsystem properties if necessary.The second security domain is used to authenticate the individual user to the Kerberos orSPNEGO authentication server. You need at least one login module to authenticate the user,and another to search for the roles to apply to the user. The following XML code shows anexample SPNEGO security domain. It includes an authorization module to map roles toindividual users. You can also use a module which searches for the roles on the authenticationserver itself.

3. Specify the security-constraint and login-config in the web.xmlThe web.xml descriptor contain information about security constraints and login configuration.The following are example values for each.

<security-domain name="SPNEGO" cache-type="default"> <authentication> <!-- Check the username and password --> <login-module code="SPNEGO" flag="requisite"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="serverSecurityDomain" value="host"/> </login-module> <!-- Search for roles --> <login-module code="UsersRoles" flag="required"> <module-option name="password-stacking" value="useFirstPass" /> <module-option name="usersProperties" value="spnego-users.properties" /> <module-option name="rolesProperties" value="spnego-roles.properties" /> </login-module> </authentication></security-domain>

<security-constraint> <display-name>Security Constraint on Conversation</display-name> <web-resource-collection> <web-resource-name>examplesWebApp</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>RequiredRole</role-name> </auth-constraint></security-constraint>

<login-config> <auth-method>SPNEGO</auth-method> <realm-name>SPNEGO</realm-name></login-config> <security-role> <description> role required to log in to the Application</description> <role-name>RequiredRole</role-name></security-role>

Security Guide

212

4. Specify the security domain and other settings in the jboss-web.xml descriptor.Specify the name of the client-side security domain (the second one in this example) in the jboss-web.xml descriptor of your deployment, to direct your application to use this securitydomain.

You can no longer override authenticators directly. Instead, you can add theNegotiationAuthenticator as a valve to your jboss-web.xml descriptor, if you need to. The <jacc-star-role-allow> allows you to use the asterisk (*) character to match multiple rolenames, and is optional.

5. Add a dependency to your application's MANIFEST.MF, to locate the Negotiation classes.The web application needs a dependency on class org.jboss.security.negotiation tobe added to the deployment's META-INF/MANIFEST.MF manifest, in order to locate the JBossNegotiation classes. The following shows a properly-formatted entry.

As an alternative, add a dependency to your application by editing the META-INF/jboss-deployment-structure.xml file:

Result

Your web application accepts and authenticates credentials against your Kerberos, Microsoft ActiveDirectory, or other SPNEGO-compatible directory service. If the user runs the application from a systemwhich is already logged into the directory service, and where the required roles are already applied to theuser, the web application does not prompt for authentication, and SSO capabilities are achieved.

Report a bug

12.9. CONFIGURE SPNEGO FALL BACK TO FORM AUTHENTICATION

Follow the procedure below to setup a SPNEGO fall back to form authentication.

<jboss-web> <security-domain>SPNEGO</security-domain> <valve> <class-name>org.jboss.security.negotiation.NegotiationAuthenticator</class-name> </valve> <jacc-star-role-allow>true</jacc-star-role-allow></jboss-web>

Manifest-Version: 1.0Build-Jdk: 1.6.0_24Dependencies: org.jboss.security.negotiation

<?xml version="1.0" encoding="UTF-8"?><jboss-deployment-structure> <deployment> <dependencies> <module name='org.jboss.security.negotiation'/> </dependencies> </deployment></jboss-deployment-structure>

CHAPTER 12. SINGLE SIGN ON (SSO)

213

Procedure 12.2. SPNEGO security with fall back to form authentication

1. Set up SPNEGORefer the procedure described in Section 12.8, “Configure Kerberos or Microsoft ActiveDirectory Desktop SSO for Web Applications”

2. Modify web.xmlAdd a login-config element to your application and setup the login and error pages inweb.xml:

3. Add web contentAdd references of login.html and error.html to web.xml. These files are added to webapplication archive to the place specified in form-login-config configuration. For moreinformation refer Enable Form-based Authentication section in the Security Guide for JBoss EAP6. A typical login.html looks like this:

<login-config> <auth-method>SPNEGO</auth-method> <realm-name>SPNEGO</realm-name> <form-login-config> <form-login-page>/login.jsp</form-login-page> <form-error-page>/error.jsp</form-error-page> </form-login-config> </login-config>

<html> <head> <title>Vault Form Authentication</title> </head> <body> <h1>Vault Login Page</h1> <p> <form method="post" action="j_security_check"> <table> <tr> <td>Username</td><td>-</td> <td><input type="text" name="j_username"></td> </tr> <tr> <td>Password</td><td>-</td> <td><input type="password" name="j_password"></td> </tr> <tr> <td colspan="2"><input type="submit"></td> </tr> </table> </form> </p> <hr> </body></html>

Security Guide

214

NOTE

The fallback to FORM logic is only available in the case when no SPNEGO (or NTLM)tokens are present. As a result, a login form is not presented to the browser if the browsersends an NTLM token.

Report a bug

CHAPTER 12. SINGLE SIGN ON (SSO)

215

CHAPTER 13. SINGLE SIGN-ON WITH SAML

13.1. ABOUT SECURITY TOKEN SERVICE (STS)

The Security Token Service generates and manages the security tokens. It does not issue tokens of aspecific type. Instead, it defines generic interfaces that allows multiple token providers to be plugged in.As a result, it can be configured to deal with various types of token, as long as a token provider exists foreach token type. It also specifies the format of the security token request and response messages.

A security token request message specifies the following:

Type of the request, such as Issue, Renew, and so on.

Type of the token.

Lifetime of the issued token.

Information about the service provider that requested the token.

Information used to encrypt the generated token.

NOTE

Support for PKCS#11 tokens has been added to JBoss EAP from version 6.3.0.

EAP security realms can accept PKCS#11 keys and trust store definitions by using the provider attribute. The value specified in this parameter is passed to the relevant KeyStore.getInstance("PKCS11") calls and the key and trust store are initialized.

Configuration for this new support is beyond the scope of EAP documentation. Users whowish to utilize this feature should familiarize themselves with the correct installation ofPKCS#11 hardware and software as well as the correct entries required in the java.security policy file. Oracle's Java PKCs#11 Reference Guide document may bea useful resource for this information.

The token request message is sent in the body of the SOAP message. All information related to thetoken request is enclosed in the RequestSecurityToken element. The sample request contains twoother WS-Trust elements: RequestType, which specifies that this request is an Issue request, and TokenType, which specifies the type of the token to be issued.

The following is an example of the WS-Trust request message.

Example 13.1. WS-Trust security token request message

<S11:Envelope xmlns:S11=".." xmlns:wsu=".." xmlns:wst=".."> <S11:Header> ... </S11:Header> <S11:Body wsu:Id="body"> <wst:RequestSecurityToken Context="context"> <wst:TokenType>http://www.tokens.org/SpecialToken</wst:TokenType> <wst:RequestType> http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue

Security Guide

216

The following is an example of a security token response.

Example 13.2. Security token response message

In the example for the security token response, the TokenType element specifies the type of the issuedtoken, while the RequestedSecurityToken element contains the token itself. The format of the tokendepends on the type of the token. The Lifetime element specifies when the token was created andwhen it expires.

Security Token Request Processing

The following are the steps in which the security token requests are processed:

A client sends a security token request to PicketLinkSTS.

PicketLinkSTS parses the request message, generating a JAXB object model.

PicketLinkSTS reads the configuration file and creates the STSConfiguration object, ifneeded. Then it obtains a reference to the WSTrustRequestHandler from the configurationand delegates the request processing to the handler instance.

The request handler uses the STSConfiguration to set default values when needed (forexample, when the request doesn't specify a token lifetime value).

The WSTrustRequestHandler creates the WSTrustRequestContext, setting the JAXBrequest object and the caller principal it received from PicketLinkSTS.

The WSTrustRequestHandler uses the STSConfiguration to get the SecurityTokenProvider that must be used to process the request based on the type of thetoken that is being requested. Then it invokes the provider, passing the constructed WSTrustRequestContext as a parameter.

</wst:RequestType> </wst:RequestSecurityToken> </S11:Body> </S11:Envelope>

<wst:RequestSecurityTokenResponse Context="context" xmlns:wst=".." xmlns:wsu=".."> <wst:TokenType>http://www.tokens.org/SpecialToken</wst:TokenType> <wst:RequestedSecurityToken> <token:SpecialToken xmlns:token="..."> ARhjefhE2FEjneovi&@FHfeoveq3 </token:SpecialToken> </wst:RequestedSecurityToken> <wst:Lifetime> <wsu:Created>...</wsu:Created> <wsu:Expires>...</wsu:Expires> </wst:Lifetime> </wst:RequestSecurityTokenResponse>

CHAPTER 13. SINGLE SIGN-ON WITH SAML

217

The SecurityTokenProvider instance process the token request and stores the issuedtoken in the request context.

The WSTrustRequestHandler obtains the token from the context, encrypts it if needed, andconstructs the WS-Trust response object containing the security token.

PicketLinkSTS dictates the response generated by the request handler and returns it to theclient.

Report a bug

13.2. CONFIGURE SECURITY TOKEN SERVICE (STS)

The EAP Security Token Service (STS) defines several interfaces that provide extension points.Implementations can be plugged in via configuration, and the default values can be specified for someproperties via configuration. All STS configurations are specified in the picketlink.xml file, whichbelongs in the WEB-INF directory of the deployed application. The following are the elements that can beconfigured in the picketlink.xml file.

NOTE

In the following text, a service provider refers to the Web service that requires a securitytoken to be presented by its clients.

PicketLinkSTS: This is the root element. It defines some properties that allows the STSadministrator to set a the following default values:

STSName: A string representing the name of the security token service. If not specified, thedefault PicketLinkSTS value is used.

TokenTimeout: The token lifetime value in seconds. If not specified, the default value of3600 (one hour) is used.

EncryptToken: A boolean specifying whether issued tokens are to be encrypted or not.The default value is false.

KeyProvider: This element and all its sub elements are used to configure the keystore that areused by PicketLink STS to sign and encrypt tokens. Properties like the keystore location, itspassword, and the signing (private key) alias and password are all configured in this section.

RequestHandler: This element specifies the fully qualified name of the WSTrustRequestHandler implementation to be used. If not specified, the default org.picketlink.identity.federation.core.wstrust.StandardRequestHandleris used.

TokenProvider: This section specifies the TokenProvider implementations that must beused to handle each type of security token. In the example we have two providers - one thathandles tokens of type SpecialToken and one that handles tokens of type SAMLV2.0. The WSTrustRequestHandler calls the getProviderForTokenType(String type) method of STSConfiguration to obtain a reference to the appropriate TokenProvider.

TokenTimeout: This is used by the WSTrustRequestHandler when no Lifetime has beenspecified in the WS-Trust request. It creates a Lifetime instance that has the current time as thecreation time and expires after the specified number of seconds.

Security Guide

218

ServiceProviders: This section specifies the token types that must be used for each serviceprovider (the Web service that requires a security token). When a WS-Trust request does notcontain the token type, the WSTrustRequestHandler must use the service provider endpointto find out the type of the token that must be issued.

EncryptToken: This is used by the WSTrustRequestHandler to decide if the issued tokenmust be encrypted or not. If true, the public key certificate (PKC) of the service provider is usedto encrypt the token.

The following is an example of STS configuration.

Example 13.3. STS Configuration

Report a bug

<PicketLinkSTS xmlns="urn:picketlink:identity-federation:config:1.0" STSName="Test STS" TokenTimeout="7200" EncryptToken="true"> <KeyProvider ClassName="org.picketlink.identity.federation.bindings.tomcat.KeyStoreKeyManager"> <Auth Key="KeyStoreURL" Value="keystore/sts_keystore.jks"/> <Auth Key="KeyStorePass" Value="testpass"/> <Auth Key="SigningKeyAlias" Value="sts"/> <Auth Key="SigningKeyPass" Value="keypass"/> <ValidatingAlias Key="http://services.testcorp.org/provider1" Value="service1"/> <ValidatingAlias Key="http://services.testcorp.org/provider2" Value="service2"/> </KeyProvider> <RequestHandler>org.picketlink.identity.federation.core.wstrust.StandardRequestHandler</RequestHandler> <TokenProviders> <TokenProvider ProviderClass="org.picketlink.test.identity.federation.bindings.wstrust.SpecialTokenProvider" TokenType="http://www.tokens.org/SpecialToken"/> <TokenProvider ProviderClass="org.picketlink.identity.federation.api.wstrust.plugins.saml.SAML20TokenProvider" TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0"/> </TokenProviders> <ServiceProviders> <ServiceProvider Endpoint="http://services.testcorp.org/provider1" TokenType="http://www.tokens.org/SpecialToken" TruststoreAlias="service1"/> <ServiceProvider Endpoint="http://services.testcorp.org/provider2" TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0" TruststoreAlias="service2"/> </ServiceProviders> </PicketLinkSTS>

CHAPTER 13. SINGLE SIGN-ON WITH SAML

219

13.3. ABOUT PICKETLINK STS LOGIN MODULES

A PicketLink Login Module is typically configured as part of the security setup of a JEE container to use aSecurity Token Service for authenticating users. The STS may be collocated on the same container asthe Login Module or be accessed remotely through Web Service calls or another technology. PicketLinkLogin Modules support non-PicketLink STS implementations through standard WS-Trust calls.

Types of STS Login Modules

The following are the different types of STS Login Modules.

STSIssuingLoginModule

Calls the configured STS and requests for a security token. Upon successfully receiving the RequestedSecurityToken, it marks the authentication as successful.

A call to STS typically requires authentication. This Login Module uses credentials from one ofthe following sources:

Its properties file, if the useOptionsCredentials module option is set to true.

Previous login module credentials if the password-stackingmodule option is set to useFirstPass.

From the configured CallbackHandler by supplying a Name and Password Callback.

Upon successful authentication, the SamlCredential is inserted in the Subject's publiccredentials if one with the same Assertion is not found to be already present there.

STSValidatingLoginModule

Calls the configured STS and validates an available security token.

A call to STS typically requires authentication. This Login Module uses credentials from one ofthe following sources:

Its properties file, if the useOptionsCredentials module option is set to true.

Previous login module credentials if the password-stacking module option is set to useFirstPass.

From the configured CallbackHandler by supplying a Name and Password Callback.

Upon successful authentication, the SamlCredential is inserted in the Subject's public credentialsif one with the same Assertion is not found to be already present there.

SAML2STSLoginModule

This Login Module supplies a ObjectCallback to the configured CallbackHandler andexpects a SamlCredential object back. The Assertion is validated against the configured STS.

If a user ID and SAML token are shared, this Login Module bypasses validation When stackedon top of another Login Module that is successfully authenticated.

Upon successful authentication, the SamlCredential is inspected for a NameID and a multi-valued role attribute that is respectively set as the ID and roles of the user.

Security Guide

220

SAML2LoginModule

This login module is used in conjunction with other components for SAML authentication andperforms no authentication itself.

The SPRedirectFormAuthenticator uses this login module in PicketLink's implementationof the SAML v2 HTTP Redirect Profile.

The Tomcat authenticator valve performs authentication through redirecting to the identityprovider and getting a SAML assertion.

This login module is used to pass the user ID and roles to the JBoss security framework to bepopulated in the JAAS subject.

Report a bug

13.4. CONFIGURE STSISSUINGLOGINMODULE

The STSIssuingLoginModule uses a user name and password to authenticate the user against anSTS by retrieving a token.

Example 13.4. Configure STSIssuingLoginModule

Most configurations can switch to the configuration sited in the above example by:

changing their declared security-domain

specifying a Principal mapping provider

<security-domain 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/endpoint</module-option> </login-module> </authentication> <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></security-domain>

CHAPTER 13. SINGLE SIGN-ON WITH SAML

221

specifying a RoleGroup mapping provider

The specified Principal mapping provider and the RoleGroup mapping provider results in anauthenticated Subject being populated that enables coarse-grained and role-based authorization. Afterauthentication, the Security Token is available and may be used to invoke other services by Single Sign-On.

Report a bug

13.5. CONFIGURE STSVALIDATINGLOGINMODULE

The STSValidatingLoginModule uses a TokenCallback to ask the configured CallbackHandler an STS byretrieving a token.

Example 13.5. Configure STSValidatingLoginModule

The configuration cited in the example enables Single Sign-On for your applications and services. Atoken once issued, either by directly contacting the STS or through a token-issuing login module, can beused to authenticate against multiple applications and services by employing the setup provided in theexample. Providing a Principal mapping provider and a RoleGroup mapping provider result in anauthenticated Subject being populated that enables coarse-grained and role-based authorization. Afterauthentication, the Security Token is available and can be used to invoke other services by Single Sign-On.

Report a bug

<security-domain 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> <module-option name="endpointURI">http://security_saml/endpoint</module-option> </login-module> </authentication> <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></security-domain>

Security Guide

222

13.6. STS CLIENT POOLING

The PicketLink provides a pool of STS clients on the server. This removes STS Client creation as abottleneck.

Client pooling can be utilized from login modules that need an STS client to obtain SAML tickets.

Login Modules that can utilize STS client pooling:

org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule

org.picketlink.identity.federation.core.wstrust.auth.STSValidatingLoginModule

org.picketlink.trust.jbossws.jaas.JBWSTokenIssuingLoginModule

The default number of clients in the pool for each login module is configured via the initialNumberOfClients login module option.

The STSClientPoolFactory class org.picketlink.identity.federation.bindings.stspool.STSClientPoolFactoryprovides client pool functionality to applications.

Using STSClientPoolFactorySTS clients are inserted into sub pools using their configuration as a key. Obtain STSClientPool instanceand then initialize a sub pool based on configuration, optionally with initial number of STS clients or relyon default number.

When you are done with a client, you can return it to the pool like so:

To check if a subpool already exists for a given configuration:

When the PicketLink Federation subsystem is enabled, all client pools created for a deployment aredestroyed automatically during the undeploy process. To manually destroy a pool:

Report a bug

13.7. SAML WEB BROWSER BASED SSO

13.7.1. About SAML Web Browser Based SSO

final STSClientPool pool = STSClientPoolFactory.getPoolInstance();pool.createPool(20, stsClientConfig);final STSClient client = pool.getClient(stsClientConfig);

pool.returnClient();

if (! pool.configExists(stsClientConfig) { pool.createPool(stsClientConfig); }

pool.destroyPool(stsClientConfig);

CHAPTER 13. SINGLE SIGN-ON WITH SAML

223

PicketLink in JBoss EAP provides a platform to implement federated identity based services. Thisincludes centralized identity services and Single Sign-On (SSO) for applications.

The SAML profile has support for both the HTTP/POST and the HTTP/Redirect bindings with centralizedidentity services to enable web SSO for your applications. The architecture for the SAML v2 based WebSSO follows the hub and spoke architecture of identity management. In this architecture an identityprovider (IDP) acts as the central source (hub) for identity and role information to all the applications(Service Providers). The spokes are the service providers (SP).

IMPORTANT

If there are two or more SPs both pointing to the same IDP, the IDP does not distinguishbetween the different SPs. If you make requests to different SPs that point to the sameIDP, the IDP handles the most recent request from an SP and sends back SAMLassertion about the authenticated user. To get back to the an older SP request, you willneed to reenter the SP URL in the browser.

Report a bug

13.7.2. Setup SAML v2 based Web SSO

To setup SAML v2 based SSO you have to configure the following:

Identity Provider: The Identity Provider is the authoritative entity responsible for authenticating anend user and asserting the identity for that user in a trusted fashion to trusted partners.

Service Provider: The Service Provider relies on the Identity Provider to assert information abouta user via an electronic user credential, leaving the service provider to manage access controland dissemination based on a trusted set of user credential assertions.

Report a bug

13.7.3. Configure Identity Provider

The Identity Provider (IDP) is a JBoss EAP server instance.

Procedure 13.1. Configure Identity Provider (IDP)

1. Configure the web application security for the IDPConfigure a web application as the Identity provider.

NOTE

The use of FORM based web application security is recommended as it givesyou the ability to customize the login page.

The following is an example of the web.xml configuration

Example 13.6. web.xml Configuration for IDP

<display-name>IDP</display-name><description>IDP</description><!-- Define a security constraint that gives unlimited access to

Security Guide

224

2. Create Security Domain for IDPCreate a Security Domain with authentication and authorization mechanisms defined for the IDP.Refer to Section 11.9, “Use a Security Domain in Your Application” for further details.

3. Configure the IDP ValvesCreate a jboss-web.xml file in the WEB-INF directory of your IDP web application to configurethe valves for the IDP. The following is an example of jboss-web.xml file.

Example 13.7. jboss-web.xml File Configuration for IDP Valves

images --><security-constraint> <web-resource-collection> <web-resource-name>Images</web-resource-name> <url-pattern>/images/*</url-pattern></web-resource-collection></security-constraint><!-- Define a Security Constraint on this Application --><security-constraint> <web-resource-collection> <web-resource-name>IDP</web-resource-name> <url-pattern>/*</url-pattern></web-resource-collection> <auth-constraint> <role-name>manager</role-name></auth-constraint></security-constraint><!-- Define the Login Configuration for this Application --><login-config> <auth-method>FORM</auth-method> <realm-name>IDP Application</realm-name> <form-login-config> <form-login-page>/jsp/login.jsp</form-login-page> <form-error-page>/jsp/loginerror.jsp</form-error-page> </form-login-config></login-config><!-- Security roles referenced by this web application --><security-role> <description> The role that is required to log in to the IDP Application </description> <role-name>manager</role-name></security-role></web-app>

<jboss-web> <security-domain>idp</security-domain> <context-root>idp</context-root> <valve> <class-name>org.picketlink.identity.federation.bindings.tomcat.idp.IDPWebBrowserSSOValve</class-name> </valve></jboss-web>

CHAPTER 13. SINGLE SIGN-ON WITH SAML

225

4. Configure the PicketLink Configuration File (picketlink.xml)The following is an example of picketlink.xml configuration. In this configuration file youprovide the URL that gets added as the issuer in the outgoing SAML2 assertions to the serviceproviders and the IDP.

Example 13.8. picketlink.xml Configuration

By default, picketlink.xml is located in the WEB-INF directory of your IDP web application.However, you can configure a custom path to a picketlink.xml that is external to theapplication:

a. Optional: Configuring a custom path to picketlink.xmlAdd two paramaters to the valve element in your application's WEB-INF/jboss-web.xml: configFile specifying for the path to picketlink.xml, and timerInterval whichspecifies the interval in milliseconds to reload the configuration. For example:

<PicketLink xmlns="urn:picketlink:identity-federation:config:2.1"> <PicketLinkIDP xmlns="urn:picketlink:identity-federation:config:2.1"> <IdentityURL>http://localhost:8080/idp/</IdentityURL> </PicketLinkIDP> <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1"> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler" /> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" /> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" /> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" /> </Handlers></PicketLink>

<valve> <class-name>...</class-name> <param> <param-name>timerInterval</param-name> <param-value>5000</param-value> </param> <param> <param-name>configFile</param-name> <param-value>path-to/picketlink.xml</param-value> </param></valve>

Security Guide

226

5. Declare dependencies on PicketLink module (META-INF/MANIFEST.MF, or jboss-deployment-structure.xml)The web application also requires a dependency defining in META-INF/MANIFEST.MF or jboss-deployment-structure.xml, so that the PicketLink classes can be located.

Example 13.9. Define Dependency in META-INF/MANIFEST.MF

Example 13.10. Define Dependency in META-INF/jboss-deployment-structure.xml

Report a bug

13.7.4. Configure Service Provider using HTTP/REDIRECT Binding

The Service Provider (SP) can be a JBoss EAP server instance.

Procedure 13.2. Configure Service Provider (SP)

1. Configure the Web Application Security For the SPThe web application to be configured as a SP should have FORM based security enabled in its web.xml file.

Example 13.11. web.xml Configuration for SP

Manifest-Version: 1.0 Build-Jdk: 1.6.0_24 Dependencies: org.picketlink

<jboss-deployment-structure> <deployment> <dependencies> <module name="org.picketlink" /> </dependencies> </deployment></jboss-deployment-structure>

<display-name>SP</display-name><description>SP</description><!-- Define a security constraint that gives unlimited access to images --><security-constraint> <web-resource-collection> <web-resource-name>Images</web-resource-name> <url-pattern>/images/*</url-pattern> </web-resource-collection></security-constraint><!-- Define a Security Constraint on this Application --><security-constraint> <web-resource-collection> <web-resource-name>SP</web-resource-name>

CHAPTER 13. SINGLE SIGN-ON WITH SAML

227

2. Create Security Domain for SPCreate a Security Domain that uses SAML2LoginModule. Here is an example configuration:

<security-domain name="sp" cache-type="default"> <authentication> <login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required"/> </authentication></security-domain>

3. Configure the SP ValveTo configure the valve for the SP, create a jboss-web.xml in the WEB-INF directory of yourSP web application.

Example 13.12. jboss-web.xml File Configuration for SP Valves

4. Configure the PicketLink Configuration File (picketlink.xml)

<url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>manager</role-name> </auth-constraint></security-constraint><!-- Define the Login Configuration for this Application --><login-config> <auth-method>FORM</auth-method> <realm-name>SP Application</realm-name> <form-login-config> <form-login-page>/jsp/login.jsp</form-login-page> <form-error-page>/jsp/loginerror.jsp</form-error-page> </form-login-config></login-config><!-- Security roles referenced by this web application --><security-role> <description> The role that is required to log in to the SP Application </description> <role-name>manager</role-name></security-role></web-app>

<jboss-web> <security-domain>sp</security-domain> <context-root>sales-post</context-root> <valve> <class-name>org.picketlink.identity.federation.bindings.tomcat.sp.ServiceProviderAuthenticator</class-name> </valve></jboss-web>

Security Guide

228

The following is an example of picketlink.xml configuration for the SP. In this configurationfile you provide the URL for the SP and for the IDP, with corresponding handlers for the SP.

Example 13.13. picketlink.xml Configuration

By default, picketlink.xml is located in the WEB-INF directory of your application. However,you can configure a custom path to a picketlink.xml that is external to the application:

a. Optional: Configuring a custom path to picketlink.xmlAdd two paramaters to the valve element in your application's WEB-INF/jboss-web.xml: configFile specifying for the path to picketlink.xml, and timerInterval whichspecifies the interval in milliseconds to reload the configuration. For example:

5. Declare dependencies on PicketLink module (META-INF/MANIFEST.MF, or jboss-deployment-structure.xml)The web application also requires a dependency defining in META-INF/MANIFEST.MF or jboss-deployment-structure.xml, so that the PicketLink classes can be located.

<PicketLink xmlns="urn:picketlink:identity-federation:config:2.1"> <PicketLinkSP xmlns="urn:picketlink:identity-federation:config:2.1" ServerEnvironment="tomcat" BindingType="REDIRECT"> <IdentityURL>${idp.url::http://localhost:8080/idp/}</IdentityURL> <ServiceURL>${sales-post.url::http://localhost:8080/sales-post/}</ServiceURL> </PicketLinkSP> <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1"> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" /> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" /> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" /> </Handlers></PicketLink>

<valve> <class-name>...</class-name> <param> <param-name>timerInterval</param-name> <param-value>5000</param-value> </param> <param> <param-name>configFile</param-name> <param-value>path-to/picketlink.xml</param-value> </param></valve>

CHAPTER 13. SINGLE SIGN-ON WITH SAML

229

Example 13.14. Define Dependency in META-INF/MANIFEST.MF

Example 13.15. Define Dependency in META-INF/jboss-deployment-structure.xml

Report a bug

13.7.5. Setup SAML v2 based Web SSO using HTTP/POST Binding

HTTP/POST binding is the recommended binding for obtaining the web browser based SSO.

Procedure 13.3. Setup SAML v2 based Web SSO using HTTP/POST Binding

1. Configure the Identity Provider (IDP).The steps to configure IDP for HTTP/POST Binding are same as that of the HTTP/RedirectBinding. For more information on configuring the IDP, see Section 13.7.2, “Setup SAML v2based Web SSO”

2. Configure the Service Provider (SP)The steps to configure SP for HTTP/POST Binding are the same as that of the HTTP/RedirectBinding, except for a single variation in the picketlink.xml file of the SP. Change BindingType="REDIRECT" to BindingType="POST".

For more information on configuring the SP, see Section 13.7.4, “Configure Service Providerusing HTTP/REDIRECT Binding”

Report a bug

13.7.6. Configure Dynamic Account Chooser at a Service Provider

Prerequisites:

Section 13.7.3, “Configure Identity Provider”

Section 13.7.4, “Configure Service Provider using HTTP/REDIRECT Binding”

If a Service Provider (SP) is configured with multiple Identity Providers (IDPs), PicketLink can beconfigured to prompt the user to choose which IDP to use to authenticate their credentials.

Manifest-Version: 1.0 Build-Jdk: 1.6.0_24 Dependencies: org.picketlink

<jboss-deployment-structure> <deployment> <dependencies> <module name="org.picketlink" /> </dependencies> </deployment></jboss-deployment-structure>

Security Guide

230

Procedure 13.4. Configure Dynamic Account Chooser at a Service Provider

1. Configure the account chooser valve in jboss-web.xml in the WEB-INF directory of your SPweb application.

Example 13.16. jboss-web.xml File Configuration for SP Account Chooser

AccountChooserValve has the following configurable options:

DomainName

The domain name to be used for the cookie that is sent to the user's browser.

CookieExpiry

The cookie expiry in seconds. Default is -1, which means the cookie expires when thebrowser is closed.

AccountIDPMapProvider

The fully-qualified name of the implementation for IDP Mapping. Default is a properties file idpmap.properties in the WEB-INF directory of your SP web application. Thisimplementation must implement org.picketlink.identity.federation.bindings.tomcat.sp.AbstractAccountChooserValve.AccountIDPMapProvider.

AccountChooserPage

The name of the HTML/JSP page for listing the different IDP accounts. Default is /accountChooser.html.

2. Define the mapping for the IDPs. By default, this is a properties file idpmap.properties in theWEB-INF directory of your SP web application.

Example 13.17. idpmap.properties Configuration

<jboss-web> <security-domain>sp</security-domain> <context-root>accountchooser</context-root> <valve> <class-name>org.picketlink.identity.federation.bindings.tomcat.sp.AccountChooserValve</class-name> </valve> <valve> <class-name>org.picketlink.identity.federation.bindings.tomcat.sp.ServiceProviderAuthenticator</class-name> </valve></jboss-web>

DomainA=http://localhost:8080/idp1/DomainB=http://localhost:8080/idp2/

CHAPTER 13. SINGLE SIGN-ON WITH SAML

231

3. Create a HTML page in your SP web application for the user to choose the IDP. By default, thisfile is accountChooser.html. The URL to each of IDP must have the parameter idp thatspecifies the name of the IDP listed in idpmap.properties.

Example 13.18. accountChooser.html Configuration

Report a bug

13.7.7. Configuration of IDP-initiated SSO

Prerequisites:

Section 13.7.3, “Configure Identity Provider”

Section 13.7.4, “Configure Service Provider using HTTP/REDIRECT Binding”

Usually in PicketLink, the SP starts the flow by sending an authentication request to the IDP, which inturns sends an SAML response to SP with a valid assertion. This flow is called SP-initiated SSO. But theSAML 2.0 specs also defines another flow, called IDP-initiated or Unsolicited Response SSO. In thisscenario, the SP does not initiate the authentication flow and receives an SAML response from the IDP.The flow starts on the IDP-side and once authenticated, the user can choose a specific SP from a list andthen get redirected to its URL.

Walkthrough

1. User accesses the IDP.

2. The IDP seeing that there is neither SAML request nor response, assumes an IDP first scenariousing SAML.

3. The IDP challenges the user to authenticate.

4. Upon authentication, the IDP shows the hosted section where the user gets a page that links toall the SP applications.

5. The user chooses an SP application.

6. The IDP redirects the user to the service provider with an SAML assertion in the queryparameter, SAML response.

7. The SP checks the SAML assertion and provides access.

Configuration

No special configuration is necessary to get Unsolicited Responses supported, you can configure yourIDP and SPs as usual. For more information about how to configure IDP and SP, refer to:

<html> ... <a href="?idp=DomainA">DomainA</a> <hr/> <a href="?idp=DomainB">DomainB</a> ...</html>

Security Guide

232

Section 13.7.3, “Configure Identity Provider”

Section 13.7.4, “Configure Service Provider using HTTP/REDIRECT Binding”

How to Use

Once the user is authenticated, the IDP shows a page with links to all service provider applications. A linkwill usually look like this:

Note that the link above redirects the user to the IDP passing the TARGET query parameter, whosevalue is the URL to the target SP application. Once the user clicks the link above, the IDP extracts theTARGET parameter from the request, builds an SAML v2.0 response, and redirects the user to the targetURL. When the user hits the SP, it is automatically authenticated.

You can use the SAML_VERSION query parameter to specify the SAML version that must be used bythe IDP to create the SAML response. SAML_VERSION parameter can have the possible options as 2.0and 1.1.

Report a bug

13.8. CONFIGURE SAML GLOBAL LOGOUT PROFILE

A Global Logout initiated at one service provider logs out the user from the Identity Provider (IDP) and allthe service providers.

NOTE

For a Global Logout to function appropriately ensure that you have only up to five ServiceProviders per Identity Provider.

Procedure 13.5. Configure Global Logout

1. Configure picketlink-handlers.xmlAdd the SAML2LogOutHandler in the picketlink-handlers.xml.

2. Configure Service Provider web pageAppend GLO=true to the link at the end of your web page of the service provider.

Example 13.19. Link to Global Logout

3. Create a logout.jsp pageAs part of the logout process, PicketLink will redirect the user to a logout.jsp page located inthe root directory of your Service Provider application. Ensure that this page is created.

Report a bug

<a href="http://localhost:8080/idp?SAML_VERSION=2.0&TARGET=http://localhost:8080/sales-post/">Sales</a>

<a href="?GLO=true">Click to Globally LogOut</a>

CHAPTER 13. SINGLE SIGN-ON WITH SAML

233

CHAPTER 14. LOGIN MODULES

Report a bug

14.1. USING MODULES

JBoss EAP 6 includes several bundled login modules suitable for most user management needs. JBossEAP 6 can read user information from a relational database, an LDAP server, or flat files. In addition tothese core login modules, JBoss EAP 6 provides other login modules that provide user information forvery customized needs.

More login modules and their options can be found in Appendix A.1.

Report a bug

14.1.1. Password Stacking

Multiple login modules can be chained together in a stack, with each login module providing both thecredentials verification and role assignment during authentication. This works for many use cases, butsometimes credentials verification and role assignment are split across multiple user managementstores.

Section 14.1.4, “Ldap Login Module” describes how to combine LDAP and a relational database,allowing a user to be authenticated by either system. Consider the case where users are managed in acentral LDAP server but application-specific roles are stored in the application's relational database. Thepassword-stacking module option captures this relationship.

To use password stacking, each login module should set the <module-option> password-stackingattribute to useFirstPass. If a previous module configured for password stacking has authenticatedthe user, all the other stacking modules will consider the user authenticated and only attempt to provide aset of roles for the authorization step.

When password-stacking option is set to useFirstPass, this module first looks for a shared username and password under the property names javax.security.auth.login.name andjavax.security.auth.login.password respectively in the login module shared state map.

If found, these properties are used as the principal name and password. If not found, the principal nameand password are set by this login module and stored under the property namesjavax.security.auth.login.name and javax.security.auth.login.password respectively.

NOTE

When using password stacking, set all modules to be required. This ensures that allmodules are considered, and have the chance to contribute roles to the authorizationprocess.

Example 14.1. Password Stacking Sample

This management CLI example shows how password stacking could be used.

/subsystem=security/security-domain=pwdStack/authentication=classic/login-module=Ldap:add( \ code=Ldap, \ flag=required, \

Security Guide

234

Report a bug

14.1.2. Password Hashing

Most login modules must compare a client-supplied password to a password stored in a usermanagement system. These modules generally work with plain text passwords, but can be configured tosupport hashed passwords to prevent plain text passwords from being stored on the server side.

IMPORTANT

Red Hat JBoss Enterprise Application Platform Common Criteria certified release onlysupports SHA-256 for password hashing.

Example 14.2. Password Hashing

The following is a login module configuration that assigns unauthenticated users the principal name nobody and contains based64-encoded, SHA-256 hashes of the passwords in a usersb64.properties file. The usersb64.properties file is part of the deployment classpath.

hashAlgorithm

module-options=[ \ ("password-stacking"=>"useFirstPass"), \ ... Ldap login module configuration ])/subsystem=security/security-domain=pwdStack/authentication=classic/login-module=Database:add( \ code=Database, \ flag=required, \ module-options=[ \ ("password-stacking"=>"useFirstPass"), \ ... Database login module configuration ])

/subsystem=security/security-domain=testUsersRoles:add/subsystem=security/security-domain=testUsersRoles/authentication=classic:add/subsystem=security/security-domain=testUsersRoles/authentication=classic/login-module=UsersRoles:add( \ code=UsersRoles, \ flag=required, \ module-options=[ \ ("usersProperties"=>"usersb64.properties"), \ ("rolesProperties"=>"test-users-roles.properties"), \ ("unauthenticatedIdentity"=>"nobody"), \ ("hashAlgorithm"=>"SHA-256"), \ ("hashEncoding"=>"base64") \ ])

CHAPTER 14. LOGIN MODULES

235

Name of the java.security.MessageDigest algorithm to use to hash the password. There is nodefault so this option must be specified to enable hashing. Typical values are SHA-256, SHA-1 and MD5.

hashEncoding

String that specifies one of three encoding types: base64, hex or rfc2617. The default is base64.

hashCharset

Encoding character set used to convert the clear text password to a byte array. The platform defaultencoding is the default.

hashUserPassword

Specifies the hashing algorithm must be applied to the password the user submits. The hashed userpassword is compared against the value in the login module, which is expected to be a hash of thepassword. The default is true.

hashStorePassword

Specifies the hashing algorithm must be applied to the password stored on the server side. This isused for digest authentication, where the user submits a hash of the user password along with arequest-specific tokens from the server to be compare. The hash algorithm (for digest, this would be rfc2617) is utilized to compute a server-side hash, which should match the hashed value sent fromthe client.

If you must generate passwords in code, the org.jboss.security.auth.spi.Util class providesa static helper method that will hash a password using the specified encoding. The following exampleproduces a base64-encoded, MD5 hashed password.

OpenSSL provides an alternative way to quickly generate hashed passwords at the command-line. Thefollowing example also produces a base64-encoded, SHA-256 hashed password. Here the password inplain text - password - is piped into the OpenSSL digest function then piped into another OpenSSLfunction to convert into base64-encoded format.

In both cases, the hashed version of the password is the same: XohImNooBHFR0OVvjcYpJ3NgPQ1qq73WKhHvch0VQtg=. This value must be stored in the users'properties file specified in the security domain - usersb64.properties - in the example above.

Report a bug

14.1.3. Unauthenticated Identity

Not all requests are received in an authenticated format. unauthenticatedIdentity is a loginmodule configuration option that assigns a specific identity (guest, for example) to requests that aremade with no associated authentication information. This can be used to allow unprotected servlets toinvoke methods on EJBs that do not require a specific role. Such a principal has no associated roles andso can only access either unsecured EJBs or EJB methods that are associated with the uncheckedpermission constraint.

String hashedPassword = Util.createPasswordHash("SHA-256", Util.BASE64_ENCODING, null, null, "password");

echo -n password | openssl dgst -sha256 -binary | openssl base64

Security Guide

236

unauthenticatedIdentity: This defines the principal name that should be assigned to requeststhat contain no authentication information.

Report a bug

14.1.4. Ldap Login Module

Ldap login module is a LoginModule implementation that authenticates against a Lightweight DirectoryAccess Protocol (LDAP) server. Use the Ldap login module if your user name and credentials are storedin an LDAP server that is accessible using a Java Naming and Directory Interface (JNDI) LDAP provider.

NOTE

If you wish to use LDAP with the SPNEGO authentication or skip some of theauthentication phases while using an LDAP server, consider using the AdvancedLdaplogin module chained with the SPNEGO login module or only the AdvancedLdap loginmodule.

Distinguished Name (DN)

In Lightweight Directory Access Protocol (LDAP), the distinguished name uniquely identifies an objectin a directory. Each distinguished name must have a unique name and location from all other objects,which is achieved using a number of attribute-value pairs (AVPs). The AVPs define information suchas common names, organization unit, among others. The combination of these values results in aunique string required by the LDAP.

NOTE

This login module also supports unauthenticated identity and password stacking.

The LDAP connectivity information is provided as configuration options that are passed through to theenvironment object used to create JNDI initial context. The standard LDAP JNDI properties used includethe following:

java.naming.factory.initial

InitialContextFactory implementation class name. This defaults to the Sun LDAP providerimplementation com.sun.jndi.ldap.LdapCtxFactory.

java.naming.provider.url

LDAP URL for the LDAP server.

java.naming.security.authentication

Security protocol level to use. The available values include none, simple, and strong. If theproperty is undefined, the behavior is determined by the service provider.

java.naming.security.protocol

Transport protocol to use for secure access. Set this configuration option to the type of serviceprovider (for example, SSL). If the property is undefined, the behavior is determined by the serviceprovider.

java.naming.security.principal

CHAPTER 14. LOGIN MODULES

237

Specifies the identity of the Principal for authenticating the caller to the service. This is built from otherproperties as described below.

java.naming.security.credentials

Specifies the credentials of the Principal for authenticating the caller to the service. Credentials cantake the form of a hashed password, a clear-text password, a key, or a certificate. If the property isundefined, the behavior is determined by the service provider.

For details of Ldap login module configuration options see Section A.1, “Included AuthenticationModules”.

NOTE

In certain directory schemas (e.g., Microsoft Active Directory), role attributes in the userobject are stored as DNs to role objects instead of simple names. For implementationsthat use this schema type, roleAttributeIsDN must be set to true.

User authentication is performed by connecting to the LDAP server, based on the login moduleconfiguration options. Connecting to the LDAP server is done by creating an InitialLdapContextwith an environment composed of the LDAP JNDI properties described previously in this section.

The Context.SECURITY_PRINCIPAL is set to the distinguished name of the user obtained by thecallback handler in combination with the principalDNPrefix and principalDNSuffix option values, and theContext.SECURITY_CREDENTIALS property is set to the respective String password.

Once authentication has succeeded (InitialLdapContext instance is created), the user's roles arequeried by performing a search on the rolesCtxDN location with search attributes set to theroleAttributeName and uidAttributeName option values. The roles names are obtaining by invoking the toString method on the role attributes in the search result set.

Example 14.3. LDAP Login Module Security Domain

This management CLI example shows how to use the parameters in a security domain authenticationconfiguration.

/subsystem=security/security-domain=testLDAP:add(cache-type=default)/subsystem=security/security-domain=testLDAP/authentication=classic:add/subsystem=security/security-domain=testLDAP/authentication=classic/login-module=Ldap:add( \ code=Ldap, \ flag=required, \ module-options=[ \ ("java.naming.factory.initial"=>"com.sun.jndi.ldap.LdapCtxFactory"), \ ("java.naming.provider.url"=>"ldap://ldaphost.jboss.org:1389/"), \ ("java.naming.security.authentication"=>"simple"), \ ("principalDNPrefix"=>"uid="), \ ("principalDNSuffix"=>",ou=People,dc=jboss,dc=org"), \ ("rolesCtxDN"=>"ou=Roles,dc=jboss,dc=org"), \ ("uidAttributeID"=>"member"), \ ("matchOnUserDN"=>true), \

Security Guide

238

The java.naming.factory.initial, java.naming.factory.url and java.naming.security options in the testLDAP security domain configuration indicate the followingconditions:

The Sun LDAP JNDI provider implementation will be used

The LDAP server is located on host ldaphost.jboss.org on port 1389

The LDAP simple authentication method will be use to connect to the LDAP server.

The login module attempts to connect to the LDAP server using a Distinguished Name (DN) representingthe user it is trying to authenticate. This DN is constructed from the passed principalDNPrefix, the username of the user and the principalDNSuffix as described above. In Example 14.4, “LDIF File Example”,the user name jsmith would map to uid=jsmith,ou=People,dc=jboss,dc=org.

NOTE

The example assumes the LDAP server authenticates users using the userPasswordattribute of the user's entry (theduke in this example). Most LDAP servers operate in thismanner, however if your LDAP server handles authentication differently you must ensureLDAP is configured according to your production environment requirements.

Once authentication succeeds, the roles on which authorization will be based are retrieved by performinga subtree search of the rolesCtxDN for entries whose uidAttributeID match the user. IfmatchOnUserDN is true, the search will be based on the full DN of the user. Otherwise the search will bebased on the actual user name entered. In this example, the search is under ou=Roles,dc=jboss,dc=org for any entries that have a member attribute equal to uid=jsmith,ou=People,dc=jboss,dc=org. The search would locate cn=JBossAdmin under theroles entry.

The search returns the attribute specified in the roleAttributeID option. In this example, the attribute is cn.The value returned would be JBossAdmin, so the jsmith user is assigned to the JBossAdmin role.

A local LDAP server often provides identity and authentication services, but is unable to useauthorization services. This is because application roles do not always map well onto LDAP groups, andLDAP administrators are often hesitant to allow external application-specific data in central LDAPservers. The LDAP authentication module is often paired with another login module, such as thedatabase login module, that can provide roles more suitable to the application being developed.

An LDAP Data Interchange Format (LDIF) file representing the structure of the directory this dataoperates against is shown in Example 14.4, “LDIF File Example”.

LDAP Data Interchange Format (LDIF)

Plain text data interchange format used to represent LDAP directory content and update requests.Directory content is represented as one record for each object or update request. Content consists ofadd, modify, delete, and rename requests.

Example 14.4. LDIF File Example

("roleAttributeID"=>"cn"), \ ("roleAttributeIsDN"=>false) \ ])

CHAPTER 14. LOGIN MODULES

239

Report a bug

14.1.5. LdapExtended Login Module

Distinguished Name (DN)

In Lightweight Directory Access Protocol (LDAP), the distinguished name uniquely identifies an objectin a directory. Each distinguished name must have a unique name and location from all other objects,which is achieved using a number of attribute-value pairs (AVPs). The AVPs define information suchas common names, organization unit, among others. The combination of these values results in aunique string required by the LDAP.

The LdapExtended (org.jboss.security.auth.spi.LdapExtLoginModule) searches for theuser to bind, as well as the associated roles, for authentication. The roles query recursively follows DNsto navigate a hierarchical role structure.

The LoginModule options include whatever options are supported by the chosen LDAP JNDI providersupports. Examples of standard property names are:

Context.INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial"

dn: dc=jboss,dc=orgobjectclass: topobjectclass: dcObjectobjectclass: organizationdc: jbosso: JBoss

dn: ou=People,dc=jboss,dc=orgobjectclass: topobjectclass: organizationalUnitou: People

dn: uid=jsmith,ou=People,dc=jboss,dc=orgobjectclass: topobjectclass: uidObjectobjectclass: personuid: jsmithcn: Johnsn: SmithuserPassword: theduke

dn: ou=Roles,dc=jboss,dc=orgobjectclass: topobjectclass: organizationalUnitou: Roles

dn: cn=JBossAdmin,ou=Roles,dc=jboss,dc=orgobjectclass: topobjectclass: groupOfNamescn: JBossAdminmember: uid=jsmith,ou=People,dc=jboss,dc=orgdescription: the JBossAdmin group

Security Guide

240

Context.SECURITY_PROTOCOL = "java.naming.security.protocol"

Context.PROVIDER_URL = "java.naming.provider.url"

Context.SECURITY_AUTHENTICATION = "java.naming.security.authentication"

Context.REFERRAL = "java.naming.referral"

Login module implementation logic follows the order below:

1. The initial LDAP server bind is authenticated using the bindDN and bindCredential properties.The bindDN is a user with permissions to search both the baseCtxDN and rolesCtxDN trees forthe user and roles. The user DN to authenticate against is queried using the filter specified by thebaseFilter property.

2. The resulting userDN is authenticated by binding to the LDAP server using the userDN as theInitialLdapContext environment Context.SECURITY_PRINCIPAL. TheContext.SECURITY_CREDENTIALS property is either set to the String password obtained bythe callback handler.

3. If this is successful, the associated user roles are queried using the rolesCtxDN, roleAttributeID,roleAttributeIsDN, roleNameAttributeID, and roleFilter options.

NOTE

AdvancedLdap Login Module differs from LdapExtended Login Module in the followingways:

The top level role is queried only for roleAttributeID and not forroleNameAttributeID.

When the roleAttributeIsDN module property is set to false, the recursive rolesearch is disabled even if the recurseRoles module option is set to true.

For details of LdapExtended login module options see Section A.1, “Included Authentication Modules”.

CHAPTER 14. LOGIN MODULES

241

Figure 14.1. LDAP Structure Example

Example 14.5. Example 2 LDAP Configuration

version: 1dn: o=example2,dc=jboss,dc=orgobjectClass: topobjectClass: organizationo: example2

dn: ou=People,o=example2,dc=jboss,dc=orgobjectClass: topobjectClass: organizationalUnitou: People

dn: uid=jduke,ou=People,o=example2,dc=jboss,dc=orgobjectClass: topobjectClass: uidObjectobjectClass: personobjectClass: inetOrgPersoncn: Java DukeemployeeNumber: judke-123sn: Dukeuid: jdukeuserPassword:: dGhlZHVrZQ==

dn: uid=jduke2,ou=People,o=example2,dc=jboss,dc=orgobjectClass: topobjectClass: uidObjectobjectClass: personobjectClass: inetOrgPersoncn: Java Duke2employeeNumber: judke2-123sn: Duke2uid: jduke2

Security Guide

242

userPassword:: dGhlZHVrZTI=

dn: ou=Roles,o=example2,dc=jboss,dc=orgobjectClass: topobjectClass: organizationalUnitou: Roles

dn: uid=jduke,ou=Roles,o=example2,dc=jboss,dc=orgobjectClass: topobjectClass: groupUserExmemberOf: cn=Echo,ou=Roles,o=example2,dc=jboss,dc=orgmemberOf: cn=TheDuke,ou=Roles,o=example2,dc=jboss,dc=orguid: jduke

dn: uid=jduke2,ou=Roles,o=example2,dc=jboss,dc=orgobjectClass: topobjectClass: groupUserExmemberOf: cn=Echo2,ou=Roles,o=example2,dc=jboss,dc=orgmemberOf: cn=TheDuke2,ou=Roles,o=example2,dc=jboss,dc=orguid: jduke2

dn: cn=Echo,ou=Roles,o=example2,dc=jboss,dc=orgobjectClass: topobjectClass: groupOfNamescn: Echodescription: the echo rolemember: uid=jduke,ou=People,dc=jboss,dc=org

dn: cn=TheDuke,ou=Roles,o=example2,dc=jboss,dc=orgobjectClass: groupOfNamesobjectClass: topcn: TheDukedescription: the duke rolemember: uid=jduke,ou=People,o=example2,dc=jboss,dc=org

dn: cn=Echo2,ou=Roles,o=example2,dc=jboss,dc=orgobjectClass: topobjectClass: groupOfNamescn: Echo2description: the Echo2 rolemember: uid=jduke2,ou=People,dc=jboss,dc=org

dn: cn=TheDuke2,ou=Roles,o=example2,dc=jboss,dc=orgobjectClass: groupOfNamesobjectClass: topcn: TheDuke2description: the duke2 rolemember: uid=jduke2,ou=People,o=example2,dc=jboss,dc=org

dn: cn=JBossAdmin,ou=Roles,o=example2,dc=jboss,dc=orgobjectClass: topobjectClass: groupOfNamescn: JBossAdmindescription: the JBossAdmin groupmember: uid=jduke,ou=People,dc=jboss,dc=org

CHAPTER 14. LOGIN MODULES

243

The module configuration for this LDAP structure example is outlined in the following managementCLI command.

Example 14.6. Example 3 LDAP Configuration

/subsystem=security/security-domain=testLdapExample2/authentication=classic/login-module=LdapExtended:add( \ code=LdapExtended, \ flag=required, \ module-options=[ \ ("java.naming.factory.initial"=>"com.sun.jndi.ldap.LdapCtxFactory"), \ ("java.naming.provider.url"=>"ldap://ldaphost.jboss.org"), \ ("java.naming.security.authentication"=>"simple"), \ ("bindDN"=>"cn=Root,dc=jboss,dc=org"), \ ("bindCredential"=>"secret1"), \ ("baseCtxDN"=>"ou=People,o=example2,dc=jboss,dc=org"), \ ("baseFilter"=>"(uid={0})"), \ ("rolesCtxDN"=>"ou=Roles,o=example2,dc=jboss,dc=org"), \ ("roleFilter"=>"(uid={0})"), \ ("roleAttributeIsDN"=>"true"), \ ("roleAttributeID"=>"memberOf"), \ ("roleNameAttributeID"=>"cn") \ ])

dn: o=example3,dc=jboss,dc=orgobjectclass: topobjectclass: organizationo: example3

dn: ou=People,o=example3,dc=jboss,dc=orgobjectclass: topobjectclass: organizationalUnitou: People

dn: uid=jduke,ou=People,o=example3,dc=jboss,dc=orgobjectclass: topobjectclass: uidObjectobjectclass: personobjectClass: inetOrgPersonuid: jdukeemployeeNumber: judke-123cn: Java Dukesn: DukeuserPassword: theduke

dn: ou=Roles,o=example3,dc=jboss,dc=orgobjectClass: topobjectClass: organizationalUnitou: Roles

Security Guide

244

The module configuration for this LDAP structure example is outlined in the following management CLIcommand.

Example 14.7. Example 4 LDAP Configuration

dn: uid=jduke,ou=Roles,o=example3,dc=jboss,dc=orgobjectClass: topobjectClass: groupUserExmemberOf: cn=Echo,ou=Roles,o=example3,dc=jboss,dc=orgmemberOf: cn=TheDuke,ou=Roles,o=example3,dc=jboss,dc=orguid: jduke

dn: cn=Echo,ou=Roles,o=example3,dc=jboss,dc=orgobjectClass: topobjectClass: groupOfNamescn: Echodescription: the JBossAdmin groupmember: uid=jduke,ou=People,o=example3,dc=jboss,dc=org

dn: cn=TheDuke,ou=Roles,o=example3,dc=jboss,dc=orgobjectClass: groupOfNamesobjectClass: topcn: TheDukemember: uid=jduke,ou=People,o=example3,dc=jboss,dc=org

/subsystem=security/security-domain=testLdapExample3/authentication=classic/login-module=LdapExtended:add( \ code=LdapExtended, \ flag=required, \ module-options=[ \ ("java.naming.factory.initial"=>"com.sun.jndi.ldap.LdapCtxFactory"), \ ("java.naming.provider.url"=>"ldap://ldaphost.jboss.org"), \ ("java.naming.security.authentication"=>"simple"), \ ("bindDN"=>"cn=Root,dc=jboss,dc=org"), \ ("bindCredential"=>"secret1"), \ ("baseCtxDN"=>"ou=People,o=example3,dc=jboss,dc=org"), \ ("baseFilter"=>"(cn={0})"), \ ("rolesCtxDN"=>"ou=Roles,o=example3,dc=jboss,dc=org"), \ ("roleFilter"=>"(member={1})"), \ ("roleAttributeID"=>"cn") \ ])

dn: o=example4,dc=jboss,dc=orgobjectclass: topobjectclass: organizationo: example4

CHAPTER 14. LOGIN MODULES

245

dn: ou=People,o=example4,dc=jboss,dc=orgobjectclass: topobjectclass: organizationalUnitou: People

dn: uid=jduke,ou=People,o=example4,dc=jboss,dc=orgobjectClass: topobjectClass: uidObjectobjectClass: personobjectClass: inetOrgPersoncn: Java DukeemployeeNumber: jduke-123sn: Dukeuid: jdukeuserPassword:: dGhlZHVrZQ==

dn: ou=Roles,o=example4,dc=jboss,dc=orgobjectClass: topobjectClass: organizationalUnitou: Roles

dn: cn=RG1,ou=Roles,o=example4,dc=jboss,dc=orgobjectClass: groupOfNamesobjectClass: topcn: RG1member: cn=empty

dn: cn=RG2,cn=RG1,ou=Roles,o=example4,dc=jboss,dc=orgobjectClass: groupOfNamesobjectClass: topcn: RG2member: cn=RG1,ou=Roles,o=example4,dc=jboss,dc=orgmember: uid=jduke,ou=People,o=example4,dc=jboss,dc=org

dn: cn=RG3,cn=RG1,ou=Roles,o=example4,dc=jboss,dc=orgobjectClass: groupOfNamesobjectClass: topcn: RG3member: cn=RG1,ou=Roles,o=example4,dc=jboss,dc=org

dn: cn=R1,ou=Roles,o=example4,dc=jboss,dc=orgobjectClass: groupOfNamesobjectClass: topcn: R1member: cn=RG2,cn=RG1,ou=Roles,o=example4,dc=jboss,dc=org

dn: cn=R2,ou=Roles,o=example4,dc=jboss,dc=orgobjectClass: groupOfNamesobjectClass: topcn: R2member: cn=RG2,cn=RG1,ou=Roles,o=example4,dc=jboss,dc=org

dn: cn=R3,ou=Roles,o=example4,dc=jboss,dc=orgobjectClass: groupOfNamesobjectClass: top

Security Guide

246

The module configuration for this LDAP structure example is outlined in the code sample.

Example 14.8. Default Active Directory Configuration

The example below represents the configuration for a default Active Directory configuration.

Some Active Directory configurations may require searching against the Global Catalog on port 3268instead of the usual port 389. This is most likely when the Active Directory forest includes multipledomains.

cn: R3member: cn=RG2,cn=RG1,ou=Roles,o=example4,dc=jboss,dc=orgmember: cn=RG3,cn=RG1,ou=Roles,o=example4,dc=jboss,dc=org

dn: cn=R4,ou=Roles,o=example4,dc=jboss,dc=orgobjectClass: groupOfNamesobjectClass: topcn: R4member: cn=RG3,cn=RG1,ou=Roles,o=example4,dc=jboss,dc=org

dn: cn=R5,ou=Roles,o=example4,dc=jboss,dc=orgobjectClass: groupOfNamesobjectClass: topcn: R5member: cn=RG3,cn=RG1,ou=Roles,o=example4,dc=jboss,dc=orgmember: uid=jduke,ou=People,o=example4,dc=jboss,dc=org

/subsystem=security/security-domain=testLdapExample4/authentication=classic/login-module=LdapExtended:add( \ code=LdapExtended, \ flag=required, \ module-options=[ \ ("java.naming.factory.initial"=>"com.sun.jndi.ldap.LdapCtxFactory"), \ ("java.naming.provider.url"=>"ldap://ldaphost.jboss.org"), \ ("java.naming.security.authentication"=>"simple"), \ ("bindDN"=>"cn=Root,dc=jboss,dc=org"), \ ("bindCredential"=>"secret1"), \ ("baseCtxDN"=>"ou=People,o=example4,dc=jboss,dc=org"), \ ("baseFilter"=>"(cn={0})"), \ ("rolesCtxDN"=>"ou=Roles,o=example4,dc=jboss,dc=org"), \ ("roleFilter"=>"(member={1})"), \ ("roleRecursion"=>"1"), \ ("roleAttributeID"=>"memberOf") \ ])

/subsystem=security/security-domain=AD_Default/authentication=classic/login-module=LdapExtended:add(

CHAPTER 14. LOGIN MODULES

247

Example 14.9. Recursive Roles Active Directory Configuration

The example below implements a recursive role search within Active Directory. The key differencebetween this example and the default Active Directory example is that the role search has beenreplaced to search the member attribute using the DN of the user. The login module then uses the DNof the role to find groups of which the group is a member.

Report a bug

\ code=LdapExtended, \ flag=required, \ module-options=[ \ ("java.naming.provider.url"=>"ldap://ldaphost.jboss.org"), \ ("bindDN"=>"JBOSS\searchuser"), \ ("bindCredential"=>"password"), \ ("baseCtxDN"=>"CN=Users,DC=jboss,DC=org"), \ ("baseFilter"=>"(sAMAccountName={0})"), \ ("rolesCtxDN"=>"CN=Users,DC=jboss,DC=org"), \ ("roleFilter"=>"(sAMAccountName={0})"), \ ("roleAttributeID"=>"memberOf"), \ ("roleAttributeIsDN"=>"true"), \ ("roleNameAttributeID"=>"cn"), \ ("searchScope"=>"ONELEVEL_SCOPE"), \ ("allowEmptyPasswords"=>"false") \ ])

/subsystem=security/security-domain=AD_Recursive/authentication=classic/login-module=LdapExtended:add( \ code=LdapExtended, \ flag=required, \ module-options=[ \ ("java.naming.provider.url"=>"ldap://ldaphost.jboss.org"), \ ("java.naming.referral"=>"follow"), \ ("bindDN"=>"JBOSS\searchuser"), \ ("bindCredential"=>"password"), \ ("baseCtxDN"=>"CN=Users,DC=jboss,DC=org"), \ ("baseFilter"=>"(sAMAccountName={0})"), \ ("rolesCtxDN"=>"CN=Users,DC=jboss,DC=org"), \ ("roleFilter"=>"(member={1})"), \ ("roleAttributeID"=>"cn"), \ ("roleAttributeIsDN"=>"false"), \ ("roleRecursion"=>"2"), \ ("searchScope"=>"ONELEVEL_SCOPE"), \ ("allowEmptyPasswords"=>"false") \ ])

Security Guide

248

14.1.6. UsersRoles Login Module

UsersRoles login module is a simple login module that supports multiple users and user roles loadedfrom Java properties files. The default username-to-password mapping filename is users.properties and the default username-to-roles mapping filename is roles.properties.

For details of UsersRoles login module options see Section A.1, “Included Authentication Modules” .

This login module supports password stacking, password hashing, and unauthenticated identity.

The properties files are loaded during initialization using the initialize method thread context class loader.This means that these files can be placed on the classpath of the Java EE deployment (for example, intothe WEB-INF/classes folder in the WAR archive), or into any directory on the server classpath. Theprimary purpose of this login module is to easily test the security settings of multiple users and rolesusing properties files deployed with the application.

Example 14.10. UsersRoles Login Module

In Example 14.10, “UsersRoles Login Module”, the ejb3-sampleapp-users.properties file uses a username=password format with each user entry on a separate line:

The ejb3-sampleapp-roles.properties file referenced in Example 14.10, “UsersRoles LoginModule” uses the pattern username=role1,role2, with an optional group name value. For example:

The user name.XXX property name pattern present in ejb3-sampleapp-roles.properties is usedto assign the user name roles to a particular named group of roles where the XXX portion of the propertyname is the group name. The user name=... form is an abbreviation for user name.Roles=..., where the Roles group name is the standard name the JBossAuthorizationManager expects to contain theroles which define the permissions of users.

The following would be equivalent definitions for the jduke user name:

/subsystem=security/security-domain=ejb3-sampleapp/authentication=classic/login-module=UsersRoles:add( \ code=UsersRoles, \ flag=required, \ module-options=[ \ ("usersProperties"=>"ejb3-sampleapp-users.properties"), \ ("rolesProperties"=>"ejb3-sampleapp-roles.properties") \ ])

username1=password1username2=password2...

username1=role1,role2,...username1.RoleGroup1=role3,role4,...username2=role1,role3,...

jduke=TheDuke,AnimatedCharacterjduke.Roles=TheDuke,AnimatedCharacter

CHAPTER 14. LOGIN MODULES

249

Report a bug

14.1.7. Database Login Module

The Database login module is a Java Database Connectivity-based (JDBC) login module that supportsauthentication and role mapping. Use this login module if you have your user name, password and roleinformation stored in a relational database.

NOTE

This module supports password stacking, password hashing and unauthenticated identity.

The Database login module is based on two logical tables:

The Principals table associates the user PrincipalID with the valid password and the Roles tableassociates the user PrincipalID with its role sets. The roles used for user permissions must becontained in rows with a RoleGroup column value of Roles.

The tables are logical in that you can specify the SQL query that the login module uses. The onlyrequirement is that the java.sql.ResultSet has the same logical structure as the Principals and Roles tables described previously. The actual names of the tables and columns are not relevant as theresults are accessed based on the column index.

To clarify this notion, consider a database with two tables, Principals and Roles, as alreadydeclared. The following statements populate the tables with the following data:

PrincipalID java with a Password of echoman in the Principals table

PrincipalID java with a role named Echo in the RolesRoleGroup in the Roles table

PrincipalID java with a role named caller_java in the CallerPrincipalRoleGroupin the Roles table

For details of Database login module options see Section A.1, “Included Authentication Modules”.

An example Database login module configuration could be constructed as follows:

A corresponding login module configuration in a security domain:

Table Principals(PrincipalID text, Password text)Table Roles(PrincipalID text, Role text, RoleGroup text)

INSERT INTO Principals VALUES('java', 'echoman')INSERT INTO Roles VALUES('java', 'Echo', 'Roles')INSERT INTO Roles VALUES('java', 'caller_java', 'CallerPrincipal')

CREATE TABLE Users(username VARCHAR(64) PRIMARY KEY, passwd VARCHAR(64))CREATE TABLE UserRoles(username VARCHAR(64), role VARCHAR(32))

/subsystem=security/security-domain=testDB/authentication=classic/login-module=Database:add( \ code=Database, \ flag=required, \

Security Guide

250

Report a bug

14.1.8. Certificate Login Module

Certificate login module authenticates users based on X509 certificates. A typical use case for thislogin module is CLIENT-CERT authentication in the web tier.

This login module only performs authentication: you must combine it with another login module capableof acquiring authorization roles to completely define access to a secured web or EJB component. Twosubclasses of this login module, CertRolesLoginModule and DatabaseCertLoginModule extendthe behavior to obtain the authorization roles from either a properties file or database.

For details of Certificate login module options see Section A.1, “Included Authentication Modules”.

The Certificate login module needs a KeyStore to perform user validation. This is obtained from aJSSE configuration of linked security domain as shown in the following configuration fragment:

Procedure 14.1. Secure Web Applications with Certificates and Role-based Authorization

This procedure describes how to secure a web application, such as the user-app.war, using clientcertificates and role-based authorization. In this example the CertificateRoles login module is usedfor authentication and authorization. Both the trusted-clients.keystore and the app-roles.properties require an entry that maps to the principal associated with the client certificate.

By default, the principal is created using the client certificate distinguished name, such as the DNspecified in Example 14.11, “Certificate Example”.

1. Declare Resources and RolesModify web.xml to declare the resources to be secured along with the allowed roles andsecurity domain to be used for authentication and authorization.

module-options=[ \ ("dsJndiName"=>"java:/MyDatabaseDS"), \ ("principalsQuery"=>"select passwd from Users where username=?"), \ ("rolesQuery"=>"select role, 'Roles' from UserRoles where username=?") \ ])

/subsystem=security/security-domain=trust-domain:add/subsystem=security/security-domain=trust-domain/jsse=classic:add( \ truststore={ \ password=>pass1234, \ url=>/home/jbosseap/trusted-clients.jks \ })

/subsystem=security/security-domain=testCert:add/subsystem=security/security-domain=testCert/authentication=classic:add/subsystem=security/security-domain=testCert/authentication=classic/login-module=Certificate:add( \ code=Certificate, \ flag=required, \ module-options=[ \ ("securityDomain"=>"trust-domain"), \ ])

CHAPTER 14. LOGIN MODULES

251

2. Specify the Security DomainIn the jboss-web.xml file, specify the required security domain.

3. Configure Login ModuleDefine the login module configuration for the app-sec-domain domain you just specified usingthe management CLI.

<?xml version="1.0" encoding="UTF-8"?><web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0">

<security-constraint> <web-resource-collection> <web-resource-name>Protect App</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>Admin</role-name> </auth-constraint> </security-constraint>

<login-config> <auth-method>CLIENT-CERT</auth-method> <realm-name>Secured area</realm-name> </login-config>

<security-role> <role-name>Admin</role-name> </security-role></web-app>

<jboss-web> <security-domain>app-sec-domain</security-domain></jboss-web>

[/subsystem=security/security-domain=trust-domain:add/subsystem=security/security-domain=trust-domain/jsse=classic:add( \ truststore={ \ password=>pass1234, \ url=>/home/jbosseap/trusted-clients.jks \ })

/subsystem=security/security-domain=app-sec-domain:add/subsystem=security/security-domain=app-sec-

Security Guide

252

Example 14.11. Certificate Example

[conf]$ keytool -printcert -file valid-client-cert.crtOwner: CN=valid-client, OU=Security QE, OU=JBoss, O=Red Hat, C=CZIssuer: CN=EAP Certification Authority, OU=Security QE, OU=JBoss, O=Red Hat, C=CZSerial number: 2Valid from: Mon Mar 24 18:21:55 CET 2014 until: Tue Mar 24 18:21:55 CET 2015Certificate fingerprints: MD5: 0C:54:AE:6E:29:ED:E4:EF:46:B5:14:30:F2:E0:2A:CB SHA1: D6:FB:19:E7:11:28:6C:DE:01:F2:92:2F:22:EF:BB:5D:BF:73:25:3D SHA256: CD:B7:B1:72:A3:02:42:55:A3:1C:30:E1:A6:F0:20:B0:2C:0F:23:4F:7A:8E:2F:2D:FA:AF:55:3E:A7:9B:2B:F4 Signature algorithm name: SHA1withRSA Version: 3

The trusted-clients.keystore would need the certificate in Example 14.11, “Certificate Example”stored with an alias of CN=valid-client, OU=Security QE, OU=JBoss, O=Red Hat, C=CZ.The app-roles.properties must have the same entry. Since the DN contains characters that arenormally treated as delimiters, you must escape the problem characters using a backslash ('\') asillustrated below.

# A sample app-roles.properties fileCN\=valid-client,\ OU\=Security\ QE,\ OU\=JBoss,\ O\=Red\ Hat,\ C\=CZ

Report a bug

14.1.9. Identity Login Module

Identity login module is a simple login module that associates a hard-coded user name to any subjectauthenticated against the module. It creates a SimplePrincipal instance using the name specified bythe principal option.

NOTE

This module supports password stacking.

domain/authentication=classic:add/subsystem=security/security-domain=app-sec-domain/authentication=classic/login-module=CertificateRoles:add( \ code=CertificateRoles, \ flag=required, \ module-options=[ \ ("securityDomain"=>"trust-domain"), \ ("rolesProperties"=>"app-roles.properties") \ ])

CHAPTER 14. LOGIN MODULES

253

This login module is useful when you need to provide a fixed identity to a service, and in developmentenvironments when you want to test the security associated with a given principal and associated roles.

For details of Identity login module options see Section A.1, “Included Authentication Modules”.

A sample security domain configuration is described below. It authenticates all users as the principalnamed jduke and assigns role names of TheDuke, and AnimatedCharacter:.

Report a bug

14.1.10. RunAs Login Module

RunAs login module is a helper module that pushes a run as role onto the stack for the duration of thelogin phase of authentication, then pops the run as role from the stack in either the commit or abortphase.

The purpose of this login module is to provide a role for other login modules that must access securedresources in order to perform their authentication (for example, a login module that accesses a securedEJB). RunAs login module must be configured ahead of the login modules that require a run as roleestablished.

For details of RunAs login module options see Section A.1, “Included Authentication Modules”.

Report a bug

14.1.10.1. RunAsIdentity Creation

In order for JBoss EAP 6 to secure access to EJB methods, the identity of the user must be known at thetime the method call is made.

A user's identity in the server is represented either by a javax.security.auth.Subject instance oran org.jboss.security.RunAsIdentity instance. Both these classes store one or more principalsthat represent the identity and a list of roles that the identity possesses. In the case of the javax.security.auth.Subject a list of credentials is also stored.

In the <assembly-descriptor> section of the ejb-jar.xml deployment descriptor, you specify one ormore roles that a user must have to access the various EJB methods. A comparison of these lists revealswhether the user has one of the roles necessary to access the EJB method.

Example 14.12. org.jboss.security.RunAsIdentity Creation

/subsystem=security/security-domain=testIdentity:add/subsystem=security/security-domain=testIdentity/authentication=classic:add/subsystem=security/security-domain=testIdentity/authentication=classic/login-module=Identity:add( \ code=Identity, \ flag=required, \ module-options=[ \ ("principal"=>"jduke"), \ ("roles"=>"TheDuke,AnimatedCharacter") \ ])

Security Guide

254

In the ejb-jar.xml file, you specify a <security-identity> element with a <run-as> role defined as achild of the <session> element.

This declaration signifies that an Admin RunAsIdentity role must be created.

To name a principal for the Admin role, you define a <run-as-principal> element in the jboss-ejb3.xml file.

The <security-identity> element in both the ejb-jar.xml and <security> element in the jboss-ejb3.xml files are parsed at deployment time. The <run-as> role name and the <run-as-principal> name are then stored in the org.jboss.metadata.ejb.spec.SecurityIdentityMetaData class.

Example 14.13. Assigning multiple roles to a RunAsIdentity

You can assign more roles to RunAsIdentity by mapping roles to principals in the jboss-ejb3.xmldeployment descriptor <assembly-descriptor> element group.

<session> ... <security-identity> <run-as> <role-name>Admin</role-name> </run-as> </security-identity> ...</session>

<jboss:ejb-jar xmlns="http://java.sun.com/xml/ns/javaee" xmlns:jboss="http://www.jboss.com/xml/ns/javaee" xmlns:s="urn:security:1.1" version="3.1" impl-version="2.0"> <assembly-descriptor> <s:security> <ejb-name>WhoAmIBean</ejb-name> <s:run-as-principal>John</s:run-as-principal> </s:security> </assembly-descriptor></jboss:ejb-jar>

<jboss:ejb-jar xmlns:sr="urn:security-role" ...> <assembly-descriptor> ... <sr:security-role> <sr:role-name>Support</sr:role-name> <sr:principal-name>John</sr:principal-name> <sr:principal-name>Jill</sr:principal-name>

CHAPTER 14. LOGIN MODULES

255

In Example 14.12, “org.jboss.security.RunAsIdentity Creation”, the <run-as-principal> of Johnwas created. The configuration in this example extends the Admin role, by adding the Support role.The new role contains extra principals, including the originally defined principal John.

The <security-role> element in both the ejb-jar.xml and jboss-ejb3.xml files are parsedat deployment time. The <role-name> and the <principal-name> data is stored in the org.jboss.metadata.ejb.spec.SecurityIdentityMetaData class.

Report a bug

14.1.11. Client Login Module

Client login module (org.jboss.security.ClientLoginModule) is an implementation of LoginModule for use by JBoss clients when establishing caller identity and credentials. This creates anew SecurityContext assigns it a principal and a credential and sets the SecurityContext to the ThreadLocal security context.

Client login module is the only supported mechanism for a client to establish the current thread's caller.Both stand-alone client applications, and server environments (acting as JBoss EJB clients where thesecurity environment has not been configured to use the EAP security subsystem transparently) mustuse Client login module.

Note that this login module does not perform any authentication. It merely copies the login informationprovided to it into the server EJB invocation layer for subsequent authentication on the server. If youneed to perform client-side authentication of users you would need to configure another login module inaddition to the Client login module.

For details of Client login module options see Section A.1, “Included Authentication Modules”.

Report a bug

14.1.12. SPNEGO Login Module

SPNEGO login module (org.jboss.security.negotiation.spnego.SPNEGOLoginModule) is animplementation of LoginModule that establishes caller identity and credentials with a KDC. The moduleimplements SPNEGO (Simple and Protected GSSAPI Negotiation mechanism) and is a part of the JBossNegotiation project. This authentication can be used in the chained configuration with the AdvancedLdap login module to allow cooperation with an LDAP server.

For details of SPNEGO login module options see Section A.1, “Included Authentication Modules”.

The JBoss Negotiation module is not included as a standard dependency for deployed applications. Touse the SPNEGO or AdvancedLdap login modules in your project, you must add the dependencymanually by editing the META-INF/jboss-deployment-structure.xml deployment descriptor file.

Example 14.14. Add JBoss Negotiation Module as a Dependency

<sr:principal-name>Tony</sr:principal-name> </sr:security-role> </assembly-descriptor></jboss:ejb-jar>

Security Guide

256

Report a bug

14.1.13. RoleMapping Login Module

RoleMapping login module supports mapping roles, that are the end result of the authenticationprocess, to one or more declarative roles. For example, if the authentication process has determined thatthe user "A" has the roles "ldapAdmin" and "testAdmin", and the declarative role defined in the web.xmlor ejb-jar.xml file for access is admin, then this login module maps the admin roles to the user A.

For details of RoleMapping login module options see Section A.1, “Included Authentication Modules”.

The RoleMapping login module must be defined as an optional module to a login module configurationas it alters mapping of the previously mapped roles.

Example 14.15. Defining mapped roles

Another example achieving the same result, but using the mapping module. This is the preferred methodof role mapping:

Example 14.16. Preferred method of defining mapped roles

<jboss-deployment-structure> <deployment> <dependencies> <module name="org.jboss.security.negotiation" /> </dependencies> </deployment></jboss-deployment-structure>

/subsystem=security/security-domain=test-domain-2/:add/subsystem=security/security-domain=test-domain-2/authentication=classic:add/subsystem=security/security-domain=test-domain-2/authentication=classic/login-module=test-2-lm/:add(\flag=required,\code=UsersRoles,\module-options=[("usersProperties"=>"users.properties"),("rolesProperties"=>"roles.properties")]\)/subsystem=security/security-domain=test-domain-2/authentication=classic/login-module=test2-map/:add(\flag=optional,\code=RoleMapping,\module-options=[("rolesProperties"=>"rolesMapping-roles.properties")]\)

/subsystem=security/security-domain=test-domain-2/:add/subsystem=security/security-domain=test-domain-

CHAPTER 14. LOGIN MODULES

257

Example 14.17. Properties File used by a RoleMappingLoginModule

If the authenticated subject contains role ldapAdmin, then the roles admin and testAdmin areadded to or substitute the authenticated subject depending on the replaceRole property value.

Report a bug

14.1.14. bindCredential Module Option

The bindCredential module option is used to store the credentials for the DN and can be used byseveral login and mapping modules. There are several methods for obtaining the password.

Plaintext in a management CLI command.

The password for the bindCredential module may be provided in plaintext, in a management CLIcommand. For example: ("bindCredential"=>"secret1"). For security reasons, the passwordshould be encrypted using the JBoss EAP vault mechanism.

Use an external command.

To obtain the password from the output of an external command, use the format {EXT}... wherethe ... is the external command. The first line of the command output is used as the password.

To improve performance, the {EXTC[:expiration_in_millis]} variant caches the password fora specified number of milliseconds. By default the cached password does not expire. If the value 0(zero) is specified, the cached credentials do not expire.

The EXTC variant is only supported by the LdapExtended login module.

Example 14.18. Obtain a password from an external command

{EXT}cat /mysecretpasswordfile

2/authentication=classic:add/subsystem=security/security-domain=test-domain-2/authentication=classic/login-module=test-2-lm/:add(\flag=required,\code=UsersRoles,\module-options=[("usersProperties"=>"users.properties"),("rolesProperties"=>"roles.properties")]\)/subsystem=security/security-domain=test-domain-2/mapping=classic/mapping-module=test2-map/:add(\code=PropertiesRoles,type=role,\module-options=[("rolesProperties"=>"rolesMapping-roles.properties")]\)

ldapAdmin=admin, testAdmin

Security Guide

258

Example 14.19. Obtain a password from an external file and cache it for 500 milliseconds

{EXTC:500}cat /mysecretpasswordfile

Report a bug

14.2. CUSTOM MODULES

If the login modules bundled with the EAP security framework do not work with your securityenvironment, you can write your own custom login module implementation. The AuthenticationManager requires a particular usage pattern of the Subject principals set. You mustunderstand the JAAS Subject class's information storage features and the expected usage of thesefeatures to write a login module that works with the AuthenticationManager.

This section examines this requirement and introduces two abstract base LoginModuleimplementations that can help you implement custom login modules.

You can obtain security information associated with a Subject by using the following methods:

For Subject identities and roles, EAP has selected the most logical choice: the principals sets obtainedvia getPrincipals() and getPrincipals(java.lang.Class). The usage pattern is as follows:

User identities (for example; user name, social security number, employee ID) are stored as java.security.Principal objects in the SubjectPrincipals set. The Principalimplementation that represents the user identity must base comparisons and equality on thename of the principal. A suitable implementation is available as the org.jboss.security.SimplePrincipal class. Other Principal instances may beadded to the SubjectPrincipals set as needed.

Assigned user roles are also stored in the Principals set, and are grouped in named role setsusing java.security.acl.Group instances. The Group interface defines a collection of Principals and/or Groups, and is a subinterface of java.security.Principal.

Any number of role sets can be assigned to a Subject.

The EAP security framework uses two well-known role sets with the names Roles and CallerPrincipal.

The Roles group is the collection of Principals for the named roles as known in theapplication domain under which the Subject has been authenticated. This role set is usedby methods like the EJBContext.isCallerInRole(String), which EJBs can use tosee if the current caller belongs to the named application domain role. The securityinterceptor logic that performs method permission checks also uses this role set.

The CallerPrincipal Group consists of the single Principal identity assigned to the

java.util.Set getPrincipals()java.util.Set getPrincipals(java.lang.Class c)java.util.Set getPrivateCredentials()java.util.Set getPrivateCredentials(java.lang.Class c)java.util.Set getPublicCredentials()java.util.Set getPublicCredentials(java.lang.Class c)

CHAPTER 14. LOGIN MODULES

259

user in the application domain. The EJBContext.getCallerPrincipal() method usesthe CallerPrincipal to allow the application domain to map from the operationenvironment identity to a user identity suitable for the application. If a Subject does nothave a CallerPrincipal Group, the application identity is the same as operationalenvironment identity.

Report a bug

14.2.1. Subject Usage Pattern Support

To simplify correct implementation of the Subject usage patterns described in Section 14.2, “CustomModules”, EAP includes login modules that populate the authenticated Subject with a template patternthat enforces correct Subject usage.

AbstractServerLoginModule

The most generic of the two is the org.jboss.security.auth.spi.AbstractServerLoginModule class.

It provides an implementation of the javax.security.auth.spi.LoginModule interface and offersabstract methods for the key tasks specific to an operation environment security infrastructure. The keydetails of the class are highlighted in Example 14.20, “AbstractServerLoginModule Class Fragment”. TheJavaDoc comments detail the responsibilities of subclasses.

IMPORTANT

The loginOk instance variable is pivotal. This must be set to true if the log in succeeds,or false by any subclasses that override the log in method. If this variable is incorrectlyset, the commit method will not correctly update the subject.

Tracking the log in phase outcomes allows login modules to be chained together with control flags.These control flags do not require the login modules to succeed as part of the authentication process.

Example 14.20. AbstractServerLoginModule Class Fragment

package org.jboss.security.auth.spi;/** * This class implements the common functionality required for a JAAS * server-side LoginModule and implements the PicketBox standard * Subject usage pattern of storing identities and roles. Subclass * this module to create your own custom LoginModule and override the * login(), getRoleSets(), and getIdentity() methods. */public abstract class AbstractServerLoginModule implements javax.security.auth.spi.LoginModule{ protected Subject subject; protected CallbackHandler callbackHandler; protected Map sharedState; protected Map options; protected Logger log;

/** Flag indicating if the shared credential should be used */ protected boolean useFirstPass;

Security Guide

260

/** * Flag indicating if the login phase succeeded. Subclasses that * override the login method must set this to true on successful * completion of login */ protected boolean loginOk; // ... /** * Initialize the login module. This stores the subject, * callbackHandler and sharedState and options for the login * session. Subclasses should override if they need to process * their own options. A call to super.initialize(...) must be * made in the case of an override. * * <p> * The options are checked for the <em>password-stacking</em> parameter. * If this is set to "useFirstPass", the login identity will be taken from the * <code>javax.security.auth.login.name</code> value of the sharedState map, * and the proof of identity from the * <code>javax.security.auth.login.password</code> value of the sharedState map. * * @param subject the Subject to update after a successful login. * @param callbackHandler the CallbackHandler that will be used to obtain the * the user identity and credentials. * @param sharedState a Map shared between all configured login module instances * @param options the parameters passed to the login module. */ public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options) { // ... }

/** * Looks for javax.security.auth.login.name and * javax.security.auth.login.password values in the sharedState * map if the useFirstPass option was true and returns true if * they exist. If they do not or are null this method returns * false. * Note that subclasses that override the login method * must set the loginOk var to true if the login succeeds in * order for the commit phase to populate the Subject. This * implementation sets loginOk to true if the login() method * returns true, otherwise, it sets loginOk to false. */ public boolean login()

CHAPTER 14. LOGIN MODULES

261

UsernamePasswordLoginModule

The second abstract base login module suitable for custom login modules is the org.jboss.security.auth.spi.UsernamePasswordLoginModule.

This login module further simplifies custom login module implementation by enforcing a string-baseduser name as the user identity and a char[] password as the authentication credentials. It alsosupports the mapping of anonymous users (indicated by a null user name and password) to a principalwith no roles. The key details of the class are highlighted in the following class fragment. The JavaDoccomments detail the responsibilities of subclasses.

Example 14.21. UsernamePasswordLoginModule Class Fragment

throws LoginException { // ... } /** * Overridden by subclasses to return the Principal that * corresponds to the user primary identity. */ abstract protected Principal getIdentity(); /** * Overridden by subclasses to return the Groups that correspond * to the role sets assigned to the user. Subclasses should * create at least a Group named "Roles" that contains the roles * assigned to the user. A second common group is * "CallerPrincipal," which provides the application identity of * the user rather than the security domain identity. * * @return Group[] containing the sets of roles */ abstract protected Group[] getRoleSets() throws LoginException;}

package org.jboss.security.auth.spi;

/** * An abstract subclass of AbstractServerLoginModule that imposes a * an identity == String username, credentials == String password * view on the login process. Subclasses override the * getUsersPassword() and getUsersRoles() methods to return the * expected password and roles for the user. */public abstract class UsernamePasswordLoginModule extends AbstractServerLoginModule{ /** The login identity */ private Principal identity; /** The proof of login identity */ private char[] credential; /** The principal to use when a null username and password are seen */

Security Guide

262

private Principal unauthenticatedIdentity;

/** * The message digest algorithm used to hash passwords. If null then * plain passwords will be used. */ private String hashAlgorithm = null;

/** * The name of the charset/encoding to use when converting the * password String to a byte array. Default is the platform's * default encoding. */ private String hashCharset = null;

/** The string encoding format to use. Defaults to base64. */ private String hashEncoding = null; // ... /** * Override the superclass method to look for an * unauthenticatedIdentity property. This method first invokes * the super version. * * @param options, * @option unauthenticatedIdentity: the name of the principal to * assign and authenticate when a null username and password are * seen. */ public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options) { super.initialize(subject, callbackHandler, sharedState, options); // Check for unauthenticatedIdentity option. Object option = options.get("unauthenticatedIdentity"); String name = (String) option; if (name != null) { unauthenticatedIdentity = new SimplePrincipal(name); } } // ... /** * A hook that allows subclasses to change the validation of the * input password against the expected password. This version * checks that neither inputPassword or expectedPassword are null * and that inputPassword.equals(expectedPassword) is true; * * @return true if the inputPassword is valid, false otherwise. */ protected boolean validatePassword(String inputPassword, String expectedPassword)

CHAPTER 14. LOGIN MODULES

263

Subclassing Login Modules

The choice of sub-classing the AbstractServerLoginModule versus UsernamePasswordLoginModule is based on whether a string-based user name and credentials areusable for the authentication technology you are writing the login module for. If the string-based semanticis valid, then subclass UsernamePasswordLoginModule, otherwise subclass AbstractServerLoginModule.

Subclassing Steps

The steps your custom login module must execute depend on which base login module class youchoose. When writing a custom login module that integrates with your security infrastructure, you shouldstart by sub-classing AbstractServerLoginModule or UsernamePasswordLoginModule toensure that your login module provides the authenticated Principal information in the form expectedby the EAP security manager.

When sub-classing the AbstractServerLoginModule, you must override the following:

void initialize(Subject, CallbackHandler, Map, Map): if you have customoptions to parse.

boolean login(): to perform the authentication activity. Be sure to set the loginOk instancevariable to true if log in succeeds, false if it fails.

Principal getIdentity(): to return the Principal object for the user authenticated bythe log() step.

Group[] getRoleSets(): to return at least one Group named Roles that contains the rolesassigned to the Principal authenticated during login(). A second common Group is namedCallerPrincipal and provides the user's application identity rather than the security domainidentity.

When sub-classing the UsernamePasswordLoginModule, you must override the following:

void initialize(Subject, CallbackHandler, Map, Map): if you have customoptions to parse.

{ if (inputPassword == null || expectedPassword == null) { return false; } return inputPassword.equals(expectedPassword); } /** * Get the expected password for the current username available * via the getUsername() method. This is called from within the * login() method after the CallbackHandler has returned the * username and candidate password. * * @return the valid password String */ abstract protected String getUsersPassword() throws LoginException;}

Security Guide

264

Group[] getRoleSets(): to return at least one Group named Roles that contains the rolesassigned to the Principal authenticated during login(). A second common Group is namedCallerPrincipal and provides the user's application identity rather than the security domainidentity.

String getUsersPassword(): to return the expected password for the current user nameavailable via the getUsername() method. The getUsersPassword() method is called fromwithin login() after the callbackhandler returns the user name and candidate password.

Report a bug

14.2.2. Custom LoginModule Example

The following information will help you to create a custom Login Module example that extends the UsernamePasswordLoginModule and obtains a user's password and role names from a JNDI lookup.

At the end of this section you will have created a custom JNDI context login module that will return auser's password if you perform a lookup on the context using a name of the form password/<username> (where <username> is the current user being authenticated). Similarly, alookup of the form roles/<username> returns the requested user's roles. In Example 14.22,“JndiUserAndPassLoginModule Custom Login Module” is the source code for the JndiUserAndPassLoginModule custom login module.

Note that because this extends the JBoss UsernamePasswordLoginModule, the JndiUserAndPassLoginModule obtains the user's password and roles from the JNDI store. The JndiUserAndPassLoginModule does not interact with the JAAS LoginModule operations.

Example 14.22. JndiUserAndPassLoginModule Custom Login Module

package org.jboss.book.security.ex2; import java.security.acl.Group;import java.util.Map;import javax.naming.InitialContext;import javax.naming.NamingException;import javax.security.auth.Subject;import javax.security.auth.callback.CallbackHandler;import javax.security.auth.login.LoginException;import org.jboss.logging.Logger;import org.jboss.security.SimpleGroup;import org.jboss.security.SimplePrincipal;import org.jboss.security.auth.spi.UsernamePasswordLoginModule;/** * An example custom login module that obtains passwords and roles for a user from a JNDI lookup. * * @author Scott.Stark@jboss.org */public class JndiUserAndPassLoginModule extends UsernamePasswordLoginModule { /** The JNDI name to the context that handles the password/username lookup */ private String userPathPrefix; /** The JNDI name to the context that handles the roles/username lookup */

CHAPTER 14. LOGIN MODULES

265

private String rolesPathPrefix; private static Logger log = Logger.getLogger(JndiUserAndPassLoginModule.class); /** * Override to obtain the userPathPrefix and rolesPathPrefix options. */ @Override public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options) { super.initialize(subject, callbackHandler, sharedState, options); userPathPrefix = (String) options.get("userPathPrefix"); rolesPathPrefix = (String) options.get("rolesPathPrefix"); } /** * Get the roles the current user belongs to by querying the rolesPathPrefix + '/' + super.getUsername() JNDI location. */ @Override protected Group[] getRoleSets() throws LoginException { try { InitialContext ctx = new InitialContext(); String rolesPath = rolesPathPrefix + '/' + super.getUsername(); String[] roles = (String[]) ctx.lookup(rolesPath); Group[] groups = { new SimpleGroup("Roles") }; log.info("Getting roles for user=" + super.getUsername()); for (int r = 0; r < roles.length; r++) { SimplePrincipal role = new SimplePrincipal(roles[r]); log.info("Found role=" + roles[r]); groups[0].addMember(role); } return groups; } catch (NamingException e) { log.error("Failed to obtain groups for user=" + super.getUsername(), e); throw new LoginException(e.toString(true)); } } /** * Get the password of the current user by querying the userPathPrefix + '/' + super.getUsername() JNDI location. */ @Override protected String getUsersPassword() throws LoginException { try { InitialContext ctx = new InitialContext(); String userPath = userPathPrefix + '/' + super.getUsername(); log.info("Getting password for user=" + super.getUsername()); String passwd = (String) ctx.lookup(userPath); log.info("Found password=" + passwd); return passwd; } catch (NamingException e) { log.error("Failed to obtain password for user=" + super.getUsername(), e); throw new LoginException(e.toString(true));

Security Guide

266

Example 14.23. Definition of security-ex2 security domain with the newly-created custom loginmodule

The choice of using the JndiUserAndPassLoginModule custom login module for the server sideauthentication of the user is determined by the login configuration for the example security domain. TheEJB JAR META-INF/jboss-ejb3.xml descriptor sets the security domain. For a web application it ispart of the WEB-INF/jboss-web.xml file.

Example 14.24. jboss-ejb3.xml Example

Example 14.25. jboss-web.xml example

} }}

/subsystem=security/security-domain=security-ex2/:add/subsystem=security/security-domain=security-ex2/authentication=classic:add/subsystem=security/security-domain=security-ex2/authentication=classic/login-module=ex2/:add(\flag=required,\code=org.jboss.book.security.ex2.JndiUserAndPassLoginModule,\module-options=[("userPathPrefix"=>"/security/store/password"),\("rolesPathPrefix"=>"/security/store/roles")]\)

<?xml version="1.0"?><jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:s="urn:security" version="3.1" impl-version="2.0"> <assembly-descriptor> <s:security> <ejb-name>*</ejb-name> <s:security-domain>security-ex2</s:security-domain> </s:security> </assembly-descriptor></jboss:ejb-jar>

<?xml version="1.0"?><jboss-web> <security-domain>security-ex2</security-domain></jboss-web>

CHAPTER 14. LOGIN MODULES

267

Report a bug

Security Guide

268

CHAPTER 15. ROLE-BASED SECURITY IN APPLICATIONS

15.1. JAVA AUTHENTICATION AND AUTHORIZATION SERVICE (JAAS)

Java Authentication and Authorization Service (JAAS) is a security API which consists of a set of Javapackages designed for user authentication and authorization. The API is a Java implementation of thestandard Pluggable Authentication Modules (PAM) framework. It extends the Java Enterprise Editionaccess control architecture to support user-based authorization.

In JBoss EAP 6, JAAS only provides declarative role-based security. For more information aboutdeclarative security, refer to Section 8.2, “Declarative Security”.

JAAS is independent of any underlying authentication technologies, such as Kerberos or LDAP. You canchange your underlying security structure without changing your application. You only need to changethe JAAS configuration.

Report a bug

15.2. ABOUT JAVA AUTHENTICATION AND AUTHORIZATION SERVICE(JAAS)

The security architecture of JBoss EAP 6 is comprised of the security configuration subsystem, andapplication-specific security configurations which are included in several configuration files within theapplication.

Domain, Server Group, and Server Specific Configuration

Server groups (in a managed domain) and servers (in a standalone server) include the configuration forsecurity domains. A security domain includes information about a combination of authentication,authorization, mapping, and auditing modules, with configuration details. An application specifies whichsecurity domain it requires, by name, in its jboss-web.xml.

Application-specific Configuration

Application-specific configuration takes place in one or more of the following four files.

Table 15.1. Application-Specific Configuration Files

File Description

ejb-jar.xml The deployment descriptor for an EnterpriseJavaBean (EJB) application, located in the META-INF directory of the archive. Use the ejb-jar.xml to specify roles and map them toprincipals, at the application level. You can also limitspecific methods and classes to certain roles. It isalso used for other EJB-specific configuration notrelated to security.

CHAPTER 15. ROLE-BASED SECURITY IN APPLICATIONS

269

web.xml The deployment descriptor for a Java EnterpriseEdition (EE) web application. Use the web.xml todeclare the resource and transport constraints for theapplication, such as limiting the type of HTTPrequests that are allowed. You can also configuresimple web-based authentication in this file. It is alsoused for other application-specific configuration notrelated to security. The security domain theapplication uses for authentication and authorizationis defined in jboss-web.xml.

jboss-ejb3.xml Contains JBoss-specific extensions to the ejb-jar.xml descriptor.

jboss-web.xml Contains JBoss-specific extensions to the web.xmldescriptor.

File Description

NOTE

The ejb-jar.xml and web.xml are defined in the Java Enterprise Edition (Java EE)specification. The jboss-ejb3.xml provides JBoss-specific extensions for the ejb-jar.xml, and the jboss-web.xml provides JBoss-specific extensions for the web.xml.

Report a bug

15.3. USE ROLE-BASED SECURITY IN SERVLETS

To add security to a servlet, you map each servlet to a URL pattern, and create security constraints onthe URL patterns which need to be secured. The security constraints limit access to the URLs to roles.The authentication and authorization are handled by the security domain specified in the WAR's jboss-web.xml.

Prerequisites

Before you use role-based security in a servlet, the security domain used to authenticate and authorizeaccess needs to be configured in the JBoss EAP 6 container.

Procedure 15.1. Add Role-Based Security to Servlets

1. Add mappings between servlets and URL patterns.Use <servlet-mapping> elements in the web.xml to map individual servlets to URLpatterns. The following example maps the servlet called DisplayOpResult to the URL pattern /DisplayOpResult.

<servlet-mapping> <servlet-name>DisplayOpResult</servlet-name> <url-pattern>/DisplayOpResult</url-pattern>

Security Guide

270

2. Add security constraints to the URL patterns.To map the URL pattern to a security constraint, use a <security-constraint>. Thefollowing example constrains access from the URL pattern /DisplayOpResult to be accessedby principals with the role eap_admin. The role needs to be present in the security domain.

You need to specify the authentication method, which can be any of the following: BASIC, FORM, DIGEST, CLIENT-CERT, SPNEGO. This example uses BASIC authentication.

3. Specify the security domain in the WAR's jboss-web.xmlAdd the security domain to the WAR's jboss-web.xml in order to connect the servlets to theconfigured security domain, which knows how to authenticate and authorize principals againstthe security constraints. The following example uses the security domain called acme_domain.

Example 15.1. Example web.xml with Role-Based Security Configured

</servlet-mapping>

<security-constraint> <display-name>Restrict access to role eap_admin</display-name> <web-resource-collection> <web-resource-name>Restrict access to role eap_admin</web-resource-name> <url-pattern>/DisplayOpResult/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>eap_admin</role-name> </auth-constraint> </security-constraint>

<security-role> <role-name>eap_admin</role-name></security-role>

<login-config> <auth-method>BASIC</auth-method></login-config>

<jboss-web> ... <security-domain>acme_domain</security-domain> ...</jboss-web>

<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"

CHAPTER 15. ROLE-BASED SECURITY IN APPLICATIONS

271

Report a bug

15.4. USE A THIRD-PARTY AUTHENTICATION SYSTEM IN YOURAPPLICATION

You can integrate third-party security systems with JBoss EAP 6. These types of systems are usuallytoken-based. The external system performs the authentication and passes a token back to the Webapplication through the request headers. This is often referred to as perimeter authentication. Toconfigure perimeter authentication in your application, add a custom authentication valve. If you have avalve from a third-party provider, be sure it is in your classpath and follow the examples below, alongwith the documentation for your third-party authentication module.

NOTE

The location for configuring valves has changed in JBoss EAP 6. There is no longer a context.xml deployment descriptor. Valves are configured directly in the jboss-web.xml descriptor instead. The context.xml is now ignored.

version="3.0">

<display-name>Use Role-Based Security In Servlets</display-name>

<welcome-file-list> <welcome-file>/index.jsp</welcome-file></welcome-file-list>

<servlet-mapping> <servlet-name>DisplayOpResult</servlet-name> <url-pattern>/DisplayOpResult</url-pattern></servlet-mapping>

<security-constraint> <display-name>Restrict access to role eap_admin</display-name> <web-resource-collection> <web-resource-name>Restrict access to role eap_admin</web-resource-name> <url-pattern>/DisplayOpResult/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>eap_admin</role-name> </auth-constraint> </security-constraint>

<security-role> <role-name>eap_admin</role-name> </security-role>

<login-config> <auth-method>BASIC</auth-method> </login-config>

</web-app>

Security Guide

272

Example 15.2. Basic Authentication Valve

This valve is used for Kerberos-based SSO. It also shows the most simple pattern for specifying athird-party authenticator for your Web application.

Example 15.3. Custom Valve With Header Attributes Set

This example shows how to set custom attributes on your valve. The authenticator checks for thepresence of the header ID and the session key, and passes them into the JAAS framework whichdrives the security layer, as the username and password value. You need a custom JAAS loginmodule which can process the username and password and populate the subject with the correctroles. If no header values match the configured values, regular form-based authentication semanticsapply.

Writing a Custom Authenticator

Writing your own authenticator is out of scope of this document. However, the following Java code isprovided as an example.

Example 15.4. GenericHeaderAuthenticator.java

<jboss-web> <valve> <class-name>org.jboss.security.negotiation.NegotiationAuthenticator</class-name> </valve></jboss-web>

<jboss-web> <valve> <class-name>org.jboss.web.tomcat.security.GenericHeaderAuthenticator</class-name> <param> <param-name>httpHeaderForSSOAuth</param-name> <param-value>sm_ssoid,ct-remote-user,HTTP_OBLIX_UID</param-value> </param> <param> <param-name>sessionCookieForSSOAuth</param-name> <param-value>SMSESSION,CTSESSION,ObSSOCookie</param-value> </param> </valve></jboss-web>

/* * JBoss, Home of Professional Open Source. * Copyright 2006, Red Hat Middleware LLC, and individual contributors * as indicated by the @author tags. See the copyright.txt file in the * distribution for a full listing of individual contributors. *

CHAPTER 15. ROLE-BASED SECURITY IN APPLICATIONS

273

* This is free software; you can redistribute it and/or modify it * under the terms of the GNU Lesser General Public License as * published by the Free Software Foundation; either version 2.1 of * the License, or (at your option) any later version. * * This software is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this software; if not, write to the Free * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA * 02110-1301 USA, or see the FSF site: http://www.fsf.org. */ package org.jboss.web.tomcat.security;

import java.io.IOException;import java.security.Principal;import java.util.StringTokenizer;

import javax.management.JMException;import javax.management.ObjectName;import javax.servlet.http.Cookie;import javax.servlet.http.HttpServletRequest;import javax.servlet.http.HttpServletResponse;

import org.apache.catalina.Realm;import org.apache.catalina.Session;import org.apache.catalina.authenticator.Constants;import org.apache.catalina.connector.Request;import org.apache.catalina.connector.Response;import org.apache.catalina.deploy.LoginConfig;import org.jboss.logging.Logger;

import org.jboss.as.web.security.ExtendedFormAuthenticator;

/** * JBAS-2283: Provide custom header based authentication support * * Header Authenticator that deals with userid from the request header Requires * two attributes configured on the Tomcat Service - one for the http header * denoting the authenticated identity and the other is the SESSION cookie * * @author <a href="mailto:Anil.Saldhana@jboss.org">Anil Saldhana</a> * @author <a href="mailto:sguilhen@redhat.com">Stefan Guilhen</a> * @version $Revision$ * @since Sep 11, 2006 */public class GenericHeaderAuthenticator extends ExtendedFormAuthenticator { protected static Logger log = Logger

Security Guide

274

.getLogger(GenericHeaderAuthenticator.class);

protected boolean trace = log.isTraceEnabled();

// JBAS-4804: GenericHeaderAuthenticator injection of ssoid and // sessioncookie name. private String httpHeaderForSSOAuth = null;

private String sessionCookieForSSOAuth = null;

/** * <p> * Obtain the value of the <code>httpHeaderForSSOAuth</code> attribute. This * attribute is used to indicate the request header ids that have to be * checked in order to retrieve the SSO identity set by a third party * security system. * </p> * * @return a <code>String</code> containing the value of the * <code>httpHeaderForSSOAuth</code> attribute. */ public String getHttpHeaderForSSOAuth() { return httpHeaderForSSOAuth; }

/** * <p> * Set the value of the <code>httpHeaderForSSOAuth</code> attribute. This * attribute is used to indicate the request header ids that have to be * checked in order to retrieve the SSO identity set by a third party * security system. * </p> * * @param httpHeaderForSSOAuth * a <code>String</code> containing the value of the * <code>httpHeaderForSSOAuth</code> attribute. */ public void setHttpHeaderForSSOAuth(String httpHeaderForSSOAuth) { this.httpHeaderForSSOAuth = httpHeaderForSSOAuth; }

/** * <p> * Obtain the value of the <code>sessionCookieForSSOAuth</code> attribute. * This attribute is used to indicate the names of the SSO cookies that may * be present in the request object. * </p> * * @return a <code>String</code> containing the names (separated by a * <code>','</code>) of the SSO cookies that may have been

CHAPTER 15. ROLE-BASED SECURITY IN APPLICATIONS

275

set by a * third party security system in the request. */ public String getSessionCookieForSSOAuth() { return sessionCookieForSSOAuth; }

/** * <p> * Set the value of the <code>sessionCookieForSSOAuth</code> attribute. This * attribute is used to indicate the names of the SSO cookies that may be * present in the request object. * </p> * * @param sessionCookieForSSOAuth * a <code>String</code> containing the names (separated by a * <code>','</code>) of the SSO cookies that may have been set by * a third party security system in the request. */ public void setSessionCookieForSSOAuth(String sessionCookieForSSOAuth) { this.sessionCookieForSSOAuth = sessionCookieForSSOAuth; }

/** * <p> * Creates an instance of <code>GenericHeaderAuthenticator</code>. * </p> */ public GenericHeaderAuthenticator() { super(); }

public boolean authenticate(Request request, HttpServletResponse response, LoginConfig config) throws IOException { log.trace("Authenticating user");

Principal principal = request.getUserPrincipal(); if (principal != null) { if (trace) log.trace("Already authenticated '" + principal.getName() + "'"); return true; }

Realm realm = context.getRealm(); Session session = request.getSessionInternal(true);

String username = getUserId(request); String password = getSessionCookie(request);

Security Guide

276

// Check if there is sso id as well as sessionkey if (username == null || password == null) { log.trace("Username is null or password(sessionkey) is null:fallback to form auth"); return super.authenticate(request, response, config); } principal = realm.authenticate(username, password);

if (principal == null) { forwardToErrorPage(request, response, config); return false; }

session.setNote(Constants.SESS_USERNAME_NOTE, username); session.setNote(Constants.SESS_PASSWORD_NOTE, password); request.setUserPrincipal(principal);

register(request, response, principal, HttpServletRequest.FORM_AUTH, username, password); return true; }

/** * Get the username from the request header * * @param request * @return */ protected String getUserId(Request request) { String ssoid = null; // We can have a comma-separated ids String ids = ""; try { ids = this.getIdentityHeaderId(); } catch (JMException e) { if (trace) log.trace("getUserId exception", e); } if (ids == null || ids.length() == 0) throw new IllegalStateException( "Http headers configuration in tomcat service missing");

StringTokenizer st = new StringTokenizer(ids, ","); while (st.hasMoreTokens()) { ssoid = request.getHeader(st.nextToken()); if (ssoid != null) break; } if (trace) log.trace("SSOID-" + ssoid); return ssoid; }

/** * Obtain the session cookie from the request *

CHAPTER 15. ROLE-BASED SECURITY IN APPLICATIONS

277

* @param request * @return */ protected String getSessionCookie(Request request) { Cookie[] cookies = request.getCookies(); log.trace("Cookies:" + cookies); int numCookies = cookies != null ? cookies.length : 0;

// We can have comma-separated ids String ids = ""; try { ids = this.getSessionCookieId(); log.trace("Session Cookie Ids=" + ids); } catch (JMException e) { if (trace) log.trace("checkSessionCookie exception", e); } if (ids == null || ids.length() == 0) throw new IllegalStateException( "Session cookies configuration in tomcat service missing");

StringTokenizer st = new StringTokenizer(ids, ","); while (st.hasMoreTokens()) { String cookieToken = st.nextToken(); String val = getCookieValue(cookies, numCookies, cookieToken); if (val != null) return val; } if (trace) log.trace("Session Cookie not found"); return null; }

/** * Get the configured header identity id in the tomcat service * * @return * @throws JMException */ protected String getIdentityHeaderId() throws JMException { if (this.httpHeaderForSSOAuth != null) return this.httpHeaderForSSOAuth; return (String) mserver.getAttribute(new ObjectName( "jboss.web:service=WebServer"), "HttpHeaderForSSOAuth"); }

/** * Get the configured session cookie id in the tomcat service * * @return * @throws JMException */ protected String getSessionCookieId() throws JMException { if (this.sessionCookieForSSOAuth != null) return this.sessionCookieForSSOAuth; return (String) mserver.getAttribute(new ObjectName(

Security Guide

278

Report a bug

"jboss.web:service=WebServer"), "SessionCookieForSSOAuth"); }

/** * Get the value of a cookie if the name matches the token * * @param cookies * array of cookies * @param numCookies * number of cookies in the array * @param token * Key * @return value of cookie */ protected String getCookieValue(Cookie[] cookies, int numCookies, String token) { for (int i = 0; i < numCookies; i++) { Cookie cookie = cookies[i]; log.trace("Matching cookieToken:" + token + " with cookie name=" + cookie.getName()); if (token.equals(cookie.getName())) { if (trace) log.trace("Cookie-" + token + " value=" + cookie.getValue()); return cookie.getValue(); } } return null; }}

CHAPTER 15. ROLE-BASED SECURITY IN APPLICATIONS

279

CHAPTER 16. MIGRATION

16.1. CONFIGURE APPLICATION SECURITY CHANGES

Configure security for basic authentication

In previous versions of JBoss EAP, properties files placed in the EAP_HOME/server/SERVER_NAME/conf/ directory were on classpath and could be easily found bythe UsersRolesLoginModule. In JBoss EAP 6, the directory structure has changed. Properties filesmust be packaged within the application to make them available in the classpath.

IMPORTANT

You must stop the server before editing the server configuration file for your change to bepersisted on server restart.

To configure security for basic authentication, add a new security domain under security-domains tothe standalone/configuration/standalone.xml or the domain/configuration/domain.xml server configuration file:

If the JBoss EAP 6 instance is running as a standalone server, ${jboss.server.config.dir}refers to the EAP_HOME/standalone/configuration/ directory. If the instance is running in amanaged domain, ${jboss.server.config.dir} refers to the EAP_HOME/domain/configuration/ directory.

Modify security domain names

In JBoss EAP 6, security domains no longer use the prefix java:/jaas/ in their names.

For Web applications, you must remove this prefix from the security domain configurations in thejboss-web.xml.

For Enterprise applications, you must remove this prefix from the security domain configurationsin the jboss-ejb3.xml file. This file has replaced the jboss.xml in JBoss EAP 6.

Report a bug

<security-domain name="example"> <authentication> <login-module code="UsersRoles" flag="required"> <module-option name="usersProperties" value="${jboss.server.config.dir}/example-users.properties"/> <module-option name="rolesProperties" value="${jboss.server.config.dir}/example-roles.properties"/> </login-module> </authentication></security-domain>

Security Guide

280

APPENDIX A. REFERENCE

A.1. INCLUDED AUTHENTICATION MODULES

The following authentication modules are included in JBoss EAP 6. Some of these handle authorizationas well as authentication. These usually include the word Role within the Code name.

When you configure these modules, use the Code value or the full (package qualified) name to refer tothe module.

Authentication Modules

Table A.1, “RealmDirect”

Table A.2, “RealmDirect Module Options”

Table A.3, “Client”

Table A.4, “Client Module Options”

Table A.5, “Remoting”

Table A.6, “Remoting Module Options”

Table A.7, “Certificate”

Table A.8, “Certificate Module Options”

Table A.9, “CertificateRoles”

Table A.10, “CertificateRoles Module Options”

Table A.11, “Database”

Table A.12, “Database Module Options”

Table A.13, “DatabaseCertificate”

Table A.14, “DatabaseCertificate Module Options”

Table A.15, “Identity”

Table A.16, “Identity Module Options”

Table A.17, “Ldap”

Table A.18, “Ldap Module Options”

Table A.19, “LdapExtended”

Table A.20, “LdapExtended Module Options”

Table A.21, “RoleMapping”

Table A.22, “RoleMapping Module Options”

APPENDIX A. REFERENCE

281

Table A.23, “RunAs”

Table A.24, “RunAs Options”

Table A.25, “Simple”

Table A.26, “ConfiguredIdentity”

Table A.27, “ConfiguredIdentity Module Options”

Table A.28, “SecureIdentity”

Table A.29, “SecureIdentity Module Options”

Table A.30, “PropertiesUsers”

Table A.31, “SimpleUsers”

Table A.32, “LdapUsers”

Table A.33, “Kerberos”

Table A.34, “Kerberos Module Options”

Table A.35, “SPNEGO”

Table A.36, “SPNEGO Module Options”

Table A.37, “AdvancedLdap”

Table A.38, “AdvancedLdap Module Options”

Table A.39, “AdvancedADLdap”

Table A.40, “UsersRoles”

Table A.41, “UsersRoles Module Options”

Custom Authentication Modules

Table A.1. RealmDirect

Code RealmDirect

Class org.jboss.as.security.RealmDirectLoginModule

Description A login module implementation to interface directlywith the security realm. This login module allows allinteractions with the backing store to be delegated tothe realm removing the need for any duplicate andsynchronized definitions. Used for remoting calls andmanagement interface.

Table A.2. RealmDirect Module Options

Security Guide

282

Option Type Default Description

realm string ApplicationRealm Name of the desiredrealm.

Table A.3. Client

Code Client

Class org.jboss.security.ClientLoginModule

Description This login module is designed to establish calleridentity and credentials when JBoss EAP 6 is actingas a client. It should never be used as part of asecurity domain used for server authentication.

Table A.4. Client Module Options

Option Type Default Description

multi-threaded true or false false Set to true if each threadhas its own principal andcredential storage. Setto false to indicate thatall threads in the VMshare the same identityand credential.

password-stacking

useFirstPass or false

false Set to useFirstPassto indicate that this loginmodule should look forinformation stored in theLoginContext to useas the identity. Thisoption can be usedwhen stacking otherlogin modules with thisone.

restore-login-identity

true or false false Set to true if the identityand credential seen atthe start of the login() methodshould be restored afterthe logout() methodis invoked.

Table A.5. Remoting

Code Remoting

Class org.jboss.as.security.remoting.RemotingLoginModule

APPENDIX A. REFERENCE

283

Description This login module is used to check if the requestcurrently being authenticated is a request receivedover a Remoting connection, and if so the identity thatwas created during the Remoting authenticationprocess is used and associated with the currentrequest. If the request did not arrive over a Remotingconnection this module does nothing and allows theJAAS based login to continue to the next module.

Table A.6. Remoting Module Options

Option Type Default Description

password-stacking

useFirstPass or false

false A value of useFirstPassindicates that this loginmodule should first lookto the information storedin the LoginContextfor the identity. Thisoption can be usedwhen stacking otherlogin modules with thisone.

principalClass A fully-qualifiedclassname.

none A Principalimplementation classwhich contains aconstructor that takesString arguments for theprincipal name.

unauthenticatedIdentity

A principal name. none Defines the principalname assigned torequests which containno authenticationinformation. This canallow unprotectedservlets to invokemethods on EJBs thatdo not require a specificrole. Such a principalhas no associated rolesand can only accessunsecured EJBs or EJBmethods that areassociated with the unchecked permissionconstraint.

Table A.7. Certificate

Code Certificate

Class org.jboss.security.auth.spi.BaseCertLoginModule

Security Guide

284

Description This login module is designed to authenticate usersbased on X509 Certificates. A use case forthis is CLIENT-CERT authentication of a webapplication.

Table A.8. Certificate Module Options

Option Type Default Description

securityDomain string other Name of the securitydomain that has theJSSE configuration forthe truststore holding thetrusted certificates.

verifier class none The class name of the org.jboss.security.auth.certs.X509CertificateVerifier to use forverification of the logincertificate.

Table A.9. CertificateRoles

Code CertificateRoles

Class org.jboss.security.auth.spi.CertRolesLoginModule

Description This login module extends the Certificate loginmodule to add role mapping capabilities from aproperties file. It takes all of the same options as theCertificate login module, and adds the followingoptions.

Table A.10. CertificateRoles Module Options

Option Type Default Description

APPENDIX A. REFERENCE

285

rolesProperties string roles.properties The name of theresource or filecontaining the roles toassign to each user. Therole properties file mustbe in the format username=role1,role2 where theusername is the DN ofthe certificate, escapingany = (equals) andspace characters. Thefollowing example is inthe correct format:

CN\=unit-tests-client,\ OU\=Red\ Hat\ Inc.,\ O\=Red\ Hat\ Inc.,\ ST\=North\ Carolina,\ C\=US

defaultRolesProperties

string defaultRoles.properties

Name of the resource orfile to fall back to if the rolesPropertiesfile cannot be found.

roleGroupSeparator

A single character. . (a single period) Which character to useas the role groupseparator in the rolesPropertiesfile.

Option Type Default Description

Table A.11. Database

Code Database

Class org.jboss.security.auth.spi.DatabaseServerLoginModule

Description A JDBC-based login module that supportsauthentication and role mapping. It is based on twological tables, with the following definitions.

Principals: PrincipalID (text), Password (text)

Roles: PrincipalID (text), Role (text), RoleGroup (text)

Security Guide

286

Table A.12. Database Module Options

Option Type Default Description

digestCallback

A fully-qualifiedclassname

none The class name of the DigestCallback implementation thatincludes pre/post digest content like saltsfor hashing the input password. Only usedif hashAlgorithm has been specified.

dsJndiName A JNDI resource java:/DefaultDS

The name of the JNDI resource storingthe authentication information. This optionis required.

hashAlgorithm

String Use plainpasswords

The message digest algorithm used tohash passwords. Supported algorithmsdepend on the Java Security Provider,but the following are supported: MD5, SHA-1, and SHA-256.

hashCharset String The platform'sdefault encoding

The name of the charset/encoding to usewhen converting the password String to abyte array. This includes all supportedJava charset names.

hashEncoding String Base64 The string encoding format to use.

ignorePasswordCase

boolean false A flag indicating if the passwordcomparison should ignore case.

inputValidator

A fully-qualifiedclassname

none The instance of the InputValidatorimplementation used to validate theusername and password supplied by theclient.

principalsQuery

prepared SQLstatement

select Password from Principals where PrincipalID=?

The prepared SQL query to obtain theinformation about the principal.

rolesQuery prepared SQLstatement

none The prepared SQL query to obtain theinformation about the roles. It should beequivalent to select Role, RoleGroup from Roles where PrincipalID=?, where Role is therole name and the RoleGroup columnvalue should always be either Roleswith a capital R or CallerPrincipal.

APPENDIX A. REFERENCE

287

storeDigestCallback

A fully-qualifiedclassname

none The class name of the DigestCallback implementation thatincludes pre/post digest content like saltsfor hashing the store/expected password.Only used if hashStorePassword or hashUserPassword is true and hashAlgorithm has been specified.

suspendResume

boolean true Whether any existing JTA transactionshould be suspended during databaseoperations.

throwValidatorError

boolean false A flag that indicates whether validationerrors should be exposed to clients or not

transactionManagerJndiName

JNDI Resource java:/TransactionManager

The JNDI name of the transactionmanager used by the login module.

Option Type Default Description

Table A.13. DatabaseCertificate

Code DatabaseCertificate

Class org.jboss.security.auth.spi.DatabaseCertLoginModule

Description This login module extends the Certificate loginmodule to add role mapping capabilities from adatabase table. It has the same options plus theseadditional options:

Table A.14. DatabaseCertificate Module Options

Option Type Default Description

dsJndiName A JNDI resource java:/DefaultDS The name of the JNDIresource storing theauthenticationinformation. This optionis required.

Security Guide

288

rolesQuery prepared SQL statement select Role,RoleGroup from Roles where PrincipalID=?

SQL prepared statementto be executed in orderto map roles. It shouldbe an equivalent to select Role, RoleGroup from Roles where PrincipalID=?,where Role is the rolename and theRoleGroup column valueshould always be either Roles with a capital Ror CallerPrincipal.

suspendResume true or false true Whether any existingJTA transaction shouldbe suspended duringdatabase operations.

Option Type Default Description

Table A.15. Identity

Code Identity

Class org.jboss.security.auth.spi.IdentityLoginModule

Description Associates the principal specified in the moduleoptions with any subject authenticated against themodule. The type of Principal class used is org.jboss.security.SimplePrincipal. Ifno principal option is specified a principal with thename of guest is used.

Table A.16. Identity Module Options

Option Type Default Description

principal String guest The name to use for theprincipal.

roles comma-separated list ofstrings

none A comma-delimited listof roles which will beassigned to the subject.

Table A.17. Ldap

Code Ldap

APPENDIX A. REFERENCE

289

Class org.jboss.security.auth.spi.LdapLoginModule

Description Authenticates against an LDAP server, when theusername and password are stored in an LDAPserver that is accessible using a JNDI LDAP provider.Many of the options are not required, because theyare determined by the LDAP provider or theenvironment.

Table A.18. Ldap Module Options

Option Type Default Description

java.naming.factory.initial

class name com.sun.jndi.ldap.LdapCtxFactory

InitialContextFactory implementationclass name.

java.naming.provider.url

ldap:// URL If the value of java.naming.security.protocol is SSL, ldap://localhost:636, otherwise ldap://localhost:389

URL for the LDAPserver.

java.naming.security.authentication

none, simple, or thename of a SASLmechanism

simple The security level to useto bind to the LDAPserver.

java.naming.security.protocol

transport protocol If unspecified,determined by theprovider.

The transport protocol touse for secure access,such as SSL or TLS.

java.naming.security.principal

string none The name of theprincipal forauthenticating the callerto the service. This isbuilt from otherproperties describedbelow.

java.naming.security.credentials

credential type none The type of credentialused by theauthentication scheme.Some examples includehashed password, clear-text password, key, orcertificate. If this propertyis unspecified, thebehavior is determinedby the service provider.

Security Guide

290

principalDNPrefix

string Prefix added to theusername to form theuser DN. You canprompt the user for ausername and build thefully-qualified DN byusing the principalDNPrefix and principalDNSuffix.

principalDNSuffix

string Suffix added to theusername to form theuser DN. You canprompt the user for ausername and build thefully-qualified DN byusing the principalDNPrefix and principalDNSuffix.

useObjectCredential

true or false false Whether the credentialshould be obtained asan opaque Object usingthe org.jboss.security.auth.callback.ObjectCallbacktype of Callback ratherthan as a char[]password using a JAASPasswordCallback. Thisallows for passing non-char[] credentialinformation to the LDAPserver.

rolesCtxDN fully-qualified DN none The fully-qualified DN forthe context to search foruser roles.

userRolesCtxDNAttributeName

attribute none The attribute in the userobject that contains theDN for the context tosearch for user roles.This differs from rolesCtxDN in thatthe context to search fora user's roles may beunique for each user.

Option Type Default Description

APPENDIX A. REFERENCE

291

roleAttributeID attribute roles Name of the attributecontaining the userroles.

roleAttributeIsDN

true or false false Whether or not the roleAttributeIDcontains the fully-qualified DN of a roleobject. If false, the rolename is taken from thevalue of the roleNameAttributeId attribute of thecontext name. Certaindirectory schemas, suchas Microsoft ActiveDirectory, require thisattribute to be set to true.

roleNameAttributeID

attribute name Name of the attributewithin the roleCtxDNcontext which containsthe role name. If the roleAttributeIsDN property is set to true, this property isused to find the roleobject's name attribute.

uidAttributeID attribute uid Name of the attribute inthe UserRolesAttributeDN that correspondsto the user ID. This isused to locate the userroles.

matchOnUserDN true or false false Whether or not thesearch for user rolesshould match on theuser's fully-distinguishedDN or the usernameonly. If true, the fulluser DN is used as thematch value. If false,only the username isused as the match valueagainst the uidAttributeNameattribute.

Option Type Default Description

Security Guide

292

allowEmptyPasswords

true or false false Whether to allow emptypasswords. Most LDAPservers treat emptypasswords asanonymous loginattempts. To rejectempty passwords, setthis to false.

Option Type Default Description

Table A.19. LdapExtended

Code LdapExtended

Class org.jboss.security.auth.spi.LdapExtLoginModule

Description An alternate LDAP login module implementation thatuses searches to locate the bind user and associatedroles. The roles query recursively follows DNs tonavigate a hierarchical role structure. It uses thesame java.naming options as the Ldap module,and uses the following options instead of the otheroptions of the Ldap module.

The authentication happens in 2 steps:

1. An initial bind to the LDAP server is doneusing the bindDN and bindCredentialoptions. The bindDN is a LDAP user withthe ability to search both the baseCtxDNand rolesCtxDN trees for the user androles. The user DN to authenticate against isqueried using the filter specified by the baseFilter attribute.

2. The resulting user DN is authenticated bybinding to the LDAP server using the userDN as the InitialLdapContextenvironment Context.SECURITY_PRINCIPAL. The Context.SECURITY_CREDENTIALSproperty is set to the String passwordobtained by the callback handler.

Table A.20. LdapExtended Module Options

Option Type Default Description

baseCtxDN fully-qualified DN none The fixed DN of the top-level context to beginthe user search.

APPENDIX A. REFERENCE

293

bindCredential string, optionallyencrypted

none See the JBoss EAPApplication SecurityGuide for moreinformation.

bindDN fully-qualified DN none The DN used to bindagainst the LDAP serverfor the user and rolesqueries. This DN needsread and searchpermissions on the baseCtxDN and rolesCtxDN values.

baseFilter LDAP filter string none A search filter used tolocate the context of theuser to authenticate. Theinput username or userDN obtained fromthe login modulecallback is substitutedinto the filter anywhere a{0} expression is used.A common example forthe search filter is (uid={0}).

rolesCtxDN fully-qualified DN none The fixed DN of thecontext to search foruser roles. This is notthe DN where the actualroles are, but the DNwhere the objectscontaining the user rolesare. For example, in aMicrosoft ActiveDirectory server, this isthe DN where the useraccount is.

Option Type Default Description

Security Guide

294

roleFilter LDAP filter string none A search filter used tolocate the rolesassociated with theauthenticated user. Theinput username or userDN obtained fromthe login modulecallback is substitutedinto the filter anywhere a{0} expression is used.The authenticated userDN is substitutedinto the filter anywhere a{1} is used. Anexample search filterthat matches on theinput username is (member={0}). Analternative that matcheson the authenticated userDN is (member={1}).

roleAttributeIsDN

true or false false Whether or not the roleAttributeIDcontains the fully-qualified DN of a roleobject. If false, the rolename is taken from thevalue of the roleNameAttributeId attribute of thecontext name. Certaindirectory schemas, suchas Microsoft ActiveDirectory, require thisattribute to be set to true.

defaultRole Role name none A role included for allauthenticated users

parseRoleNameFromDN

true or false false A flag indicating if theDN returned by a querycontains theroleNameAttributeID. Ifset to true, the DN ischecked for theroleNameATtributeID. Ifset to false, the DN isnot checked for theroleNameAttributeID.This flag can improvethe performance ofLDAP queries.

Option Type Default Description

APPENDIX A. REFERENCE

295

parseUsername true or false false A flag indicating if theDN is to be parsed forthe username. If set to true, the DN is parsedfor the username. If setto false the DN is notparsed for theusername. This option isused together withusernameBeginStringandusernameEndString.

usernameBeginString

string none Defines the string whichis to be removed fromthe start of the DN toreveal the username.This option is usedtogether with usernameEndString.

usernameEndString

string none Defines the string whichis to be removed fromthe end of the DN toreveal the username.This option is usedtogether with usernameBeginString.

roleNameAttributeID

attribute name Name of the attributewithin the roleCtxDNcontext which containsthe role name. If the roleAttributeIsDN property is set to true, this property isused to find the roleobject's name attribute.

distinguishedNameAttribute

attribute distinguishedName

The name of theattribute in the userentry that contains theDN of the user. Thismay be necessary if theDN of the user itselfcontains specialcharacters (backslashfor example) thatprevent correct usermapping. If the attributedoes not exist, theentry's DN is used.

Option Type Default Description

Security Guide

296

roleRecursion integer 0 The numbers of levels ofrecursion the role searchwill go below a matchingcontext. Disablerecursion by setting thisto 0.

searchTimeLimit integer 10000 (10 seconds) The timeout inmilliseconds for user orrole searches.

searchScope One of: OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE

SUBTREE_SCOPE The search scope touse.

allowEmptyPasswords

true or false false Whether to allow emptypasswords. Most LDAPservers treat emptypasswords asanonymous loginattempts. To rejectempty passwords, setthis to false.

referralUserAttributeIDToCheck

attribute none If you are not usingreferrals, this option canbe ignored. When usingreferrals, this optiondenotes the attributename which containsusers defined for acertain role (for example,member), if the roleobject is inside thereferral. Users arechecked against thecontent of this attributename. If this option isnot set, the check willalways fail, so roleobjects cannot be storedin a referral tree.

Option Type Default Description

Table A.21. RoleMapping

Code RoleMapping

Class org.jboss.security.auth.spi.RoleMappingLoginModule

APPENDIX A. REFERENCE

297

Description Maps a role which is the end result of theauthentication process to a declarative role. Thismodule must be flagged as optional when youadd it to the security domain.

Table A.22. RoleMapping Module Options

Option Type Default Description

rolesProperties The fully-qualified filepath and name of aproperties file orresource

none The fully-qualified filepath and name of aproperties file orresource which mapsroles to replacementroles. The format is original_role=role1,role2,role3

replaceRole true or false false Whether to add to thecurrent roles, or replacethe current roles with themapped ones. Replacesif set to true.

NOTE

The rolesProperties module option is required for RoleMapping.

Table A.23. RunAs

Code RunAs

Class org.jboss.security.auth.spi.RunAsLoginModule

Description A helper module that pushes a run as role onto thestack for the duration of the login phase ofauthentication, and pops the run as role off thestack in either the commit or abort phase. This loginmodule provides a role for other login modules thatmust access secured resources in order to performtheir authentication, such as a login module whichaccesses a secured EJB. RunAsLoginModulemust be configured before the login modules thatrequire a run as role to be established.

Table A.24. RunAs Options

Option Type Default Description

Security Guide

298

roleName role name nobody The name of the role touse as the run as roleduring the login phase.

principalName principal name nobody Name of the principal touse as the run asprincipal during loginphase. If not specified adefault of nobody isused.

principalClass A fully-qualifiedclassname.

none A Principalimplementation classwhich contains aconstructor that takesString arguments for theprincipal name.

Option Type Default Description

Table A.25. Simple

Code Simple

Class org.jboss.security.auth.spi.SimpleServerLoginModule

Description A module for quick setup of security for testingpurposes. It implements the following simplealgorithm:

If the password is null, authenticate the userand assign an identity of guest and a roleof guest.

Otherwise, if the password is equal to theuser, assign an identity equal to theusername and both admin and guestroles.

Otherwise, authentication fails.

Simple Module Options

The Simple module has no options.

Table A.26. ConfiguredIdentity

Code ConfiguredIdentity

Class org.picketbox.datasource.security.ConfiguredIdentityLoginModule

APPENDIX A. REFERENCE

299

Description Associates the principal specified in the moduleoptions with any subject authenticated against themodule. The type of Principal class used is org.jboss.security.SimplePrincipal.

Table A.27. ConfiguredIdentity Module Options

Option Type Default Description

username string none The username forauthentication.

password encrypted string "" The password to use forauthentication. Toencrypt the password,use the module directlyat the command line.

java org.picketbox.datasource.security.SecureIdentityLoginModule password_to_encrypt

Paste the result of thiscommand into themodule option's valuefield. The default valueis an empty string.

principal Name of a principal none The principal which willbe associated with anysubject authenticatedagainst the module.

Table A.28. SecureIdentity

Code SecureIdentity

Class org.picketbox.datasource.security.SecureIdentityLoginModule

Description This module is provided for legacy purposes. Itallows you to encrypt a password and then use theencrypted password with a static principal. If yourapplication uses SecureIdentity, considerusing a password vault mechanism instead.

Table A.29. SecureIdentity Module Options

Security Guide

300

Option Type Default Description

username string none The username forauthentication.

password encrypted string "" The password to use forauthentication. Toencrypt the password,use the module directlyat the command line.

java org.picketbox.datasource.security.SecureIdentityLoginModule password_to_encrypt

Paste the result of thiscommand into themodule option's valuefield. The default valueis an empty string.

managedConnectionFactoryName

JCA resource none The name of the JCAconnection factory foryour datasource.

Table A.30. PropertiesUsers

Code PropertiesUsers

Class org.jboss.security.auth.spi.PropertiesUsersLoginModule

Description Uses a properties file to store usernames andpasswords for authentication. No authorization (rolemapping) is provided. This module is onlyappropriate for testing.

Table A.31. SimpleUsers

Code SimpleUsers

Class org.jboss.security.auth.spi.SimpleUsersLoginModule

APPENDIX A. REFERENCE

301

Description This login module stores the username and clear-textpassword using module-option. module-option's name and value attributes specify ausername and password. It is included for testingonly, and is not appropriate for a productionenvironment.

Table A.32. LdapUsers

Code LdapUsers

Class org.jboss.security.auth.spi.LdapUsersLoginModule

Description The LdapUsers module is superseded by the ExtendedLDAP and AdvancedLdap modules.

Table A.33. Kerberos

Code Kerberos

Class com.sun.security.auth.module.Krb5LoginModule. In the IBM JDK the classname is com.ibm.security.auth.module.Krb5LoginModule.

Description Performs Kerberos login authentication, usingGSSAPI. This module is part of the securityframework from the API provided by SunMicrosystems. Details can be found athttp://docs.oracle.com/javase/7/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html. This module needs to be paired withanother module which handles the authentication androles mapping.

Table A.34. Kerberos Module Options

Option Type Default Description

storekey true or false false Whether or not to addthe KerberosKey tothe subject's privatecredentials.

doNotPrompt true or false false If set to true, the useris not prompted for thepassword if credentialscannot be obtained fromthe cache, the keytab, orthrough shared state.

Security Guide

302

useTicketCache Boolean value of trueor false.

false If true, the TGT isobtained from the ticketcache. If false, theticket cache is not used.

ticketcache A file or resourcerepresenting a Kerberosticket cache. If this is set,useTicketCachemust also be set to true, otherwise aconfiguration error willbe returned.

The default depends onwhich operating systemyou use.

Red HatEnterpriseLinux / Solaris: /tmp/krb5cc_uid, usingthe numericUID value ofthe operatingsystem.

MicrosoftWindowsServer: usesthe LocalSecurityAuthority (LSA)API to find theticketcache.

The location of the ticketcache.

useKeyTab true or false false Whether to obtain theprincipal's key from akey table file.

keytab A file or resourcerepresenting a Kerberoskeytab.

the location in theoperating system'sKerberos configurationfile, or /home/user/krb5.keytab

The location of the keytable file.

principal string none The name of theprincipal. This can eitherbe a simple user nameor a service name suchas host/testserver.acme.com. Use thisinstead of obtaining theprincipal from the keytable, or when the keytable contains more thanone principal.

Option Type Default Description

APPENDIX A. REFERENCE

303

useFirstPass true or false false Whether to retrieve theusername and passwordfrom the module'sshared state, using javax.security.auth.login.nameand javax.security.auth.login.password as the keys. Ifauthentication fails, noretry attempt is made.

tryFirstPass true or false false Same as useFirstPass, but ifauthentication fails, themodule uses the CallbackHandler toretrieve a new usernameand password. If thesecond authenticationfails, the failure isreported to the callingapplication.

storePass true or false false Whether to store theusername and passwordin the module's sharedstate. This does nothappen if the keysalready exist in theshared state, or ifauthentication fails.

clearPass true or false false Set this to true to clearthe username andpassword from theshared state after bothphases of authenticationcomplete.

Option Type Default Description

Table A.35. SPNEGO

Code SPNEGO

Class org.jboss.security.negotiation.spnego.SPNEGOLoginModule

Description Allows SPNEGO authentication to a Microsoft ActiveDirectory server or other environment which supportsSPNEGO. SPNEGO can also carry Kerberoscredentials. This module needs to be paired withanother module which handles authentication androle mapping.

Security Guide

304

Table A.36. SPNEGO Module Options

Option Type Default Description

serverSecurityDomain

string null. Defines the domain thatis used to retrieve theidentity of the serverservice through thekerberos login module.This property must beset.

removeRealmFromPrincipal

boolean false Specifies that theKerberos realm shouldbe removed from theprincipal before furtherprocessing.

usernamePasswordDomain

string null Specifies anothersecurity domain withinthe configuration thatshould be used as afailover login whenKerberos fails.

Table A.37. AdvancedLdap

Code AdvancedLdap

Class org.jboss.security.negotiation.AdvancedLdapLoginModule

Description A module which provides additional functionality,such as SASL and the use of a JAAS securitydomain.

Table A.38. AdvancedLdap Module Options

Option Type Default Description

bindAuthentication

string none The type of SASLauthentication to use forbinding to the directoryserver.

java.naming.provider.url

string If the value of java.naming.security.protocol is SSL, ldap://localhost:686, otherwise ldap://localhost:389

The URI of the directoryserver.

APPENDIX A. REFERENCE

305

baseCtxDN fully-qualified DN none The distinguished nameto use as the base forsearches.

baseFilter String representing aLDAP search filter.

none The filter to use tonarrow down searchresults.

roleAttributeID String valuerepresenting an LDAPattribute.

none The LDAP attributewhich contains thenames of authorizationroles.

roleAttributeIsDN

true or false false Whether the roleattribute is aDistinguished Name(DN).

roleNameAttributeID

String representing anLDAP attribute.

none The attribute containedwithin the RoleAttributeIdwhich contains theactual role attribute.

recurseRoles true or false false Whether to recursivelysearch the RoleAttributeIdfor roles.

referralUserAttributeIDToCheck

attribute none If you are not usingreferrals, this option canbe ignored. When usingreferrals, this optiondenotes the attributename which containsusers defined for acertain role (for example,member), if the roleobject is inside thereferral. Users arechecked against thecontent of this attributename. If this option isnot set, the check willalways fail, so roleobjects cannot be storedin a referral tree.

Option Type Default Description

Table A.39. AdvancedADLdap

Code AdvancedADLdap

Security Guide

306

Class org.jboss.security.negotiation.AdvancedADLoginModule

Description This module extends the AdvancedLdap loginmodule, and adds extra parameters that are relevantto Microsoft Active Directory.

Table A.40. UsersRoles

Code UsersRoles

Class org.jboss.security.auth.spi.UsersRolesLoginModul

Description A simple login module that supports multiple usersand user roles stored in two different properties files.

Table A.41. UsersRoles Module Options

Option Type Default Description

usersProperties Path to a file orresource.

users.properties The file or resourcewhich contains the user-to-password mappings.The format of the file is username=password

rolesProperties Path to a file orresource.

roles.properties The file or resourcewhich contains the user-to-role mappings. Theformat of the file is username=role1,role2,role3

password-stacking

useFirstPass or false

false A value of useFirstPassindicates that this loginmodule should first lookto the information storedin the LoginContextfor the identity. Thisoption can be usedwhen stacking otherlogin modules with thisone.

APPENDIX A. REFERENCE

307

hashAlgorithm String representing apassword hashingalgorithm.

none The name of the java.security.MessageDigestalgorithm to use to hashthe password. There isno default so this optionmust be explicitly set toenable hashing. When hashAlgorithm isspecified, the clear textpassword obtained fromthe CallbackHandler ishashed before it ispassed to UsernamePasswordLoginModule.validatePassword as theinputPasswordargument. Thepassword stored in the users.propertiesfile must be comparablyhashed.

hashEncoding base64 or hex base64 The string format for thehashed password, ifhashAlgorithm is alsoset.

hashCharset string The default encoding setin the container'sruntime environment

The encoding used toconvert the clear-textpassword to a bytearray.

unauthenticatedIdentity

principal name none Defines the principalname assigned torequests which containno authenticationinformation. This canallow unprotectedservlets to invokemethods on EJBs thatdo not require a specificrole. Such a principalhas no associated rolesand can only accessunsecured EJBs or EJBmethods that areassociated with the unchecked permissionconstraint.

Option Type Default Description

Custom Authentication Modules

Security Guide

308

Authentication modules are implementations of javax.security.auth.spi.LoginModule. Refer tothe API documentation for more information about creating a custom authentication module.

Report a bug

A.2. INCLUDED AUTHORIZATION MODULES

The following modules provide authorization services.

Code Class

DenyAll org.jboss.security.authorization.modules.AllDenyAuthorizationModule

PermitAll org.jboss.security.authorization.modules.AllPermitAuthorizationModule

Delegating org.jboss.security.authorization.modules.DelegatingAuthorizationModule

Web org.jboss.security.authorization.modules.web.WebAuthorizationModule

JACC org.jboss.security.authorization.modules.JACCAuthorizationModule

XACML org.jboss.security.authorization.modules.XACMLAuthorizationModule

AllDenyAuthorizationModule

This is a simple authorization module that always denies an authorization request. No configurationoptions are available.

AllPermitAuthorizationModule

This is a simple authorization module that always permits an authorization request. No configurationoptions are available.

DelegatingAuthorizationModule

This is the default authorization module that delegates decision making to the configured delegates.

WebAuthorizationModule

This is the default web authorization module with the default Tomcat authorization logic (permit all).

JACCAuthorizationModule

This module enforces JACC semantics using two delegates (WebJACCPolicyModuleDelegate for webcontainer authorization requests and EJBJACCPolicyModuleDelegate for EJB container requests). Noconfiguration options available.

XACMLAuthorizationModule

APPENDIX A. REFERENCE

309

This module enforces XACML authorization using two delegates for web and EJB containers(WebXACMLPolicyModuleDelegate and EJBXACMLPolicyModuleDelegate). It creates a PDP objectbased on registered policies and evaluates web or EJB requests against it.

AbstractAuthorizationModule

This is the base authorization module which has to be overridden and provides a facility for delegating toother authorization modules.

Report a bug

A.3. INCLUDED SECURITY MAPPING MODULES

The following security mapping roles are provided in JBoss EAP 6.

Code Class

PropertiesRoles org.jboss.security.mapping.providers.role.PropertiesRolesMappingProvider

SimpleRoles org.jboss.security.mapping.providers.role.SimpleRolesMappingProvider

DeploymentRoles org.jboss.security.mapping.providers.DeploymentRolesMappingProvider

DatabaseRoles org.jboss.security.mapping.providers.role.DatabaseRolesMappingProvider

LdapRoles org.jboss.security.mapping.providers.role.LdapRolesMappingProvider

LdapAttributes org.jboss.security.mapping.providers.attribute.LdapAttributeMappingProvider

DeploymentRolesMappingProvider

A Role Mapping Module that takes into consideration a principal to roles mapping that can be done in jboss-web.xml and jboss-app.xml deployment descriptors.

Example A.1. Example

<jboss-web>... <security-role> <role-name>Support</role-name> <principal-name>Mark</principal-name> <principal-name>Tom</principal-name> </security-role>...</jboss-web>

Security Guide

310

org.jboss.security.mapping.providers.DeploymentRoleToRolesMappingProvider

A Role to Roles Mapping Module that takes into consideration a principal to roles mapping that can bedone in the deployment descriptors jboss-web.xml and jboss-app.xml. In this case principal-namedenotes role to map other roles.

Example A.2. Example

Which means that each principal having role Support or Sales will also have role Employee assigned.

org.jboss.security.mapping.providers.OptionsRoleMappingProvider

Role Mapping Provider that picks up the roles from the options and then appends them to the passedGroup. Takes the properties style mapping of role name (key) with a comma separated list of roles(values).

org.jboss.security.mapping.providers.principal.SimplePrincipalMappingProvider

A principal mapping provider that takes in a SimplePrincipal and converts into SimplePrincipal with adifferent principal name.

DatabaseRolesMappingProvider

A MappingProvider that reads roles from a database.

Options:

dsJndiName: JNDI name of data source used to map roles to the user.

rolesQuery: This option should be a prepared statement equivalent to "select RoleName fromRoles where User=?" ? is substituted with current principal name.

suspendResume: Boolean - To suspend and later resume transaction associated with currentthread while performing search for roles.

transactionManagerJndiName: JNDI name of Transaction mamager (default isjava:/TransactionManager)

LdapRolesMappingProvider

A mapping provider that assigns roles to an user using a LDAP server to search for the roles.

Options:

<jboss-web> ... <security-role> <role-name>Employee</role-name> <principal-name>Support</principal-name> <principal-name>Sales</principal-name> </security-role> ... </jboss-web>

APPENDIX A. REFERENCE

311

bindDN: The DN used to bind against the LDAP server for the user and roles queries. This DNneeds read and search permissions on the baseCtxDN and rolesCtxDN values.

bindCredential: The password for the bindDN. This can be encrypted if thejaasSecurityDomain is specified.

rolesCtxDN: The fixed DN of the context to search for user roles. This is not the DN where theactual roles are, but the DN where the objects containing the user roles are. For example, in aMicrosoft Active Directory server, this is the DN where the user account is.

roleAttributeID: The LDAP attribute which contains the names of authorization roles.

roleAttributeIsDN: Whether or not the roleAttributeID contains the fully-qualified DNof a role object. If false, the role name is taken from the value of the roleNameAttributeIdattribute of the context name. Certain directory schemas, such as Microsoft Active Directory,require this attribute to be set to true.

roleNameAttributeID: Name of the attribute within the roleCtxDN context which containsthe role name. If the roleAttributeIsDN property is set to true, this property is used to findthe role object's name attribute.

parseRoleNameFromDN: A flag indicating if the DN returned by a query contains theroleNameAttributeID. If set to true, the DN is checked for the roleNameATtributeID. If set to false, the DN is not checked for the roleNameAttributeID. This flag can improve theperformance of LDAP queries.

roleFilter: A search filter used to locate the roles associated with the authenticated user.The input username or userDN obtained from the login module callback is substituted into thefilter anywhere a {0} expression is used. The authenticated userDN is substituted into the filteranywhere a {1} is used. An example search filter that matches on the input username is (member={0}). An alternative that matches on the authenticated userDN is (member={1}).

roleRecursion: The numbers of levels of recursion the role search will go below a matchingcontext. Disable recursion by setting this to 0.

searchTimeLimit: The timeout in milliseconds for the user/role searches. Defaults to 10000(10 seconds).

searchScope: The search scope to use.

PropertiesRolesMappingProvider

A MappingProvider that reads roles from a properties file in the following format:username=role1,role2,...

Options:

rolesProperties: Properties formatted file name. Expansion of JBoss variables can be usedin form of ${jboss.variable}.

SimpleRolesMappingProvider

A simple MappingProvider that reads roles from the options map. The option attribute name is the nameof principal to assign roles to and the attribute value is the comma separated role names to assign to theprincipal.

Security Guide

312

Example A.3. Example

org.jboss.security.mapping.providers.attribute.DefaultAttributeMappingProvider

Checks module and locates principal name from mapping context to create attribute e-mail address frommodule option named principalName + ".email" and maps it to the given principal.

LdapAttributeMappingProvider

Maps attributes from LDAP to the subject. The options include whatever options your LDAP JNDIprovider supports.

Example A.4. Examples of standard property names include:

Options:

bindDN: The DN used to bind against the LDAP server for the user and roles queries. This DNneeds read and search permissions on the baseCtxDN and rolesCtxDN values.

bindCredential: The password for the bindDN. This can be encrypted if thejaasSecurityDomain is specified.

baseCtxDN: The fixed DN of the context to start the user search from.

baseFilter: A search filter used to locate the context of the user to authenticate. The inputusername or userDN as obtained from the login module callback is substituted into the filteranywhere a {0} expression is used. This substituion behavior comes from the standard __DirContext.search(Name, String, Object[], SearchControls cons)__method. An common example search filter is (uid={0}).

searchTimeLimit: The timeout in milliseconds for the user/role searches. Defaults to 10000(10 seconds).

attributeList: A comma-separated list of attributes for the user. For example,mail,cn,sn,employeeType,employeeNumber.

jaasSecurityDomain: The JaasSecurityDomain to use to decrypt the java.naming.security.principal. The encrypted form of the password is that returnedby the JaasSecurityDomain#encrypt64(byte[]) method. The org.jboss.security.plugins.PBEUtils can also be used to generate the encryptedform.

Report a bug

<module-option name="JavaDuke" value="JBossAdmin,Admin"/> <module-option name="joe" value="Users"/>

Context.INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial"Context.SECURITY_PROTOCOL = "java.naming.security.protocol"Context.PROVIDER_URL = "java.naming.provider.url"Context.SECURITY_AUTHENTICATION = "java.naming.security.authentication"

APPENDIX A. REFERENCE

313

A.4. INCLUDED SECURITY AUDITING PROVIDER MODULES

JBoss EAP 6 provides one security auditing provider.

Code Class

LogAuditProvider org.jboss.security.audit.providers.LogAuditProvider

Report a bug

A.5. JBOSS-WEB.XML CONFIGURATION REFERENCE

Introduction

The jboss-web.xml and web.xml deployment descriptors are both placed in the deployment's WEB-INF directory. The jboss-web.xml is a web application deployment descriptor for JBoss EAP whichcontains additional configuration options for additional features of JBoss Web. This descriptor can beused to override the settings from web.xml descriptor and to set JBoss EAP specific settings.

Mapping Global Resources to WAR Requirements

Many of the available settings map requirements set in the application's web.xml to local resources. Theexplanations of the web.xml settings can be found athttp://docs.oracle.com/cd/E13222_01/wls/docs81/webapp/web_xml.html.

For instance, if the web.xml requires jdbc/MyDataSource, the jboss-web.xml may map the globaldatasource java:/DefaultDS to fulfill this need. The WAR uses the global datasource to fill its needfor jdbc/MyDataSource.

Table A.42. Common Top-Level Attributes of jboss-web.xml

Attribute Description

servlet The servlet element specifies servlet specificbindings.

max-active-sessions Determines the max number of active sessionsallowed. If the number of sessions managed by thesession manager exceeds this value and passivation is enabled, the excess will bepassivated based on the configured passivation-min-idle-time

If set to -1, means no limit.

replication-config The replication-config element is used forconfiguring session replication in the jboss-web.xml file.

passivation-config The passivation-config element is used forconfiguring session passivation in the jboss-web.xml file.

Security Guide

314

distinct-name The distinct-name element specifies the EJB 3distinct name for the web application.

data-source A mapping to a data-source required by the web.xml.

context-root The root context of the application. The default valueis the name of the deployment without the .warsuffix.

virtual-host The name of the HTTP virtual-host the applicationaccepts requests from. It refers to the contents of theHTTP Host header.

annotation Describes an annotation used by the application.Refer to <annotation> for more information.

listener Describes a listener used by the application. Refer to<listener> for more information.

session-config This element fills the same function as the <session-config> element of the web.xmland is included for compatibility only.

valve Describes a valve used by the application. Refer to<valve> for more information.

overlay The name of an overlay to add to the application.

security-domain The name of the security domain used by theapplication. The security domain itself is configured inthe web-based management console or themanagement CLI.

security-role This element fills the same function as the <security-role> element of the web.xml andis included for compatibility only.

jacc-star-role-allow The jacc-star-role-allow element specifieswhether the jacc permission generating agent in theweb layer needs to generate a WebResourcePermission permission such thatthe jacc provider can make a decision as to bypassauthorization or not.

Attribute Description

APPENDIX A. REFERENCE

315

use-jboss-authorization If this element is present and contains the caseinsensitive value "true", the JBoss web authorizationstack is used. If it is not present or contains any valuethat is not "true", then only the authorizationmechanisms specified in the Java Enterprise Editionspecifications are used. This element is new to JBossEAP 6.

disable-audit Set this boolean element to false to enable and true to disable web auditing. Web security auditingis not part of the Java EE specification. This elementis new to JBoss EAP 6.

disable-cross-context If false, the application is able to call anotherapplication context. Defaults to true.

enable-websockets Set this element to true in jboss-web.xml tospecify if websockets access should be enabled forthe web application.

Attribute Description

The following elements each have child elements.

<annotation>

Describes an annotation used by the application. The following table lists the child elements of an <annotation>.

Table A.43. Annotation Configuration Elements

Attribute Description

class-name Name of the class of the annotation

servlet-security The element, such as @ServletSecurity, whichrepresents servlet security.

run-as The element, such as @RunAs, which represents therun-as information.

multipart-config The element, such as @MultiPart, whichrepresents the multipart-config information.

<listener>

Describes a listener. The following table lists the child elements of a <listener>.

Table A.44. Listener Configuration Elements

Security Guide

316

Attribute Description

class-name Name of the class of the listener

listener-type List of condition elements, which indicate whatkind of listener to add to the Context of theapplication. Valid choices are:

CONTAINER

Adds a ContainerListener to the Context.

LIFECYCLE

Adds a LifecycleListener to the Context.

SERVLET_INSTANCE

Adds an InstanceListener to the Context.

SERVLET_CONTAINER

Adds a WrapperListener to the Context.

SERVLET_LIFECYCLE

Adds a WrapperLifecycle to the Context.

module The name of the module containing the listener class.

param A parameter. Contains two child elements, <param-name> and <param-value>.

<valve>

Describes a valve of the application. Similar to the <listener>, has class-name, module and paramelements.

Report a bug

A.6. EJB SECURITY PARAMETER REFERENCE

Table A.45. EJB security parameter elements

Element Description

<security-identity> Contains child elements pertaining to the securityidentity of an EJB.

<use-caller-identity /> Indicates that the EJB uses the same security identityas the caller.

<run-as> Contains a <role-name> element.

APPENDIX A. REFERENCE

317

<run-as-principal> If present, indicates the principal assigned tooutgoing calls. If not present, outgoing calls areassigned to a principal named anonymous.

<role-name> Specifies the role the EJB should run as.

<description> Describes the role named in <role-name>.

Element Description

Example A.5. Security identity examples

This example shows each tag described in Table A.45, “EJB security parameter elements”. They canalso be used inside a <session>.

Report a bug

<ejb-jar> <enterprise-beans> <session> <ejb-name>ASessionBean</ejb-name> <security-identity> <use-caller-identity/> </security-identity> </session> <session> <ejb-name>RunAsBean</ejb-name> <security-identity> <run-as> <description>A private internal role</description> <role-name>InternalRole</role-name> </run-as> </security-identity> </session> <session> <ejb-name>RunAsBean</ejb-name> <security-identity> <run-as-principal>internal</run-as-principal> </security-identity> </session> </enterprise-beans></ejb-jar>

Security Guide

318

APPENDIX B. REVISION HISTORY

Revision 6.4.0-11 Tuesday April 14 2015 Lucas CostiRed Hat JBoss Enterprise Application Platform 6.4.0.GA

APPENDIX B. REVISION HISTORY

319