JBoss Enterprise Application Platform 6.3 Security Guide en US

JBoss Enterprise Application
Platform 6.3
Security Guide
For Use with Red Hat JBoss Enterprise Application Platform 6
Red Hat Customer Content Services
JBoss Enterprise Application Platform 6.3 Security Guide
For Use with Red Hat JBoss Enterprise Application Platform 6
Legal Notice
Co pyright 20 14 Red Hat, Inc..
This do cument is licensed by Red Hat under the Creative Co mmo ns Attributio n-ShareAlike 3.0
Unpo rted License. If yo u distribute this do cument, o r a mo dified versio n o f it, yo u must pro vide
attributio n to Red Hat, Inc. and pro vide a link to the o riginal. If the do cument is mo dified, all Red
Hat trademarks must be remo ved.
Red Hat, as the licenso r o f this do cument, waives the right to enfo rce, and agrees no t to assert,
Sectio n 4 d o f CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shado wman lo go , JBo ss, MetaMatrix, Fedo ra, the Infinity
Lo go , and RHCE are trademarks o f Red Hat, Inc., registered in the United States and o ther
co untries.
Linux is the registered trademark o f Linus To rvalds in the United States and o ther co untries.
Java is a registered trademark o f Oracle and/o r its affiliates.
XFS is a trademark o f Silico n Graphics Internatio nal Co rp. o r its subsidiaries in the United
States and/o r o ther co untries.
MySQL is a registered trademark o f MySQL AB in the United States, the Euro pean Unio n and
o ther co untries.
No de.js is an o fficial trademark o f Jo yent. Red Hat So ftware Co llectio ns is no t fo rmally
related to o r endo rsed by the o fficial Jo yent No de.js o pen so urce o r co mmercial pro ject.
The OpenStack Wo rd Mark and OpenStack Lo go are either registered trademarks/service
marks o r trademarks/service marks o f the OpenStack Fo undatio n, in the United States and o ther
co untries and are used with the OpenStack Fo undatio n's permissio n. We are no t affiliated with,
endo rsed o r spo nso red by the OpenStack Fo undatio n, o r the OpenStack co mmunity.
All o ther trademarks are the pro perty o f their respective o wners.
Abstract
This bo o k is a guide to securing Red Hat JBo ss Enterprise Applicatio n Platfo rm 6 and its patch
releases.
T able of Cont ent s
T able of Contents
.Preface
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7. . . . . . . . . .
1. Do c ument Co nventio ns
7
1.1. Typ o g rap hic Co nventio ns
7
1.2. Pull-q uo te Co nventio ns
8
1.3. No tes and Warning s
9
2 . G etting Help and G iving Feed b ac k
9
2 .1. Do Yo u Need Help ?
2 .2. We Need Feed b ac k!
9
10
. .art
P
. . .I.. Securit
......y
. .for
. . .Red
. . . .Hat
. . . .JBoss
. . . . . Ent
. . . .erprise
. . . . . . Applicat
. . . . . . . ion
. . . .Plat
. . . form
. . . . .6. . . . . . . . . . . . . . . . . . . . . . . . .1. 1. . . . . . . . . .
. .hapt
C
. . . .er
. .1. .. Int
. . .roduct
. . . . . .ion
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. 2. . . . . . . . . .
1.1. Ab o ut Red Hat JBo s s Enterp ris e Ap p lic atio n Platfo rm 6
12
1.2. Ab o ut Sec uring JBo s s EAP 6
12
. .art
P
. . .II.. .Securing
. . . . . . . .t.he
. . Plat
. . . .form
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. 3. . . . . . . . . .
. .hapt
C
. . . .er
. .2. .. Java
. . . . Securit
. . . . . . .y. Manager
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. 4. . . . . . . . . .
2 .1. Ab o ut the Java Sec urity Manag er
2 .2. Ab o ut Java Sec urity Manag er Po lic ies
14
14
2 .3. Run JBo s s EAP 6 Within the Java Sec urity Manag er
2 .4. Write a Java Sec urity Manag er Po lic y
15
16
2 .5. IBM JRE and the Java Sec urity Manag er

2 .6 . Deb ug Sec urity Manag er Po lic ies
17
17
. .hapt
C
. . . .er
. .3.
. .Securit
. . . . . . y. .Realms
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. 9. . . . . . . . . .
3 .1. Ab o ut Sec urity Realms
3 .2. Ad d a New Sec urity Realm
19
19
3 .3. Ad d a Us er to a Sec urity Realm
20
. .hapt
C
. . . .er
. .4. .. Encrypt
. . . . . . . .Net
. . .work
. . . .T
. .raffic
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. 1. . . . . . . . . .
4 .1. Sp ec ify Whic h Netwo rk Interfac e JBo s s EAP 6 Us es
21
4 .2. Co nfig ure Netwo rk Firewalls to Wo rk with JBo s s EAP 6
4 .3. Netwo rk Po rts Us ed By JBo s s EAP 6
22
25
4 .4. Ab o ut Enc ryp tio n

4 .5. Ab o ut SSL Enc ryp tio n
4 .6 . Imp lement SSL Enc ryp tio n fo r the JBo s s EAP 6 Web Server
4 .7. G enerate a SSL Enc ryp tio n Key and Certific ate
27
27
28
30
4 .8 . SSL Co nnec to r Referenc e

4 .9 . FIPS 140 -2 Co mp liant Enc ryp tio n
4 .9 .1. Ab o ut FIPS 140 -2 Co mp lianc e
4 .9 .2. FIPS 140 -2 Co mp liant Cryp to g rap hy o n IBM JDK
33
39
39
39
Key s to rag e
Examine FIPS p ro vid er info rmatio n
4 .9 .3. FIPS 140 -2 Co mp liant Pas s wo rd s
4 .9 .4. Enab le FIPS 140 -2 Cryp to g rap hy fo r SSL o n Red Hat Enterp ris e Linux 6
39
40
40
40
. .hapt
C
. . . .er
. .5.
. .Secure
. . . . . . t. he
. . .Management
. . . . . . . . . . . .Int
. . erfaces
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. 4. . . . . . . . . .
5 .1. Default Us er Sec urity Co nfig uratio n
44
5 .2.
5 .3.
5 .4.
5 .5.
O verview o f Ad vanc ed Manag ement Interfac e Co nfig uratio n

Dis ab le the HTTP Manag ement Interfac e
Remo ve Silent Authentic atio n fro m the Default Sec urity Realm
Dis ab le Remo te Ac c es s to the JMX Sub s ys tem
5 .6 . Co nfig ure Sec urity Realms fo r the Manag ement Interfac es
45
46
47
49
49
JBoss Ent erprise Applicat ion Plat form 6 .3 Securit y G uide

5 .6 . Co nfig ure Sec urity Realms fo r the Manag ement Interfac es
5 .7. Co nfig ure the Manag ement Co ns o le fo r HTTPS
5 .8 . Us e Dis tinc t Interfac es fo r HTTP and HTTPS c o nnec tio ns to the Manag ement Interfac e
5 .9 . Us ing 2-way SSL fo r the Manag ement interfac e and the CLI
5 .10 . Sec ure the Manag ement Interfac es via JAAS
49
51
54
55
58
5 .11. LDAP
5 .11.1. Ab o ut LDAP
5 .11.2. Us e LDAP to Authentic ate to the Manag ement Interfac es
5 .11.3. Us ing O utb o und LDAP with 2-way SSL in the Manag ement Interfac e and CLI
58
58
59
62
. .hapt
C
. . . .er
. .6. .. Secure
. . . . . . .t he
. . . Management
. . . . . . . . . . . .Int
. . erfaces
. . . . . . . wit
. . .h. .Role. . . . Based
. . . . . . Access
. . . . . . . Cont
. . . . rol
. . . . . . . . . . . . . . . . . 6. 3. . . . . . . . . .
6 .1. Ab o ut Ro le-Bas ed Ac c es s Co ntro l (RBAC)
6 .2. Ro le-Bas ed Ac c es s Co ntro l in the Manag ement Co ns o le and CLI
6 .3. Sup p o rted Authentic atio n Sc hemes
6 .4. The Stand ard Ro les
63
63
64
64
6 .5. Ab o ut Ro le Permis s io ns
6 .6 . Ab o ut Co ns traints
6 .7. Ab o ut JMX and Ro le-Bas ed Ac c es s Co ntro l
6 .8 . Co nfig uring Ro le-Bas ed Ac c es s Co ntro l
65
66
67
67
6 .8 .1. O verview o f RBAC Co nfig uratio n Tas ks

6 .8 .2. Enab ling Ro le-Bas ed Ac c es s Co ntro l
67
68
6 .8 .3. Chang ing the Permis s io n Co mb inatio n Po lic y
69
6 .9 . Manag ing Ro les

6 .9 .1. Ab o ut Ro le Memb ers hip
70
70
6 .9 .2. Co nfig ure Us er Ro le As s ig nment

6 .9 .3. Co nfig ure Us er Ro le As s ig nment us ing the Manag ement CLI
71
74
6 .9 .4. Ab o ut Ro les and Us er G ro up s
77
6 .9 .5. Co nfig ure G ro up Ro le As s ig nment

6 .9 .6 . Co nfig ure G ro up Ro le As s ig nment us ing the Manag ement CLI
78
81
6 .9 .7. Ab o ut Autho riz atio n and G ro up Lo ad ing with LDAP

us ername-to -d n
84
85
The G ro up Searc h
87
G eneral G ro up Searc hing

6 .9 .8 . Ab o ut Sc o p ed Ro les
89
91
6 .9 .9 . Creating Sc o p ed Ro les
91
6 .10 . Co nfig uring Co ns traints

6 .10 .1. Co nfig ure Sens itivity Co ns traints
6 .10 .2. Co nfig ure Ap p lic atio n Res o urc e Co ns traints
6 .10 .3. Co nfig ure the Vault Exp res s io n Co ns traint
6 .11. Co ns traints Referenc e
6 .11.1. Ap p lic atio n Res o urc e Co ns traints Referenc e
6 .11.2. Sens itivity Co ns traints Referenc e
93
93
95
96
97
97
99
. .hapt
C
. . . .er
. .7. .. Secure
. . . . . . .Passwords
. . . . . . . . . .and
...O
. .t.her
. . . Sensit
. . . . . .ive
. . .St
. .rings
. . . . .wit
..h
. . Password
. . . . . . . . . Vault
. . . . . . . . . . . . . . . . . .1.0. 7. . . . . . . . . .
7 .1. Pas s wo rd Vault Sys tem
7 .2. Create a Java Keys to re to Sto re Sens itive String s
10 7
10 7
7 .3. Mas k the Keys to re Pas s wo rd and Initializ e the Pas s wo rd Vault
10 9
7 .4. Co nfig ure JBo s s EAP 6 to Us e the Pas s wo rd Vault

7 .5. Co nfig ure JBo s s EAP 6 to Us e a Cus to m Imp lementatio n o f the Pas s wo rd Vault
111
112
7 .6 . Sto re and Retrieve Enc ryp ted Sens itive String s in the Java Keys to re
113
7 .7. Sto re and Res o lve Sens itive String s In Yo ur Ap p lic atio ns
116
. .hapt
C
. . . .er
. .8. .. Web,
. . . . .HT
..T
. .P. Connect
. . . . . . . .ors,
. . . .and
. . . .HT
. .T
. .P. Clust
. . . . .ering
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.1. 9. . . . . . . . . .
8 .1. Co nfig ure a mo d _c lus ter Wo rker No d e
119
. .hapt
C
. . . .er
. .9. .. Pat
. . . ch
. . .Inst
. . . allat
. . . . ion
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. 2. 5. . . . . . . . . .
9 .1. Ab o ut Patc hes and Up g rad es
9 .2. Ab o ut Patc hing Mec hanis ms
125
125
9 .3. Sub s c rib e to Patc h Mailing Lis ts
126
9 .4. Ins tall Patc hes in Zip Fo rm

9 .4.1. The Patc h Manag ement Sys tem
126
127
9 .4.2. Ins talling Patc hes in Zip Fo rm Us ing the Patc h Manag ement Sys tem
9 .4.3. Ro llb ac k the Ap p lic atio n o f a Patc h in Zip Fo rm Us ing the Patc h Manag ement Sys tem
128
130
9 .5. Patc hing an RPM Ins tallatio n
132
9 .6 . Severity and Imp ac t Rating o f JBo s s Sec urity Patc hes

9 .7. Manag e Sec urity Up d ates fo r Dep end enc ies Bund led Ins id e the Ap p lic atio ns Dep lo yed o n
JBo s s EAP
133
134
. .art
P
. . .III.
. . Developing
. . . . . . . . . . .Secure
. . . . . . Applicat
. . . . . . . ions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. 36
...........
. .hapt
C
. . . .er
. .1. 0. .. Securit
. . . . . . .y. O
. .verview
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. 37
...........
10 .1. Ab o ut Ap p lic atio n Sec urity
10 .2. Dec larative Sec urity
137
137
10 .2.1. Java EE Dec larative Sec urity O verview
137
10 .2.2. Sec urity Referenc es

10 .2.3. Sec urity Id entity
137
139
10 .2.4. Sec urity Ro les
141
10 .2.5. EJB Metho d Permis s io ns

10 .2.6 . Enterp ris e Beans Sec urity Anno tatio ns
142
145
10 .2.7. Web Co ntent Sec urity Co ns traints

10 .2.8 . Enab le Fo rm-b as ed Authentic atio n
146
149
10 .2.9 . Enab le Dec larative Sec urity
150
. .hapt
C
. . . .er
. .1. 1. .. Applicat
. . . . . . . .ion
. . .Securit
. . . . . . y. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. 51
...........
11.1. Datas o urc e Sec urity
11.1.1. Ab o ut Datas o urc e Sec urity
151
151
11.2. EJB Ap p lic atio n Sec urity

11.2.1. Sec urity Id entity
152
152
11.2.1.1. Ab o ut EJB Sec urity Id entity
152
11.2.1.2. Set the Sec urity Id entity o f an EJB

11.2.2. EJB Metho d Permis s io ns
152
153
11.2.2.1. Ab o ut EJB Metho d Permis s io ns
153
11.2.2.2. Us e EJB Metho d Permis s io ns
154
11.2.3. EJB Sec urity Anno tatio ns

11.2.3.1. Ab o ut EJB Sec urity Anno tatio ns
156
157
11.2.3.2. Us e EJB Sec urity Anno tatio ns
157
11.2.4. Remo te Ac c es s to EJBs
158
11.2.4.1. Ab o ut Remo te Metho d Ac c es s
158
11.2.4.2. Ab o ut Remo ting Callb ac ks

11.2.4.3. Ab o ut Remo ting Server Detec tio n
159
16 0
11.2.4.4. Co nfig ure the Remo ting Sub s ys tem
16 0
11.2.4.5. Us e Sec urity Realms with Remo te EJB Clients
16 8
11.2.4.6 . Ad d a New Sec urity Realm
16 9
11.2.4.7. Ad d a Us er to a Sec urity Realm

11.2.4.8 . Ab o ut Remo te EJB Ac c es s Us ing SSL Enc ryp tio n
170
170
11.3. JAX-RS Ap p lic atio n Sec urity
170
11.3.1. Enab le Ro le-Bas ed Sec urity fo r a RESTEas y JAX-RS Web Servic e
171
11.3.2. Sec ure a JAX-RS Web Servic e us ing Anno tatio ns
172
. .hapt
C
. . . .er
. .1. 2. .. T
. .he
. . Securit
. . . . . . .y. Subsyst
. . . . . . . em
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.7. 4. . . . . . . . . .

. .hapt
C
. . . .er
. .1. 2. .. T
. .he
. . Securit
. . . . . . .y. Subsyst
. . . . . . . em
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.7. 4. . . . . . . . . .
12.1. Ab o ut the Sec urity Sub s ys tem
12.2. Ab o ut the Struc ture o f the Sec urity Sub s ys tem
174
174
12.3. Co nfig uring the Sec urity Sub s ys tem
175
12.3.1. Co nfig ure the Sec urity Sub s ys tem
175
12.3.2. Sec urity Manag ement
176
12.3.2.1. Ab o ut Deep Co p y Sub jec t Mo d e
176
2.3.2.2. Enab le Deep Co p y Sub jec t Mo d e

1
12.3.3. Sec urity Do mains
176
177
12.3.3.1. Ab o ut Sec urity Do mains
177
12.3.3.2. CLI O p eratio ns Related to Sec urity Do mains
177
. .hapt
C
. . . .er
. .1. 3.
. . Aut
. . . hent
. . . . icat
. . . .ion
. . . and
. . . .Aut
. . . horiz
. . . . .at. ion
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.7. 9. . . . . . . . . .
13.1. Kerb ero s and SPNEG O Integ ratio n
179
13.1.1. Ab o ut Kerb ero s and SPNEG O Integ ratio n

13.1.2. Des kto p SSO us ing SPNEG O
179
179
13.1.3. Co nfig ure JBo s s Neg o tiatio n fo r Mic ro s o ft Wind o ws Do main
18 2
13.1.4. Kerb ero s Authentic atio n fo r Pic ketLink IDP
18 3
13.1.5. Lo g in with Certific ate with Pic ketLink IDP
18 7
3.1.5.1. JBo s s EAP 6 .3 SSL Co nfig uratio n

1
13.2. Authentic atio n
18 7
18 9
13.2.1. Ab o ut Authentic atio n
18 9
13.2.2. Co nfig ure Authentic atio n in a Sec urity Do main
19 0
13.3. JAAS - Java Authentic atio n and Autho riz atio n Servic e
19 1
13.3.1. Ab o ut JAAS
13.3.2. JAAS Co re Clas s es
19 2
19 2
13.3.3. Sub jec t and Princ ip al c las s es
19 2
13.3.4. Sub jec t Authentic atio n
19 3
13.4. Java Authentic atio n SPI fo r Co ntainers (JASPI)

13.4.1. Ab o ut Java Authentic atio n SPI fo r Co ntainers (JASPI) Sec urity
13.4.2. Co nfig ure Java Authentic atio n SPI fo r Co ntainers (JASPI) Sec urity
13.5. Autho riz atio n
13.5.1. Ab o ut Autho riz atio n
13.5.2. Co nfig ure Autho riz atio n in a Sec urity Do main
13.6 . Java Autho riz atio n Co ntrac t fo r Co ntainers (JACC)
13.6 .1. Ab o ut Java Autho riz atio n Co ntrac t fo r Co ntainers (JACC)
19 6
19 6
19 6
19 7
19 7
19 7
19 8
19 8
13.6 .2. Co nfig ure Java Autho riz atio n Co ntrac t fo r Co ntainers (JACC) Sec urity
19 9
13.6 .3. Fine G rained Autho riz atio n Us ing XACML
20 0
13.6 .3.1. Ab o ut Fine G rained Autho riz atio n and XACML
20 0
13.6 .3.2. Co nfig ure XACML fo r Fine G rained Autho riz atio n
20 1
13.7. Sec urity Aud iting

13.7.1. Ab o ut Sec urity Aud iting
20 8
20 8
13.7.2. Co nfig ure Sec urity Aud iting
20 9
13.7.3. New Sec urity Pro p erties
210
13.8 . Sec urity Map p ing

13.8 .1. Ab o ut Sec urity Map p ing
13.8 .2. Co nfig ure Sec urity Map p ing in a Sec urity Do main
13.9 . Us e a Sec urity Do main in Yo ur Ap p lic atio n
210
210
211
212
. .hapt
C
. . . .er
. .1. 4. .. Single
. . . . . . Sign
. . . . .O. n
. .(SSO
. . . . ). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. 1. 5. . . . . . . . . .
14.1. Ab o ut Sing le Sig n O n (SSO ) fo r Web Ap p lic atio ns
215
14.2. Ab o ut Clus tered Sing le Sig n O n (SSO ) fo r Web Ap p lic atio ns
215
14.3. Cho o s e the Rig ht SSO Imp lementatio n

14.4. Us e Sing le Sig n O n (SSO ) In A Web Ap p lic atio n
216
216

14.4. Us e Sing le Sig n O n (SSO ) In A Web Ap p lic atio n
216
14.5. Ab o ut Kerb ero s
218
14.6 . Ab o ut SPNEG O
219
14.7. Ab o ut Mic ro s o ft Ac tive Direc to ry
219
14.8 . Co nfig ure Kerb ero s o r Mic ro s o ft Ac tive Direc to ry Des kto p SSO fo r Web Ap p lic atio ns
14.9 . Co nfig ure SPNEG O Fall Bac k to Fo rm Authentic atio n
219
223
. .hapt
C
. . . .er
. .1. 5.
. . Single
. . . . . . Sign. . . . .O. n
. . wit
. . .h. SAML
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. 2. 5. . . . . . . . . .
15.1. Ab o ut Sec urity To ken Servic e (STS)
225
15.2. Co nfig ure Sec urity To ken Servic e (STS)
227
15.3. Ab o ut Pic ketLink STS Lo g in Mo d ules
228
15.4. Co nfig ure STSIs s uing Lo g inMo d ule

15.5. Co nfig ure STSValid ating Lo g inMo d ule
230
231
15.6 . STS Client Po o ling

Us ing STSClientPo o lFac to ry
15.7. SAML Web Bro ws er Bas ed SSO
15.7.1. Ab o ut SAML Web Bro ws er Bas ed SSO
15.7.2. Setup SAML v2 b as ed Web SSO
231
232
232
232
233
15.7.3. Co nfig ure Id entity Pro vid er
233
15.7.4. Co nfig ure Servic e Pro vid er us ing HTTP/REDIRECT Bind ing
236
15.7.5. Setup SAML v2 b as ed Web SSO us ing HTTP/PO ST Bind ing
239
15.7.6 . Co nfig ure Dynamic Ac c o unt Cho o s er at a Servic e Pro vid er
240
5.7.7. Co nfig uratio n o f IDP-initiated SSO

1
15.8 . Co nfig ure SAML G lo b al Lo g o ut Pro file
241
242
. .hapt
C
. . . .er
. .1. 6. .. Login
. . . . . .Modules
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.4. 4. . . . . . . . . .
16 .1. Us ing Mo d ules
244
16 .1.1. Pas s wo rd Stac king
244
16 .1.2. Pas s wo rd Has hing
245
16 .1.3. Unauthentic ated Id entity

16 .1.4. Ld ap Lo g in Mo d ule
246
247
16 .1.5. Ld ap Extend ed Lo g in Mo d ule
250
16 .1.6 . Us ers Ro les Lo g in Mo d ule
258
16 .1.7. Datab as e Lo g in Mo d ule
259
16 .1.8 . Certific ate Lo g in Mo d ule

16 .1.9 . Id entity Lo g in Mo d ule
26 0
26 3
16 .1.10 . RunAs Lo g in Mo d ule
26 3
16 .1.10 .1. RunAs Id entity Creatio n
26 4
16 .1.11. Client Lo g in Mo d ule
26 5
16 .1.12. SPNEG O Lo g in Mo d ule

16 .1.13. Ro leMap p ing Lo g in Mo d ule
26 5
26 6
16 .1.14. b ind Cred ential Mo d ule O p tio n
26 7
16 .2. Cus to m Mo d ules
26 8
16 .2.1. Sub jec t Us ag e Pattern Sup p o rt
26 9
16 .2.2. Cus to m Lo g inMo d ule Examp le
274
. .hapt
C
. . . .er
. .1. 7. .. Role. . . . . Based
. . . . . . Securit
......y
. .in
. . Applicat
. . . . . . . ions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.7. 8. . . . . . . . . .
17.1. Java Authentic atio n and Autho riz atio n Servic e (JAAS)
278
17.2. Ab o ut Java Authentic atio n and Autho riz atio n Servic e (JAAS)
278
17.3. Us e a Sec urity Do main in Yo ur Ap p lic atio n
279
17.4. Us e Ro le-Bas ed Sec urity In Servlets
28 1
17.5. Us e A Third -Party Authentic atio n Sys tem In Yo ur Ap p lic atio n
28 4
. .hapt
C
. . . .er
. .1. 8. .. Migrat
. . . . . .ion
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.9. 2. . . . . . . . . .
18 .1. Co nfig ure Ap p lic atio n Sec urity Chang es
29 2
.Reference
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. 9. 3. . . . . . . . . .
A .1. Inc lud ed Authentic atio n Mo d ules
29 3
A .2. Inc lud ed Autho riz atio n Mo d ules
319
A .3. Inc lud ed Sec urity Map p ing Mo d ules
320
A .4. Inc lud ed Sec urity Aud iting Pro vid er Mo d ules
324
A .5. jb o s s -web .xml Co nfig uratio n Referenc e

A .6 . EJB Sec urity Parameter Referenc e
324
327
. . . . . . . . .Hist
Revision
. . . ory
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
. . 9. . . . . . . . . .
Preface
Preface
1. Document Convent ions
This manual uses several conventions to highlight certain words and phrases and draw attention to
specific pieces of information.
1.1. T ypographic Convent ions

Four typographic conventions are used to call attention to specific words and phrases. These
conventions, and the circumstances they apply to, are as follows.
Mo no -spaced Bo l d
Used to highlight system input, including shell commands, file names and paths. Also used to
highlight keys and key combinations. For example:
To see the contents of the file my_next_bestsel l i ng _no vel in your current
working directory, enter the cat my_next_bestsel l i ng _no vel command at the
shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key, all presented in mono-spaced bold and
all distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects each
part of a key combination. For example:
Press Enter to execute the command.
Press C trl +Al t+F2 to switch to a virtual terminal.
The first example highlights a particular key to press. The second example highlights a key
combination: a set of three keys pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values
mentioned within a paragraph will be presented as above, in mo no -spaced bo l d . For example:
File-related classes include fi l esystem for file systems, fi l e for files, and d i r for
directories. Each class has its own associated set of permissions.
Pro p o rt io n al B o ld
This denotes words or phrases encountered on a system, including application names; dialog-box
text; labeled buttons; check-box and radio-button labels; menu titles and submenu titles. For
example:
Choose Syst em Pref eren ces Mo u se from the main menu bar to launch
Mo u se Pref eren ces. In the Butto ns tab, select the Left-hand ed mo use check
box and click C l o se to switch the primary mouse button from the left to the right
(making the mouse suitable for use in the left hand).
To insert a special character into a g ed it file, choose Ap p licat io n s
Accesso ries C h aract er Map from the main menu bar. Next, choose Search
Fin d from the C h aract er Map menu bar, type the name of the character in the
Search field and click Next. The character you sought will be highlighted in the
C haracter T abl e. D ouble-click this highlighted character to place it in the T ext

to co py field and then click the C o py button. Now switch back to your document
and choose Ed it Past e from the g ed it menu bar.
The above text includes application names; system-wide menu names and items; application-specific
menu names; and buttons and text found within a GUI interface, all presented in proportional bold
and all distinguishable by context.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or
variable text. Italics denotes text you do not input literally or displayed text that changes depending
on circumstance. For example:
To connect to a remote machine using ssh, type ssh username@ domain.name at a
shell prompt. If the remote machine is exampl e. co m and your username on that
machine is john, type ssh jo hn@ exampl e. co m.
The mo unt -o remo unt file-system command remounts the named file system.
For example, to remount the /ho me file system, the command is mo unt -o remo unt
/ho me.
To see the version of a currently installed package, use the rpm -q package
command. It will return a result as follows: package-version-release.
Note the words in bold italics above: username, domain.name, file-system, package, version and
release. Each word is a placeholder, either for text you enter when issuing a command or for text
displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and
important term. For example:
Publican is a DocBook publishing system.
1.2. Pull-quot e Convent ions

Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in mo no -spaced ro man and presented thus:
books
books_tests
Desktop
Desktop1
documentation drafts mss

downloads
images notes
photos
scripts
stuff
svgs
svn
Source-code listings are also set in mo no -spaced ro man but add syntax highlighting as follows:
static int kvm_vm_ioctl_deassign_device(struct kvm *kvm,
struct kvm_assigned_pci_dev *assigned_dev)
int r = 0;
struct kvm_assigned_dev_kernel *match;

mutex_lock(& kvm->lock);
match = kvm_find_assigned_dev(& kvm->arch.assigned_dev_head,

assigned_dev->assigned_dev_id);
if (!match) {
printk(KERN_INFO "%s: device hasn't been assigned
Preface
before, "
"so cannot be deassigned\n", __func__);

r = -EINVAL;
goto out;
kvm_deassign_device(kvm, match);
kvm_free_assigned_device(kvm, match);
o ut:
mutex_unlock(& kvm->lock);
return r;
1.3. Not es and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
Note
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should
have no negative consequences, but you might miss out on a trick that makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that only apply to
the current session, or services that need restarting before an update will apply. Ignoring a
box labeled Important will not cause data loss but may cause irritation and frustration.
Warning
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.
2. Get t ing Help and Giving Feedback

2.1. Do You Need Help?
If you experience difficulty with a procedure described in this documentation, visit the Red Hat
Customer Portal at http://access.redhat.com. Through the customer portal, you can:
search or browse through a knowledgebase of technical support articles about Red Hat products.
submit a support case to Red Hat Global Support Services (GSS).
access other product documentation.
Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and
technology. You can find a list of publicly available mailing lists at
https://www.redhat.com/mailman/listinfo. Click on the name of any mailing list to subscribe to that list
or to access the list archives.
2.2. We Need Feedback!

If you find a typographical error in this manual, or if you have thought of a way to make this manual
better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/
against the product JB o ss En t erp rise Ap p licat io n Plat f o rm.
When submitting a bug report, be sure to mention the manual's identifier: Security_Guide
If you have a suggestion for improving the documentation, try to be as specific as possible when
describing it. If you have found an error, please include the section number and some of the
surrounding text so we can find it easily.
10
P art I. Securit y for Red Hat JBoss Ent erprise Applicat ion Plat form 6
Part I. Security for Red Hat JBoss Enterprise Application

Platform 6
11
Chapter 1. Introduction
1.1. About Red Hat JBoss Ent erprise Applicat ion Plat form 6
Red Hat JBoss Enterprise Application Platform 6 (JBoss EAP 6) is a middleware platform built on
open standards and compliant with the Java Enterprise Edition 6 specification. It integrates JBoss
Application Server 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
configuration files unnecessary and add the ability to script and automate tasks.
In addition, JBoss EAP 6 includes APIs and development frameworks for quickly developing secure
and scalable 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 deals
with securing the virtual environments that power the digital age. This can include data protection
and integrity, application security, risk and vulnerability assessment and authentication and
authorization protocols.
Computer data is an all important asset for most organizations. D ata protection is vital and forms the
core of most businesses. JBoss EAP 6 provides a multi-layered approach to security to take care of
data at all stages.
Truly secure systems are the ones that are designed from the ground up with security as the main
feature. Such systems use the principle of Security by D esign. In such systems, malicious attacks
and infiltration's are accepted as part and parcel of normal security apparatus and systems are
designed to work around them.
Security can be applied at the operating system, middleware and application level. For more
information about security at the operating system level as it applies to RHEL, refer to the Red Hat
Enterprise Linux Security 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
12
P art II. Securing t he Plat form
Part II. Securing the Platform
13
Chapter 2. Java Security Manager

2.1. About t he Java Securit y Manager
Java Secu rit y Man ag er
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 the JVM. When the Java Security Manager is
activated, the Java API checks with the security manager for approval before
executing a wide range of potentially unsafe operations.
The Java Security Manager uses a security policy to determine whether a given action will be
permitted or denied.
Report a bug
2.2. About Java Securit y Manager Policies

Secu rit y Po licy
A set of defined permissions for different classes of code. The Java Security Manager
compares actions requested by applications against the security policy. If an action
is allowed by the policy, the Security Manager will permit that action to take place. If
the action is not allowed by the policy, the Security Manager will deny that action. The
security policy can define permissions based on the location of code, on the code's
signature, or based on the subject's principals.
The Java Security Manager and the security policy used are configured using the Java Virtual
Machine options java. securi ty. manag er and java. securi ty. po l i cy.
B asic In f o rmat io n
A security policy's entry consists of the following configuration elements, which are connected to the
po l i cyto o l :
C o d eB ase
The URL location (excluding the host and domain information) where the code originates
from. This parameter is optional.
Sig n ed B y
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.
Prin cip als
A list of principal_type/principal_name pairs, which must be present within the
executing thread's principal set. The Principals entry is optional. If it is omitted, it signifies
that the principals of the executing thread will have no impact on the Java Security
Manager.
Permissio n s
14
Chapt er 2 . Java Securit y Manager
A permission is the access which is granted to the code. Many permissions are provided as
part of the Java Enterprise Edition 6 (Java EE 6) specification.
Report a bug
2.3. Run JBoss EAP 6 Wit hin t he Java Securit y Manager

To specify a Java Security Manager policy, you need to edit the Java options passed to the domain
or server instance during the bootstrap process. For this reason, you cannot pass the parameters as
options to the d o mai n. sh or stand al o ne. sh scripts. The following procedure guides you
through the steps of configuring your instance to run within a Java Security Manager policy.
Prereq u isit es
Before you following this procedure, you need to write a security policy, using the po l i cyto o l
command which is included with your Java D evelopment Kit (JD K). This procedure assumes that
your policy is located at EAP_HOME/bi n/server. po l i cy. As an alternative, write the security
policy using any text editor and manually save it as EAP_HOME/bi n/server. po l i cy
The domain or standalone server must be completely stopped before you edit any configuration
files.
Perform the following procedure for each physical host or instance in your domain, if you have
domain members spread across multiple systems.
Pro ced u re 2.1. C o n f ig u re t h e Secu rit y Man ag er f o r JB o ss EAP 6
1. O p en t h e co n f ig u rat io n f ile.
Open the configuration file for editing. This file is located in one of two places, depending on
whether you use a managed domain or standalone server. This is not the executable file used
to start the server or domain.
A. Man ag ed D o main
For Linux: EAP_HOME/bi n/d o mai n. co nf
For Windows: EAP_HOME\bi n\d o mai n. co nf. bat
B. St an d alo n e Server
For Linux: EAP_HOME/bi n/stand al o ne. co nf
For Windows: EAP_HOME\bi n\stand al o ne. co nf. bat
2. Ad d t h e Java o p t io n s t o t h e f ile.
To ensure the Java options are used, add them to the code block that begins with:
if [ "x$JAVA_OPTS" = "x" ]; then
You can modify the -D java. securi ty. po l i cy value to specify the exact location of your
security policy. It should go onto one line only, with no line break. Using = = when setting the
-D java. securi ty. po l i cy property specifies that the security manager will use only the
specified policy file. Using = specifies that the security manager will use the specified policy
15
combined with the policy set in the po l i cy. url section of

JAVA_HOME/l i b/securi ty/java. securi ty.
Important
JBoss Enterprise Application Platform releases from 6.2.2 onwards require that the
system property jbo ss. mo d ul es. po l i cy-permi ssi o ns is set to true.
Examp le 2.1. d o main .co n f

JAVA_OPTS="$JAVA_OPTS -Djava.security.manager Djava.security.policy==$PWD/server.policy Djboss.home.dir=/path/to/EAP_HOME -Djboss.modules.policypermissions=true"
Examp le 2.2. d o main .co n f .b at

set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.manager Djava.security.policy==\path\to\server.policy Djboss.home.dir=\path\to\EAP_HOME -Djboss.modules.policypermissions=true"
Examp le 2.3. st an d alo n e.co n f

JAVA_OPTS="$JAVA_OPTS -Djava.security.manager Djava.security.policy==$PWD/server.policy Djboss.home.dir=$JBOSS_HOME -Djboss.modules.policypermissions=true"
Examp le 2.4 . st an d alo n e.co n f .b at

set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.manager Djava.security.policy==\path\to\server.policy Djboss.home.dir=%JBOSS_HOME% -Djboss.modules.policypermissions=true"
3. St art t h e d o main o r server.

Start the domain or server as normal.
Report a bug
2.4 . Writ e a Java Securit y Manager Policy

In t ro d u ct io n
16
Chapt er 2 . Java Securit y Manager
An application called po l i cyto o l is included with most JD K and JRE distributions, for the purpose
of creating and editing Java Security Manager security policies. D etailed information about
po l i cyto o l is linked from http://docs.oracle.com/javase/6/docs/technotes/tools/.
Pro ced u re 2.2. Set u p a n ew Java Secu rit y Man ag er Po licy
1. St art po l i cyto o l .
Start the po l i cyto o l tool in one of the following ways.
A. R ed H at En t erp rise Lin u x
From your GUI or a command prompt, run /usr/bi n/po l i cyto o l .
B. Micro so f t Win d o ws Server
Run po l i cyto o l . exe from your Start menu or from the bi n\ of your Java installation.
The location can vary.
2. C reat e a p o licy.
To create a policy, select Ad d P o l i cy Entry. Add the parameters you need, then click
D o ne.
3. Ed it an exist in g p o licy
Select the policy from the list of existing policies, and select the Ed i t P o l i cy Entry
button. Edit the parameters as needed.
4. D elet e an exist in g p o licy.
Select the policy from the list of existing policies, and select the R emo ve P o l i cy Entry
button.
Report a bug
2.5. IBM JRE and t he Java Securit y Manager

IBM JRE uses a default policy provider which does not work correctly with the JBoss Enterprise
Application Platform security policy. You must change the JRE configuration to use the standard
policy provider, if you want to use the IBM JRE to host JBoss Enterprise Application Platform with the
Java Security Manager enabled.
To configure the JRE configuration for the IBM JRE, edit the
JAVA_HO ME/jre/l i b/securi ty/java. securi ty file, and set the po l i cy. pro vi d er value to
sun. securi ty. pro vi d er. P o l i cyFi l e.
policy.provider=sun.security.provider.PolicyFile
Report a bug
2.6. Debug Securit y Manager Policies

You can enable debugging information to help you troubleshoot security policy-related issues. The
java. securi ty. d ebug option configures the level of security-related information reported. The
17
command java -D java. securi ty. d ebug = hel p will produce help output with the full range of
debugging options. Setting the debug level to al l is useful when troubleshooting a security-related
failure whose cause is completely unknown, but for general use it will produce too much information.
A sensible general default is access: fai l ure.
Pro ced u re 2.3. En ab le g en eral d eb u g g in g
T h is p ro ced u re will en ab le a sen sib le g en eral level o f secu rit y- relat ed d eb u g
in f o rmat io n .
Add the following line to the server configuration file.
If the JBoss EAP 6 instance is running in a managed domain, the line is added to the
bi n/d o mai n. co nf file for Linux or the bi n\d o mai n. co nf. bat file for Windows.
If the JBoss EAP 6 instance is running as a standalone server, the line is added to the
bi n/stand al o ne. co nf file for Linux, or the bi n\stand al o ne. co nf. bat file for
Windows.
Li nux
JAVA_OPTS="$JAVA_OPTS -Djava.security.debug=access:failure"
Wi nd o ws
set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.debug=access:failure"
R esu lt
A general level of security-related debug information has been enabled.
Report a bug
18
Chapt er 3. Securit y Realms
Chapter 3. Security Realms

3.1. About Securit y Realms
A security realm is a series of mappings between users and passwords, and users and roles. Security
realms are a mechanism for adding authentication and authorization to your EJB and Web
applications. JBoss EAP 6 provides two security realms by default:
Manag ementR eal m stores authentication information for the Management API, which provides
the functionality for the Management CLI and web-based Management Console. It provides an
authentication system for managing JBoss EAP 6 itself. You could also use the
Manag ementR eal m if your application needed to authenticate with the same business rules you
use for the Management API.
Appl i cati o nR eal m stores user, password, and role information for Web Applications and
EJBs.
Each realm is stored in a number of files on the filesystem:
REALM-users. pro perti es stores usernames and hashed passwords.
REALM-ro l es. pro perti es stores user-to-role mappings.
mg mt-g ro ups. pro perti es stores user-to-group mapping file for Manag ementR eal m. Only
used when Role-based Access Control (RBAC) is enabled.
The properties files are stored in the d o mai n/co nfi g urati o n/ and
stand al o ne/co nfi g urati o n/ directories. The files are written simultaneously by the ad d user. sh or ad d -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 Securit y Realm

1. R u n t h e Man ag emen t C LI.
Start the jbo ss-cl i . sh or jbo ss-cl i . bat command and connect to the server.
2. C reat e t h e n ew secu rit y realm it self .
Run the following command to create a new security realm named MyD o mai nR eal m on a
domain controller or a standalone server.
For a domain instance, use this command:
/host=master/core-service=management/securityrealm=MyDomainRealm:add()
For a standalone instance, use this command:
/core-service=management/security-realm=MyDomainRealm:add()
3. C reat e t h e ref eren ces t o t h e p ro p ert ies f ile wh ich will st o re in f o rmat io n ab o u t
t h e n ew ro le.
19
Run the following command to create a pointer a file named myfi l e. pro perti es, which
will contain the properties pertaining to the new role.
Note
The newly created properties file is not managed by the included ad d -user. sh and
ad d -user. bat scripts. It must be managed externally.
/host=master/core-service=management/securityrealm=MyDomainRealm/authentication=properties:add(path=myfile.prope
rties)
/core-service=management/securityrealm=MyDomainRealm/authentication=properties:add(path=myfile.prope
rties)
R esu lt
Your new security realm is created. When you add users and roles to this new realm, the information
will be stored in a separate file from the default security realms. You can manage this new file using
your own applications or procedures.
Report a bug
3.3. Add a User t o a Securit y Realm

1. R u n t h e ad d -user. sh o r ad d -user. bat co mman d .
Open a terminal and change directories to the EAP_HOME/bi n/ directory. If you run Red Hat
Enterprise Linux or another UNIX-like operating system, run ad d -user. sh. If you run
Microsoft Windows Server, run ad d -user. bat.
2. C h o o se wh et h er t o ad d a Man ag emen t U ser o r Ap p licat io n U ser.
For this procedure, type b to add an Application User.
3. C h o o se t h e realm t h e u ser will b e ad d ed t o .
By default, the only available realm is Appl i cati o nR eal m. If you have added a custom
realm, you can type its name instead.
4. T yp e t h e u sern ame, p asswo rd , an d ro les, wh en p ro mp t ed .
Type the desired username, password, and optional roles when prompted. Verify your choice
by typing yes, or type no to cancel the changes. The changes are written to each of the
properties files for the security realm.
Report a bug
20
Chapt er 4 . Encrypt Net work T raffic
Chapter 4. Encrypt Network Traffic

4 .1. Specify Which Net work Int erface JBoss EAP 6 Uses
O verview
Isolating services so that they are accessible only to the clients who need them increases the security
of your network. JBoss EAP 6 includes two interfaces in its default configuration, both of which bind
to the IP address 127. 0 . 0 . 1, or l o cal ho st, by default. One of the interfaces is called
manag ement, and is used by the Management Console, CLI, and API. The other is called publ i c,
and is used to deploy applications. These interfaces are not special or significant, but are provided
as a starting point.
The manag ement interface uses ports 9 9 9 0 and 9 9 9 9 by default, and the publ i c interface uses
port 80 80 , or port 84 4 3 if you use HTTPS.
You can change the IP address of the management interface, public interface, or both.
Be cautious when exposing the management interfaces.

If you expose the management interfaces to other network interfaces which are accessible from
remote hosts, be aware of the security implications. Most of the time, it is not advisable to
provide remote access to the management interfaces.
1. St o p JB o ss EAP 6 .
Stop JBoss EAP 6 by sending an interrupt in the appropriate way for your operating system.
If you are running JBoss EAP 6 as a foreground application, the typical way to do this is to
press C trl + C .
2. R est art JB o ss EAP 6 , sp ecif yin g t h e b in d ad d ress.
Use the -b command-line switch to start JBoss EAP 6 on a specific interface.
Examp le 4 .1. Sp ecif y t h e p u b lic in t erf ace.

EAP_HOME/bin/domain.sh -b 10.1.1.1
Examp le 4 .2. Sp ecif y t h e man ag emen t in t erf ace.

EAP_HOME/bin/domain.sh -bmanagement=10.1.1.1
Examp le 4 .3. Sp ecif y d if f eren t ad d resses f o r each in t erf ace.

EAP_HOME/bin/domain.sh -bmanagement=127.0.0.1 -b 10.1.1.1
Examp le 4 .4 . B in d t h e p u b lic in t erf ace t o all n et wo rk in t erf aces.
21
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 at runtime, so this is not recommended. If you do decide to do this, be sure to stop JBoss
EAP 6 completely before editing the XML file.
Report a bug
4 .2. Configure Net work Firewalls t o Work wit h JBoss EAP 6

Su mmary
Most production environments use firewalls as part of an overall network security strategy. If you
need multiple server instances to communicate with each other or with external services such as web
servers or databases, your firewall must take this into account. A well-managed firewall only opens
the ports which are necessary for operation, and limits access to the ports to specific IP addresses,
subnets, and network protocols.
A full discussion of firewalls is out of the scope of this documentation.
Prereq u isit es
D etermine the ports you need to open.
An understanding of your firewall software is required. This procedure uses the systemco nfi g -fi rewal l command in Red Hat Enterprise Linux 6. Microsoft Windows Server includes
a built-in firewall, and several third-party firewall solutions are available for each platform. On
Microsoft Windows Server, you can use PowerShell to configure the firewall.
Assu mp t io n s
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 external
interface eth1.
You want traffic on port 54 4 5 (a port used by JMS) forwarded to JBoss EAP 6. No other traffic
should be allowed through the network firewall.
Pro ced u re 4 .1. Man ag e N et wo rk Firewalls an d JB o ss EAP 6 t o wo rk t o g et h er
1. Lo g in t o t h e Man ag emen t C o n so le.
Log into the Management Console. By default, it runs on http://localhost:9990/console/.
2. D et ermin e t h e so cket b in d in g s u sed b y t h e so cket b in d in g g ro u p .
a. Click the C o nfi g urati o n label at the top of the Management Console.
b. Expand the G eneral C o nfi g urati o n menu. Select the So cket Bi nd i ng .
22
c. The So cket Bi nd i ng D ecl arati o ns screen appears. Initially, the stand ard so ckets group 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 the
pages by using the arrow navigation below the table.
3. D et ermin e t h e p o rt s yo u n eed t o o p en .
D epending on the function of the particular port and the requirements of your environment,
some ports may need to be opened on your firewall.
4. C o n f ig u re yo u r f irewall t o f o rward t raf f ic t o JB o ss 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-co nfi g -fi rewal l to launch the firewall configuration
utility. A GUI or command-line utility launches, depending on the way you are logged
into the firewall system. This task makes the assumption that you are logged in via
SSH and using the command-line interface.
c. Use the T AB key on your keyboard to navigate to the C usto mi ze button, and press
the ENT ER key. The T rusted Servi ces screen appears.
d. D o not change any values, but use the T AB key to navigate to the Fo rward button,
and press ENT ER to advanced to the next screen. The O ther P o rts screen appears.
e. Use the T AB key to navigate to the <Ad d > button, and press ENT ER . The P o rt and
P ro to co l screen appears.
f. Enter 54 4 5 in the P o rt / P o rt R ang e field, then use the T AB key to move to the
P ro to co l field, and enter tcp. Use the T AB key to navigate to the O K button, and
press ENT ER .
g. Use the T AB key to navigate to the Fo rward button until you reach the P o rt
Fo rward i ng screen.
h. Use the T AB key to navigate to the <Ad d > button, and press the ENT ER key.
i. Fill in the following values to set up port forwarding for port 54 4 5.
Source interface: eth1
Protocol: tcp
Port / Port Range: 54 4 5
D estination IP address: 10 . 1. 1. 2
Port / Port Range: 54 4 5
23
Use the T AB key to navigate to the O K button, and press ENT ER .

j. Use the T AB key to navigate to the C l o se button, and press ENT ER .
k. Use the T AB key to navigate to the O K button, and press ENT ER . To apply the
changes, read the warning and click Y es.
5. C o n f ig u re a f irewall o n yo u r JB o ss EAP 6 h o st .
Some organizations choose to configure a firewall on the JBoss EAP 6 server itself, and
close all ports that are not necessary for its operation. See Section 4.3, Network Ports Used
By JBoss EAP 6 and determine which ports to open, then close the rest. The default
configuration of Red Hat Enterprise Linux 6 closes all ports except 22 (used for Secure Shell
(SSH) and 5353 (used for multicast D NS). While you are configuring ports, ensure you have
physical access to your server so that you do not inadvertently lock yourself out.
R esu lt
Your firewall is configured to forward traffic to your internal JBoss EAP 6 server in the way you
specified in your firewall configuration. If you chose to enable a firewall on your server, all ports are
closed except the ones needed to run your applications.
Pro ced u re 4 .2. C o n f ig u rin g Firewall o n Micro so f t Win d o ws u sin g Po werSh ell
1. Switch off firewall for debug purpose to determine whether the current network behavior is
related to the firewall configuration.
Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList 'command "NetSh Advfirewall set allprofiles state off"'
2. Allow UD P 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"'
Pro ced u re 4 .3. C o n f ig u re t h e Firewall o n R ed H at En t erp rise Lin u x 7 t o Allo w
mo d _clu st er Ad vert isin g
To allow mod_cluster advertising on Red Hat Enterprise Linux 7, you must enable the UD P port in
the firewall as follows:
firewall-cmd --permanent --zone=public --add-port=23364/udp
Note
224.0.1.105:23364 is the default address and port for mod_cluster balancer advertising
UD P multicast.
Report a bug
24
4 .3. Net work Port s 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.
Numerical port offsets

A numerical port offset can be configured, to alleviate port conflicts when you run multiple
servers on the same physical server. If your server uses a numerical port offset, add the offset
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 80 80 , and your server uses a port offset of 10 0 , its
HTTP port is 8180 .
Unless otherwise stated, the ports use the TCP protocol.
T h e d ef au lt so cket b in d in g g ro u p s
ful l -ha-so ckets
ful l -so ckets
ha-so ckets
stand ard -so ckets
T ab le 4 .1. R ef eren ce o f t h e d ef au lt so cket b in d in g s
N ame
Po rt
ajp
8009
http
8080
https
8443
jaco rb
3528
jaco rb
-ssl
3529
Mu lt ica
st Po rt
D escrip t io n
f u ll- h aso cket s
f u llso cket s
h aso cket
st an d ar
dso cket
Apache JServ
Protocol. Used for
HTTP clustering
and load balancing.
The default port for
deployed web
applications.
SSL-encrypted
connection between
deployed web
applications and
clients.
CORBA services for
JTS transactions
and other ORBdependent services.
SSL-encrypted
CORBA services.
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
No
Yes
Yes
No
No
25
N ame
Po rt
Mu lt ica
st Po rt
D escrip t io n
f u llso cket s
h aso cket
st an d ar
dso cket
jg ro up
sd i ag no
sti cs
7500
Yes
No
Yes
No
jg ro up
smpi ng
45700
Multicast. Used for

peer discovery in HA
clusters. Not
configurable using
the Management
Interfaces.
Multicast. Used to
discover initial
membership in a HA
cluster.
Unicast peer
discovery in HA
clusters using TCP.
Used for HA failure
detection over TCP.
Yes
No
Yes
No
Yes
No
Yes
No
Yes
No
Yes
No
Multicast peer
discovery in HA
clusters using UD P.
Used for HA failure
detection over UD P.
Yes
No
Yes
No
Yes
No
Yes
No
JMS service.
Yes
Yes
No
No
Referenced by
HornetQ JMS
broadcast and
discovery groups.
Used by JMS
Remoting.
Yes
Yes
No
No
Yes
Yes
No
No
Multicast port for

communication
between JBoss EAP
6 and the HTTP
load balancer.
Used by internal
components which
use the OSGi
subsystem. Not
configurable using
the Management
Interfaces.
Used for remote EJB
invocation.
The JTA transaction
recovery manager.
Yes
No
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
jg ro up
s-tcp
7600
jg ro up
s-tcpfd
jg ro up
s-ud p
57600
jg ro up
s-ud pfd
messag
i ng
messag
i ng g ro up
54200
messag
i ng thro ug
hput
mo d _cl
uster
5455
o sg i http
8090
55200
5445
23364
remo ti
4447
ng
txn4712
reco ver
yenvi ro
nment
26
45688
N ame
Po rt
txnstatusmanag e
r
4713
Mu lt ica
st Po rt
D escrip t io n
f u llso cket s
h aso cket
st an d ar
dso cket
The JTA / JTS

transaction
manager.
Yes
Yes
Yes
Yes
Man ag emen t Po rt s
In addition to the socket binding groups, each host controller opens two more ports for management
purposes:
9 9 9 0 - The Web Management Console port
9 9 9 9 - 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 Encrypt ion

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 data
communication streams. The HTTPS protocol, for instance, encrypts all data before transferring it
from one party to another. If you connect from one server to another using the Secure Shell (SSH)
protocol, all of your communication is sent in an encrypted tunnel .
Report a bug
4 .5. About SSL Encrypt ion

Secure Sockets Layer (SSL) encrypts network traffic between two systems. Traffic between the two
systems is encrypted using a two-way key, generated during the handshake phase of the connection
and known only by those two systems.
For secure exchange of the two-way encryption key, SSL makes use of Public Key Infrastructure
(PKI), a method of encryption that utilizes a key pair. A key pair consists of two separate but matching
cryptographic keys - a public key and a private key. The public key is shared with others and is used
to encrypt data, and the private key is kept secret and is used to decrypt data that has been
encrypted using the public key.
When a client requests a secure connection, a handshake phase takes place before secure
communication can begin. D uring the SSL handshake the server passes its public key to the client in
the form of a certificate. The certificate contains the identity of the server (its URL), the public key of
the server, and a digital signature that validates the certificate. The client then validates the certificate
and makes a decision about whether the certificate is trusted or not. If the certificate is trusted, the
27
client generates the two-way encryption key for the SSL connection, encrypts it using the public key
of the server, and sends it back to the server. The server decrypts the two-way encryption key, using
its private key, and further communication between the two machines over this connection is
encrypted using the two-way encryption key.
Warning
Red Hat recommends that you explicitly disable SSL in favor of TLSv1.1 or TLSv1.2 in all
affected packages.
Report a bug
4 .6. Implement SSL Encrypt ion for t he JBoss EAP 6 Web Server
In t ro d u ct io n
Many web applications require an SSL-encrypted connection between clients and server, also known
as a HT T P S connection. You can use this procedure to enable HT T P S on your server or server
group.
Warning
affected packages.
Prereq u isit es
A set of SSL encryption keys and an SSL encryption certificate. You may purchase these from a
certificate-signing authority, or you can generate them yourself using command-line utilities. To
generate 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.
C ip h er Su it es
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
primitives which, while they may be used for compatibility with existing software, are not considered
as secure as those recommended.
28
Warning
Red Hat recommends selectively whitelisting a set of strong ciphers to use for ci pher-sui te.
Enabling weak ciphers is a significant security risk. Consult your JD K vendor's documentation
before deciding on particular cipher suites as there may be compatibility issues.
T ab le 4 .2. R eco mmen d ed C ryp t o g rap h ic Primit ives

RSA with 2048 bit keys and OAEP
AES-128 in CBC mode
SHA-256
HMAC-SHA-256
HMAC-SHA-1
T ab le 4 .3. O t h er C ryp t o g rap h ic Primit ives
RSA with key sizes larger than 1024 and legacy padding
AES-192
AES-256
3D ES (triple D ES, with two or three 56 bit keys)
RC4 (strongly discouraged)
SHA-1
HMAC-MD 5
For a full listing of parameters you can set for the SSL properties of the connector, see Section 4.8,
SSL Connector Reference .
Note
This procedure uses commands appropriate for a JBoss EAP 6 configuration that uses a
managed domain. If you use a standalone server, modify Management CLI commands by
removing the /pro fi l e= d efaul t from the beginning of any management CLI commands.
Warning
affected packages.
Pro ced u re 4 .4 . C o n f ig u re t h e JB o ss Web Server t o u se H T T PS

1. Ad d a n ew H T T PS co n n ect o r.
Create a secure connector, named HTTPS, which uses the https scheme, the https socket
binding (which defaults to 84 4 3), and is set to be secure.
/profile=default/subsystem=web/connector=HTTPS/:add(socketbinding=https,scheme=https,protocol=HTTP/1.1,secure=true)
29
2. C o n f ig u re t h e SSL en cryp t io n cert if icat e an d keys.

Configure your SSL certificate, substituting your own values for the example ones. This
example assumes that the keystore is copied to the server configuration directory, which is
EAP_HOME/d o mai n/co nfi g urati o n/ for a managed domain.
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration:ad
d(name=https,certificate-keyfile="${jboss.server.config.dir}/keystore.jks",password=SECRET, keyalias=KEY_ALIAS, cipher-suite=CIPHERS)
3. Set t h e p ro t o co l t o T LSv1.
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:w
rite-attribute(name=protocol,value=TLSv1)
4. D ep lo y an ap p licat io n .
D eploy an application to a server group which uses the profile you have configured. If you
use a standalone server, deploy an application to your server. HTTPS requests to it use the
new SSL-encrypted connection.
Report a bug
4 .7. Generat e a SSL Encrypt ion Key and Cert ificat e

To use a SSL-encrypted HTTP connection (HTTPS), as well as other types of SSL-encrypted
communication, you need a signed encryption certificate. You can purchase a certificate from a
Certificate Authority (CA), or you can use a self-signed certificate. Self-signed certificates are not
considered 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
Red Hat Enterprise Linux.
Prereq u isit es
You need the keyto o l utility, which is provided by any Java D evelopment Kit implementation.
OpenJD K on Red Hat Enterprise Linux installs this command to /usr/bi n/keyto o l .
Understand the syntax and parameters of the keyto o l command. This procedure uses extremely
generic instructions, because further discussion of the specifics of SSL certificates or the
keyto o l command are out of scope for this documentation.
Pro ced u re 4 .5. G en erat e a SSL En cryp t io n K ey an d C ert if icat e
1. G en erat e a keyst o re wit h p u b lic an d p rivat e keys.
Run the following command to generate a keystore named server. keysto re with the alias
jbo ss 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"
30
The following table describes the parameters used in the keytool command:
Paramet er
D escrip t io n
-genkeypair
The keyto o l command to generate a key

pair containing a public and private key.
The alias for the keystore. This value is
arbitrary, but the alias jbo ss is the default
used by the JBoss Web server.
The key pair generation algorithm. In this
case it is R SA.
The name and location of the keystore file.
The default location is the current directory.
The name you choose is arbitrary. In this
case, the file will be named
server. keysto re.
This password is used to authenticate to the
keystore so that the key can be read. The
password must be at least 6 characters long
and must be provided when the keystore is
accessed. In this case, we used
mykeysto repass. If you omit this
parameter, you will be prompted to enter it
when you execute the command.
This is the password for the actual key.
-alias
-keyalg
-keystore
-storepass
-keypass
Note
D ue to an implementation limitation
this must be the same as the store
password.
--dname
A quoted string describing the distinguished

name for the key, for example:
" CN=jsmith,OU=Engineering,O=mycompany.
com,L=Raleigh,C=US" . This string is a
concatenation of the following components:
C N - The common name or host name. If
the hostname is
" jsmith.mycompany.com" , the C N is
" jsmith" .
O U - 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" ,
When you execute the above command, you are prompted for the following information:
31
If you did not use the -storepass parameter on the command line, you are asked to
enter the 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
the key password. Press Enter to set this to the same value as the keystore password.
When the command completes, the file server. keysto re now contains the single key with
the alias jbo ss.
2. Verif y t h e 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
this case, a single key called jbo ss). Notice the type of the jbo ss key, which is
P ri vateKeyEntry. This indicates that the keystore contains both a public and private entry
for this key.
3. G en erat e a cert if icat e sig n in g req u est .
Run the following command to generate a certificate signing request using the public key
from the keystore you created in step 1.
keytool -certreq -keyalg RSA -alias jboss -keystore server.keystore
-file certreq.csr
You are prompted for the password in order to authenticate to the keystore. The keyto o l
command then creates a new certificate signing request called certreq . csr in the current
working directory.
4. T est t h e n ewly g en erat ed cert if icat e sig n in g req u est .
Test the contents of the certificate by using the following command.
openssl req -in certreq.csr -noout -text
The certificate details are shown.
5. O p t io n al: Su b mit yo u r cert if icat e sig n in g req u est t o a C ert if icat e Au t h o rit y ( C A) .
A Certificate Authority (CA) can authenticate your certificate so that it is considered
trustworthy by third-party clients. The CA supplies you with a signed certificate, and
optionally with one or more intermediate certificates.
6. O p t io n al: Exp o rt a self - sig n ed cert if icat e f ro m t h e keyst o re.
If you only need it for testing or internal purposes, you can use a self-signed certificate. You
can export one from the keystore you created in step 1 as follows:
keytool -export -alias jboss -keystore server.keystore -file
server.crt
32
You are prompted for the password in order to authenticate to the keystore. A self-signed
certificate, named server. crt, is created in the current working directory.
7. Imp o rt t h e sig n ed cert if icat e, alo n g wit h an y in t ermed iat e cert if icat es.
Import each certificate, in the order that you are instructed by the CA. For each certificate to
import, replace i ntermed i ate. ca or server. crt with the actual file name. If your
certificates are not provided as separate files, create a separate file for each certificate, and
paste its contents into the file.
Note
Your signed certificate and certificate keys are valuable assets. Be cautious with how
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. T est t h at yo u r cert if icat es imp o rt ed su ccessf u lly.
Run the following command, and enter the keystore password when prompted. The contents
of your keystore are displayed, and the certificates are part of the list.
keytool -list -keystore server.keystore
R esu lt
Your signed certificate is now included in your keystore and is ready to be used to encrypt SSL
connections, including HTTPS web server communications.
Report a bug
4 .8. SSL Connect or Reference

JBoss Web connectors may include the following SSL configuration attributes. The CLI commands
provided are designed for a managed domain using profile d efaul t. Change the profile name to the
one you wish to configure, for a managed domain, or omit the /pro fi l e= d efaul t portion of the
command, for a standalone server.
T ab le 4 .4 . SSL C o n n ect o r At t rib u t es
At t rib u t e
D escrip t io n
C LI C o mman d
name
The display name of the SSL

connector.
Attribute name is read-only.
33
At t rib u t e
D escrip t io n
C LI C o mman d
verify-client
The possible values of

veri fy-cl i ent differ, based
upon whether the HTTP/HTTPS
connector is used, or the native
APR connector is used.
The first example command

uses the HTTPS connector.
H T T P/H T T PS C o n n ect o r
/profile=default/subs
ystem=web/connector=
HTTPS/ssl=configurat
ion/:writeattribute(name=verif
y-client,value=want)
Possible values are true,

fal se, or want. Set to true to
require a valid certificate chain
The second example command
from the client before accepting
uses the APR connector.
a connection. Set to want if you
want the SSL stack to request a
client Certificate, but not fail if
one is not presented. Set to
APR/ssl=configuratio
fal se (the default) to not
n/:writerequire a certificate chain
attribute(name=verif
unless the client requests a
yresource protected by a
client,value=require
security constraint that uses
)
C LIENT -C ER T authentication.
N at ive APR C o n n ect o r
verify-depth
34
Possible values are

o pti o nal , req ui re,
o pti o nal No C A, and no ne (or
any other string, which will
have the same effect as no ne).
These values determine
whether a certification is
optional, required, optional
without a Certificate Authority,
or not required at all. The
default is no ne, meaning the
client will not have the
opportunity to submit a
certificate.
The maximum number of
intermediate certificate issuers
checked before deciding that
the clients do not have a valid
certificate. The default value is
10 .
ion/:writeattribute(name=verif
y-depth,value=10)
At t rib u t e
D escrip t io n
certificate-key-file
The full file path and file name

of the keystore file where the
signed server certificate is
stored. With JSSE encryption,
this certificate file will be the
only one, while OpenSSL uses
several files. The default value
is the . keysto re file in the
home directory of the user
running JBoss EAP 6. If your
keysto reT ype does not use a
file, set the parameter to an
empty string.
If you use OpenSSL encryption,
set the value of this parameter
to the path to the file containing
the server certificate.
certificate-file
password
protocol
The password for both the

truststore and keystore. In the
following example, replace
PASSWORD with your own
password.
The version of the SSL protocol

to use. Supported values
depend on the underlying SSL
implementation (whether JSSE
or OpenSSL). Refer to the Java
SSE D ocumentation.
You can also specify a
combination of protocols,
which is comma separated. For
example, TLSv1,
TLSv1.1,TLSv1.2.
Warning
C LI C o mman d
ion/:writeattribute(name=certi
ficate-keyfile,value=../domain
/configuration/serve
r.keystore)
ficatefile,value=server.cr
t)
ion/:writeattribute(name=passw
ord,value=PASSWORD)
ion/:writeattribute(name=proto
col,value=ALL)
ion/:writeattribute(name=proto
col,value="TLSv1,
TLSv1.1,TLSv1.2")
Red Hat recommends

that you explicitly
disable SSL in favor of
TLSv1.1 or TLSv1.2 in all
affected packages.
35
At t rib u t e
D escrip t io n
cipher-suite
A list of the encryption ciphers

which are allowed. For JSSE
syntax, it must be a commaseparated list. For OpenSSL
syntax, it must be a colonseparated list. Ensure that you
only use one syntax.
The default is
HIG H: ! aNULL: ! eNULL: ! EX
P O R T : ! D ES: ! R C 4 : ! MD 5.
C LI C o mman d
ion/:writeattribute(name=ciphe
r-suite,
value="TLS_RSA_WITH_
AES_128_CBC_SHA,TLS_
RSA_WITH_AES_256_CBC
_SHA")
The example only lists two

possible ciphers, but real-world
examples will likely use more.
Important
Using weak ciphers is a
significant security risk.
See
http://www.nist.gov/manu
script-publicationsearch.cfm?
pub_id=915295 for NIST
recommendations on
cipher suites.
For a list of available OpenSSL
ciphers, see
https://www.openssl.org/docs/a
pps/ciphers.html#CIPHER_STRI
NGS. Note that the following
are not supported:
@ SEC LEVEL, SUIT EB128,
SUIT EB128O NLY ,
SUIT EB19 2.
key-alias
36
The alias used to for the server

certificate in the keystore. In the
following example, replace
KEY_ALIAS with your
certificate's alias.
ion/:writeattribute(name=keyalias,value=KEY_ALIA
S)
At t rib u t e
D escrip t io n
truststore-type
The type of the truststore.

Various types of truststores are
available, including P KC S12
and Java's standard JKS.
keystore-type
ca-certificate-file
ca-certificate-password
ca-revocation-url
The type of the keystore,

Various types of keystores are
available, including P KC S12
and Java's standard JKS.
The file containing the CA

certificates. This is the
truststo reFi l e, in the case
of JSSE, and uses the same
password as the keystore. The
ca-certi fi cate-fi l e file is
used to validate client
certificates.
The Certificate password for the

ca-certi fi cate-fi l e. In
the following example, replace
the MASKED_PASSWORD with
your own masked password.
A file or URL which contains the

revocation list. It refers to the
crl Fi l e for JSSE or the
SSLC AR evo cati o nFi l e for
SSL.
C LI C o mman d
ion/:writeattribute(name=trust
storetype,value=jks)
ion/:writeattribute(name=keyst
ore-type,value=jks)
ficatefile,value=ca.crt)
ion/:writeattribute(name=cacertificatepassword,value=MASKE
D_PASSWORD)
ion/:writeattribute(name=carevocationurl,value=ca.crl)
37
At t rib u t e
D escrip t io n
session-cache-size
The size of the SSLSession

cache. This attribute applies
only to JSSE connectors. The
default is 0 , which specifies an
unlimited cache size.
session-timeout
C LI C o mman d
The number of seconds before

a cached SSLSession expires.
This attribute applies only to
JSSE connectors. The default
is 86 4 0 0 seconds, which is 24
hours.
ion/:writeattribute(name=sessi
on-cachesize,value=100)
ion/:writeattribute(name=sessi
ontimeout,value=43200)
Report a bug
4 .9. FIPS 14 0-2 Compliant Encrypt ion

4 .9.1. About FIPS 14 0-2 Compliance
The Federal Information Processing Standard 140-2 (FIPS 140-2) is a US government computer
security standard for the accreditation of cryptographic software modules. FIPS 140-2 compliance is
often a requirement 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
compliant cryptography module.
Report a bug
4 .9.2. FIPS 14 0-2 Compliant Crypt ography on IBM JDK

On the IBM JD K, the IBM JCE (Java Cryptographic Extension) IBMJCEFIPS provider and the IBM
JSSE (Java Secure Sockets Extension) FIPS 140-2 Cryptographic Module (IBMJSSEFIPS) for Multiplatforms provide FIPS 140-2 compliant cryptography.
For more information on the IBMJCEFIPS provider, refer to the IBM D ocumentation for IBM JCEFIPS,
and the NIST IBMJCEFIPS Security Policy.
Ke y st o rage
Note that the IBM JCE does not provide a keystore. The keys are stored on the computer and do not
leave its physical boundary. If the keys are moved between computers they must be encrypted.
To run keyto o l in FIPS-compliant mode use the -pro vi d erC l ass option on each command like
this:
38
keytool -list -storetype JCEKS -keystore mystore.jck -storepass

mystorepass -providerClass com.ibm.crypto.fips.provider.IBMJCEFIPS
Exam ine FIPS pro vide r info rm at io n

To examine information about the IBMJCEFIPS used by the server, enable debug-level logging by
adding -D javax. net. d ebug = true to stand al o ne. co nf or d o mai n. co nf. Information about
the FIPS provider is logged to server. l o g , for example:
04:22:45,685 INFO [stdout] (http-/127.0.0.1:8443-1) JsseJCE: Using
MessageDigest SHA from provider IBMJCEFIPS version 1.7
04:22:45,689 INFO [stdout] (http-/127.0.0.1:8443-1) DHCrypt: DH
KeyPairGenerator from provider from init IBMJCEFIPS version 1.7
KeyFactory DiffieHellman from provider IBMJCEFIPS version 1.7
KeyAgreement DiffieHellman from provider IBMJCEFIPS version 1.7
KeyAgreement from provider IBMJCEFIPS version 1.7
KeyAgreement from provider from initIBMJCEFIPS version 1.7
Report a bug
4 .9.3. FIPS 14 0-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
uppercase ASCII letter for restriction 2.
If the last character of the password is an ASCII digit, then it does not count as an ASCII digit for
restriction 2.
Report a bug
4 .9.4 . Enable FIPS 14 0-2 Crypt ography for SSL on Red Hat Ent erprise Linux 6
This task describes how to configure the web container (JBoss Web) of JBoss EAP 6 to FIPS 140-2
compliant cryptography for SSL. This task only covers the steps to do this on Red Hat Enterprise
Linux 6.
39
This task uses the Mozilla NSS library in FIPS mode for this feature.
Prereq u isit es
Red Hat Enterprise Linux 6 must already be configured to be FIPS 140-2 compliant. Refer to
https://access.redhat.com/knowledge/solutions/137833.
Pro ced u re 4 .6 . En ab le FIPS 14 0- 2 C o mp lian t C ryp t o g rap h y f o r SSL
1. C reat e t h e d at ab ase
Create the NSS database in a directory own by the jbo ss user.
$ mkdir -p /usr/share/jboss-as/nssdb
$ chown jboss /usr/share/jboss-as/nssdb
$ modutil -create -dbdir /usr/share/jboss-as/nssdb
2. C reat e N SS co n f ig u rat io n f ile
Create a new text file with the name nss_pkcsl l _fi ps. cfg in the /usr/share/jbo ss-as
directory with the following contents:
name = nss-fips
nssLibraryDirectory=/usr/lib64
nssSecmodDirectory=/usr/share/jboss-as/nssdb
nssModule = fips
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
nssLi braryD i recto ry to /usr/l i b instead of /usr/l i b6 4 .
3. En ab le Su n PK C S11 p ro vid er
Edit the java. securi ty configuration file for your JRE
($JAVA_HO ME/jre/l i b/securi ty/java. securi ty) and add the following line:
security.provider.1=sun.security.pkcs11.SunPKCS11
as/nss_pkcsll_fips.cfg
/usr/share/jboss-
Note that the configuration file specified in this line is the file created in step 2.
Any other securi ty. pro vi d er. X lines in this file must have the value of their X increased
by one to ensure that this provider is given priority.
4. En ab le FIPS mo d e f o r t h e N SS lib rary
Run the mo d uti l command as shown to enable FIPS mode:
modutil -fips true -dbdir /usr/share/jboss-as/nssdb
40
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 library
signatures for some of the NSS shared objects.
5. C h an g e t h e p asswo rd o n t h e FIPS t o ken
Set the password on the FIPS token using the following command. Note that the name of the
token must be NSS FIP S 14 0 -2 C erti fi cate D B.
modutil -changepw "NSS FIP S 14 0 -2 C erti fi cate D B" -dbdir
/usr/share/jboss-as/nssdb
The password used for the FIPS token must be a FIPS compliant password.
6. C reat e cert if icat e u sin g N SS t o o ls
Enter 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/jbossas/nssdb
7. C o n f ig u re t h e H T T PS co n n ect o r t o u se t h e PK C S11 keyst o re
Add a HTTPS connector using the following command in the JBoss CLI Tool:
/subsystem=web/connector=https/:add(socketbinding=https,scheme=https,protocol=HTTP/1.1,secure=true)
Then add the SSL configuration with the following command, replacing PASSWORD with the
FIPS compliant password from step 5.
/subsystem=web/connector=https/ssl=configuration:add(name=https,pass
word=PASSWORD,keystore-type=PKCS11,
ciphersuite="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_CB
C_SHA,
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_3DES_EDE_C
BC_SHA,
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_C
BC_SHA,
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_RSA_WITH_AES_128_CBC_SH
A,
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_S
HA,
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_S
41
HA,
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. Verif y
Verify that the JVM can read the private key from the PKCS11 keystore by running the
following command:
keytool -list -storetype pkcs11
Examp le 4 .5. XML co n f ig u rat io n f o r H T T PS co n n ect o r u sin g FIPS 14 0- 2 co mp lian ce

< connector name="https" protocol="HTTP/1.1" scheme="https" socketbinding="https" secure="true">
<ssl name="https" password="****"
ciphersuite="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_S
HA,
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>
Note that the ci pher-sui te attribute has linebreaks inserted to make it easier to read.
Report a bug
42
Chapter 5. Secure the Management Interfaces

A common development scenario is to run JBoss EAP 6 with no security on the management
interfaces to 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)
to connect to the Management CLI without requiring a username or password. This is a convenience
for local users and Management CLI scripts. To disable this, refer to Section 5.4, Remove Silent
Authentication from the D efault Security Realm .
Report a bug
5.1. Default User Securit y Configurat ion

In t ro d u ct io n
All management interfaces in JBoss EAP 6 are secured by default. This security takes two different
forms:
Local interfaces are secured by a SASL contract between local clients and the server they connect
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 otherwise change
the configuration to thwart other security mechanisms. This adheres to the principle that if
physical access to the filesystem is achieved, other security mechanisms are superfluous. The
mechanism happens in four steps:
Note
HTTP access is considered to be remote, even if you connect to the localhost using HTTP.
The client sends a message to the server which includes a request to authenticate with the
local SASL mechanism.
The server generates a one-time token, writes it to a unique file, and sends a message to
the client with the full path of the file.
The client reads the token from the file and sends it to the server, verifying that it has local
access to the filesystem.
The server verifies the token and then deletes the file.
Remote clients, including local HTTP clients, use realm-based security. The default realm with the
permissions to configure the JBoss EAP 6 instance remotely using the management interfaces is
Manag ementR eal m. A script is provided which allows you to add users to this realm (or realms
you create). For more information on adding users, see the Getting Started chapter of the JBoss
EAP 6 Installation Guide. For each user, the username and a hashed password are stored in a file.
Man ag ed d o main
43
EAP_HOME/d o mai n/co nfi g urati o n/mg mt-users. pro perti es

St an d alo n e server
EAP_HOME/stand al o ne/co nfi g urati o n/mg mt-users. pro perti es
Even though the contents of the mg mt-users. pro perti es are masked, the file must still be
treated as a sensitive file. It is recommended that it be set to the file mode of 6 0 0 , which gives no
access other than read and write access by the file owner.
Report a bug
5.2. Overview of Advanced Management Int erface Configurat ion

The Management interface configuration in the EAP_HOME/d o mai n/co nfi g urati o n/ho st. xml
or EAP_HOME/stand al o ne/co nfi g urati o n/stand al o ne. xml controls which network
interfaces the host controller process binds to, which types of management interfaces are available at
all, and which type of authentication system is used to authenticate users on each interface. This
topic discusses how to configure the Management Interfaces to suit your environment.
The Management subsystem consists of a <manag ement> element that includes the following four
configurable child elements. The security realms and outbound connections are each first defined,
and then 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 and Configuration
Guide for more information on audit logging.
Secu rit y R ealms

The security realm is responsible for the authentication and authorization of users allowed to
administer JBoss 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: Manag ementR eal m
and Appl i cati o nR eal m. Each of these security realms uses a -users. pro perti es file to store
users and hashed passwords, and a -ro l es. pro perti es to store mappings between users and
roles. Support is also included for an LD AP-enabled security realm.
Note
Security realms can also be used for your own applications. The security realms discussed
here are specific to the management interfaces.
O u t b o u n d C o n n ect io n s
44
Chapt er 5. Secure t he Management Int erfaces
Some security realms connect to external interfaces, such as an LD AP server. An outbound
connection defines how to make this connection. A pre-defined connection type, l d apco nnecti o n, sets all of the required and optional attributes to connect to the LD AP server and verify
the credential.
For more information on how to configure LD AP authentication see Section 5.11.2, Use LD AP to
Authenticate to the Management Interfaces .
Man ag emen t In t erf aces
A management interface includes properties about how connect to and configure JBoss EAP. Such
information includes the named network interface, port, security realm, and other configurable
information about the interface. Two interfaces are included in a default installation:
http-i nterface is the configuration for the web-based Management Console.
nati ve-i nterface is the configuration for the command-line Management CLI and the RESTlike Management API.
Each of the main configurable elements of the host management subsystem are interrelated. A
security realm 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 t he HT T P Management Int erface

In a managed domain, you only need access to the HTTP interface on the domain controller, rather
than on 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, you can
set the co nso l e-enabl ed attribute of the HTTP interface to fal se, instead of disabling the
interface completely.
/host=master/core-service=management/management-interface=httpinterface/:write-attribute(name=console-enabled,value=false)
To disable access to the HTTP interface, which also disables access to the web-based Management
Console, you can delete the HTTP interface altogether.
The following JBoss CLI command allows you to read the current contents of your HTTP interface, in
case you decide to add it again.
Examp le 5.1. R ead t h e C o n f ig u rat io n o f t h e H T T P In t erf ace
45
/ho st= master/co re-servi ce= manag ement/manag ement-i nterface= httpi nterface/: read -reso urce(recursi ve= true,pro xi es= fal se,i ncl ud erunti me= fal se,i ncl ud e-d efaul ts= true)
{
"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:
Examp le 5.2. R emo ve t h e H T T P In t erf ace

/host=master/core-service=management/management-interface=httpinterface/:remove
To re-enable access, issue the following commands to re-create the HTTP Interface with the default
values.
Examp le 5.3. R e- C reat e t h e H T T P In t erf ace

/host=master/core-service=management/management-interface=httpinterface:add(consoleenabled=true,interface=management,port="${jboss.management.http.port:9
990}",security-realm=ManagementRealm)
Report a bug
5.4 . Remove Silent Aut hent icat ion from t he Default Securit y Realm
Su mmary
The default installation of JBoss EAP 6 contains a method of silent authentication for a local
Management CLI user. This allows the local user the ability to access the Management CLI without
username or password authentication. This functionality is enabled as a convenience, and to assist
local users running Management CLI scripts without requiring authentication. It is considered a
useful feature given that access to the local configuration typically also gives the user the ability to
add their own user details or otherwise disable security checks.
The convenience of silent authentication for local users can be disabled where greater security
control is required. This can be achieved by removing the l o cal element within the securi tyreal m section of the configuration file. This applies to both the stand al o ne. xml for a Standalone
Server instance, or ho st. xml for a Managed D omain. You should only consider the removal of the
l o cal element if you understand the impact that it might have on your particular server
configuration.
46
The preferred method of removing silent authentication is by use of the Management CLI, which
directly removes the l o cal element visible in the following example.
Examp le 5.4 . Examp le o f t h e l o cal elemen t in t h e securi ty-real m

<security-realms>
<security-realm name="ManagementRealm">
<authentication>
<local default-user="$local"/>
<properties path="mgmt-users.properties" relativeto="jboss.server.config.dir"/>
</authentication>
</security-realm>
<security-realm name="ApplicationRealm">
<authentication>
<local default-user="$local" allowed-users="*"/>
<properties path="application-users.properties" relativeto="jboss.server.config.dir"/>
</authentication>
<authorization>
<properties path="application-roles.properties" relativeto="jboss.server.config.dir"/>
</authorization>
</security-realm>
</security-realms>
Prereq u isit es
Start the JBoss EAP 6 instance.
Launch the Management CLI.
Pro ced u re 5.1. R emo ve Silen t Au t h en t icat io n f ro m t h e D ef au lt Secu rit y R ealm
R emo ve silen t au t h en t icat io n wit h t h e Man ag emen t C LI
Remove the l o cal element from the Management Realm and Application Realm as required.
Remove the l o cal element from the Management Realm.
A. Fo r St an d alo n e Servers
/core-service=management/securityrealm=ManagementRealm/authentication=local:remove
B. Fo r Man ag ed D o main s
/host=HOST_NAME/core-service=management/securityrealm=ManagementRealm/authentication=local:remove
Remove the l o cal element from the Application Realm.
A. Fo r St an d alo n e Servers
47
/core-service=management/securityrealm=ApplicationRealm/authentication=local:remove
B. Fo r Man ag ed D o main s
/host=HOST_NAME/core-service=management/securityrealm=ApplicationRealm/authentication=local:remove
R esu lt
The silent authentication mode is removed from the Manag ementR eal m and the
Appl i cati o nR eal m.
Report a bug
5.5. Disable Remot e Access t o t he JMX Subsyst em

Remote access to the JMX subsystem allows you to trigger JD K and application management
operations remotely. In order to secure an installation, disable this function either by removing the
remoting connector or removing the JMX subsystem. The example Management CLI commands are
suitable for a managed domain. For a standalone server, remove the /pro fi l e= d efaul t prefix
from the commands.
Note
In a managed domain the remoting connector is removed from the JMX subsystem by default.
This command is provided for your information, in case you add it during development.
Examp le 5.5. R emo ve t h e R emo t in g C o n n ect o r f ro m t h e JMX Su b syst em

/profile=default/subsystem=jmx/remoting-connector=jmx/:remove
Examp le 5.6 . R emo ve t h e JMX Su b syst em

For a managed domain, run this command for each profile.
/profile=default/subsystem=jmx/:remove
Report a bug
5.6. Configure Securit y Realms for t he Management Int erfaces

The management interfaces use security realms to control authentication and access to the
configuration mechanisms of JBoss EAP 6. A Security Realm is similar to a Unix group. It is
effectively a database of usernames and passwords that can be use to authenticate users.
D ef au lt Man ag emen t R ealm
48
The management interfaces are configured to use the Manag ementR eal m security realm by default.
The ManagementRealm stores its user password combinations in the file mg mtusers. pro perti es.
Examp le 5.7. D ef au lt Man ag emen t R ealm

/ho st= master/co re-servi ce= manag ement/securi tyreal m= Manag ementR eal m/: read reso urce(recursi ve= true,pro xi es= fal se,i ncl ud e-runti me= fal se,i ncl ud ed efaul ts= true)
{
"result" => {
"authorization" => undefined,
"server-identity" => undefined,
"authentication" => {"properties" => {
"path" => "mgmt-users.properties",
"plain-text" => false,
"relative-to" => "jboss.domain.config.dir"
}}
}
}
C reat e a n ew Secu rit y R ealm

The following commands create a new security realm called T estR eal m and set the directory for the
relevant properties file.
Examp le 5.8. C reat e a n ew Secu rit y R ealm

/ho st= master/co re-servi ce= manag ement/securi ty-real m= T estR eal m/: ad d
/ho st= master/co re-servi ce= manag ement/securi tyreal m= T estR eal m/authenti cati o n= pro perti es/: ad d (path= T estUsers. pro pert
i es, rel ati ve-to = jbo ss. d o mai n. co nfi g . d i r)
C o n f ig u re Secu rit y R ealm au t h en t icat io n t h ro u g h an exist in g Secu rit y D o main

To use Security D omain to authenticate to the Management interfaces:
First, create a Security Realm. Then, set specify it as the value for the securi ty-real m attribute of
the management interface:
Examp le 5.9 . Sp ecif y a Secu rit y R ealm t o u se f o r t h e H T T P Man ag emen t In t erf ace
/ho st= master/co re-servi ce= manag ement/manag ement-i nterface= httpi nterface/: wri te-attri bute(name= securi ty-real m,val ue= TestRealm)
Report a bug
49
5.7. Configure t he Management Console for HT T PS

Configuring the JBoss EAP management console for communication o n ly via HTTPS provides
increased security. All network traffic between the client (web browser) and management console is
encrypted, which reduces the risk of security attacks such as a man-in-the-middle attack. Anyone
administering 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
is disabled. Passwords used in these communications are stored encrypted using the JBoss EAP
vau lt feature, and passwords used in configuration files are masked.
This procedure applies to both stand al o ne and d o mai n mode configurations. For d o mai n mode,
prefix the management CLI commands with the name of the host, for example: /ho st= master.
Pro ced u re 5.2.
1. C reat e a keyst o re t o secu re t h e man ag emen t co n so le.
Note
This keystore must be in JKS format as the management console is not compatible 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 equals
two years.
keytool -genkeypair -alias appserver -storetype jks -keyalg RSA keysize 2048 -keypass password1 -keystore
EAP_HOME/stand al o ne/co nfi g urati o n/i d enti ty. jks -storepass
password1 -dname "CN=appserver,OU=Sales,O=Systems
Inc,L=Raleigh,ST=NC,C=US" -validity 730 -v
2. En su re t h e Man ag emen t C o n so le B in d s t o H T T PS
A. St an d alo n e Mo d e
Ensure the management console binds to HT T P S for its interface by adding the
manag ement-https configuration and removing the manag ement-http configuration.
Ensure the JBoss EAP instance is running, then enter the following management CLI
commands:
/co re-servi ce= manag ement/manag ement-i nterface= httpi nterface: wri te-attri bute(name= secure-so cket-bi nd i ng ,
val ue= manag ement-https)
/co re-servi ce= manag ement/manag ement-i nterface= httpi nterface: und efi ne-attri bute(name= so cket-bi nd i ng )
50
The expected output from these commands is:

{"outcome" => "success"}
Note
At this point the JBoss EAP log may display the following error message. This is 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.
B. D o main Mo d e
Change the socket element within the management-interface section by adding secureport and removing port configuration.
Ensure the JBoss EAP instance is running, then enter the following management CLI
commands:
/ho st= master/co re-servi ce= manag ement/manag ement-i nterface= httpi nterface: wri te-attri bute(name= secure-po rt,val ue= 9 4 4 3)
/ho st= master/co re-servi ce= manag ement/manag ement-i nterface= httpi nterface: und efi ne-attri bute(name= po rt)
Note
At this point the JBoss EAP log may display the following error message. This is 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. O p t io n al: C u st o m so cket - b in d in g g ro u p
If you are using a custom socket-binding group, ensure the management-https binding
is defined (it is present by default, bound to port 9 4 4 3). Edit the master configuration file - for
example stand al o ne. xml - to match the following.
<socket-binding-group name="standard-sockets" defaultinterface="public" port-offset="${jboss.socket.binding.portoffset:0}">
<socket-binding name="management-native"
interface="management"
port="${jboss.management.native.port:9999}"/>
51
<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}"/>
4. C reat e a n ew Secu rit y R ealm
Enter the following commands to create a new security realm named
Manag ementR eal mHT T P S:
/host=master/core-service=management/securityrealm=ManagementRealmHTTPS/:add
/host=master/core-service=management/securityrealm=ManagementRealmHTTPS/authentication=properties/:add(path=Man
agementUsers.properties, relative-to=jboss.domain.config.dir)
5. C o n f ig u re Man ag emen t In t erf ace t o u se t h e n ew secu rit y realm
Enter the following commands:
/host=master/core-service=management/management-interface=httpinterface/:write-attribute(name=securityrealm,value=ManagementRealmHTTPS)
6. C o n f ig u re t h e man ag emen t co n so le t o u se t h e keyst o re.
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 management
console.
/core-service=management/securityrealm=ManagementRealmHTTPS/server-identity=ssl:add(keystorepath=identity.jks,keystore-relative-to=jboss.server.config.dir,
keystore-password=password1, alias=appserver)
The expected output from this command is:
{
"response-headers" => {
"operation-requires-reload" => true,
"process-state" => "reload-required"
}
}
7. R est art t h e JB o ss EAP server.
On restarting the server the log should contain the following, just before the text which states
the number 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/management
52
14: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 details on
how to do this see Section 7.1, Password Vault System .
Report a bug
5.8. Use Dist inct Int erfaces for HT T P and HT T PS connect ions t o t he
Management Int erface
The Management Interface can listen on distinct interfaces for HTTP and HTTPS connections. One
scenario for this is to listen for encrypted traffic on an external network, and use unencrypted traffic
on an internal network.
The secure-i nterface attribute specifies the network interface on which the host's socket for
HTTPS management communication should be opened, if a different interface should be used from
that specified by the i nterface attribute. If it is not specified then the interface specified by the
i nterface attribute is used.
The secure-i nterface attribute has no effect if the secure-po rt attribute is not set.
Note that when the server listens for HTTP and HTTPS traffic on the same interface, HTTPS requests
received by the HTTP listener are automatically redirected to the HTTPS port. When distinct interfaces
are used for HTTP and HTTPS traffic, no redirection is performed when an HTTPS request is received
by the HTTP listener.
Here is an example EAP_HOME/d o mai n/co nfi g urati o n/ho st. xml configuration that sets the
secure-i nterface 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" relativeto="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"
53
port="${jboss.management.http.port:9990}" secureport="${jboss.management.https.port:9943}" secure-interface="securemanagement"/>

</http-interface>
</management-interfaces>
</management>
<domain-controller>
<local/>


</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 t he Management int erface and t he CLI
2-way SSL authentication, also known as client authentication, authenticates both the client and the
server using SSL certificates. This provides assurance that not only is the server who it says it is, but
the client is also who it says it is.
In this topic the following conventions are used:
HOST1
The JBoss server hostname. For example; jbo ss. red hat. co m
HOST2
A suitable name for the client. For example: mycl i ent. Note this is not necessarily an
actual hostname.
CA_HOST1
The D N (distinguished name) to use for the HOST1 certificate. For example
cn= jbo ss,d c= red hat,d c= co m.
CA_HOST2
The D N (distinguished name) to use for the HOST2 certificate. For example
cn= mycl i ent,d c= red hat,d c= co m.
Prereq u isit es
54
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, Password
Vault System .
Pro ced u re 5.3.
1. Generate the stores:
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
2. Export the certificates:
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
3. Import the certificates into the opposing trust stores:
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
4. D efine a CertificateRealm in the configuration for your installation (ho st. xml or
stand al o ne. xml ) and point the interface to it:
This can be done by manually editing the configuration file (not recommended) or by using
the following commands:
/co re-servi ce= manag ement/securi ty-real m= C erti fi cateR eal m: ad d ()
/co re-servi ce= manag ement/securi ty-real m= C erti fi cateR eal m/serveri d enti ty= ssl : ad d (keysto repath= /path/to /HO ST 1. keysto re. jks,keysto re-passwo rd = secret,
al i as= HO ST 1_al i as)
/co re-servi ce= manag ement/securi tyreal m= C erti fi cateR eal m/authenti cati o n= truststo re: ad d (keysto repath= /path/to /HO ST 1. truststo re. jks,keysto re-passwo rd = secret)
55
Important
The provided commands apply to standalone mode only. For domain mode, add
/ho st= master before each command.
5. Change the security-realm of the native-interface to the new Certificate Realm.
/ho st= master/co re-servi ce= manag ement/manag ement-i nterface= nati vei nterface: wri te-attri bute(name= securi tyreal m,val ue= C erti fi cateR eal m)
6. Add the SSL configuration for the CLI, which uses EAP_HOME/bi n/jbo ss-cl i . xml as a
settings file. Either use a password vault to store the keystore and truststore passwords
(recommended), or store them in plain text:
A. To store the keystore and truststore passwords in a password vault:
Edit EAP_HOME/bi n/jbo ss-cl i . xml and add the SSL configuration (using the
appropriate values for the variables). Also add the vault configuration, replacing each
value with those of your vault.
<ssl>
<vault>
<vault-option name="KEYSTORE_URL" value="pathto/vault/vault.keystore"/>
<vault-option name="KEYSTORE_PASSWORD" value="MASK5WNXs8oEbrs"/>
<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/jbosseap/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-storepassword>
<modify-trust-store>true</modify-trust-store>
</ssl>
B. To store the keystore and truststore passwords in plain text:
Edit EAP_HOME/bi n/jbo ss-cl i . xml and add the SSL configuration (using the
appropriate values for the variables):
<ssl>
<alias>$HOST2alias</alias>
<key-store>/path/to/HOST2.keystore.jks</key-store>
<key-store-password>secret</key-store-password>
56
<trust-store>/path/to/HOST2.truststore.jks</trust-store>
<trust-store-password>secret</trust-store-password>
<modify-trust-store>true</modify-trust-store>
</ssl>
Report a bug
5.10. Secure t he Management Int erfaces via JAAS

To use JAAS to authenticate to the Management interfaces:
First, create a security domain with the UserRoles login module:
/subsystem=security/security-domain=UsersLMDomain:add(cache-type=default)
/subsystem=security/securitydomain=UsersLMDomain/authentication=classic:add
/subsystem=security/securitydomain=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/securityrealm=SecurityDomainAuthnRealm/authentication=jaas:add(name=UsersLMDomain
)
The attribute assi g n-g ro ups determines whether loaded user membership information from the
Security D omain is used for group assignment in the Security Realm. When set to true this group
assignment is used for Role-Based Access Control (RBAC).
The assi g n-g ro ups attribute can be set to true by this CLI command:
/core-service=management/securityrealm=ManagementRealm/authentication=jaas:write-attribute(name=assigngroups,value=true)
Report a bug
5.11. LDAP
5.11.1. About LDAP
Lightweight D irectory Access Protocol (LD AP) is a protocol for storing and distributing directory
information across a network. This directory information includes information about users, hardware
devices, access roles and restrictions, and other information.
Some common implementations of LD AP include OpenLD AP, Microsoft Active D irectory, IBM Tivoli
D irectory Server, Oracle Internet D irectory, and others.
JBoss EAP 6 includes several authentication and authorization modules which allow you to use a
LD AP server as the authentication and authorization authority for your Web and EJB applications.
Report a bug
57
5.11.2. Use LDAP t o Aut hent icat e t o t he Management Int erfaces

To use an LD AP 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 LD AP server.
2. Create an LD AP-enabled security realm.
3. Reference the new security domain in the Management Interface.
C reat e an O u t b o u n d C o n n ect io n t o an LD AP Server
The LD AP outbound connection allows the following attributes:
T ab le 5.1. At t rib u t es o f an LD AP O u t b o u n d C o n n ect io n
At t rib u t e
R eq u ired
D escrip t io n
url
yes
search-d n
no
search-cred enti al s
no
i ni ti al -co ntext-facto ry
no
securi ty-real m
no
The URL address of the

directory server.
The fully distinguished name
(D N) of the user authorized to
perform searches.
The password of the user
authorized to perform searches.
The initial context factory to use
when establishing the
connection. D efaults to
co m. sun. jnd i . l d ap. Ld ap
C txFacto ry.
The security realm to reference
to obtain a configured
SSLC o ntext to use when
establishing the connection.
Examp le 5.10. Ad d an LD AP O u t b o u n d C o n n ect io n

This example adds an outbound connection with the following properties set:
Search D N: cn= search,d c= acme,d c= co m
Search Credential: myP ass
URL: l d ap: //127. 0 . 0 . 1: 389
The first command adds the security realm.
/host=master/core-service=management/securityrealm=ldap_security_realm:add
The second command adds the LD AP connection.
/host=master/core-service=management/ldapconnection=ldap_connection/:add(searchcredential=myPass,url=ldap://127.0.0.1:389,searchdn="cn=search,dc=acme,dc=com")
58
C reat e an LD AP- En ab led Secu rit y R ealm

The Management Interfaces can authenticate against LD AP server instead of the property-file based
security realms configured by default. The LD AP authenticator operates by first establishing a
connection to the remote directory server. It then performs a search using the username which the
user passed to the authentication system, to find the fully-qualified distinguished name (D N) of the
LD AP record. A new connection is established, using the D N of the user as the credential, and
password supplied by the user. If this authentication to the LD AP server is successful, the D N is
verified to be valid.
The LD AP security realm uses the following configuration attributes:
co n n ect io n
The name of the connection defined in outbound-connections to use to connect to the
LD AP directory.
ad van ced - f ilt er
The fully defined filter used to search for a user based on the supplied user ID . The filter
must contain a variable in the following format: {0 }. This is later replaced with the user
name supplied by the user.
b ase- d n
The distinguished name of the context to begin searching for the user.
recu rsive
Whether the search should be recursive throughout the LD AP directory tree, or only search
the specified context. D efaults to fal se.
u ser- d n
The attribute of the user that holds the distinguished name. This is subsequently used to
test authentication as the user can complete. D efaults to d n.
u sern ame- at t rib u t e
The name of the attribute to search for the user. This filter performs a simple search where
the user name entered by the user matches the specified attribute.
allo w- emp t y- p asswo rd s
This attribute determines whether an empty password is accepted. The default value for this
attribute is fal se.
Eit h er username-fi l ter o r ad vanced -fi l ter mu st b e sp ecif ied
The advanced-filter attribute contains a filter query in the standard LD AP syntax, for
example:
(& (sAMAccountName={0})
(memberOf=cn=admin,cn=users,dc=acme,dc=com))
Examp le 5.11. XML R ep resen t in g an LD AP- en ab led Secu rit y R ealm
59
This example uses the following parameters:

connection - l d ap_co nnecti o n
base-dn - cn= users,d c= acme,d c= co m.
username-filter - attri bute= "sambaAcco untName"
< security-realm name="ldap_security_realm">
<authentication>
<ldap connection="ldap_connection" basedn="cn=users,dc=acme,dc=com">
<username-filter attribute="sambaAccountName" />
</ldap>
</authentication>
< /security-realm>
Warning
It is important to ensure that you do not allow empty LD AP passwords; unless you specifically
desire this in your environment, it is a serious security concern.
EAP 6.1 includes a patch for CVE-2012-5629, which sets the allowEmptyPasswords option for
the LD AP login modules to false if the option is not already configured. For older versions, this
option should be configured manually
Examp le 5.12. Ad d an LD AP Secu rit y R ealm

The command below adds an LD AP authentication to a security realm and sets its attributes for a
host named master in the domain.
/host=master/core-service=management/securityrealm=ldap_security_realm/authentication=ldap:add(basedn="DC=mycompany,DC=org", recursive=true, usernameattribute="MyAccountName", connection="ldap_connection")
Ap p ly t h e N ew Secu rit y R ealm t o t h e Man ag emen t In t erf ace

After you create a security realm, you need to reference it in the configuration of your management
interface. The management interface will use the security realm for HTTP digest authentication.
Examp le 5.13. Ap p ly t h e Secu rit y R ealm t o t h e H T T P In t erf ace

After this configuration is in place, and you restart the host controller, the web-based Management
Console will use LD AP to authenticate its users.
/host=master/core-service=management/management-interface=httpinterface/:write-attribute(name=securityrealm,value=ldap_security_realm)
60
Examp le 5.14 . Ap p ly t h e Secu rit y R ealm t o t h e N at ive In t erf ace

Use the following command to apply the same settings to the native interface:
/host=master/core-service=management/management-interface=nativeinterface/:write-attribute(name=securityrealm,value=ldap_security_realm)
Report a bug
5.11.3. Using Out bound LDAP wit h 2-way SSL in t he Management Int erface and
CLI
JBoss EAP 6 can be configured to use an outbound connection to a LD AP server using 2-way SSL
for authentication in the Management Interface and CLI.
Prereq u isit es
An LD AP-enabled security realm must be created. See Section 5.11.2, Use LD AP to Authenticate
to the Management Interfaces for details on creating the security realm.
Pro ced u re 5.4 . C o n f ig u re O u t b o u n d LD AP wit h 2- way SSL
1. Configure the security realm keystore and truststore. The security realm must contain a
keystore configured with the key that the JBoss EAP 6 server will use to authenticate against
the LD AP server. The security realm must also contain a truststore configured with the LD AP
server's certificates. See Section 5.9, Using 2-way SSL for the Management interface and the
CLI for instructions on configuring keystores and truststores.
2. Add the outbound connection to the LD AP server, specifying the configured security realm:
/core-service=management/ldapconnection=LocalLdap:add(url="ldaps://LDAP_HOST:LDAP_PORT")
/core-service=management/ldap-connection=LocalLdap:writeattribute(name=security-realm,value="LdapSSLRealm")
3. Configure LD AP authentication within the security realm and the management interfaces as
shown in Section 5.11.2, Use LD AP to Authenticate to the Management Interfaces .
Report a bug
61
Chapter 6. Secure the Management Interfaces with Role-Based

Access Control
6.1. About Role-Based Access Cont rol (RBAC)
Role-Based Access Control (RBAC) is a mechanism for specifying a set of permissions for
management users. It allows multiple users to share responsibility for managing JBoss EAP 6.3
servers without each of them requiring unrestricted access. By providing " separation of duties" for
management users, JBoss EAP 6.3 makes it easy for an organization to spread responsibility
between individuals or groups without granting unnecessary privileges. This ensures the maximum
possible security of your servers and data while still providing flexibility for configuration,
deployment, and management.
Role-Based Access Control in JBoss EAP 6.3 works through a combination of role permissions and
constraints.
Seven predefined roles are provided that each have different fixed permissions. The predefined roles
are: Monitor, Operator, Maintainer, D eployer, Auditor, Administrator, and SuperUser. Each
management user is assigned one or more roles, which specify what the user is permitted to do when
managing the server.
Report a bug
6.2. Role-Based Access Cont rol in t he Management Console and CLI

When Role-Based Access Control (RBAC) is enabled, the role assigned to a user determines the
resources to which they have access and what operations they can conduct with a resource's
attributes.
T h e Man ag emen t C o n so le
In the management console some controls and views are disabled (greyed out) or not
visible at all depending 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 the console. For example, most roles cannot read the username and password fields for
datasources.
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 edit button for the resource will not appear.
If a user does not have permissions to access a resource or attribute (it is " unaddressable"
for that role), it will not appear in the console for that user. An example of that is the access
control system itself which is only visible to a few roles by default.
T h e Man ag emen t C LI o r API
Users of the Management CLI or management API will encounter slightly different behavior
in the API when RBAC is enabled.
Resources and attributes that cannot be read are filtered from results. If the filtered items are
addressable by the role, their names are listed as fi l tered -attri butes in the
respo nse-head ers section of the result. If a resource or attribute is not addressable by
the role, it is not listed.
62
Chapt er 6 . Secure t he Management Int erfaces wit h Role- Based Access Cont rol
Attempting to access a resource that is not addressable will result in a reso urce no t
fo und error.
If a user attempts to write or read a resource that they can address but lack the appropriate
write or read permissions, a P ermi ssi o n D eni ed error is returned.
Report a bug
6.3. Support ed Aut hent icat ion Schemes

Role-Based Access Control works with the standard authentication providers that are included with
JBoss EAP 6.3. The standard authentication providers are: username/passwo rd , cl i ent
certi fi cate, and l o cal user.
U sern ame/Passwo rd
Users are authenticated using a username and password combination which is verified
against either the mg mt-users. pro perti es file, or an LD AP server.
C lien t C ert if icat e
Using the Trust Store.
Lo cal U ser
jbo ss-cl i . sh authenticates automatically as Local User if the server that is running on
the same machine. 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 mg mt-users. pro perti es file or an LD AP server, those
systems can supply user group information. This information can also be used by JBoss EAP to
assign roles to users.
Report a bug
6.4 . T he St andard Roles

JBoss EAP 6 provides seven predefined user roles: Monitor, Operator, Maintainer, D eployer, Auditor,
Administrator, and SuperUser. Each of these roles has a different set of permissions and is designed
for specific use cases. The Monitor, Operator, Maintainer, Administrator, and SuperUser role each
build upon each other, with each having more permissions than the previous. The Auditor and
D eployer roles are similar to the Monitor and Maintainer roles respectively but have some additional
special permissions and restrictions.
Mo n it o r
Users of the Monitor role have the fewest permissions and can only read the current
configuration and state of the server. This role is intended for users who need to track and
report on the performance of the server.
Monitors cannot modify server configuration nor can they access sensitive data or
operations.
O p erat o r
The Operator role extends the Monitor role by adding the ability to modify the runtime state
of the server. This means that Operators can reload and shutdown the server as well as
pause and resume JMS destinations. The Operator role is ideal for users who are
63
responsible for the physical or virtual hosts of the application server so they can ensure
that servers can be shutdown and restarted corrected when needed.
Operators cannot modify server configuration or access sensitive data or operations.
Main t ain er
The Maintainer role has access to view and modify runtime state and all configuration
except sensitive data and operations. The Maintainer role is the general purpose role that
doesn't have access to sensitive data and operation. The Maintainer role allows users to be
granted almost complete access to administer the server without giving those users access
to passwords and other sensitive information.
Maintainers cannot access sensitive data or operations.
Ad min ist rat o r
The Administrator role has unrestricted access to all resources and operations on the
server except the audit logging system. The Administrator role has access to sensitive data
and operations. This role can also configure the access control system. The Administrator
role is only required when handling sensitive data or configuring users and roles.
Administrators cannot access the audit logging system and cannot change themselves to
the Auditor or SuperUser role.
Su p erU ser
The SuperUser role has no restrictions and has complete access to all resources and
operations of the server including the audit logging system. This role is equivalent to the
administrator users of earlier versions of JBoss EAP 6 (6.0 and 6.1). If RBAC is disabled, all
management users have permissions equivalent to the SuperUser role.
D ep lo yer
The D eployer role has the same permissions as the Monitor, but can modify configuration
and state for deployments and any other resource type enabled as an application resource.
Au d it o r
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 other than 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 every
permission. 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 access
control system.
Table 6.1, Role Permissions Matrix summarizes the permissions of each role.
64
T ab le 6 .1. R o le Permissio n s Mat rix
Read Config and

State
Read Sensitive
D ata [2]
Modify Sensitive
D ata [2]
Read/Modify Audit
Log
Modify Runtime
State
Modify Persistent
Config
Read/Modify Access
Control
Monitor
Operator
Maintain
er
X
D eployer
Auditor
Administr SuperUs
ator
er
X
X
X
X
X[1]
X[1]
[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 Const raint s

Constraints are named sets of access-control configuration for a specified list of resources. The
RBAC system uses the combination of constraints and role permissions to determine if any specific
user can perform a management action.
Constraints are divided into three classifications: application, sensitivity and vault expression.
Ap p licat io n C o n st rain t s
Application Constraints define sets of resources and attributes that can be accessed by
users of the D eployer 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) for datasources, logging, mail, messaging, naming, resourceadapters and security. These constraints allow D eployer users to not only deploy
applications but also configure and maintain the resources that are required by those
applications.
Application constraint configuration is in the Management API at /co reservi ce= manag ement/access= autho ri zati o n/co nstrai nt= appl i cati o ncl assi fi cati o n.
Sen sit ivit y C o n st rain t s
Sensitivity Constraints define sets of resources that are considered " sensitive" . A sensitive
resource is generally one that is either secret, like a password, or one that will have serious
impact on the operation of the server, like networking, JVM configuration, or system
properties. The access control system itself is also considered sensitive.
65
The only roles permitted to write to sensitive resources are Administrator and SuperUser.
The Auditor role is only able to read sensitive resources. No other roles have access.
Sensitivity constraint configuration is in the Management API at /co reservi ce= manag ement/access= autho ri zati o n/co nstrai nt= sensi ti vi tycl assi fi cati o n.
Vau lt Exp ressio n C o n st rain t
The Vault Expression constraint defines if reading or writing vault expressions is consider a
sensitive operation. By default both reading and writing vault expressions is a sensitive
operation.
Vault Expression constraint configuration is in the Management API at /co reservi ce= manag ement/access= autho ri zati o n/co nstrai nt= vaul t-expressi o n.
Constraints can not be configured in the Management Console at this time.
Report a bug
6.7. About JMX and Role-Based Access Cont rol

Role-Based Access Control applies to JMX in three ways:
1. The Management API of JBoss EAP 6 is exposed as JMX Management Beans. These
Management Beans are referred to as " core mbeans" and access to them is controlled and
filtered exactly the same as the underlying Management API itself.
2. The JMX subsystem is configured with write permissions being " sensitive" . This means only
users of the Administrator and SuperUser roles can make changes to that subsystem. Users
of the Auditor role can also read this subsystem configuration.
3. By default Management Beans registered by deployed applications and services (non-core
mbeans) can be accessed by all management users, but only users of the Maintainer,
Operator, Administrator, SuperUser roles can write to them.
Report a bug
6.8. Configuring Role-Based Access Cont rol

6.8.1. Overview of RBAC Configurat ion T asks
When RBAC is enabled only users of the Administration or SuperUser role can view and make
changes to 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
The management CLI provides access to the complete access control system. This means that
66
everything that can be done in the management console can be done there, but a number of
additional tasks 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 Cont rol

By default the Role-Based Access Control (RBAC) system is disabled. It is enabled by changing the
provider attribute from si mpl e to rbac. This can be done using the Management CLI or by editing
the server configuration XML file if the server is offline. When RBAC is disabled or enabled on a
running server, 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
the Management CLI runs as the SuperUser role if it is run on the same machine as the server.
Pro ced u re 6 .1. En ab lin g R B AC
To enable RBAC with the Management CLI, use the wri te-attri bute operation of the access
authorization resource to set the provider attribute to rbac.
/core-service=management/access=authorization:writeattribute(name=provider, value=rbac)
[standalone@ localhost:9999 /] /coreservice=management/access=authorization:write-attribute(name=provider,
value=rbac)
{
}
}
[standalone@ localhost:9999 /] /:reload
{
"result" => undefined
}
Pro ced u re 6 .2. D isab lin g R B AC
To disable RBAC with the Management CLI, use the wri te-attri bute operation of the access
authorization resource to set the provider attribute to si mpl e.
/core-service=management/access=authorization:writeattribute(name=provider, value=simple)
67
[standalone@ localhost:9999 /] /coreservice=management/access=authorization:write-attribute(name=provider,

value=simple)
{
}
}
[standalone@ localhost:9999 /] /:reload
{
"result" => undefined
}
If the server is offline the XML configuration can be edited to enabled or disable RBAC. To do this,
edit the pro vi d er attribute of the access-co ntro l element of the management element. Set the
value to rbac to enable, and si mpl e to disable.
< management>
<access-control provider="rbac">
<role-mapping>
<role name="SuperUser">
<include>
<user name="$local"/>
</include>
</role>
</role-mapping>
</access-control>
</management>
Report a bug
6.8.3. Changing t he Permission Combinat ion Policy

The Permission Combination Policy determines how permissions are determined if a user is assigned
more than one role. This can be set to permi ssi ve or rejecti ng . The default is permi ssi ve.
When set to permi ssi ve, if any role is assigned to the user that permits an action, then the action is
allowed.
When set to rejecti ng , if multiple roles are assigned to a user, then no action is allowed. This
means that when the policy is set to rejecti ng each user should only be assigned one role. Users
with multiple roles will not be able to use the Management Console or the Management CLI when the
policy is set to rejecti ng .
The Permission Combination Policy is configured by setting the permi ssi o n-co mbi nati o npo l i cy attribute to either permi ssi ve or rejecti ng . This can be done using the Management CLI
or by editing the server configuration XML file if the server is offline.
Pro ced u re 6 .3. Set t h e Permissio n C o mb in at io n Po licy
68
Use the wri te-attri bute operation of the access authorization resource to set the
permi ssi o n-co mbi nati o n-po l i cy attribute to the required policy name.
/core-service=management/access=authorization:writeattribute(name=permission-combination-policy, value=POLICYNAME)
The valid policy names are rejecting and permissive.
[standalone@ localhost:9999 /] /coreservice=management/access=authorization:writeattribute(name=permission-combination-policy, value=rejecting)
[standalone@ localhost:9999 access=authorization]
If the server is offline the XML configuration can be edited to change the permission combination
policy value. To do this, edit the permi ssi o n-co mbi nati o n-po l i cy attribute of the accesscontrol element.
< access-control provider="rbac" permission-combinationpolicy="rejecting">
<role-mapping>
<role name="SuperUser">
<include>
<user name="$local"/>
</include>
</role>
</role-mapping>
< /access-control>
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 is
determined by the roles to which the user is assigned. JBoss EAP 6.3 uses a system of includes and
excludes 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:
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
69
management console 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
and the Management CLI. This topic only shows using the Management Console.
Only users in the SuperUser or Ad mi ni strato r 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 Ad min ist rat io n tab.
3. Expand the Access C o ntro l menu and select R o le Assig n men t .
4. Select the U SER S tab.
Pro ced u re 6 .4 . C reat e a n ew ro le assig n men t f o r a u ser
1. Login to the Management console.
2. Navigate to the U sers tab of the R o l e Assi g nment section.
3. Click the Ad d button at the top right of the user list. Ad d User dialog appears.
70
Fig u re 6 .1. Ad d U ser D ialo g

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 the
Control key (Command key on OSX).
7. Click Save to finish.
71
When successful, the Ad d User dialog closes, and the list of users is updated to reflect the
changes made. If unsuccessful a Fai l ed to save ro l e assi g nment message is
displayed.
Pro ced u re 6 .5. U p d at e t h e ro le assig n men t f o r a u ser
2. Navigate to the U sers tab of the R o l e Assi g nment section.
3. Select user from the list.
4. Click Ed it . The selection panel enters edit mode.
Fig u re 6 .2. Select io n Ed it View

Here you can add and remove assigned and excluded roles for the user.
a. To add an assigned role, select the required role from the list of available roles on the
left and click button with the right-facing arrow next to the assigned roles list. The role
moves from the available list to the assigned list.
72
b. To remove an assigned role, selected the required role from the assigned roles list on
the right and click the button with the left-facing arrow next to the assigned roles list.
The role moves from the assigned list to the available list.
c. To add an excluded role, select the required role from the list of available roles on the
left and click button with the right-facing arrow next to the excluded roles list. The role
moves from the available list to the excluded list.
d. To remove an excluded role, selected the required role from the excluded roles list on
the right and click the button with the left-facing arrow next to the excluded roles list.
The role moves from the excluded list to the available list.
When successful, the edit view closes, and the list of users is updated to reflect the changes
made. If unsuccessful a Fai l ed to save ro l e assi g nment message is displayed.
Pro ced u re 6 .6 . R emo ve ro le assig n men t f o r a u ser
2. Navigate to the U sers tab of the Role Assignment section.
3. Select the user from the list.
4. Click R emo ve. The R emo ve R o l e Assi g nment confirmation prompt appears.
5. Click C o n f irm.
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 the system,
nor does it guarantee that no roles will be assigned to the user. Roles might still be assigned
from group membership.
Report a bug
6.9.3. Configure User Role Assignment using t he Management CLI

Roles for a user to be included in and excluded from can be configured in the Management Console
and the 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:
/co re-servi ce= manag ement/access= autho ri zati o n as ro l e-mappi ng 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 /co reservi ce= manag ement/access= autho ri zati o n location:
[standalone@ localhost:9999] cd /coreservice=management/access=authorization
Pro ced u re 6 .7. Viewin g R o le Assig n men t C o n f ig u rat io n
73
1. Use the :read-children-names operation to get a complete list of the configured roles:
/core-service=management/access=authorization:read-childrennames(child-type=role-mapping)
[standalone@ localhost:9999 access=authorization] :read-childrennames(child-type=role-mapping)
{
"result" => [
"Administrator",
"Deployer",
"Maintainer",
"Monitor",
"Operator",
"SuperUser"
]
}
2. Use the read -reso urce operation of a specified role-mapping to get the full details of a
specific role:
/core-service=management/access=authorization/rolemapping=ROLENAME:read-resource(recursive=true)
[standalone@ localhost:9999 access=authorization] ./rolemapping=Administrator:read-resource(recursive=true)
{
"result" => {
"include-all" => false,
"exclude" => undefined,
"include" => {
"user-theboss" => {
"name" => "theboss",
"realm" => undefined,
"type" => "USER"
},
"user-harold" => {
"name" => "harold",
"type" => "USER"
},
"group-SysOps" => {
"name" => "SysOps",
"type" => "GROUP"
}
}
}
}
Pro ced u re 6 .8. Ad d a n ew ro le
74
This procedure shows how to add a role-mapping entry for a role. This must be done before the role
can be configured.
Use the ad d operation to add a new role configuration.
/core-service=management/access=authorization/rolemapping=ROLENAME:add
ROLENAME is the name of the role that the new mapping is for.
[standalone@ localhost:9999 access=authorization] ./rolemapping=Auditor:add
Pro ced u re 6 .9 . Ad d a u ser as in clu d ed in a ro le
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 ad d operation to add a user entry to the includes list of the role.
/core-service=management/access=authorization/rolemapping=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 naming
convention 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] ./rolemapping=Auditor/include=user-max:add(name=max, type=USER)
Pro ced u re 6 .10. Ad d a u ser as exclu d ed in a ro le
This procedure shows how to add a user to the excluded list of a role.
Use the ad d operation to add a user entry to the excludes list of the role.
/core-service=management/access=authorization/rolemapping=ROLENAME/exclude=ALIAS:add(name=USERNAME, type=USER)
USERNAME is the name of the user being added to the exclude list.
75
[standalone@ localhost:9999 access=authorization] ./rolemapping=Auditor/exclude=user-max:add(name=max, type=USER)

Pro ced u re 6 .11. R emo ve u ser ro le in clu d e co n f ig u rat io n
This procedure shows how to remove a user include entry from a role mapping.
Use the remo ve operation to remove the entry.
/core-service=management/access=authorization/rolemapping=ROLENAME/include=ALIAS:remove
ROLENAME is the name of the role being configured
[standalone@ localhost:9999 access=authorization] ./rolemapping=Auditor/include=user-max:remove
Removing the user from the list of includes does not remove the user from the system, nor does it
guarantee that the role won't be assigned to the user. The role might still be assigned based on
group membership.
Pro ced u re 6 .12. R emo ve u ser ro le exclu d e co n f ig u rat io n
This procedure shows how to remove an user exclude entry from a role mapping.
/core-service=management/access=authorization/rolemapping=ROLENAME/exclude=ALIAS:remove
[standalone@ localhost:9999 access=authorization] ./rolemapping=Auditor/exclude=user-max:remove
Removing the user from the list of excludes does not remove the user from the system, nor does it
guarantee the role will be assigned to the user. Roles might still be excluded based on group
membership.
Report a bug
6.9.4 . About Roles and User Groups
76
Users authenticated using either the mg mt-users. pro perti es file or an LD AP server, can be
members 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 user
groups they are members of. It can also exclude users from roles based on group membership.
When using the mg mt-users. pro perti es file, group information is stored in the mg mtg ro ups. pro perti es file. When using LD AP the group information is stored in the LD AP sever and
maintained by those responsible for the LD AP 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
the Management CLI. This topic only shows using the Management Console.
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 Ad min ist rat io n tab.
3. Expand the Access C o n t ro l menu and select R o le Assig n men t .
4. Select the G R O U PS tab.
Pro ced u re 6 .13. C reat e a n ew ro le assig n men t f o r a g ro u p
1. Login to the Management console
2. Navigate to the G R O U PS tab of the R o l e Assi g nment section.
3. Click the Ad d button at the top right of the user list. Ad d G ro up dialog appears.
77
Fig u re 6 .3. Ad d G ro u p D ialo g

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 the
Control key (Command key on OSX).
78
When successful, the Ad d G ro up dialog closes, and the list of groups is updated to reflect
the changes made. If unsuccessful a Fai l ed to save ro l e assi g nment message is
displayed.
Pro ced u re 6 .14 . U p d at e a ro le assig n men t f o r a g ro u p
2. Navigate to the G R O U PS tab of the Role Assignment section.
3. Select the group from the list.
4. Click Edit. The Selection view enters Edit mode.
Fig u re 6 .4 . Select io n View Ed it Mo d e

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 and
click button with the right-facing arrow next to the assigned roles list. The role moves from
the available list to the assigned list.
79
To remove an assigned role, selected the required role from the assigned roles list on the
right and click the button with the left-facing arrow next to the assigned roles list. The role
moves 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 left
and click button with the right-facing arrow next to the excluded roles list. The role moves
from the available list to the excluded list.
To remove an excluded role, selected the required role from the excluded roles list on the
right and click the button with the left-facing arrow next to the excluded roles list. The role
moves from the excluded list to the available list.
When successful, the edit view closes, and the list of groups is updated to reflect the changes
made. If unsuccessful a Failed t o save ro le assig n men t message is displayed.
Pro ced u re 6 .15. R emo ve ro le assig n men t f o r a g ro u p
2. Navigate to the G R O U PS tab of the R o le Assig n men t section.
3. Select the group from the list.
4. Click R emo ve. The R emo ve R o l e Assi g nment confirmation prompt appears.
5. Click C o nfi rm.
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 the
system, nor does it guarantee that no roles will be assigned to members of that group. Each
group member might still have a role assigned to them directly.
Report a bug
6.9.6. Configure Group Role Assignment using t he Management CLI

Groups to be included or excluded from a role can be configured in the Management Console and
the 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:
/co re-servi ce= manag ement/access= autho ri zati o n 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 /co reservi ce= manag ement/access= autho ri zati o n location:
[standalone@ localhost:9999] cd /coreservice=management/access=authorization
Pro ced u re 6 .16 . Viewin g G ro u p R o le Assig n men t C o n f ig u rat io n
1. Use the read -chi l d ren-names operation to get a complete list of the configured roles:
80
/core-service=management/access=authorization:read-childrennames(child-type=role-mapping)
[standalone@ localhost:9999 access=authorization] :read-childrennames(child-type=role-mapping)
{
"result" => [
"Administrator",
"Deployer",
"Maintainer",
"Monitor",
"Operator",
"SuperUser"
]
}
2. Use the read -reso urce operation of a specified role-mapping to get the full details of a
specific role:
/core-service=management/access=authorization/rolemapping=ROLENAME:read-resource(recursive=true)
[standalone@ localhost:9999 access=authorization] ./rolemapping=Administrator:read-resource(recursive=true)
{
"result" => {
"include-all" => false,
"exclude" => undefined,
"include" => {
"user-theboss" => {
"name" => "theboss",
"type" => "USER"
},
"user-harold" => {
"name" => "harold",
"type" => "USER"
},
"group-SysOps" => {
"name" => "SysOps",
"type" => "GROUP"
}
}
}
}
Pro ced u re 6 .17. Ad d a n ew ro le
81
This procedure shows how to add a role-mapping entry for a role. This must be done before the role
can be configured.
Use the ad d operation to add a new role configuration.
/core-service=management/access=authorization/rolemapping=ROLENAME:add
[standalone@ localhost:9999 access=authorization] ./rolemapping=Auditor:add
Pro ced u re 6 .18. Ad d a G ro u p as in clu d ed in a ro le
This procedure shows how to add a Group to the included list of a role.
Use the ad d operation to add a Group entry to the includes list of the role.
/core-service=management/access=authorization/rolemapping=ROLENAME/include=ALIAS:add(name=GROUPNAME, type=GROUP)
GROUPNAME is the name of the group being added to the include list.
convention for your aliases such as g ro up-GROUPNAME.
[standalone@ localhost:9999 access=authorization] ./rolemapping=Auditor/include=group-investigators:add(name=investigators,
type=GROUP)
Pro ced u re 6 .19 . Ad d a g ro u p as exclu d ed in a ro le
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 ad d operation to add a group entry to the excludes list of the role.
/core-service=management/access=authorization/rolemapping=ROLENAME/exclude=ALIAS:add(name=GROUPNAME, type=GROUP)
GROUPNAME is the name of the group being added to the include list
82
[standalone@ localhost:9999 access=authorization] ./rolemapping=Auditor/exclude=group-supervisors:add(name=supervisors,

type=GROUP)
Pro ced u re 6 .20. R emo ve g ro u p ro le in clu d e co n f ig u rat io n
This procedure shows how to remove a group include entry from a role mapping.
/core-service=management/access=authorization/rolemapping=ROLENAME/include=ALIAS:remove
[standalone@ localhost:9999 access=authorization] ./rolemapping=Auditor/include=group-investigators:remove
Removing the group from the list of includes does not remove the group from the system, nor does
it guarantee that the role won't be assigned to users in this group. The role might still be assigned
to users in the group individually.
Pro ced u re 6 .21. R emo ve a u ser g ro u p exclu d e en t ry
This procedure shows how to remove a group exclude entry from a role mapping.
/core-service=management/access=authorization/rolemapping=ROLENAME/exclude=ALIAS:remove
[standalone@ localhost:9999 access=authorization] ./rolemapping=Auditor/exclude=group-supervisors:remove
Removing the group from the list of excludes does not remove the group from the system. It also
does not guarantee the role will be assigned to members of the group. Roles might still be
excluded based on group membership.
Report a bug
6.9.7. About Aut horiz at ion and Group Loading wit h LDAP
83
6.9.7. About Aut horiz at ion and Group Loading wit h LDAP
An LD AP directory contains entries for user accounts and groups, cross referenced by attributes.
D epending on the LD AP server configuration, a user entity may map the groups the user belongs to
through memberO f attributes; a group entity may map which users belong to it through
uni q ueMember attributes; or both mappings may be maintained by the LD AP server.
Users generally authenticate against the server using a simple user name. When searching for group
membership information, depending on the directory server in use, searches could be performed
using this 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 is
successfully authenticated the server loads the user's groups. The authentication step and the
authorization step each require a connection to the LD AP server. The realm optimizes this process by
reusing the authentication connection for the group loading step. As will be shown within the
configuration steps below it is possible to define rules within the authorization section to convert a
user's simple user name to their distinguished name. The result of a " user name to distinguished
name mapping" search during authentication is cached and reused during the authorization query
when the fo rce attribute is set to " false" . When fo rce is true, the search is performed again during
authorization (while loading groups). This is typically done when different servers perform
authentication and authorization.
< authorization>
<ldap connection="...">

<username-to-dn force="true">

<username-is-dn />
<username-filter base-dn="..." recursive="..." user-dnattribute="..." attribute="..." />
<advanced-filter base-dn="..." recursive="..." user-dnattribute="..." filter="..." />
</username-to-dn>
<group-search group-name="..." iterative="..." group-dnattribute="..." group-name-attribute="..." >

<group-to-principal base-dn="..." recursive="..." searchby="...">
<membership-filter principal-attribute="..." />
</group-to-principal>
<principal-to-group group-attribute="..." />
</group-search>
</ldap>
< /authorization>
Important
These examples specify some attributes with their default values. This is done for
demonstration. Attributes that specify their default values are removed from the configuration
when it is persisted by the server. The exception is the fo rce attribute. It is required, even
when set to the default value of fal se.
use rnam e -t o -dn
84
The username-to -d n element specifies how to map the user name to the distinguished name of
their entry in the LD AP directory. This element is only required when both of the following are true:
The authentication and authorization steps are against different LD AP servers.
The group search uses the distinguished name.
1:1 u sern ame- t o - d n
This specifies that the user name entered by the remote user is the user's distinguished
name.
< username-to-dn force="false">
<username-is-dn />
< /username-to-dn>
This defines a 1:1 mapping and there is no additional configuration.
u sern ame- f ilt er
The next option is very similar to the simple option described above for the authentication
step. A specified attribute is searched for a match against the supplied user name.
< username-to-dn force="true">
<username-filter basedn="dc=people,dc=harold,dc=example,dc=com" recursive="false"

attribute="sn" user-dn-attribute="dn" />
< /username-to-dn>
The attributes that can be set here are:
base-d n: The distinguished name of the context to begin the search.
recursi ve: Whether the search will extend to sub contexts. D efaults to fal se.
attri bute: The attribute of the users entry to try and match against the supplied user
name. D efaults to ui d .
user-d n-attri bute: The attribute to read to obtain the users distinguished name.
D efaults to d n.
ad van ced - f ilt er
The final option is to specify an advanced filter, as in the authentication section this is an
opportunity to use a custom filter to locate the users distinguished name.
< username-to-dn force="true">
<advanced-filter basedn="dc=people,dc=harold,dc=example,dc=com" recursive="false"

filter="sAMAccountName={0}" user-dn-attribute="dn" />
< /username-to-dn>
For the attributes that match those in the username-filter example, the meaning and default
values are the same. There is one new attribute:
fi l ter: Custom filter used to search for a user's entry where the user name will be
substituted in the {0 } place holder.
85
Important
The XML must remain valid after the filter is defined so if any special characters are
used such as & ensure the proper form is used. For example & amp; for the &
character.
T he Gro up Se arch
There are two different styles that can be used when searching for group membership information.
The first style is where the user's entry contains an attribute that references the groups the user is a
member of. 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's
entry referencing the group is used. This is because with this method group information can be
loaded by reading attributes of known distinguished names without having to perform any searches.
The other approach requires extensive searches to identify the groups that reference the user.
Before describing the configuration here are some LD IF examples to illustrate this.
Examp le 6 .1. Prin cip al t o G ro u p - LD IF examp le.

This example illustrates where we have a user T estUserO ne who is a member of G ro upO ne,
G ro upO ne is in turn a member of G ro upFi ve. The group membership is shown by the use of a
memberO f attribute which is set to the distinguished name of the group of which the user (or
group) is a member.
It is not shown here but a user could potentially have multiple memberO f attributes set, one for
each group of which the user is directly a member.
dn: uid=TestUserOne,ou=users,dc=principal-to-group,dc=example,dc=org
objectClass: extensibleObject
objectClass: top
objectClass: groupMember
objectClass: inetOrgPerson
objectClass: uidObject
objectClass: person
objectClass: organizationalPerson
cn: Test User One
sn: Test User One
uid: TestUserOne
distinguishedName: uid=TestUserOne,ou=users,dc=principal-togroup,dc=example,dc=org
memberOf: uid=GroupOne,ou=groups,dc=principal-togroup,dc=example,dc=org
memberOf: uid=Slashy/Group,ou=groups,dc=principal-togroup,dc=example,dc=org
userPassword::
e1NTSEF9WFpURzhLVjc4WVZBQUJNbEI3Ym96UVAva0RTNlFNWUpLOTdTMUE9PQ==
dn: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=org
objectClass: top
86
objectClass: group
uid: GroupOne
distinguishedName: uid=GroupOne,ou=groups,dc=principal-togroup,dc=example,dc=org
memberOf: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-togroup,dc=example,dc=org
dn: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-togroup,dc=example,dc=org
objectClass: top
objectClass: group
uid: GroupFive
distinguishedName: uid=GroupFive,ou=subgroups,ou=groups,dc=principalto-group,dc=example,dc=org
Examp le 6 .2. G ro u p t o Prin cip al - LD IF Examp le

This example shows the same user T estUserO ne who is a member of G ro upO ne which is in turn
a member of G ro upFi ve - however in this case it is an attribute uni q ueMember from the group to
the user being used for the cross reference.
Again the attribute used for the group membership cross reference can be repeated, if you look at
GroupFive there is also a reference to another user TestUserFive which is not shown here.
dn: uid=TestUserOne,ou=users,dc=group-to-principal,dc=example,dc=org
objectClass: top
objectClass: person
objectClass: organizationalPerson
cn: Test User One
sn: Test User One
uid: TestUserOne
userPassword::
e1NTSEF9SjR0OTRDR1ltaHc1VVZQOEJvbXhUYjl1dkFVd1lQTmRLSEdzaWc9PQ==
dn: uid=GroupOne,ou=groups,dc=group-to-principal,dc=example,dc=org
objectClass: top
objectClass: groupOfUniqueNames
cn: Group One
uid: GroupOne
uniqueMember: uid=TestUserOne,ou=users,dc=group-toprincipal,dc=example,dc=org
dn: uid=GroupFive,ou=subgroups,ou=groups,dc=group-toprincipal,dc=example,dc=org
objectClass: top
objectClass: groupOfUniqueNames
cn: Group Five
87
uid: GroupFive
uniqueMember: uid=TestUserFive,ou=users,dc=group-toprincipal,dc=example,dc=org
uniqueMember: uid=GroupOne,ou=groups,dc=group-toprincipal,dc=example,dc=org
Ge ne ral Gro up Se arching

Before looking at the examples for the two approaches shown above we first need to define the
attributes common to both of these.
< group-search group-name="..." iterative="..." group-dn-attribute="..."
group-name-attribute="..." >
...
< /group-search>
g ro up-name: This attribute is used to specify the form that should be used for the group name
returned as the list of groups of which the user is a member. This can either be the simple form of
the group name or the group's distinguished name. If the distinguished name is required this
attribute can be set to D IST ING UISHED _NAME. D efaults to SIMP LE.
i terati ve: This attribute is used to indicate if, after identifying the groups a user is a member of,
we should also iteratively search based on the groups to identify which groups the groups are a
member of. If iterative searching is enabled we keep going until either we reach a group that is not
a member if any other groups or a cycle is detected. D efaults to fal se.
Cyclic group membership is not a problem. A record of each search is kept to prevent groups that
have already 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 to identify the
groups of which the group is a member. This would not be possible if for group to group
membership the name of the attribute used for the cross reference changes or if the direction of
the reference changes.
g ro up-d n-attri bute: On an entry for a group which attribute is its distinguished name.
D efaults to d n.
g ro up-name-attri bute: On an entry for a group which attribute is its simple name. D efaults to
ui d .
Examp le 6 .3. Prin cip al t o G ro u p Examp le C o n f ig u rat io n

Based on the example LD IF from above here is an example configuration iteratively loading a
user's groups where the attribute used to cross reference is the memberO f attribute on the user.
< authorization>
<ldap connection="LocalLdap">
<username-to-dn>
<username-filter base-dn="ou=users,dc=principal-to-
88
group,dc=example,dc=org" recursive="false" attribute="uid" user-dnattribute="dn" />
</username-to-dn>
<group-search group-name="SIMPLE" iterative="true" group-dnattribute="dn" group-name-attribute="uid">
<principal-to-group group-attribute="memberOf" />
</group-search>
</ldap>
< /authorization>
The most important aspect of this configuration is that the pri nci pal -to -g ro up element has been
added with a single attribute.
g ro up-attri bute: The name of the attribute on the user entry that matches the distinguished
name of the group the user is a member of. D efaults to memberO f.
Examp le 6 .4 . G ro u p t o Prin cip al Examp le C o n f ig u rat io n

This example shows an iterative search for the group to principal LD IF example shown above.
< authorization>
<ldap connection="LocalLdap">
<username-to-dn>
<username-filter base-dn="ou=users,dc=group-toprincipal,dc=example,dc=org" recursive="false" attribute="uid" user-dnattribute="dn" />
</username-to-dn>
<group-search group-name="SIMPLE" iterative="true" group-dnattribute="dn" group-name-attribute="uid">
<group-to-principal base-dn="ou=groups,dc=group-toprincipal,dc=example,dc=org" recursive="true" searchby="DISTINGUISHED_NAME">
<membership-filter principalattribute="uniqueMember" />
</group-to-principal>
</group-search>
</ldap>
</authorization>
Here an element g ro up-to -pri nci pal is added. This element is used to define how searches for
groups that reference the user entry will be performed. The following attributes are set:
base-d n: The distinguished name of the context to use to begin the search.
recursi ve: Whether sub-contexts also be searched. D efaults to fal se.
search-by: The form of the role name used in searches. Valid values are SIMP LE and
D IST ING UISHED _NAME. D efaults to D IST ING UISHED _NAME.
Within the group-to-principal element there is a membership-filter element to define the cross reference.
pri nci pal -attri bute: The name of the attribute on the group entry that references the user
entry. D efaults to member.
Report a bug
89
6.9.8. About Scoped Roles

Scoped Roles are user-defined roles that grant the permissions of one of the standard roles but only
for one or more specified server groups or hosts. Scoped roles allow for management users to be
granted permissions 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
roles are.
Creating a scoped role does not let you define new permissions. Scoped roles can only be used to
apply the permissions of an existing role in a limited scope. For example, you could create a scoped
role based on the D eployer role which is restricted to a single server group.
There are only two scopes that roles can be limited to, host and server group.
H o st - sco p ed ro les
A role that is host-scoped restricts the permissions of that role to one or more hosts. This
means access is provided to the relevant /ho st= */ resource trees but resources that are
specific to other hosts are hidden.
Server- G ro u p - sco p ed ro les
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 and server resources that are associated with the specified
server-groups. Any sub-resources within any of those that are not logically related to the
server-group will not be visible to the user.
Both host and server-group scoped roles have permissions of the Monitor role for the remainder of
the managed domain configuration.
Report a bug
6.9.9. Creat ing Scoped Roles

Scoped Roles are user-defined roles that grant the permissions of one of the standard roles but only
for one or more specified server groups or hosts. This topic shows how to create scoped roles.
Scoped Role configuration in the management console can be found by following these steps:
1. Login to the Management Console
2. Click on the Ad min ist rat io n tab
90
3. Expand the Access C o n t ro l menu and select R o le Assig n men t .

4. Select R O LES tab, and then the Sco p ed R o les tab within it.
The Sco ped R o l es section of the Management Console consists of two main areas, a table
containing a list of the currently configured scoped roles, and the Sel ecti o n panel which displays
the details of the role currently selected in the table.
The following procedures show how to perform configuration tasks for Scoped Roles.
Pro ced u re 6 .22. Ad d a N ew Sco p ed R o le
2. Navigate to the Sco p ed R o les area of the R o les tab.
3. Click Ad d . The Ad d Sco ped R o l e dialog appears.
4. Specify the following details:
Name, the unique name for the new scoped role.
Base R o l e, the role which this role will base its permissions on.
T ype, whether this role will be restricted to hosts or server groups.
Sco pe, the list of hosts or server groups that the role is restricted to. Multiple entries can
be selected.
Incl ud e Al l , should this role automatically include all users. D efaults to no.
5. Click Save and the dialog will close and the newly created role will appear in the table.
Pro ced u re 6 .23. Ed it a Sco p ed R o le
3. Click on the scoped role you want to edit in the table. The details of that role appears in the
Sel ecti o n panel below the table.
4. Click Ed i t in the Sel ecti o n panel. The Sel ecti o n panel enters edit mode.
5. Update the details you need to change and click the Save button. The Sel ecti o n panel
returns to its previous state. Both the Sel ecti o n panel and table show the newly updated
details.
Pro ced u re 6 .24 . View Sco p ed R o le Memb ers
2. Navigate to the Sco ped R o l es area of the R o les tab.
3. Click on the scoped role in the table that you want to view the Memb ers of, then click
Memb ers. The Memb ers o f ro le dialog appears. It shows users and groups that are
included or excluded from the role.
4. Click D o ne when you have finished reviewing this information.
Pro ced u re 6 .25. D elet e a Sco p ed R o le
91
Pro ced u re 6 .25. D elet e a Sco p ed R o le
Important
A Sco p ed R o le cannot be deleted if users or groups are assigned to it. Remove the role
assignments first, and then delete it.
3. Select the scoped role to be removed in the table.
4. Click the R emo ve button. The R emo ve Sco ped R o l e dialog appears.
5. Click C o n f irm.The dialog closes and the role is removed.
Report a bug
6.10. Configuring Const raint s

6.10.1. Configure Sensit ivit y Const raint s
Each Sensitivity Constraint defines a set of resources that are considered " sensitive" . A sensitive
resource is generally one that either should be secret, like passwords, or one that will have serious
impact on the server, like networking, JVM configuration, or system properties. The access control
system itself is also considered sensitive. Resource sensitivity limits which roles are able to read,
write or address a specific resource.
Sensitivity constraint configuration is in the Management API at /co reservi ce= manag ement/access= autho ri zati o n/co nstrai nt= sensi ti vi tycl assi fi cati o n.
Within the management model each Sensitivity Constraint is identified as a cl assi fi cati o n. The
classifications are then grouped into types. There are 39 included classifications that are arranged
into 13 types.
To configure a sensitivity constraint, use the wri te-attri bute operation to set the co nfi g ured req ui res-read , co nfi g ured -req ui res-wri te, or co nfi g ured -req ui res-ad d ressabl e
attribute. To make that type of operation sensitive set the value of the attribute to true, otherwise to
make it nonsensitive set it to fal se. By default these attributes are not set and the values of
d efaul t-req ui res-read , d efaul t-req ui res-wri te, and d efaul t-req ui resad d ressabl e are used. Once the configured attribute is set it is that value that is used instead of the
default. The default values cannot be changed.
Examp le 6 .5. Make read in g syst em p ro p ert ies a sen sit ive o p erat io n
[domain@ localhost:9999 /] cd /coreservice=management/access=authorization/constraint=sensitivityclassification/type=core/classification=system-property
[domain@ localhost:9999 classification=system-property] :writeattribute(name=configured-requires-read, value=true)
{
92
"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
{
"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
is summarized in Table 6.2, Sensitivity Constraint Configuration outcomes .
T ab le 6 .2. Sen sit ivit y C o n st rain t C o n f ig u rat io n o u t co mes
Valu e
req ui res-read
req ui res-wri te
req ui res-ad d ressabl e
true
Read is sensitive.
Write is sensitive.
Addressing is sensitive.
Only Aud i to r,
Ad mi ni strato r,
SuperUser can read.
Only Ad mi ni strato r and

SuperUser can write
Only Aud i to r,
Ad mi ni strato r,
SuperUser can address.
Read is not sensitive.
Write is not sensitive.
Addressing is not sensitive.
Any management user can

read.
Only Mai ntai ner,

Ad mi ni strato r and
SuperUser can write.
D epl o yers can also write
the resource is an
application resource.
Any management user can

address.
fal se
Report a bug
93
6.10.2. Configure Applicat ion Resource Const raint s

Each Application Resource Constraint defines a set of resources, attributes and operations that are
usually associated with the deployment of applications and services. When an application resource
constraint is enabled management users of the D eployer role are granted access to the resources
that it applies to.
Application constraint configuration is in the Management Model at /co reservi ce= manag ement/access= autho ri zati o n/co nstrai nt= appl i cati o ncl assi fi cati o n/.
Within the management model each Application Resource Constraint is identified as a
cl assi fi cati o n. The classifications are then grouped into types. There are 14 included
classifications that are arranged into 8 types. Each classification has an appl i es-to element
which is a list of resource path patterns to which the classifications configuration applies.
By default the only Application Resource classification that is enabled is co re. Core includes
deployments, deployment overlays, and the deployment operations.
To enable an Application Resource, use the wri te-attri bute operation to set the co nfi g ured appl i cati o n attri bute of the classification to true. To disable an Application Resource, set
this attribute to fal se. By default these attributes are not set and the value of d efaul tappl i cati o n attri bute is used. The default value cannot be changed.
Examp le 6 .6 . En ab lin g t h e lo g g er- p ro f ile ap p licat io n reso u rce classif icat io n

[domain@ localhost:9999 /] cd /coreservice=management/access=authorization/constraint=applicationclassification/type=logging/classification=logging-profile
[domain@ localhost:9999 classification=logging-profile] :writeattribute(name=configured-application, value=true)
{
{
}}}}
}
[domain@ localhost:9999 classification=logging-profile] :read-resource
{
"result" => {
"configured-application" => true,
"default-application" => false,
"applies-to" => {"/profile=*/subsystem=logging/loggingprofile=*" => undefined}
}
}
[domain@ localhost:9999 classification=logging-profile]
94
Important
Application Resource Constraints apply to all resources that match its configuration. For
example, It is not possible to grant a D epl o yer user access to one datasource resource but
not another. If this level of separation is required then it is recommended to configure the
resources in different server groups and create different scoped D epl o yer roles for each
group.
Report a bug
6.10.3. Configure t he Vault Expression Const raint

By default, reading and writing vault expressions are sensitive operations. Configuring the Vault
Expression 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 /co reservi ce= manag ement/access= autho ri zati o n/co nstrai nt= vaul t-expressi o n.
To configure the vault expression constraint, use the wri te-attri bute operation to set the
attributes of co nfi g ured -req ui res-wri te and co nfi g ured -req ui res-read to true or
fal se. By default these are not set and the values of d efaul t-req ui res-read and d efaul treq ui res-wri te are used. The default values cannot be changed.
Examp le 6 .7. Makin g writ in g t o vau lt exp ressio n s a n o n sen sit ive o p erat io n
[domain@ localhost:9999 /] cd /coreservice=management/access=authorization/constraint=vault-expression
[domain@ localhost:9999 constraint=vault-expression] :writeattribute(name=configured-requires-write, value=false)
{
{
}}}}
}
[domain@ localhost:9999 constraint=vault-expression] :read-resource
{
"result" => {
"configured-requires-read" => undefined,
"configured-requires-write" => false,
"default-requires-read" => true,
"default-requires-write" => true
}
}
[domain@ localhost:9999 constraint=vault-expression]
95
What roles will be able to read and write to vault expressions depending on this configuration is
summarized in Table 6.3, Vault Expression Constraint Configuration outcomes .
T ab le 6 .3. Vau lt Exp ressio n C o n st rain t C o n f ig u rat io n o u t co mes
Valu e
true
fal se
req ui res-read
req ui res-wri te
Read operation is sensitive.
Write operation is sensitive.
Only Aud i to r, Ad mi ni strato r, and

SuperUser can read.
Only Ad mi ni strato r, and SuperUser

can write.
Read operation is not sensitive.
Write operation is not sensitive.
All management users can read.
Mo ni to r, Ad mi ni strato r, and
SuperUser can write. D epl o yers can
also write if the vault expression is in an
Application Resource.
Report a bug
6.11. Const raint s Reference

6.11.1. Applicat ion Resource Const raint s Reference
T yp e: co re
C lassif icat io n : d ep lo ymen t - o verlay
default: true
PATH: /deployment-overlay=*
PATH: /deployment=*
PATH: /
Operation:
upload-deployment-stream, full-replace-deployment, upload-deployment-url, uploaddeployment-bytes
T yp e: d at aso u rces
C lassif icat io n : d at aso u rce
default: false
PATH: /deployment=*/subdeployment=*/subsystem=datasources/data-source=*
PATH: /subsystem=datasources/data-source=*
PATH: /subsystem=datasources/data-source=ExampleD S
PATH: /deployment=*/subsystem=datasources/data-source=*
C lassif icat io n : jd b c- d river
96
default: false
PATH: /subsystem=datasources/jdbc-driver=*
C lassif icat io n : xa- d at a- so u rce
default: false
PATH: /subsystem=datasources/xa-data-source=*
PATH: /deployment=*/subsystem=datasources/xa-data-source=*
PATH: /deployment=*/subdeployment=*/subsystem=datasources/xa-data-source=*
T yp e: lo g g in g
C lassif icat io n : lo g g er
default: false
PATH: /subsystem=logging/logger=*
PATH: /subsystem=logging/logging-profile=*/logger=*
C lassif icat io n : lo g g in g - p ro f ile
default: false
PATH: /subsystem=logging/logging-profile=*
T yp e: mail
C lassif icat io n : mail- sessio n
default: false
PATH: /subsystem=mail/mail-session=*
T yp e: n amin g
C lassif icat io n : b in d in g
default: false
PATH: /subsystem=naming/binding=*
T yp e: reso u rce- ad ap t ers
C lassif icat io n : reso u rce- ad ap t ers
default: false
PATH: /subsystem=resource-adapters/resource-adapter=*
T yp e: secu rit y
C lassif icat io n : secu rit y- d o main
default: false
PATH: /subsystem=security/security-domain=*
97
Report a bug
6.11.2. Sensit ivit y Const raint s Reference

T yp e: co re
C lassif icat io n : access- co n t ro l
requires-addressable: true
requires-read: true
requires-write: true
PATH: /core-service=management/access=authorization
PATH: /subsystem=jmx ATTRIBUTE: non-core-mbean-sensitivity
C lassif icat io n : cred en t ial
requires-addressable: false
requires-read: 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, recoveryusername, 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
C lassif icat io n : d o main - co n t ro ller
requires-read: false
C lassif icat io n : d o main - n ames
98
C lassif icat io n : ext en sio n s

PATH: /extension=*
C lassif icat io n : jvm
PATH: /core-service=platform-mbean/type=runtime ATTRIBUTE: input-arguments, bootclass-path, class-path, boot-class-path-supported, library-path
C lassif icat io n : man ag emen t - in t erf aces
/core-service=management/management-interface=native-interface
/core-service=management/management-interface=http-interface
C lassif icat io n : mo d u le- lo ad in g
PATH: /core-service=module-loading
C lassif icat io n : p at ch in g
PATH: /core-service=patching/addon=*
PATH: /core-service=patching/layer=*"
PATH: /core-service=patching
C lassif icat io n : read - wh o le- co n f ig
requires-read: true
99
PATH: / OPERATION: read-config-as-xml
C lassif icat io n : secu rit y- d o main
requires-read: true
PATH: /subsystem=security/security-domain=*
C lassif icat io n : secu rit y- d o main - ref
requires-read: 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, securitydomain-and-application
C lassif icat io n : secu rit y- realm
requires-read: true
PATH: /core-service=management/security-realm=*
C lassif icat io n : secu rit y- realm- ref
requires-read: 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
C lassif icat io n : secu rit y- vau lt
100
PATH: /core-service=vault
C lassif icat io n : service- co n t ain er
PATH: /core-service=service-container
C lassif icat io n : sn ap sh o t s
requires-write: false
PATH: / ATTRIBUTE: take-snapshot, list-snapshots, delete-snapshot
C lassif icat io n : so cket - b in d in g - ref
PATH: /subsystem=mail/mail-session=*/server=pop3 ATTRIBUTE: outbound-socketbinding-ref
PATH: /subsystem=mail/mail-session=*/server=imap ATTRIBUTE: outbound-socketbinding-ref
PATH: /subsystem=remoting/connector=* ATTRIBUTE: socket-binding
PATH: /subsystem=web/connector=* ATTRIBUTE: socket-binding
PATH: /subsystem=remoting/local-outbound-connection=* ATTRIBUTE: outboundsocket-binding-ref
PATH: /socket-binding-group=*/local-destination-outbound-socket-binding=*
ATTRIBUTE: socket-binding-ref
PATH: /subsystem=remoting/remote-outbound-connection=* ATTRIBUTE: outboundsocket-binding-ref
PATH: /subsystem=mail/mail-session=*/server=smtp ATTRIBUTE: outbound-socketbinding-ref
PATH: /subsystem=transactions ATTRIBUTE: process-id-socket-binding, status-socketbinding, socket-binding
C lassif icat io n : so cket - co n f ig
101
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
C lassif icat io n : syst em- p ro p ert y
PATH: /core-service=platform-mbean/type=runtime ATTRIBUTE: system-properties
PATH: /system-property=*
PATH: / OPERATION: resolve-expression
T yp e: d at aso u rces
C lassif icat io n : d at a- so u rce- secu rit y
requires-read: true
PATH: /subsystem=datasources/xa-data-source=* ATTRIBUTE: user-name, securitydomain, password
PATH: /subsystem=datasources/data-source=* ATTRIBUTE: user-name, securitydomain, password
T yp e: jd r
C lassif icat io n : jd r
PATH: /subsystem=jdr OPERATION: generate-jdr-report
102
T yp e: jmx
C lassif icat io n : jmx
PATH: /subsystem=jmx
T yp e: mail
C lassif icat io n : mail- server- secu rit y
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
T yp e: n amin g
C lassif icat io n : jn d i- view
requires-read: true
PATH: /subsystem=naming OPERATION: jndi-view
C lassif icat io n : n amin g - b in d in g
PATH: /subsystem=naming/binding=*
T yp e: remo t in g
C lassif icat io n : remo t in g - secu rit y
103
requires-read: true
PATH: /subsystem=remoting/connector=* ATTRIBUTE: authentication-provider, securityrealm
PATH: /subsystem=remoting/remote-outbound-connection=* ATTRIBUTE: username,
security-realm
PATH: /subsystem=remoting/connector=*/security=sasl
T yp e: reso u rce- ad ap t ers
C lassif icat io n : reso u rce- ad ap t er- secu rit y
requires-read: true
PATH: /subsystem=resource-adapters/resource-adapter=*/connection-definitions=*
ATTRIBUTE: security-domain, recovery-username, recovery-security-domain, securityapplication, security-domain-and-application, recovery-password
T yp e: secu rit y
C lassif icat io n : misc- secu rit y
requires-read: true
PATH: /subsystem=security ATTRIBUTE: deep-copy-subject-mode
T yp e: web
C lassif icat io n : web - access- lo g
PATH: /subsystem=web/virtual-server=*/configuration=access-log
C lassif icat io n : web - co n n ect o r
PATH: /subsystem=web/connector=*
C lassif icat io n : web - ssl
104
requires-read: true
PATH: /subsystem=web/connector=*/configuration=ssl
C lassif icat io n : web - sso
requires-read: true
PATH: /subsystem=web/virtual-server=*/configuration=sso
C lassif icat io n : web - valve
PATH: /subsystem=web/valve=*
Report a bug
105
Chapter 7. Secure Passwords and Other Sensitive Strings with

Password Vault
7.1. Password Vault Syst em
JBoss EAP 6 has a Password Vault to encrypt sensitive strings, store them in an encrypted keystore,
and decrypt them for applications and verification systems.
Plain-text configuration files, such as XML deployment descriptors, need to specify passwords and
other sensitive information.
Use the JBoss EAP Password Vault to securely store sensitive strings in plain-text files.
Report a bug
7.2. Creat e a Java Keyst ore t o St ore Sensit ive St rings

Prereq u isit es
The keyto o l command must be available to use. It is provided by the Java Runtime Environment
(JRE). Locate the path for the file. In Red Hat Enterprise Linux, it is installed to
/usr/bi n/keyto o l .
Warning
The JCEKS keystore implementations differ between Java vendors. You must generate the
vaul t. keysto re using the keyto o l from the same vendor as the JD K you use.
Using a vault generated by the keyto o l from one vendor's JD K in an EAP instance running
on a JD K from a different vendor results in the following exception:
java.io.IOException:
com.sun.crypto.provider.SealedObjectForKeyProtector
Pro ced u re 7.1. Set u p a Java K eyst o re

1. C reat e a d irect o ry t o st o re yo u r keyst o re an d o t h er en cryp t ed in f o rmat io n .
Create a directory to hold your keystore and other important information. The rest of this
procedure assumes that the directory is EAP_HOME/vaul t/. Since this directory will contain
sensitive information it should be accessible to only limited users. At a minimum the user
account under which JBoss EAP is running requires read-write access.
2. D et ermin e t h e p aramet ers t o u se wit h keyto o l .
D etermine the following parameters:
alias
106
Chapt er 7 . Secure Passwords and O t her Sensit ive St rings wit h Password Vault
The alias is a unique identifier for the vault or other data stored in the keystore. The
alias in the example command at the end of this procedure is vaul t. Aliases are
case-insensitive.
keyalg
The algorithm to use for encryption. The example in this procedure uses AES. Use
the documentation for your JRE and operating system to see which other choices
may be available to you.
keysiz e
The size of an encryption key impacts how difficult it is to decrypt through brute
force. The example in this procedure uses 128. For information on appropriate
values, see the documentation distributed with the keyto o l .
keyst o re
The keystore is a database which holds encrypted information and the information
about how to decrypt it. If you do not specify a keystore, the default keystore to use
is a file called . keysto re in your home directory. The first time you add data to a
keystore, it is created. The example in this procedure uses the vaul t. keysto re
keystore.
The keyto o l command has many other options. See the documentation for your JRE or
your operating system for more details.
3. D et ermin e t h e an swers t o q u est io n s t h e keysto re co mman d will ask.
The keysto re needs the following information in order to populate the keystore entry:
K eyst o re p asswo rd
When you create a keystore, you must set a password. In order to work with the
keystore in the future, you need to provide the password. Create a strong password
that you will remember. The keystore is only as secure as its password and the
security of the file system and operating system where it resides.
K ey p asswo rd ( o p t io n al)
In addition to the keystore password, you can specify a password for each key it
holds. In order to use such a key, the password needs to be given each time it is
used. Usually, this facility is not used.
First n ame ( g iven n ame) an d last n ame ( su rn ame)
This, and the rest of the information in the list, helps to uniquely identify the key and
place it into a hierarchy of other keys. It does not necessarily need to be a name at
all, but it should be two words, and must be unique to the key. The example in this
procedure uses Acco unti ng Ad mi ni strato r. In directory terms, this becomes
the common name of the certificate.
O rg an iz at io n al u n it
This is a single word that identifies who uses the certificate. It may be the
application or the business unit. The example in this procedure uses
Acco unti ng Servi ces. Typically, all keystores used by a group or application
use the same organizational unit.
O rg an iz at io n
107
This is usually a single-word representation of your organization's name. This

typically remains the same across all certificates used by an organization. This
example uses MyO rg ani zati o n.
C it y o r mu n icip alit y
Your city.
St at e o r p ro vin ce
Your state or province, or the equivalent for your locality.
C o u n t ry
The two-letter code for your country.
All of this information together will create a hierarchy for your keystores and certificates,
ensuring that they use a consistent naming structure but are unique.
4. R u n t h e keyto o l co mman d , su p p lyin g t h e in f o rmat io n t h at yo u g at h ered .
Examp le 7.1. Examp le in p u t an d o u t p u t o f keysto re co mman d

$ keytool -genseckey -alias vault -storetype jceks -keyalg AES keysize 128 -storepass vault22 -keypass vault22 -validity 730 keystore EAP_HOME/vaul t/vault.keystore
Enter keystore password: vault22
Re-enter new password:vault22
What is your first and last name?
[Unknown]: Acco unti ng Ad mi ni strato r
What is the name of your organizational unit?
[Unknown]: Acco unti ng Servi ces
What is the name of your organization?
[Unknown]: MyO rg ani zati o n
What is the name of your City or Locality?
[Unknown]: R al ei g h
What is the name of your State or Province?
[Unknown]: NC
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=Accounting Administrator, OU=AccountingServices,
O=MyOrganization, L=Raleigh, ST=NC, C=US correct?
[no]: yes
Enter key password for <vault>
(RETURN if same as keystore password):
R esu lt
A file named vaul t. keysto re is created in the EAP_HOME/vaul t/ directory. It stores a single key,
called vaul t, which will be used to store encrypted strings, such as passwords, for JBoss EAP 6.
Report a bug
7.3. Mask t he Keyst ore Password and Init ializ e t he Password Vault
108
Prereq u isit es
Section 7.2, Create a Java Keystore to Store Sensitive Strings
1. R u n t h e vaul t. sh co mman d .
Run EAP_HOME/bi n/vaul t. sh. Start a new interactive session by typing 0 .
2. En t er t h e d irect o ry wh ere en cryp t ed f iles will b e st o red .
This directory should be accessible to only limited users. At a minimum the user account
under which JBoss EAP is running requires read-write access. If you followed Section 7.2,
Create a Java Keystore to Store Sensitive Strings , your keystore is in a directory called
EAP_HOME/vaul t/.
Include the trailing slash on the directory name.

D o not forget to include the trailing slash on the directory name. Either use / or \,
depending on your operating system.
3. En t er t h e p at h t o t h e keyst o re.
Enter the full path to the keystore file. This example uses
EAP_HOME/vaul t/vaul t. keysto re.
4. En cryp t t h e keyst o re p asswo rd .
The following steps encrypt the keystore password, so that you can use it in configuration
files and applications securely.
a. En t er t h e keyst o re p asswo rd .
When prompted, enter the keystore password.
b. En t er a salt valu e.
Enter an 8-character salt value. The salt value, together with the iteration count
(below), are used to create the hash value.
c. En t er t h e it erat io n co u n t .
Enter a number for the iteration count.
d. Make a n o t e o f t h e masked p asswo rd in f o rmat io n .
The masked password, the salt, and the iteration count are printed to standard
output. Make a note of them in a secure location. An attacker could use them to
decrypt the password.
e. En t er t h e alias o f t h e vau lt .
When prompted, enter the alias of the vault. If you followed Section 7.2, Create a
Java Keystore to Store Sensitive Strings to create your vault, the alias is vaul t.
109
5. Exit t h e in t eract ive co n so le.

Type 2 to exit the interactive console.
R esu lt
Your keystore password has been masked for use in configuration files and deployments. In
addition, your vault is fully configured and ready to use.
Report a bug
7.4 . Configure JBoss EAP 6 t o Use t he Password Vault

O verview
Before you can mask passwords and other sensitive attributes in configuration files, you need to
make JBoss EAP 6 aware of the password vault which stores and decrypts them. Follow this
procedure to enable this functionality.
Prereq u isit es
Section 7.3, Mask the Keystore Password and Initialize the Password Vault
Pro ced u re 7.2. Set u p a Passwo rd Vau lt
1. D et ermin e t h e co rrect valu es f o r t h e co mman d .
D etermine the values for the following parameters, which are determined by the commands
used to create the keystore itself. For information on creating a keystore, refer the following
topics: Section 7.2, Create a Java Keystore to Store Sensitive Strings and Section 7.3,
Mask the Keystore Password and Initialize the Password Vault .
Paramet er
D escrip t io n
KEYSTORE_URL
The file system path or URI of the keystore

file, usually called something like
vaul t. keysto re
The password used to access the keystore.
This value should be masked.
The name of the keystore alias.
The salt used to encrypt and decrypt
keystore values.
The number of times the encryption
algorithm is run.
The path to the directory from which the
keystore commands are run. Typically the
directory containing the password vault.
The name of the host you are configuring
KEYSTORE_PASSWORD
KEYSTORE_ALIAS
SALT
ITERATION_COUNT
ENC_FILE_D IR
host (managed domain only)
2. U se t h e Man ag emen t C LI t o en ab le t h e p asswo rd vau lt .

Run one of the following commands, depending on whether you use a managed domain or
standalone server configuration. Substitute the values in the command with the ones from the
first step of this procedure.
110
Note
If you use Microsoft Windows Server, in the CLI command, escape each \ character in
a directory path with an additional \ character. For example,
C : \\d ata\\vaul t\\vaul t. keysto re. This is because single \ character is used
for character escaping.
A. Man ag ed D o main
/host=YOUR_HOST/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")])
B. St an d alo n e Server
/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")])
The following is an example of the command with hypothetical values:
/core-service=vault:add(vault-options=[("KEYSTORE_URL" =>
"/home/user/vault/vault.keystore"), ("KEYSTORE_PASSWORD" => "MASK3y28rCZlcKR"), ("KEYSTORE_ALIAS" => "vault"), ("SALT" =>
"12438567"),("ITERATION_COUNT" => "50"), ("ENC_FILE_DIR" =>
"/home/user/vault/")])
R esu lt
JBoss EAP 6 is configured to decrypt masked strings using the password vault. To add strings to the
vault and use them in your configuration, refer to the following topic: Section 7.6, Store and Retrieve
Encrypted Sensitive Strings in the Java Keystore .
Report a bug
7.5. Configure JBoss EAP 6 t o Use a Cust om Implement at ion of t he

Password Vault
Su mmary
You can use your own implementation of Securi tyVaul t to mask passwords and other sensitive
attributes in configuration files.
Pro ced u re 7.3. U se a C u st o m Imp lemen t at io n o f t h e Passwo rd Vau lt
1. Create a class that implements the interface Securi tyVaul t.
111
2. Create a module containing the class from the previous step, and specify a dependency on
o rg . pi cketbo x where the interface is Securi tyVaul t.
3. Enable the custom Password Vault in the JBoss EAP server configuration by adding the vault
element with the following attributes:
co d e
The fully qualified name of class that implements Securi tyVaul t.
mo d u le
The name of the module that contains the custom class.
Optionally, you can use vaul t-o pti o ns parameters to initialize the custom class for a
Password Vault. For example:
/coreservice=vault:add(code="custom.vault.implementation.CustomSecurity
Vault", module="custom.vault.module", 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")])
R esu lt
JBoss EAP 6 is configured to decrypt masked strings using a custom implementation of the
password vault.
Report a bug
7.6. St ore and Ret rieve Encrypt ed Sensit ive St rings in t he Java
Keyst ore
Su mmary
Including passwords and other sensitive strings in plain-text configuration files is insecure. JBoss
EAP 6 includes the ability to store and mask these sensitive strings in an encrypted keystore, and use
masked values in configuration files.
Prereq u isit es
Section 7.3, Mask the Keystore Password and Initialize the Password Vault
Section 7.4, Configure JBoss EAP 6 to Use the Password Vault
The EAP_HOME/bi n/vaul t. sh application must be accessible via a command-line interface.
Pro ced u re 7.4 . Set u p t h e Java K eyst o re
1. R u n t h e vaul t. sh co mman d .
Run EAP_HOME/bi n/vaul t. sh. Start a new interactive session by typing 0 .
112
2. En t er t h e d irect o ry wh ere en cryp t ed f iles will b e st o red .

If you followed Section 7.2, Create a Java Keystore to Store Sensitive Strings , your keystore
is in the directory EAP_HOME/vaul t. In most cases, it makes sense to store all of your
encrypted information in the same place as the key store. Since this directory will contain
sensitive information it should be accessible to only limited users. At a minimum the user
account under which JBoss EAP is running requires read-write access.
Note
D o not forget to include the trailing slash on the directory name. Either use / or \,
depending on your operating system.
3. En t er t h e p at h t o t h e keyst o re.
Enter the full path to the keystore file. This example uses
EAP_HOME/vaul t/vaul t. keysto re.
4. En t er t h e keyst o re p asswo rd , vau lt n ame, salt , an d it erat io n co u n t .
When prompted, enter the keystore password, vault name, salt, and iteration count. A
handshake is performed.
5. Select t h e o p t io n t o st o re a p asswo rd .
Select option 0 to store a password or other sensitive string.
6. En t er t h e valu e.
When prompted, enter the value twice. If the values do not match, you are prompted to try
again.
7. En t er t h e vau lt b lo ck.
Enter the vault block, which is a container for attributes which pertain to the same resource.
An example of an attribute name would be d s_Exampl eD S. This will form part of the
reference to the encrypted string, in your datasource or other service definition.
8. En t er t h e at t rib u t e n ame.
Enter the name of the attribute you are storing. An example attribute name would be
passwo rd .
R esu lt
A message such as the one below shows that the attribute has been saved.
Secured attribute value has been stored in vault.
9. Make n o t e o f t h e in f o rmat io n ab o u t t h e en cryp t ed st rin g .
A message prints to standard output, showing the vault block, attribute name, shared key,
and advice about using the string in your configuration. Make note of this information in a
secure location. Example output is shown below.
113
********************************************
Vault Block:ds_ExampleDS
Attribute Name:password
Configuration should be done as follows:
VAULT::ds_ExampleDS::password::1
********************************************
10. U se t h e en cryp t ed st rin g in yo u r co n f ig u rat io n .
Use the string from the previous step in your configuration, in place of a plain-text string. A
datasource using the encrypted password above is shown below.
...
<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-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</xadatasource-class>
</driver>
</drivers>
</datasources>
</subsystem>
...
You can use an encrypted string anywhere in your domain or standalone configuration file
where expressions are allowed.
Note
To check if expressions are allowed within a particular subsystem, run the following
CLI command against that subsystem:
/host=master/core-service=management/securityrealm=TestRealm:read-resource-description(recursive=true)
From the output of running this command, look for the value for the expressi o nsal l o wed parameter. If this is true, then you can use expressions within the
configuration of this particular subsystem.
114
After you store your string in the keystore, use the following syntax to replace any clear-text
string with an encrypted one.
${VAULT::VAULT_BLOCK::ATTRIBUTE_NAME::ENCRYPTED_VALUE}
Here is a sample real-world value, where the vault block is d s_Exampl eD S and the attribute
is passwo rd .
<password>${VAULT::ds_ExampleDS::password::1}</password>
Report a bug
7.7. St ore and Resolve Sensit ive St rings In Your Applicat ions
O verview
Configuration elements of JBoss EAP 6 support the ability to resolve encrypted strings against
values stored in a Java Keystore, via the Security Vault mechanism. You can add support for this
feature to your own applications.
First, add the password to the vault. Second, replace the clear-text password with the one stored in
the vault. You can use this method to obscure any sensitive string in your application.
Prereq u isit es
Before performing this procedure, make sure that the directory for storing your vault files exists. It
does not matter where you place them, as long as the user who executes JBoss EAP 6 has
permission to read and write the files. This example places the vaul t/ directory into the
/ho me/USER/vaul t/ directory. The vault itself is a file called vaul t. keysto re inside the vaul t/
directory.
Examp le 7.2. Ad d in g t h e Passwo rd St rin g t o t h e Vau lt

Add the string to the vault using the EAP_HOME/bi n/vaul t. sh command. The full series of
commands and responses is included in the following screen output. Values entered by the user
are emphasized. Some output is removed for formatting. In Microsoft Windows, the name of the
command is vaul t. bat. Note that in Microsoft Windows, file paths use the \ character as a
directory separator, rather than the / character.
[user@ host bin]$ ./vault.sh
**********************************
**** JBoss Vault ********
**********************************
Please enter a Digit::
0: Start Interactive Session 1: Remove
Interactive Session 2: Exit
0
Starting an interactive session
Enter directory to store encrypted files:/ho me/user/vaul t/
Enter Keystore URL:/ho me/user/vaul t/vaul t. keysto re
Enter Keystore password: . . .
Enter Keystore password again: . . .
Values match
Enter 8 character salt:1234 56 78
Enter iteration count as a number (Eg: 44):25
115
Enter Keystore Alias:vaul t

Vault is initialized and ready for use
Handshake with Vault complete
0: Store a password 1: Check whether password
exists 2: Exit
0
Task: Store a password
Please enter attribute value: sa
Please enter attribute value again: sa
Values match
Enter Vault Block:D S
Enter Attribute Name:theP ass
Secured attribute value has been stored in vault.
Please make note of the following:
********************************************
Vault Block:DS
Attribute Name:thePass
Configuration should be done as follows:
VAULT::DS::thePass::1
********************************************
exists 2: Exit
2
0: Store a password
1: Check whether password
The string that will be added to the Java code is the last value of the output, the line beginning
with VAULT .
The following servlet uses the vaulted string instead of a clear-text password. The clear-text version
is commented out so that you can see the difference.
Examp le 7.3. Servlet U sin g a Vau lt ed Passwo rd
p ackage vaulterror.web;
i mport java.io.IOException;
i mport java.io.Writer;
i mport
i mport
i mport
i mport
i mport
i mport
i mport
i mport
javax.annotation.Resource;
javax.annotation.sql.DataSourceDefinition;
javax.servlet.ServletException;
javax.servlet.annotation.WebServlet;
javax.servlet.http.HttpServlet;
javax.servlet.http.HttpServletRequest;
javax.servlet.http.HttpServletResponse;
javax.sql.DataSource;
/ *@ DataSourceDefinition(
name = "java:jboss/datasources/LoginDS",
user = "sa",
116
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"
)
@ WebServlet(name = "MyTestServlet", urlPatterns = { "/my/" },
loadOnStartup = 1)
p ublic class MyTestServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
@ Resource(lookup = "java:jboss/datasources/LoginDS")
private DataSource ds;
@ Override
protected void doGet(HttpServletRequest req, HttpServletResponse

resp) throws ServletException, IOException {
Writer writer = resp.getWriter();
writer.write((ds != null) + "");
Your servlet is now able to resolve the vaulted string.

Report a bug
117
Chapter 8. Web, HTTP Connectors, and HTTP Clustering

8.1. Configure a mod_clust er Worker Node
Su mmary
A mod_cluster worker node is an application server that participates in a load-balanced cluster.
Requests from users are received by a web server, which then forwards these requests to a pool of
mod_cluster worker nodes. A worker node can be part of a server group in a Managed D omain, or a
standalone server. For an overview of web server load balancing, refer to Overview of HTTP
Connectors in the Administration and Configuration Guide.
The load-balancing web server is configured via the mo d _cl uster subsystem. To configure the
mo d _cl uster subsystem, refer to Configure the mod_cluster Subsystem in the Administration and
Configuration Guide.
Worker nodes in a managed domain shares an identical configuration across a server group.
Worker nodes running as standalone servers are configured individually. The configuration steps
are otherwise identical.
Wo rker N o d e C o n f ig u rat io n
A standalone server must be started with the stand al o ne-ha or stand al o ne-ful l -ha profile.
A server group in a managed domain must use the ha or ful l -ha profile, and the ha-so ckets
or ful l -ha-so ckets socket binding group. JBoss EAP 6 ships with a cluster-enabled server
group called o ther-server-g ro up which meets these requirements.
Note
Where Management CLI commands are given, they assume you use a managed domain. If you
use a standalone server, remove the /pro fi l e= ful l -ha portion of the commands.
Pro ced u re 8.1. C o n f ig u re a Wo rker N o d e

1. C o n f ig u re t h e n et wo rk in t erf aces.
By default, the network interfaces all default to 127. 0 . 0 . 1. Every physical host that hosts
either a standalone server or one or more servers in a server group needs its interfaces to be
configured to use its public IP address, which the other servers can see.
To change the IP address of a JBoss EAP 6 host, you need to shut it down and edit its
configuration file directly. This is because the Management API which drives the Management
Console and Management CLI relies on a stable management address.
Follow these steps to change the IP address on each server in your cluster to the master's
public IP address.
a. Start the JBoss EAP server using the profile described earlier in this topic.
b. Launch the Management CLI, using the EAP_HOME/bi n/jbo ss-cl i . sh command
in Linux or the EAP_HOME\bi n\jbo ss-cl i . bat command in Microsoft Windows
Server. Type co nnect to connect to the domain controller on the localhost, or
co nnect IP_ADDRESS to connect to a domain controller on a remote server.
118
Chapt er 8 . Web, HT T P Connect ors, and HT T P Clust ering
c. Modify the external IP address for the manag ement, publ i c and unsecure
interfaces by typing the following commands. Be sure to replace
EXT ER NAL_IP _AD D R ESS in the command with the actual external IP address of the
host.
/i nterface= manag ement: wri te-attri bute(name= i netad d ress,val ue= "${jbo ss. bi nd . ad d ress. manag ement: EXTERNAL_IP_
ADDRESS}"
/i nterface= publ i c: wri te-attri bute(name= i netad d ress,val ue= "${jbo ss. bi nd . ad d ress. publ i c: EXTERNAL_IP_ADDR
ESS}"
/i nterface= unsecure: wri te-attri bute(name= i netad d ress,val ue= "${jbo ss. bi nd . ad d ress. unsecure: EXTERNAL_IP_AD
DRESS}"
: rel o ad
You should see the following result for each command.
"outcome" => "success"
d. For hosts that participate in a managed domain but are not the master, you must
change the host name from master to a unique name. This name must be unique
across slaves and will be used for the slave to identify to the cluster, so make a note
of the name you use.
i. Start the JBoss EAP slave host using the following syntax:
bi n/d o mai n. sh --ho st-co nfi g = HOST_SLAVE_XML_FILE_NAME
For example:
bi n/d o mai n. sh --ho st-co nfi g = ho st-sl ave0 1. xml
ii. Launch the Management CLI.
iii. Use the following syntax to replace the host name:
/ho st= master: wri teattri bute(name= "name",val ue= UNIQUE_HOST_SLAVE_NAME)
For example:
/ho st= master: wri te-attri bute(name= "name",val ue= "ho stsl ave0 1")
You should see the following result.
This modifies the XML in the ho st-sl ave0 1. xml file as follows:
<host name="host-slave01" xmlns="urn:jboss:domain:1.6">
119
e. For newly configured hosts that need to join a managed domain, you must remove the
l o cal element and add the remo te element ho st attribute that points to the domain
controller. This step does not apply for a standalone server.
i. Start the JBoss EAP slave host using the following syntax:
bi n/d o mai n. sh --ho st-co nfi g = HOST_SLAVE_XML_FILE_NAME
For example:
bi n/d o mai n. sh --ho st-co nfi g = ho st-sl ave0 1. xml
ii. Launch the Management CLI.
iii. Use the following syntax specify the domain controller:
/ho st= UNIQ UE_HO ST _SLAVE_NAME/: wri te-remo te-d o mai nco ntro l l er(ho st= DOMAIN_CONTROLLER_IP_ADDRESS,po rt= ${jbo
ss. d o mai n. master. po rt: 9 9 9 9 },securi tyreal m= "Manag ementR eal m")
For example:
/ho st= ho st-sl ave0 1/: wri te-remo te-d o mai nco ntro l l er(ho st= "19 2. 16 8. 1. 20 0 ",po rt= ${jbo ss. d o mai n. m
aster. po rt: 9 9 9 9 },securi ty-real m= "Manag ementR eal m")
You should see the following result.
This modifies the XML in the ho st-sl ave0 1. xml file as follows:
<domain-controller>
<remote host="192.168.1.200"
port="${jboss.domain.master.port:9999}" securityrealm="ManagementRealm"/>
</domain-controller>
2. C o n f ig u re au t h en t icat io n f o r each slave server.
Each slave server needs a username and password created in the domain controller's or
standalone master's Manag ementR eal m. On the domain controller or standalone master,
run the EAP_HOME/bi n/ad d -user. sh command. Add a user with the same username as
the slave, to the Manag ementR eal m. When asked if this user will need to authenticate to an
external JBoss AS instance, answer yes. An example of the input and output of the command
is below, for a slave called sl ave1, with password chang eme.
user:bin user$ ./add-user.sh
What type of user do you wish to add?
a) Management User (mgmt-users.properties)
b) Application User (application-users.properties)
(a): a
120
Enter the details of the new user to add.

Realm (ManagementRealm) :
Username : sl ave1
Password : chang eme
Re-enter Password : chang eme
About to add user 'slave1' for realm 'ManagementRealm'
Is this correct yes/no? yes
Added user 'slave1' to file '/home/user/jboss-eap6.0/standalone/configuration/mgmt-users.properties'
Added user 'slave1' to file '/home/user/jboss-eap6.0/domain/configuration/mgmt-users.properties'
Is this new user going to be used for one AS process to connect to
another AS process e.g. slave domain controller?
yes/no? yes
To represent the user add the following to the server-identities
definition <secret value="Y2hhbmdlbWU=" />
3. C o p y t h e B ase6 4 - en co d ed <secret> elemen t f ro m t h e ad d -user. sh o u t p u t .
If you plan to specify the Base64-encoded password value for authentication, copy the
<secret> element value from the last line of the ad d -user. sh output as you will need it in
the step below.
4. Mo d if y t h e slave h o st ' s secu rit y realm t o u se t h e n ew au t h en t icat io n .
You can specify the secret value in one of the following ways:
A. Sp ecif y t h e B ase6 4 - en co d ed p asswo rd valu e in t h e server co n f ig u rat io n f ile
u sin g t h e Man ag emen t C LI.
a. Launch the Management CLI, using the EAP_HOME/bi n/jbo ss-cl i . sh
command in Linux or the EAP_HOME\bi n\jbo ss-cl i . bat command in
Microsoft Windows Server. Type co nnect to connect to the domain controller on
the localhost, or co nnect IP_ADDRESS to connect to a domain controller on a
remote server.
b. Specify the secret value by typing the following command. Be sure to replace the
SEC R ET _VALUE with the secret value returned from the ad d -user output from the
previous step.
/co re-servi ce= manag ement/securi tyreal m= Manag ementR eal m/serveri d enti ty= secret: ad d (val ue= "SECRET_VALUE")
: rel o ad
B. C o n f ig u re t h e h o st t o g et t h e p asswo rd f ro m t h e vau lt .
121
a. Use the vaul t. sh script to generate a masked password. It will generate a string
like the following:
VAULT : : secret: : passwo rd : : O D VmY mJjNG MtZD U2ZC 0 0 Y mNl LWE4 O D MtZj
Q 1NWNmND U4 ZD c1T El O R V9 C UkVBS3Zhd Wx0 .
You can find more information on the vault in the Password Vaults for Sensitive
Strings section of this guide starting here: Section 7.1, Password Vault System .
b. Launch the Management CLI, using the EAP_HOME/bi n/jbo ss-cl i . sh
Microsoft Windows Server. Type co nnect to connect to the domain controller on
the localhost, or co nnect IP_ADDRESS to connect to a domain controller on a
remote server.
c. Specify the secret value by typing the following command. Be sure to replace the
SEC R ET _VALUE with the masked password generated in the previous step.
/co re-servi ce= manag ement/securi tyreal m= Manag ementR eal m/serveri d enti ty= secret: ad d (val ue= "${VAULT : : secret: : passwo rd : : SEC
RET_VALUE}")
: rel o ad
Note
When creating a password in the vault, it must be specified in plain text, not
Base64-encoded.
C. Sp ecif y t h e p asswo rd as a syst em p ro p ert y.

The following examples use server. i d enti ty. passwo rd as the system property name
for the password.
a. Specify the system property for the password in the server configuration file using
the Management CLI.
i. Launch the Management CLI, using the EAP_HOME/bi n/jbo ss-cl i . sh
Microsoft Windows Server. Type co nnect to connect to the domain
controller on the localhost, or co nnect IP_ADDRESS to connect to a
domain controller on a remote server.
ii. Type the following command to configure the secret identity to use the
system property.
/co re-servi ce= manag ement/securi tyreal m= Manag ementR eal m/serveri d enti ty= secret: ad d (val ue= "${server. i d enti ty. passwo r
d }")
: rel o ad
122

b. When you specify the password as a system property, you can configure the host
in either of the following ways:
A. Start the server entering the password in plain text as a command line
argument, for example:
-Dserver.identity.password=changeme
Note
The password must be entered in plain text and will be visible to anyone
who issues a ps -ef command.
B. Place the password in a properties file and pass the properties file URL as a
command line argument.
i. Add the key/value pair to a properties file. For example:
server.identity.password=changeme
ii. Start the server with the command line arguments
--properties=URL_TO_PROPERTIES_FILE
.
5. R est art t h e server.
The slave will now authenticate to the master using its host name as the username and the
encrypted string as its password.
R esu lt
Your standalone server, or servers within a server group of a managed domain, are now configured
as mod_cluster worker nodes. If you deploy a clustered application, its sessions are replicated to all
cluster nodes for failover, and it can accept requests from an external Web server or load balancer.
Each node of the cluster discovers the other nodes using automatic discovery, by default.To
configure automatic discovery, and the other specific settings of the mo d _cl uster subsystem, see
Configure the mod_cluster Subsystem in the Administration and Configuration Guide. To configure the
Apache HTTP Server, see Use an External Web Server as the Web Front-end for JBoss EAP 6 Applications
in the Administration and Configuration Guide.
Report a bug
123
Chapter 9. Patch Installation

9.1. About Pat ches and Upgrades
Patching in JBoss EAP 6 applies updates which are made available to a specific minor version of
JBoss EAP 6, for example JBoss EAP 6.2. Patches can contain individual or cumulative updates.
Upgrading is the process of moving to a newer major version (for example, from 5.0 to 6.0) or newer
minor version (for example, from 6.1 to 6.2), and cannot be done via patching.
Report a bug
9.2. About Pat ching Mechanisms

JBoss patches are distributed in two forms: zip (for all products) and RPM (for a subset of products).
Important
A JBoss product installation must always only be updated using one patch method: either zip
or RPM patches. Only security and cumulative patches will be available via RPM, and
customers using an RPM installation will not be able to update using zip patches.
JBoss patches can be either an asynchronous update, or a planned update:
Asynchronous updates: individual patches which are released outside the normal update cycle of
the existing product. These may include security patches, as well as other individual patches
provided by Red Hat Global Support Services (GSS) to fix specific issues.
Planned updates: These include cumulative patches, as well as micro, minor or major upgrades
of an existing product. Cumulative patches include all previously developed updates for that
version of the product.
D eciding whether a patch is released as part of a planned update or an asynchronous update
depends on the severity of the issue being fixed. An issue of low impact is typically deferred, and is
resolved in the next cumulative patch or minor release of the affected product. Issues of moderate or
higher impact are typically addressed in order of importance as an asynchronous update to the
affected product, and contain a fix for only a specific issue.
Security updates for JBoss products are provided by an erratum (for both zip and RPM methods).
The erratum encapsulates a list of the resolved flaws, their severity ratings, the affected products,
textual description of the flaws, and a reference to the patches. Bug fix updates are not announced
via an erratum.
124
Chapt er 9 . Pat ch Inst allat ion
Important
It is important to note that after a patch has been applied, the jars picked up at runtime are
picked up from the
EAP_HOME/mo d ul es/system/l ayers/base/. o verl ays/$P AT C H_ID /$MO D ULE
directory. The original files are left in
EAP_HOME/mo d ul es/system/l ayers/base/$MO D ULE. The patching mechanism cripples
the original jar files for security reasons. This means that if you apply a patch which updates a
module, the original module's jar files are altered to be unusable. If the patch is rolled back,
the original files will be reverted back to a usable state. This also means that the proper
rollback procedure must be used to rollback any applied patch. See Section 9.4.3, Rollback
the Application of a Patch in Z ip Form Using the Patch Management System for the proper
rollback procedure.
For more information on how Red Hat rates JBoss security flaws, refer to: Section 9.6, Severity and
Impact Rating of JBoss Security Patches
Red Hat maintains a mailing list for notifying subscribers about security related flaws. See
Section 9.3, Subscribe to Patch Mailing Lists
Report a bug
9.3. Subscribe t o Pat ch Mailing List s

Su mmary
The JBoss team at Red Hat maintains a mailing list for security announcements for Red Hat JBoss
Middleware products. This section covers what you need to do to subscribe to this list.
Prereq u isit es
None
Pro ced u re 9 .1. Su b scrib e t o t h e JB o ss Wat ch List
1. Click the following link to go to the JBoss Watch mailing list page: JBoss Watch Mailing List.
2. Enter your email address in the Subscri bi ng to Jbo ss-watch-l i st section.
3. [You may also wish to enter your name and select a password. D oing so is optional but
recommended.]
4. Press the Subscri be button to start the subscription process.
5. You can browse the archives of the mailing list by going to: JBoss Watch Mailing List
Archives.
R esu lt
After confirmation of your email address, you will be subscribed to receive security related
announcements from the JBoss patch mailing list.
Report a bug
9.4 . Inst all Pat ches in Zip Form

125
9.4 . Inst all Pat ches in Zip Form

9.4 .1. T he Pat ch Management Syst em
The JBoss EAP 6 patch management system is used to apply downloaded zip patches to a single
JBoss EAP 6 server. It can be accessed either through the Management CLI by using the patch
command, or through the Management Console. The patch management system cannot be used to
automatically patch JBoss EAP 6 server instances across a managed domain, but individual server
instances in a managed domain can be patched independently.
Important
JBoss EAP 6 server instances which have been installed using the RPM method cannot be
updated using the patch management system. Refer to Section 9.5, Patching an RPM
Installation to update RPM-installed JBoss EAP 6 servers.
Note
The patch management system can only be used with patches produced for versions of JBoss
EAP 6.2 and later. For patches for versions of JBoss EAP prior to 6.2, you should instead refer
to the relevant version's documentation available at
https://access.redhat.com/site/documentation/.
In addition to applying patches, the patch management system can provide basic information on the
state of installed patches, and also provides a way to immediately rollback the application of a
patch.
When applying or rolling back a patch, the patch management system will check the modules and
other miscellaneous files that it is changing for any user modifications. If a user modification is
detected, and a conflict-handling switch has not been specified, the patch management system will
abort the operation and warn that there is a conflict. The warning will include a list of the modules
and other files that are in conflict. To complete the operation, it must be retried with a switch
specifying how to resolve the conflict: either to preserve the user modifications, or to override them.
The table below lists the arguments and switches for the Management CLI patch command.
T ab le 9 .1. patch C o mman d Arg u men t s an d Swit ch es
Arg u men t o r Swit ch
D escrip t io n
appl y
--o verri d e-al l
Applies a patch.
If there is a conflict, the patch operation
overrides any user modifications.
If there is a conflict as a result of any modified
modules, this switch overrides those
modifications with the contents of the patch
operation.
For specified miscellaneous files only, this will
override the conflicting modified files with the
files in the patch operation.
For specified miscellaneous files only, this will
preserve the conflicting modified files.
--o verri d e-mo d ul es
--o verri d e= path(,path)
--preserve= path(,path)
126
Arg u men t o r Swit ch
D escrip t io n
--ho st= HOST_NAME
Available in domain mode, this specifies the

host that the patch operation will be performed
on.
Returns information on currently installed
patches.
Returns information on the patching history.
Rollsback the application of a patch.
Required for rollback, the ID of the patch to
rollback.
Required for rollback, this specifies whether to
restore the server configuration files as part of
the rollback operation.
If the patch to rollback is an individual (one-off)
patch, using this argument specifies that the
rollback operation will also rollback all other
one-off patches that have been applied on top
of the specified patch.
i nfo
hi sto ry
ro l l back
--patch-i d = PATCH_ID
--reset-co nfi g urati o n= TRUE| FALSE
--ro l l back-to
Report a bug
9.4 .2. Inst alling Pat ches in Zip Form Using t he Pat ch Management Syst em
Su mmary
Patches that are in the zip format can be installed using the JBoss EAP 6 patch management system
via either the Management CLI or the Management Console.
Important
The patch management system is a feature that was added in JBoss EAP 6.2. For versions of
JBoss EAP prior to 6.2, the process to install patches in zip form is different, and you should
instead refer to the relevant version's documentation available at
Prereq u isit es
Valid access and subscription to the Red Hat Customer Portal.
A current subscription to a JBoss product installed in zip format.
Access to the Management CLI or the Management Console for the JBoss EAP 6 server to be
updated. Refer to Launch the Management CLI or Log in to the Management Console in the
Administration and Configuration Guide.
Warning
Before installing a patch, you should backup your JBoss product along with all customized
configuration files.
127
Pro ced u re 9 .2. Ap p ly a z ip p at ch t o a JB o ss EAP 6 server in st an ce u sin g t h e

Man ag emen t C LI
1. D ownload the patch zip file from the Customer Portal at
https://access.redhat.com/downloads/
2. From the Management CLI, apply the patch with the following command including the
appropriate path to the patch file:
[standalone@ localhost:9999 /] patch appl y /path/to/downloadedpatch.zip
The patch tool will warn if there are any conflicts in attempting the apply the patch. Refer to
Section 9.4.1, The Patch Management System for available patch command switches to rerun the command to resolve any conflicts.
3. Restart the JBoss EAP 6 server for the patch to take effect:
[standalone@ localhost:9999 /] shutd o wn --restart= true
Pro ced u re 9 .3. Ap p ly a z ip p at ch t o a JB o ss EAP 6 server in st an ce u sin g t h e
Man ag emen t C o n so le
1. D ownload the patch zip file from the Customer Portal at
https://access.redhat.com/downloads/
2. In the Management Console:
A. For a standalone server: click on the R unti me tab at the top of the screen, then click
P atch Manag ement.
B. For a managed domain: click on the D o mai n tab at the top of the screen, select the host
you want to patch from the Ho st drop-down menu, then click P atch Manag ement.
3. Click Appl y a New P atch.
a. If you are patching a managed domain host, on the next screen select whether to
shutdown the servers on the host, and click Next.
4. Click the Bro wse button, select the downloaded patch you want to apply, and then click
Next.
a. If there are any conflicts in attempting to apply the patch, a warning will be displayed.
Click Vi ew erro r d etai l s to see the detail of the conflicts. If there is a conflict, you
can either cancel the operation, or select the O verri d e al l co nfl i cts check box
and click Next. Overriding conflicts will result in the content of the patch overriding
any user modifications.
5. After the patch has been successfully applied, select whether to restart the JBoss EAP 6
server now for the patch to take effect, and click Fi ni sh.
R esu lt
The JBoss EAP 6 server instance is patched with the latest update.
Report a bug
128
9.4 .3. Rollback t he Applicat ion of a Pat ch in Zip Form Using t he Pat ch
Management Syst em
Su mmary
The JBoss EAP 6 patch management system can be used to rollback the application of a previously
applied zip patch, via either the Management CLI or the Management Console.
Warning
Rolling back the application of a patch using the patch management system is not intended
as a general uninstall functionality. It is only intended to be used immediately after the
application of a patch which had undesirable consequences.
Important
The patch management system is a feature that was added in JBoss EAP 6.2. For versions of
JBoss EAP prior to 6.2, the process to rollback patches in zip form is different, and you should
instead refer to the relevant version's documentation available at
Prereq u isit es
A patch that was previously applied using the JBoss EAP 6 patch management system.
Access to the Management CLI or the Management Console for the JBoss EAP 6 server. Refer to
Launch the Management CLI or Log in to the Management Console in the Administration and
Configuration Guide.
Warning
When following either procedure, use caution when specifying the value of the R eset
C o nfi g urati o n option:
If set to T R UE, the patch rollback process will also rollback the JBoss EAP 6 server
configuration files to their pre-patch state. Any changes that were made to the JBoss EAP 6
server configuration files after the patch was applied will be lost.
If set to FALSE, the server configuration files will not be rolled back. In this situation, it is
possible that the server will not start after the rollback, as the patch may have altered
configurations, such as namespaces, which may no longer be valid and have to be fixed
manually.
Pro ced u re 9 .4 . R o llb ack a p at ch f ro m a JB o ss EAP 6 server in st an ce u sin g t h e

Man ag emen t C LI
1. From the Management CLI, use the patch i nfo command to find the ID of the patch that is
to be rolled back.
129
A. For cumulative patches, the patch ID is the value of the first cumul ati ve-patch-i d
shown in the patch i nfo output.
B. Individual security or bug fix patch ID s are listed as the value of the first patches shown
in the patch i nfo output, with the most recently applied individual patch listed first.
2. From the Management CLI, rollback the patch with the appropriate patch ID from the previous
step.
[standalone@ localhost:9999 /] patch ro l l back --patch-i d = PATCH_ID -reset-co nfi g urati o n= TRUE
The patch tool will warn if there are any conflicts in attempting the rollback the patch. Refer to
Section 9.4.1, The Patch Management System for available patch command switches to rerun the command to resolve any conflicts.
3. Restart the JBoss EAP 6 server for the patch rollback to take effect:
[standalone@ localhost:9999 /] shutd o wn --restart= true
Pro ced u re 9 .5. R o llb ack a p at ch f ro m a JB o ss EAP 6 server in st an ce u sin g t h e
Man ag emen t C o n so le
1. In the Management Console:
A. For a standalone server: click on the R unti me tab at the top of the screen, then click
P atch Manag ement.
B. For a managed domain: click on the D o mai n tab at the top of the screen, select the
relevant host from the Ho st drop-down menu, then click P atch Manag ement.
2. In the R ecent P atch Hi sto ry table, select the patch that you want to rollback, then click
R o l l back.
a. For a managed domain host, on the next screen select whether to shutdown the
servers on the host, and click Next.
3. Choose your options for the rollback process, then click Next.
4. Confirm the options and the patch to be rolled back, then click Next.
a. If the O verri d e al l option was not selected and there are any conflicts in
attempting to rollback the patch, a warning will be displayed. Click Vi ew erro r
d etai l s to see the detail of the conflicts. If there is a conflict, you can either cancel
the operation, or click C ho o se O pti o ns and try the operation again with the
O verri d e al l check box selected. Overriding conflicts will result in the rollback
operation overriding any user modifications.
5. After the patch has been successfully rolled back, select whether to restart the JBoss EAP 6
server now for the changes to take effect, and click Fi ni sh.
R esu lt
The patch, and optionally also the server configuration files, are rolled back on the JBoss EAP 6
server instance.
Report a bug
130
9.5. Pat ching an RPM Inst allat ion

Su mmary
JBoss patches are distributed in two forms: Z IP (for all products) and RPM (for a subset of products).
This task describes the steps you need to take to install the patches via the RPM format.
Prereq u isit es
A valid subscription to the Red Hat Network.
A current subscription to a JBoss product installed via an RPM package.
Pro ced u re 9 .6 . Ap p ly a p at ch t o a JB o ss p ro d u ct via t h e R PM met h o d
Security updates for JBoss products are provided by errata (for both zip and RPM methods). The
errata encapsulates a list of the resolved flaws, their severity ratings, the affected products, textual
description of the flaws, and a reference to the patches.
For RPM distributions of JBoss products, the errata include references to the updated RPM
packages. The patch can be installed by using yum.
Warning
Before installing a patch, you must backup your JBoss product along with all customized
configuration files.
1. Get notified about the security patch either via being a subscriber to the JBoss watch mailing
list or by browsing the JBoss watch mailing list archives.
2. Read the errata for the security patch and confirm that it applies to a JBoss product in your
environment.
3. If the security patch applies to a JBoss product in your environment, then follow the link to
download the updated RPM package which is included in the errata.
4. Use
yum upd ate
to install the patch.
Important
When updating an RPM installation, your JBoss product is updated cumulatively with
all RPM-released fixes.
R esu lt
The JBoss product is patched with the latest update using the RPM format.
Report a bug
131
9.6. Severit y and Impact Rat ing of JBoss Securit y Pat ches
To communicate the risk of each JBoss security flaw, Red Hat uses a four-point severity scale of low,
moderate, important and critical, in addition to Common Vulnerability Scoring System (CVSS)
version 2 base scores which can be used to identify the impact of the flaw.
T ab le 9 .2. Severit y R at in g s o f JB o ss Secu rit y Pat ch es
Severit y
D escrip t io n
Critical
This rating is given to flaws that could be easily

exploited by a remote unauthenticated attacker
and lead to system compromise (arbitrary code
execution) without requiring user interaction.
These are the types of vulnerabilities that can be
exploited by worms. Flaws that require an
authenticated remote user, a local user, or an
unlikely configuration are not classed as critical
impact.
This rating is given to flaws that can easily
compromise the confidentiality, integrity, or
availability of resources. These are the types of
vulnerabilities that allow local users to gain
privileges, allow unauthenticated remote users
to view resources that should otherwise be
protected by authentication, allow authenticated
remote users to execute arbitrary code, or allow
local or remote users to cause a denial of
service.
This rating is given to flaws that may be more
difficult to exploit but could still lead to some
compromise of the confidentiality, integrity, or
availability of resources, under certain
circumstances. These are the types of
vulnerabilities that could have had a critical
impact or important impact but are less easily
exploited based on a technical evaluation of the
flaw, or affect unlikely configurations.
This rating is given to all other issues that have
a security impact. These are the types of
vulnerabilities that are believed to require
unlikely circumstances to be able to be
exploited, or where a successful exploit would
give minimal consequences.
Important
Moderate
Low
The impact component of a CVSS v2 score is based on a combined assessment of three potential
impacts: Confidentiality (C), Integrity (I) and Availability (A). Each of these can be rated as None (N),
Partial (P) or Complete (C).
Because the JBoss server process runs as an unprivileged user and is isolated from the host
operating system, JBoss security flaws are only rated as having impacts of either None (N) or Partial
(P).
Examp le 9 .1. C VSS v2 Imp act Sco re
132
The example below shows a CVSS v2 impact score, where exploiting the flaw would have no
impact on system confidentiality, partial impact on system integrity and complete impact on system
availability (that is, the system would become completely unavailable for any use, for example, via
a kernel crash).
C : N/I: P /A: C
Combined with the severity rating and the CVSS score, organizations can make informed decisions
on the risk each issue places on their unique environment and schedule upgrades accordingly.
For more information about CVSS2, please see: CVSS2 Guide.
Report a bug
9.7. Manage Securit y Updat es for Dependencies Bundled Inside t he

Applicat ions Deployed on JBoss EAP
Red Hat provides security patches for all components that are part of the JBoss EAP distribution.
However, many users of JBoss EAP deploy applications which bundle their own dependencies,
rather than exclusively using components provided as part of the JBoss EAP distribution. For
example, a deployed WAR file may include dependency JARs in the WEB-INF/lib/ directory. These
JARs are out of scope for security patches provided by Red Hat. Managing security updates for
dependencies bundled inside the applications deployed on JBoss EAP is the responsibility of the
applications' maintainers. The following tools and data sources may assist in this effort, and are
provided without any support or warranty.
T o o ls an d D at a So u rces
JB o ss p at ch mailin g list s
Subscribing to the JBoss patch mailing lists will keep you informed regarding security flaws
that have been fixed in JBoss products, allowing you to check whether your deployed
applications are bundling vulnerable versions of the affected components.
Secu rit y ad viso ry p ag e f o r b u n d led co mp o n en t s.
Many open source components have their own security advisory page. For example, Struts
2 is a commonly-used component with many known security issues that is not provided as
part of the JBoss EAP distribution. The Struts 2 project maintains an upstream security
advisory page, which should be monitored if your deployed applications bundle Struts 2.
Many commercially-provided components also maintain security advisory pages.
R eg u larly scan yo u r d ep lo yed ap p licat io n s f o r kn o wn vu ln erab ilit ies
There are several commercial tools available to do this. There is also an open source tool
called Victims, which is developed by Red Hat employees, but comes with no support or
warranty. Victims provides plugins for several build and integration tools, which
automatically scan applications for bundling known-vulnerable dependencies. Plugins are
available for Maven, Ant and Jenkins. For more information about the Victims tool, see
https://victi.ms/about.html.
See Also :
Section 9.3, Subscribe to Patch Mailing Lists
133
Report a bug
134
Part III. Developing Secure Applications
135
Chapter 10. Security Overview

10.1. About Applicat ion Securit y
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 13.2.1, About Authentication
Section 13.5.1, About Authorization
Section 13.7.1, About Security Auditing
Section 13.8.1, About Security Mapping
Section 10.2, D eclarative Security
Section 11.2.2.1, About EJB Method Permissions
Section 11.2.3.1, About EJB Security Annotations
See also Section 13.9, Use a Security D omain in Your Application .
Report a bug
10.2. Declarat ive Securit y

Declarative security is a method to separate security concerns from your application code by using
the container to manage security. The container provides an authorization system based on either
file permissions 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
10.2.1. Java EE Declarat ive Securit y Overview

The Java EE security model is declarative in that you describe the security roles and permissions in a
standard XML descriptor rather than embedding security into your business component. This
isolates security from business-level code because security tends to be more a function of where the
component is deployed than an inherent aspect of the component's business logic. For example,
consider an Automated Teller Machine (ATM) that is to be used to access a bank account. The
security requirements, roles and permissions will vary independent of how you access the bank
account, based on 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
via the standard Java EE deployment descriptors. You secure access to EJBs and web components
in an enterprise application by using the ejb-jar. xml and web. xml deployment descriptors.
Report a bug
10.2.2. Securit y References
136
Chapt er 1 0 . Securit y O verview
Both Enterprise Java Beans (EJBs) and servlets can declare one or more <security-role-ref>
elements.
Fig u re 10.1. Secu rit y R o les R ef eren ce Mo d el

This element declares that a component is using the <role-name> element's ro l e-nameT ype
attribute value as an argument to the i sC al l erInR o l e(Stri ng ) method. By using the
i sC al l erInR o l e method, 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> element through the <role-link> element. The typical use of i sC al l erInR o l e is
to perform a security check that cannot be defined by using the role-based <method-permissions>
elements.
Examp le 10.1. ejb - jar.xml d escrip t o r f rag men t


<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>
137
Note
This fragment is an example only. In deployments, the elements in this section must contain
role names and links relevant to the EJB deployment.
Examp le 10.2. web .xml d escrip t o r f rag men t
< 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>
Report a bug
10.2.3. Securit y Ident it y

An Enterprise Java Bean (EJB) can specify the identity another EJB must use when it invokes
methods on components using the <security-identity> element.
Fig u re 10.2. Java EE Secu rit y Id en t it y D at a Mo d el

The invocation identity can be that of the current caller, or it can be a specific role. The application
assembler uses the <security-identity> element with a <use-caller-identity> child element. This
indicate that the current caller's identity should be propagated as the security identity for method
invocations made by the EJB. Propagation of the caller's identity is the default used in the absence
of an explicit <security-identity> element declaration.
138
Alternatively, the application assembler can use the <run-as> or <role-name> child element to specify
that a specific security role supplied by the <role-name> element value must be used as the security
identity for method invocations made by the EJB.
Note that this does not change the caller's identity as seen by the
EJBC o ntext. g etC al l erP ri nci pal () method. Rather, the caller's security roles are set to the
single role 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.
You configure this behavior by assigning the internal EJB <method-permission> elements, which
restrict access to a role never assigned to an external client. EJBs that must in turn use internal EJBs
are then configured with a <run-as> or <role-name> equal to the restricted role. The following
descriptor fragment describes an example<security-identity> element usage.
< ejb-jar>
<enterprise-beans>
<session>

<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>
</session>
</enterprise-beans>


< /ejb-jar>
When you use <run-as> to assign a specific role to outgoing calls, a principal named ano nymo us is
assigned to all outgoing calls. If you want another principal to be associated with the call, you must
associate a <run-as-principal> with the bean in the jbo ss-ejb3. xml file. The following fragment
associates a principal named i nternal with R unAsBean from the prior example.
< session>
<security-identity>
<run-as-principal>internal</run-as-principal>
< /session>
The <run-as> element is also available in servlet definitions in a web. xml file. The following
example shows how to assign the role Internal R o l e to a servlet:
139
<servlet>

<run-as>
</run-as>
</servlet>
Calls from this servlet are associated with the anonymous pri nci pal . The <run-as-principal>
element is available in the jbo ss-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 i nternal to the
servlet above.
<servlet>
</servlet>
Report a bug
10.2.4 . Securit y Roles

The security role name referenced by either the securi ty-ro l e-ref or securi ty-i d enti ty
element needs to map to one of the application's declared roles. An application assembler defines
logical security roles by declaring securi ty-ro l e elements. The ro l e-name value is a logical
application role name like Administrator, Architect, SalesManager, etc.
The Java EE specifications note that it is important to keep in mind that the security roles in the
deployment descriptor are used to define the logical security view of an application. Roles defined in
the Java EE deployment descriptors should not be confused with the user groups, users, principals,
and other concepts that exist in the target enterprise's operational environment. The deployment
descriptor roles are application constructs with application domain-specific names. For example, a
banking application might use role names such as BankManager, Teller, or Customer.
In JBoss EAP, a securi ty-ro l e element is only used to map securi ty-ro l e-ref/ro l e-name
values to the logical role that the component role references. The user's assigned roles are a
dynamic function of the application's security manager. JBoss does not require the definition of
securi ty-ro l e elements in order to declare method permissions. However, the specification of
securi ty-ro l e elements is still a recommended practice to ensure portability across application
servers and for deployment descriptor maintenance.
Examp le 10.3. An ejb - jar.xml d escrip t o r f rag men t t h at illu st rat es t h e secu rit y- ro le
elemen t u sag e.
< !-- A sample ejb-jar.xml fragment -->

< ejb-jar>
<assembly-descriptor>
<security-role>
<description>The single application role</description>
14 0
<role-name>TheApplicationRole</role-name>
</security-role>
</assembly-descriptor>
< /ejb-jar>
Examp le 10.4 . An examp le web .xml d escrip t o r f rag men t t h at illu st rat es t h e secu rit yro le elemen t u sag e.
< !-- A sample web.xml fragment -->

< web-app>
<security-role>
<description>The single application role</description>
<role-name>TheApplicationRole</role-name>
</security-role>
< /web-app>
Report a bug
10.2.5. EJB Met hod Permissions

An application assembler can set the roles that are allowed to invoke an EJB's home and remote
interface methods through method-permission element declarations.
Fig u re 10.3. Java EE Met h o d Permissio n s Elemen t

Each metho d -permi ssi o n element contains one or more role-name child elements that define the
logical roles that are allowed to access the EJB methods as identified by method child elements. You
can also specify an unchecked element instead of the ro l e-name element to declare that any
authenticated user can access the methods identified by method child elements. In addition, you can
14 1
declare that no one should have access to a method that has the excl ud e-l i st element. If an EJB
has methods that have not been declared as accessible by a role using a metho d -permi ssi o n
element, the EJB methods default to being excluded from use. This is equivalent to defaulting the
methods into the excl ud e-l i st.
Fig u re 10.4 . Java EE Met h o d Elemen t

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
enterprise bean:
< method>
<ejb-name>EJBNAME</ejb-name>
<method-name>*</method-name>
< /method>
The second style is used for referring to a specified method of the home or component interface of the
named enterprise bean:
<method>
<method-name>METHOD</method-name>
</method>
If there are multiple methods with the same overloaded name, this style refers to all of the overloaded
14 2
methods.
The third style is used to refer to a specified method within a set of methods with an overloaded name:
< method>
<method-name>METHOD</method-name>
<method-params>
<method-param>PARAMETER_1</method-param>

<method-param>PARAMETER_N</method-param>
</method-params>
< /method>
The method must be defined in the specified enterprise bean's home or remote interface. The methodparam element values are the fully qualified name of the corresponding method parameter type. If
there are multiple methods with the same overloaded signature, the permission applies to all of the
matching overloaded methods.
The optional metho d -i ntf element can be used to differentiate methods with the same name and
signature that are defined in both the home and remote interfaces of an enterprise bean.
Example 10.5, An ejb-jar.xml descriptor fragment that illustrates the method-permission element
usage. provides complete examples of the metho d -permi ssi o n element usage.
Examp le 10.5. An ejb - jar.xml d escrip t o r f rag men t t h at illu st rat es t h e met h o d p ermissio n elemen t u sag e.
< ejb-jar>
<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>
</method-permission>
<method-permission>
<description>The employee role may access the

findByPrimaryKey,
getEmployeeInfo, and the updateEmployeeInfo(String)

method of
the AardvarkPayroll bean </description>
<method>
<ejb-name>AardvarkPayroll</ejb-name>
<method-name>findByPrimaryKey</method-name>
</method>
<method>
<method-name>getEmployeeInfo</method-name>
14 3
</method>
<method>
<method-name>updateEmployeeInfo</method-name>
<method-params>
<method-param>java.lang.String</method-param>
</method-params>
</method>
<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>
<method-permission>
<description>Any authenticated user may access any method
of the
EmployeeServiceHelp bean</description>
<unchecked/>
<method>
<ejb-name>EmployeeServiceHelp</ejb-name>
</method>
<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>
Report a bug
10.2.6. Ent erprise Beans Securit y Annot at ions

Enterprise beans use Annotations to pass information to the deployer about security and other
aspects of the application. The deployer can set up the appropriate enterprise bean security policy
for the application if specified in annotations, or the deployment descriptor.
Any method values explicitly specified in the deployment descriptor override annotation values. If a
method 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:
14 4
@DeclareRoles
D eclares each security role declared in the code. For information about configuring roles,
refer to the Java EE 6 Tutorial Specifying Authorized Users by D eclaring Security Roles.
@RolesAllowed, @PermitAll, an d @DenyAll
Specifies method permissions for annotations. For information about configuring
annotation method permissions, refer to the Java EE 6 Tutorial Specifying Authorized Users
by D eclaring Security Roles.
@RunAs
Configures the propagated security identity of a component. For information about
configuring propagated security identities using annotations, refer to the Java EE 6 Tutorial
Propagating a Security Identity (Run-As).
Report a bug
10.2.7. Web Cont ent Securit y Const raint s

In a web application, security is defined by the roles that are allowed access to content by a URL
pattern that identifies the protected content. This set of information is declared by using the web. xml
security-constraint element.
14 5
Fig u re 10.5. Web C o n t en t Secu rit y C o n st rain t s

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
an optional series of <http-method> elements. The <url-pattern> element value specifies a URL
pattern against which a request URL must match for the request to correspond to an attempt to
access secured content. The <http-method> element value specifies a type of HTTP request to allow.
The optional <user-data-constraint> element specifies the requirements for the transport layer of the
client to server connection. The requirement may be for content integrity (preventing data tampering
in the 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 server should be protected. Its values are NO NE, INT EG R AL, and C O NFID ENT IAL. A value of
NO NE means that the application does not require any transport guarantees. A value of INT EG R AL
means that the application requires the data sent between the client and server to be sent in such a
way that it can not be changed in transit. A value of C O NFID ENT IAL means that the application
requires the data to be transmitted in a fashion that prevents other entities from observing the
contents of the transmission. In most cases, the presence of the INT EG R AL or C O NFID ENT IAL flag
indicates that the use of SSL is required.
14 6
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 form login mechanism.
Fig u re 10.6 . Web Lo g in C o n f ig u rat io n

The <auth-method> child element specifies the authentication mechanism for the web application. As
a prerequisite to gaining access to any web resources that are protected by an authorization
constraint, a user must have authenticated using the configured mechanism. Legal <auth-method>
values are BASIC , D IG EST , FO R M, SP NEG O , and C LIENT -C ER T . The <realm-name> child element
specifies the realm name to use in HTTP basic and digest authorization. The <form-login-config>
child element specifies the log in as well as error pages that should be used in form-based log in. If
the <auth-method> value is not FO R M, then fo rm-l o g i n-co nfi g and its child elements are
ignored.
The following configuration example indicates that any URL lying under the web application's
/restri cted path requires an Autho ri zed User role. There is no required transport guarantee
and the authentication method used for obtaining the user identity is BASIC HTTP authentication.
Examp le 10.6 . web .xml D escrip t o r Frag men t
< web-app>
<security-constraint>
<web-resource-collection>
<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>
14 7
</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>
Report a bug
10.2.8. Enable Form-based Aut hent icat ion

Form-based authentication provides flexibility in defining a custom JSP/HTML page for log in, and a
separate page to which users are directed if an error occurs during login.
Form-based authentication is defined by including <auth-metho d >FO R M</auth-metho d > in the
<login-config> element of the deployment descriptor, web. xml . The login and error pages are also
defined in <login-config>, as follows:
<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>
When a web application with form-based authentication is deployed, the web container uses
Fo rmAuthenti cato r to direct users to the appropriate page. JBoss EAP maintains a session pool
so that authentication information does not need to be present for each request. When
Fo rmAuthenti cato r receives a request, it queries o rg . apache. catal i na. sessi o n. Manag er
for an existing session. If no session exists, a new session is created. Fo rmAuthenti cato r then
verifies the credentials of the session.
Authentication Requests
Each session is identified by a session ID , a 16 byte string generated from random values.
These values are retrieved from /d ev/urand o m (Linux) by default, and hashed with MD 5.
Checks are performed at session ID creation to ensure that the ID created is unique.
Once verified, the session ID is assigned as part of a cookie, and then returned to the client. This
cookie is 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 identifier
attribute is called JSESSIO NID . Its value is a hex-string of the session ID . This cookie is configured
to be non-persistent. This means that on the client side it will be deleted when the browser exits. On
14 8
the server side, sessions expire after 30 minutes of inactivity, at which time session objects and their
credential information are deleted.
Say a user attempts to access a web application that is protected with form-based authentication.
Fo rmAuthenti cato r caches the request, creates a new session if necessary, and redirects the user
to the login page defined in l o g i n-co nfi g . (In the previous example code, the login page is
l o g i n. html .) The user then enters their user name and password in the HTML form provided. User
name and password are passed to Fo rmAuthenti cato r via the j_securi ty_check form action.
The Fo rmAuthenti cato r then authenticates the user name and password against the realm
attached to the web application context. In JBoss Enterprise Application Platform, the realm is
JBo ssWebR eal m. When authentication is successful, Fo rmAuthenti cato r retrieves the saved
request from the cache and redirects the user to their original request.
Note
The server recognizes form authentication requests only when the URI ends with
/j_securi ty_check and at least the j_username and j_passwo rd parameters exist.
Report a bug
10.2.9. Enable Declarat ive Securit y

The Java EE security elements that have been covered so far describe the security requirements only
from the application's perspective. Because Java EE security elements declare logical roles, the
application deployer maps the roles from the application domain onto the deployment environment.
The Java EE specifications omit these application server-specific details.
To map application roles onto the deployment environment, specify a security manager that
implements the Java EE security model using JBoss EAP-specific deployment descriptors.
See Also :
Chapter 17, Role-Based Security in Applications
Report a bug
14 9
Chapter 11. Application Security

11.1. Dat asource Securit y
11.1.1. About Dat asource Securit y
D atasource security refers to encrypting or obscuring passwords for datasource connections. These
passwords 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:
Security domains: Section 12.3.3.1, About Security D omains .
Password vaults: Section 7.1, Password Vault System .
Examp le 11.1. Secu rit y D o main Examp le

<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>
The D sRealm domain is referenced by a datasource like so:
<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>
Examp le 11.2. Passwo rd Vau lt Examp le

<security>
<user-name>admin</user-name>
<password>${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4
MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}</password>
</security>
150
Chapt er 1 1 . Applicat ion Securit y
Report a bug
11.2. EJB Applicat ion Securit y

11.2.1. Securit y Ident it y
1 1 .2 .1 .1 . Abo ut EJB Se curit y Ide nt it y
An EJB can specify an identity to use when invoking methods on other components. This is the EJB's
security identity (also known as invocation identity).
By default, the EJB uses its own caller identity. The identity can alternatively be set to a specific
security role. Using specific security roles is useful when you want to construct a segmented security
model - for example, restricting access to a set of components to internal EJBs only.
Report a bug
1 1 .2 .1 .2 . Se t t he Se curit y Ide nt it y o f an EJB

The security identity of the EJB is specified through the <securi ty-i d enti ty> tag in the security
configuration.
By default - if no <securi ty-i d enti ty> tag is present - the EJB's own caller identity is used.
Examp le 11.3. Set t h e secu rit y id en t it y o f an EJB t o b e t h e same as it s caller

This example sets the security identity for method invocations made by an EJB to be the same as
the current caller's identity. This behavior is the default if you do not specify a <securi tyi d enti ty> element declaration.
< ejb-jar>
<enterprise-beans>
<session>

<security-identity>
</session>

</enterprise-beans>
< /ejb-jar>
Examp le 11.4 . Set t h e secu rit y id en t it y o f an EJB t o a sp ecif ic ro le

To set the security identity to a specific role, use the <run-as> and <ro l e-name> tags inside the
<securi ty-i d enti ty> tag.
< ejb-jar>
<enterprise-beans>
151
<session>

<security-identity>
<run-as>
</run-as>
</session>
</enterprise-beans>

< /ejb-jar>
By default, when you use <run-as>, a principal named ano nymo us is assigned to outgoing
calls. To assign a different principal, uses the <run-as-pri nci pal >.
< session>
<security-identity>
< /session>
Specifying security identity in servlets

You can also use the <run-as> and <run-as-pri nci pal > elements inside a servlet
element.
See also :
Section 11.2.1.1, About EJB Security Identity
Section A.6, EJB Security Parameter Reference
Report a bug
11.2.2. EJB Met hod Permissions

1 1 .2 .2 .1 . Abo ut EJB Me t ho d Pe rm issio ns
EJBs can restrict access to their methods to specific security roles.
The EJB <metho d -permi ssi o n> element declaration specifies the roles that can invoke the EJB's
interface 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
152
A specified method within a set of methods with an overloaded name

Report a bug
1 1 .2 .2 .2 . Use EJB Me t ho d Pe rm issio ns

O verview
The <metho d -permi ssi o n> element defines the logical roles that are allowed to access the EJB
methods defined by <metho d > elements. Several examples demonstrate the syntax of the XML.
Multiple method permission statements may be present, and they have a cumulative effect. The
<metho d -permi ssi o n> element is a child of the <assembl y-d escri pto r> element of the <ejbjar> descriptor.
The XML syntax is an alternative to using annotations for EJB method permissions.
Examp le 11.5. Allo w ro les t o access all met h o d s o f an EJB
< method-permission>
<description>The employee and temp-employee roles may access any
method
of the EmployeeService bean </description>
<method>
</method>
< /method-permission>
Examp le 11.6 . Allo w ro les t o access o n ly sp ecif ic met h o d s o f an EJB , an d limit in g

wh ich met h o d p aramet ers can b e p assed .
<description>The employee role may access the findByPrimaryKey,
getEmployeeInfo, and the updateEmployeeInfo(String) method of
the AcmePayroll bean </description>
<method>
<ejb-name>AcmePayroll</ejb-name>
</method>
<method>
</method>
<method>
<method-params>
153
</method-params>
</method>
Examp le 11.7. Allo w an y au t h en t icat ed u ser t o access met h o d s o f EJB s

Using the <unchecked /> element allows any authenticated user to use the specified methods.
<description>Any authenticated user may access any method of the
<unchecked/>
<method>
</method>
Examp le 11.8. C o mp let ely exclu d e sp ecif ic EJB met h o d s f ro m b ein g u sed
< exclude-list>
<description>No fireTheCTO methods of the EmployeeFiring bean may be
<method>
</method>
< /exclude-list>
Examp le 11.9 . A co mp let e <assembl y-d escri pto r> co n t ain in g several <metho d permi ssi o n> b lo cks
< ejb-jar>
<method-permission>
<description>The employee and temp-employee roles may

access any
<method>
</method>
<method-permission>
<description>The employee role may access the
154
findByPrimaryKey,
getEmployeeInfo, and the updateEmployeeInfo(String)

method of
the AcmePayroll bean </description>
<method>
</method>
<method>
</method>
<method>
<method-params>
</method-params>
</method>
<method-permission>
<description>The admin role may access any method of the
EmployeeServiceAdmin bean </description>
<method>
<ejb-name>EmployeeServiceAdmin</ejb-name>
</method>
<method-permission>
<description>Any authenticated user may access any method

of the
<unchecked/>
<method>
</method>
<exclude-list>
<description>No fireTheCTO methods of the EmployeeFiring

bean may be
<method>
</method>
</exclude-list>
< /ejb-jar>
Report a bug
11.2.3. EJB Securit y Annot at ions
155
1 1 .2 .3.1 . Abo ut EJB Se curit y Anno t at io ns

EJB javax. anno tati o n. securi ty annotations are defined in JSR250.
EJBs use security annotations to pass information about security to the deployer. These include:
@ D eclareR o les
D eclares which roles are available.
@ R u n As
Configures the propagated security identity of a component.
Report a bug
1 1 .2 .3.2 . Use EJB Se curit y Anno t at io ns

O verview
You can use either XML descriptors or annotations to control which security roles are able to call
methods in your Enterprise JavaBeans (EJBs). For information on using XML descriptors, refer to
Section 11.2.2.2, Use EJB Method Permissions .
Any method values explicitly specified in the deployment descriptor override annotation values. If a
method value is not specified in the deployment descriptor, those values set using annotations are
used. The overriding granularity is on a per-method basis.
An n o t at io n s f o r C o n t ro llin g Secu rit y Permissio n s o f EJB s
@ D eclareR o les
Use @D eclareRoles to define which security roles to check permissions against. If no
@D eclareRoles is present, the list is built automatically from the @RolesAllowed
annotation. For information about configuring roles, refer to the Java EE 6 Tutorial
Specifying Authorized Users by D eclaring Security Roles.
@ R o lesAllo wed , @ Permit All, @ D en yAll
Use @ R o l esAl l o wed to list which roles are allowed to access a method or methods. Use
@ P ermi tAl l or @ D enyAl l to either permit or deny all roles from using a method or
methods. For information about configuring annotation method permissions, refer to the
Java EE 6 Tutorial Specifying Authorized Users by D eclaring Security Roles.
@ R u n As
Use @ R unAs to specify a role a method uses when making calls from the annotated method.
For information about configuring propagated security identities using annotations, refer to
the Java EE 6 Tutorial Propagating a Security Identity (Run-As).
Examp le 11.10. Secu rit y An n o t at io n s Examp le
@ Stateless
@ RolesAllowed({"admin"})
@ SecurityDomain("other")
p ublic class WelcomeEJB implements Welcome {
156
@ PermitAll
public String WelcomeEveryone(String msg) {
return "Welcome to " + msg;
}
@ RunAs("tempemployee")
public String GoodBye(String msg) {
return "Goodbye, " + msg;

}
public String GoodbyeAdmin(String msg) {
return "See you later, " + msg;
}
}
In this code, all roles can access method Wel co meEveryo ne. The G o o d Bye method uses the
tempempl o yee role when making calls. Only the ad mi n role can access method
G o o d byeAd mi n, and any other methods with no security annotation.
Report a bug
11.2.4 . Remot e Access t o EJBs

1 1 .2 .4 .1 . Abo ut Re m o t e Me t ho d Acce ss
JBoss Remoting is the framework which provides remote access to EJBs, JMX MBeans, and other
similar services. It works within the following transport types, with or without SSL:
Su p p o rt ed T ran sp o rt T yp es
Socket / Secure Socket
RMI / RMI over SSL
HTTP / HTTPS
Servlet / Secure Servlet
Bisocket / Secure Bisocket
Warning
affected packages.
JBoss Remoting also provides automatic discovery via Multicast or JND I.
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.
D at a Marsh allin g
157
The Remoting system also provides data marshalling and unmarshalling services. D ata marshalling
refers to the ability to safely move data across network and platform boundaries, so that a separate
system can perform work on it. The work is then sent back to the original system and behaves as
though it were handled locally.
Arch it ect u re O verview
When you design a client application which uses Remoting, you direct your application to
communicate with the server by configuring it to use a special type of resource locator called an
Invo kerLo cato r, which is a simple String with a URL-type format. The server listens for requests for
remote resources on a co nnecto r, which is configured as part of the remo ti ng subsystem. The
co nnecto r hands the request off to a configured ServerInvo cati o nHand l er. Each
ServerInvo cati o nHand l er implements a method i nvo ke(Invo cati o nR eq uest), which
knows how to handle the request.
The JBoss Remoting framework contains three layers that mirror each other on the client and server
side.
JB o ss R emo t in g Framewo rk Layers
The user interacts with the outer layer. On the client side, the outer layer is the C l i ent class,
which sends invocation requests. On the server side, it is the InvocationHandler, which is
implemented 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 wire
formats.
Report a bug
1 1 .2 .4 .2 . Abo ut Re m o t ing Callbacks

When a Remoting client requests information from the server, it can block and wait for the server to
reply, but this is often not the ideal behavior. To allow the client to listen for asynchronous events on
the server, and continue doing other work while waiting for the server to finish the request, your
application can ask the server to send a notification when it has finished. This is referred to as a
callback. One client can add itself as a listener for asynchronous events generated on behalf of
another client, as well. There are two different choices for how to receive callbacks: pull callbacks or
push callbacks. Clients check for pull callbacks synchronously, but passively listen for push
callbacks.
In essence, a callback works by the server sending an Invo cati o nR eq uest to the client. Your
server-side code works the same regardless of whether the callback is synchronous or
asynchronous. Only the client needs to know the difference. The server's InvocationRequest sends a
respo nseO bject to the client. This is the payload that the client has requested. This may be a direct
response to a request or an event notification.
Your server also tracks listeners using an m_l i steners object. It contains a list of all listeners that
have been added to your server handler. The ServerInvo cati o nHand l er interface includes
methods that allow you to manage this list.
The client handles pull and push callback in different ways. In either case, it must implement a
callback handler. A callback handler is an implementation of interface
o rg . jbo ss. remo ti ng . Invo kerC al l backHand l er, which processes the callback data. After
implementing the callback handler, you either add yourself as a listener for a pull callback, or
implement a callback server for a push callback.
158
Pu ll C allb acks
For a pull callback, your client adds itself to the server's list of listeners using the
C l i ent. ad d Li stener() method. It then polls the server periodically for synchronous delivery of
callback data. This poll is performed using the C l i ent. g etC al l backs().
Pu sh C allb ack
A push callback requires your client application to run its own InvocationHandler. To do this, you
need to run a Remoting service on the client itself. This is referred to as a callback server. The
callback server accepts incoming requests asynchronously and processes them for the requester (in
this case, the server). To register your client's callback server with the main server, pass the callback
server's Invo kerLo cato r as the second argument to the ad d Li stener method.
Report a bug
1 1 .2 .4 .3. Abo ut Re m o t ing Se rve r De t e ct io n

Remoting servers and clients can automatically detect each other using JND I or Multicast. A
Remoting D etector is added to both the client and server, and a NetworkRegistry is added to the
client.
The D etector on the server side periodically scans the InvokerRegistry and pulls all server invokers it
has created. It uses this information to publish a detection message which contains the locator and
subsystems supported by each server invoker. It publishes this message via a multicast broadcast or
a binding into a JND I server.
On the client side, the D etector receives the multicast message or periodically polls the JND I server to
retrieve detection messages. If the D etector notices that a detection message is for a newly-detected
remoting server, it registers it into the NetworkRegistry. The D etector also updates the
NetworkRegistry if it detects that a server is no longer available.
Report a bug
1 1 .2 .4 .4 . Co nfigure t he Re m o t ing Subsyst e m

O verview
JBoss Remoting has three top-level configurable elements: the worker thread pool, one or more
connectors, and a series of local and remote connection URIs. This topic presents an explanation of
each configurable item, example CLI commands for how to configure each item, and an XML example
of a fully-configured subsystem. This configuration only applies to the server. Most people will not
need to configure 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 a specific connector.
Note
The Remoting subsystem configuration is not exposed to the web-based Management
Console, but it is fully configurable from the command-line based Management CLI. Editing the
XML by hand is not recommended.
Ad ap t in g t h e C LI C o mman d s
159
The CLI commands are formulated for a managed domain, when configuring the d efaul t profile. To
configure a different profile, substitute its name. For a standalone server, omit the
/pro fi l e= d efaul t part of the command.
C o n f ig u rat io n O u t sid e t h e R emo t in g Su b syst em
There are a few configuration aspects which are outside of the remo ti ng subsystem:
N et wo rk In t erf ace
The network interface used by the remo ti ng subsystem is the unsecure interface defined
in the d o mai n/co nfi g urati o n/d o mai n. xml or
stand al o ne/co nfi g urati o n/stand al o ne. xml .
< interfaces>
<interface name="management"/>
<interface name="public"/>
<interface name="unsecure"/>
< /interfaces>
The per-host definition of the unsecure interface is defined in the ho st. xml in the same
directory as the d o mai n. xml or stand al o ne. xml . This interface is also used by several
other subsystems. Exercise caution when modifying it.
< 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">

<inet-address
value="${jboss.bind.address.unsecure:127.0.0.1}"/>
</interface>
< /interfaces>
so cket - b in d in g
The default socket-binding used by the remo ti ng subsystem binds to TCP port 4777. Refer
to the documentation about socket bindings and socket binding groups for more
information if you need to change this.
R emo t in g C o n n ect o r R ef eren ce f o r EJB
The EJB subsystem contains a reference to the remoting connector for remote method
invocations. The following is the default configuration:
160
< remote connector-ref="remoting-connector" thread-poolname="default"/>
Secu re T ran sp o rt C o n f ig u rat io n

Remoting transports use StartTLS to use a secure (HTTPS, Secure Servlet, etc) connection
if the client requests it. The same socket binding (network port) is used for secured and
unsecured connections, so no additional server-side configuration is necessary. The client
requests the secure or unsecured transport, as its needs dictate. JBoss EAP 6 components
which use Remoting, such as EJBs, the ORB, and the JMS provider, request secured
interfaces by default.
Warning: StartT LS Security Considerations

StartTLS works by activating a secure connection if the client requests it, and otherwise
defaulting to an unsecured connection. It is inherently susceptible to a Man in the Middle style
exploit, wherein an attacker intercepts the client's request and modifies it to request an
unsecured connection. Clients must be written to fail appropriately if they do not receive a
secure connection, unless an unsecured connection actually is an appropriate fall-back.
Wo rker T h read Po o l
The worker thread pool is the group of threads which are available to process work which comes in
through the Remoting connectors. It is a single element <wo rker-thread -po o l >, and takes several
attributes. Tune these attributes if you get network timeouts, run out of threads, or need to limit
memory usage. Specific recommendations depend on your specific situation. Contact Red Hat
Global Support Services for more information.
T ab le 11.1. Wo rker T h read Po o l At t rib u t es
At t rib u t e
D escrip t io n
C LI C o mman d
read-threads
The number of read threads to

create for the remoting worker.
D efaults to 1.
write-threads
The number of write threads to

create for the remoting worker.
D efaults to 1.
task-keepalive
The number of milliseconds to

keep non-core remoting worker
task threads alive. D efaults to
60.
task-max-threads

threads for the remoting worker
task thread pool. D efaults to
16 .
/pro fi l e= d efaul t/subsys

tem= remo ti ng /: wri teattri bute(name= wo rkerread -thread s,val ue= 1)
tem= remo ti ng /: wri teattri bute(name= wo rkerwri te-thread s,val ue= 1)
tem= remo ti ng /: wri teattri bute(name= wo rkertaskkeepal i ve,val ue= 6 0 )
tem= remo ti ng /: wri teattri bute(name= wo rkertask-maxthread s,val ue= 16 )
161
At t rib u t e
D escrip t io n
C LI C o mman d
task-core-threads
The number of core threads for

the remoting worker task thread
pool. D efaults to 4 .
task-limit

remoting worker tasks to allow
before rejecting. D efaults to
16 384 .

tem= remo ti ng /: wri teattri bute(name= wo rkertask-co rethread s,val ue= 4 )
tem= remo ti ng /: wri teattri bute(name= wo rkertask-l i mi t,val ue= 16 384 )
C o n n ect o r
The connector is the main Remoting configuration element. Multiple connectors are allowed. Each
consists of a element <co nnecto r> element with several sub-elements, as well as a few possible
attributes. The default connector is used by several subsystems of JBoss EAP 6. Specific settings for
the elements and attributes of your custom connectors depend on your applications, so contact Red
Hat Global Support Services for more information.
T ab le 11.2. C o n n ect o r At t rib u t es
At t rib u t e
D escrip t io n
C LI C o mman d
socket-binding
The name of the socket binding

to use for this connector.
authentication-provider
The Java Authentication

Service Provider Interface for
Containers (JASPIC) module to
use with this connector. The
module must be in the
classpath.
security-realm
Optional. The security realm

which contains your
application's users,
passwords, and roles. An EJB
or Web Application can
authenticate against a security
realm. Appl i cati o nR eal m is
available in a default JBoss
EAP 6 installation.

tem= remo ti ng /co nnecto r=
remo ti ng co nnecto r/: wri teattri bute(name= so cketbi nd i ng ,val ue= remo ti ng
)
remo ti ng co nnecto r/: wri teattri bute(name= authenti c
ati o npro vi d er,val ue= myP ro vi d
er)
remo ti ng co nnecto r/: wri teattri bute(name= securi tyreal m,val ue= Appl i cati o n
R eal m)
T ab le 11.3. C o n n ect o r Elemen t s

At t rib u t e
D escrip t io n
C LI C o mman d
sasl
Enclosing element for Simple

Authentication and Security
Layer (SASL) authentication
mechanisms
N/A
162
At t rib u t e
D escrip t io n
C LI C o mman d
properties
Contains one or more

<pro perty> elements, each
with a name attribute and an
optional val ue attribute.

remo ti ng co nnecto r/pro perty= myP r
o p/: ad d (val ue= myP ro pVa
l ue)
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 a security
realm.
All of the outbound connections are enclosed in an <o utbo und -co nnecti o ns> element. Each of
these connection types takes an o utbo und -so cket-bi nd i ng -ref attribute. The outboundconnection takes a uri attribute. The remote outbound connection takes optional username and
securi ty-real m attributes to use for authorization.
T ab le 11.4 . O u t b o u n d C o n n ect io n Elemen t s
At t rib u t e
D escrip t io n
outbound-connection
Generic outbound connection.
local-outbound-connection
remote-outbound-connection
C LI C o mman d

tem= remo ti ng /o utbo und co nnecti o n= myco nnecti o n/: ad d (uri = htt
p: //my-co nnecti o n)
Outbound connection with a
implicit local:// URI scheme.
tem= remo ti ng /l o cal o utbo und -co nnecti o n= myco nnecti o n/: ad d (o utbo un
d -so cket-bi nd i ng ref= remo ti ng 2)
Outbound connections for
remote:// URI scheme, using
tem= remo ti ng /remo tebasic/digest authentication with o utbo und -co nnecti o n= mya security realm.
co nnecti o n/: ad d (o utbo un
d -so cket-bi nd i ng ref= remo ti ng ,username= m
yUser,securi tyreal m= Appl i cati o nR eal m)
SASL Elemen t s
Before defining the SASL child elements, you need to create the initial SASL element. Use the
following command:
/profile=default/subsystem=remoting/connector=remotingconnector/security=sasl:add
163
The child elements of the SASL element are described in the table below.
At t rib u t e
D escrip t io n
include-mechanisms
Contains a val ue attribute,

which is a space-separated list
of SASL mechanisms.
qop
strength
reuse-session
server-auth
policy
164

of SASL Quality of protection
values, in decreasing order of
preference.

of SASL cipher strength values,
in decreasing order of
preference.
Contains a val ue attribute

which is a boolean value. If
true, attempt to reuse sessions.
Contains a val ue attribute

which is a boolean value. If
true, the server authenticates to
the client.
C LI C o mman d
ystem=remoting/conne
ctor=remotingconnector/security=s
asl:writeattribute(name=inclu
de-mechanisms,value=
["DIGEST","PLAIN","G
SSAPI"])
asl:writeattribute(name=qop,v
alue=["auth"])
asl:writeattribute(name=stren
gth,value=
["medium"])
asl:writeattribute(name=reuse
-session,value=false)
asl:writeattribute(name=serve
r-auth,value=false)
At t rib u t e
An
enclosing
D escrip
t io n element which
contains zero or more of the
following elements, which each
take a single val ue.
forward-secrecy whether
mechanisms are required to
implement forward secrecy
(breaking into one session
will not automatically
provide information for
breaking into future
sessions)
no-active whether
mechanisms susceptible to
non-dictionary attacks are
permitted. A value of fal se
permits, and true denies.
no-anonymous whether
mechanisms that accept
anonymous login are
permitted. A value of fal se
permits, and true denies.
no-dictionary whether
mechanisms susceptible to
passive dictionary attacks
are allowed. A value of
fal se permits, and true
denies.
no-plain-text whether
mechanisms which are
susceptible to simple plain
passive attacks are allowed.
A value of fal se permits,
and true denies.
pass-credentials whether
mechanisms which pass
client credentials are
allowed.
C LI
C o mman d
asl/saslpolicy=policy:add
asl/saslpolicy=policy:writeattribute(name=forwa
rdsecrecy,value=true)
asl/saslpolicy=policy:writeattribute(name=noactive,value=false)
asl/saslpolicy=policy:writeattribute(name=noanonymous,value=fals
e)
asl/saslpolicy=policy:writeattribute(name=nodictionary,value=tru
e)
asl/sasl-
165
At t rib u t e
D escrip t io n
policy=policy:writeC LI
C o mman d
attribute(name=noplaintext,value=false)
asl/saslpolicy=policy:writeattribute(name=passcredentials,value=tr
ue)
properties
Contains one or more

<pro perty> elements, each
with a name attribute and an
optional val ue attribute.
asl/property=myprop:
add(value=1)
asl/property=myprop2
:add(value=2)
Examp le 11.11. Examp le C o n f ig u rat io n s

This example shows the default remoting subsystem that ships with JBoss EAP 6.
< subsystem xmlns="urn:jboss:domain:remoting:1.1">
<connector name="remoting-connector" socket-binding="remoting"

security-realm="ApplicationRealm"/>
< /subsystem>
This example contains many hypothetical values, and is presented to put the elements and
attributes discussed previously into context.
< subsystem xmlns="urn:jboss:domain:remoting:1.1">
<worker-thread-pool read-threads="1" task-keepalive="60" task-maxthreads="16" task-core-thread="4" task-limit="16384" write-threads="1"

/>
<connector name="remoting-connector" socket-binding="remoting"

security-realm="ApplicationRealm">
<sasl>
166
<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" outboundsocket-binding-ref="my-outbound-socket"/>
</outbound-connections>
< /subsystem>
C o n f ig u rat io n Asp ect s N o t Yet D o cu men t ed

JND I and Multicast Automatic D etection
Report a bug
1 1 .2 .4 .5 . Use Se curit y Re alm s wit h Re m o t e EJB Clie nt s

One way to add security to clients which invoke EJBs remotely is to use security realms. A security
realm is a simple database of username/password pairs and username/role pairs. The terminology is
also 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,
follow these steps:
Add a new security realm to the domain controller or standalone server.
Add the following parameters to the jbo ss-ejb-cl i ent. pro perti es file, which is in the
classpath of the application. This example assumes the connection is referred to as d efaul t by
the other parameters in the file.
167
remote.connection.default.username=appuser
remote.connection.default.password=apppassword
Create a custom Remoting connector on the domain or standalone server, which uses your new
security realm.
D eploy your EJB to the server group which is configured to use the profile with the custom
Remoting connector, or to your standalone server if you are not using a managed domain.
Report a bug
1 1 .2 .4 .6 . Add a Ne w Se curit y Re alm

1. R u n t h e Man ag emen t C LI.
Start the jbo ss-cl i . sh or jbo ss-cl i . bat command and connect to the server.
2. C reat e t h e n ew secu rit y realm it self .
Run the following command to create a new security realm named MyD o mai nR eal m on a
domain controller or a standalone server.
/host=master/core-service=management/securityrealm=MyDomainRealm:add()
/core-service=management/security-realm=MyDomainRealm:add()
3. C reat e t h e ref eren ces t o t h e p ro p ert ies f ile wh ich will st o re in f o rmat io n ab o u t
t h e n ew ro le.
Run the following command to create a pointer a file named myfi l e. pro perti es, which
will contain the properties pertaining to the new role.
Note
The newly created properties file is not managed by the included ad d -user. sh and
ad d -user. bat scripts. It must be managed externally.
/host=master/core-service=management/securityrealm=MyDomainRealm/authentication=properties:add(path=myfile.prope
rties)
/core-service=management/securityrealm=MyDomainRealm/authentication=properties:add(path=myfile.prope
rties)
168
R esu lt
Your new security realm is created. When you add users and roles to this new realm, the information
will be stored in a separate file from the default security realms. You can manage this new file using
your own applications or procedures.
Report a bug
1 1 .2 .4 .7 . Add a Use r t o a Se curit y Re alm

1. R u n t h e ad d -user. sh o r ad d -user. bat co mman d .
Open a terminal and change directories to the EAP_HOME/bi n/ directory. If you run Red Hat
Enterprise Linux or another UNIX-like operating system, run ad d -user. sh. If you run
Microsoft Windows Server, run ad d -user. bat.
2. C h o o se wh et h er t o ad d a Man ag emen t U ser o r Ap p licat io n U ser.
For this procedure, type b to add an Application User.
3. C h o o se t h e realm t h e u ser will b e ad d ed t o .
By default, the only available realm is Appl i cati o nR eal m. If you have added a custom
realm, you can type its name instead.
4. T yp e t h e u sern ame, p asswo rd , an d ro les, wh en p ro mp t ed .
Type the desired username, password, and optional roles when prompted. Verify your choice
by typing yes, or type no to cancel the changes. The changes are written to each of the
properties files for the security realm.
Report a bug
1 1 .2 .4 .8 . Abo ut Re m o t e EJB Acce ss Using SSL Encrypt io n

By default, the network traffic for Remote Method Invocation (RMI) of EJB2 and EJB3 Beans is not
encrypted. In instances where encryption is required, Secure Sockets Layer (SSL) can be utilized so
that the connection between the client and server is encrypted. Using SSL also has the added benefit
of allowing the network traffic to traverse some firewalls, depending on the firewall configuration.
Warning
affected packages.
Report a bug
11.3. JAX-RS Applicat ion Securit y

11.3.1. Enable Role-Based Securit y for a REST Easy JAX-RS Web Service
169
Su mmary
RESTEasy supports the @RolesAllowed, @PermitAll, and @D enyAll 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
D o not activate role-based security if the application uses EJBs. The EJB container will
provide the functionality, instead of RESTEasy.
Pro ced u re 11.1. En ab le R o le- B ased Secu rit y f o r a R EST Easy JAX- R S 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. D eclare 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-role>
</security-role>
4. Authorize access to all URLs handled by the JAX-RS runtime for all roles:
<web-resource-name>Resteasy</web-resource-name>
<url-pattern>/PATH</url-pattern>
<auth-constraint>
</auth-constraint>
R esu lt
Role-based security has been enabled within the application, with a set of defined roles.
Examp le 11.12. Examp le R o le- B ased Secu rit y C o n f ig u rat io n

<web-app>
170
<context-param>
<param-name>resteasy.role.based.security</param-name>
</context-param>
<servlet-mapping>
<servlet-name>Resteasy</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
<web-resource-name>Resteasy</web-resource-name>
<url-pattern>/security</url-pattern>
<auth-constraint>
<role-name>user</role-name>
</auth-constraint>
<security-role>
</security-role>
<security-role>
<role-name>user</role-name>
</security-role>
</web-app>
Report a bug
11.3.2. Secure a JAX-RS Web Service using Annot at ions

Su mmary
This topic covers the steps to secure a JAX-RS web service using the supported security annotations
Pro ced u re 11.2. Secu re a JAX- R S Web Service u sin g Su p p o rt ed Secu rit y An n o t at io n s
1. Enable role-based security. For more information, refer to: Section 11.3.1, Enable RoleBased Security for a RESTEasy JAX-RS Web Service
2. Add security annotations to the JAX-RS web service. RESTEasy supports the following
annotations:
@ R o lesAllo wed
D efines which roles can access the method. All roles should be defined in the
web. xml file.
@ Permit All
Allows all roles defined in the web. xml file to access the method.
@ D en yAll
171
D enies all access to the method.

Report a bug
172
Chapter 12. The Security Subsystem

12.1. About t he Securit y Subsyst em
The securi ty subsystem provides security infrastructure for applications. The subsystem uses a
security context associated with the current request to expose the capabilities of the authentication
manager, authorization manager, audit manager, and mapping manager to the relevant container.
The securi ty 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-subjectmode. In most cases, administrators will focus on the configuration of security domains.
D eep C o p y Mo d e
See Section 12.3.2.1, About D eep Copy Subject Mode for details about deep copy subject mode.
Secu rit y D o main
A security domain is a set of Java Authentication and Authorization Service (JAAS) declarative security
configurations which one or more applications use to control authentication, authorization, auditing,
and mapping. Three security domains are included by default: jbo ss-ejb-po l i cy, jbo ss-webpo l i cy, and o ther. You can create as many security domains as you need to accommodate your
application requirements. See Section 13.9, Use a Security D omain in Your Application for details
about security domain.
Report a bug
12.2. About t he St ruct ure of t he Securit y Subsyst em

The security subsystem is configured in the managed domain or standalone configuration file. Most
of the 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.
Examp le 12.1. Examp le Secu rit y Su b syst em C o n f ig u rat io n
< 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"/>
173
<module-option name="realm"
value="ApplicationRealm"/>
</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>
<vault>
...
</vault>
< /subsystem>
The <securi ty-manag ement>, <subject-facto ry> and <securi ty-pro perti es> elements
are not present in the default configuration. The <subject-facto ry> and <securi typro perti es> elements have been deprecated in JBoss EAP 6.1 onwards.
Report a bug
12.3. Configuring t he Securit y Subsyst em

12.3.1. Configure t he Securit y Subsyst em
You can configure the security subsystem using the Management CLI or web-based Management
Console.
Each top-level element within the security subsystem contains information about a different aspect of
the security configuration. Refer to Section 12.2, About the Structure of the Security Subsystem for
an example of security subsystem configuration.
<secu rit y- man ag emen t >
This section overrides high-level behaviors of the security subsystem. It contains an
optional setting d eep-co py-subject-mo d e, that specifies whether to copy or link to
security tokens, for additional thread safety.
<secu rit y- d o main s>
A container element which holds multiple security domains. A security domain may contain
information about authentication, authorization, mapping, and auditing modules, as well
as JASPI authentication and JSSE configuration. Your application would specify a security
domain to manage its security information.
<secu rit y- p ro p ert ies>
174
Chapt er 1 2 . T he Securit y Subsyst em
Contains names and values of properties which are set on the java.security.Security class.
Report a bug
12.3.2. Securit y Management

1 2 .3.2 .1 . Abo ut De e p Co py Subje ct Mo de
If deep copy subject mode is disabled (the default), copying a security data structure makes a
reference to the original, rather than copying the entire data structure. This behavior is more efficient,
but is prone to data corruption if multiple threads with the same identity clear the subject by means of
a flush or logout operation.
D eep copy subject mode causes a complete copy of the data structure and all its associated data to
be made, as long as they are marked cloneable. This is more thread-safe, but less efficient.
D eep copy subject mode is configured as part of the security subsystem.
Report a bug
1 2 .3.2 .2 . Enable De e p Co py Subje ct Mo de

You can enable deep copy security mode from the web-based management console or the
management CLI.
Pro ced u re 12.1. En ab le D eep C o p y Secu rit y Mo d e f ro m t h e Man ag emen t C o n so le
1. Lo g in t o t h e Man ag emen t C o n so le.
For detailed instructions, see the section entitled The Management Console in the Administration
and Configuration Guide for JBoss Enterprise Application Platform 6.x located on the Customer
Portal at
https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.
2. Man ag ed D o main : Select t h e ap p ro p riat e p ro f ile.
In a managed domain, the security subsystem is configured per profile, and you can enable
or disable the deep copy security mode independently in each profile.
To select a profile, click C o nfi g urati o n at the top of the screen, and then select a profile
from the P ro fi l e drop down box at the top left.
3. O p en t h e Securi ty Subsystem co n f ig u rat io n men u .
Expand the Securi ty menu, then select Securi ty Subsystem.
4. En ab le D eep C o py Subject mo d e.
Click Ed i t. Check the box beside D eep C o py Subjects to enable deep copy subject
mode.
En ab le D eep C o p y Su b ject Mo d e U sin g t h e Man ag emen t C LI
If you prefer to use the management CLI to enable this option, use one of the following commands.
Examp le 12.2. Man ag ed D o main
175
/profile=full/subsystem=security/:write-attribute(name=deep-copysubject-mode,value=TRUE)
Examp le 12.3. St an d alo n e Server

/subsystem=security/:write-attribute(name=deep-copy-subjectmode,value=TRUE)
Report a bug
12.3.3. Securit y Domains

1 2 .3.3.1 . Abo ut Se curit y Do m ains
Security domains are part of the JBoss EAP 6 security subsystem. All security configuration is now
managed 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, and
auditing. 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
as a principal. Although authentication and authorization are different, many of the included
authentication modules also handle authorization.
Authorization is a process by which the server determines if an authenticated user has permission or
privileges 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, or
attribute before passing the information to your application.
The auditing manager allows you to configure provider modules to control the way that security events
are reported.
If you use security domains, you can remove all specific security configuration from your application
itself. This allows you to change security parameters centrally. One common scenario that benefits
from this type of configuration structure is the process of moving applications between testing and
production environments.
Report a bug
1 2 .3.3.2 . CLI Ope rat io ns Re lat e d t o Se curit y Do m ains
Examp le 12.4 . f lu sh - cach e

This CLI command removes entries stored in the authentication cache for a security domain. A
single entry can be flushed by using the principal argument with the username as the value. If no
argument is passed to the operation, all entries are flushed. For more details about this operation,
use the CLI command:
/subsystem=security/security-domain=other:read-operationdescription(name=flush-cache)
176
Chapt er 1 2 . T he Securit y Subsyst em
Examp le 12.5. list - cach ed - p rin cip als

This CLI command lists the principals stored in the authentication cache for this security domain.
For more details about this operation, use the CLI command:
/subsystem=security/security-domain=other:read-operationdescription(name=list-cached-principals)
Report a bug
177
Chapter 13. Authentication and Authorization

13.1. Kerberos and SPNEGO Int egrat ion
13.1.1. About Kerberos and SPNEGO Int egrat ion
Kerberos is an authentication method that is designed for open network computing environments. It
works on the basis of a ticket and authenticator to establish the identity of both the user and the
server. It helps the two nodes communicating over a non secure environment to establish their
identity to each other 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
other are not sure of the authentication protocol the other supports. SPNEGO determines the
common GSSAPI mechanisms between the client application and the server and then dispatches all
further security operations to it.
K erb ero s an d SPN EG O In t eg rat io n
In a typical setup, the user logs into a desktop which is governed by the Active D irectory domain. The
user then uses the web browser, either Firebox or Internet Explorer, to access a web application that
uses JBoss Negotiation hosted on the JBoss EAP. The web browser transfers the desktop sign on
information to the web application. JBoss EAP uses background GSS messages with the Active
D irectory or any Kerberos Server to validate the user. This enables the user to achieve a seamless
SSO into the web application.
Report a bug
13.1.2. Deskt op SSO using SPNEGO

To configure the desktop SSO using SPNEGO configure the following:
Security D omain
System Properties
Web Application
Pro ced u re 13.1. C o n f ig u re D eskt o p SSO u sin g SPN EG O
1. C o n f ig u re Secu rit y D o main
Configure the security domains to represent the identity of the server and to secure the web
application.
Examp le 13.1. Secu rit y D o main C o n f ig u rat io n

<security-domains>
<security-domain name="host" cache-type="default">
<authentication>
<login-module code="Kerberos" flag="required">
178
Chapt er 1 3. Aut hent icat ion and Aut horiz at ion
<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="serverSecurityDomain"
value="host"/>
</login-module>


</security-domain>
2. Set u p t h e Syst em Pro p ert ies

If required, the system properties can be set in the domain model.
Examp le 13.2. C o n f ig u re Syst em Pro p ert ies

<system-properties>
<property name="java.security.krb5.kdc"
value="mykdc.mydomain"/>
179
<property name="java.security.krb5.realm"
value="MY_REALM"/>
</system-properties>
3. C o n f ig u re Web Ap p licat io n
It is not possible to override the authenticators, but it is possible to add the
Neg o ti ati o nAuthenti cato r as a valve to your jboss-web.xml descriptor to configure the
web application.
Note
The valve requires the securi ty-co nstrai nt and l o g i n-co nfi g to be defined in
the web.xml file as this is used to decide which resources are secured. However, the
chosen auth-metho d is overridden by this authenticator.
Examp le 13.3. C o n f ig u re Web Ap p licat io n

<!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>
<classname>org.jboss.security.negotiation.NegotiationAuthenticator</cla
ss-name>
</valve>
</jboss-web>
The web application also requires a dependency defining in MET A-INF/MANIFEST . MF so

that the JBoss Negotiation classes can be located.
Examp le 13.4 . D ef in e D ep en d en cy in MET A-INF/MANIFEST . MF

Manifest-Version: 1.0
Build-Jdk: 1.6.0_24
Dependencies: org.jboss.security.negotiation
180
Report a bug
13.1.3. Configure JBoss Negot iat ion for Microsoft Windows Domain
This section describes how to configure the accounts required for JBoss Negotiation to be used
when JBoss EAP is running on a Microsoft Windows server, which is a part of the Active D irectory
domain.
In this section, the hostname that is used to access the server as is referred to as {ho stname}, realm
is referred to as {real m}, domain is referred to as {d o mai n}, and the server hosting the JBoss EAP
instance is referred to as {machi ne_name}.
Pro ced u re 13.2. C o n f ig u re JB o ss N eg o t iat io n f o r Micro so f t Win d o ws D o main
1. C lear Exist in g Service Prin cip al Map p in g s
On a Microsoft Windows network some mappings are created automatically. D elete the
automatically created mappings to map the identity of the server to the service principal for
negotiation to take place correctly. The mapping enables the web browser on the client
computer to trust the server and attempt SPNEGO. The client computer verifies with the
domain controller for a mapping in the form of HT T P {ho stname}.
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 {machi ne_name}.
D elete the existing mappings using the commands, setspn -D HT T P /{ho stname}
{machi ne_name} and setspn -D ho st/{ho stname} {machi ne_name}.
2. Create a host user account.
Note
Ensure the host user name is different from the {machi ne_name}.
In the rest of the section the host user name is referred to as {user_name}.
3. D ef in e t h e map p in g b et ween t h e {user_name} an d {ho stname}.
Run the following command to configure the Service Principal Mapping, ktpass -pri nc
HT T P /{ho stname}@ {real m} -pass * -mapuser {d o mai n}\{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 the keytab.
Verify the mapping by running the following command, setspn -L {user_name}
4. Exp o rt t h e keyt ab o f t h e u ser t o t h e server o n wh ich EAP JB o ss is in st alled .
181
Run the following command to export the keytab, ktab -k servi ce. keytab -a
HT T P /{ho stname}@ {real m}.
Note
This command exports the ticket for the HTTP/{hostname} principal to the keytab
servi ce. keytab, which is used to configure the host security domain on JBoss.
5. D efine the principal within the security domain as follows:
<module-option name="principal">HTTP/{hostname}@ {realm}</moduleoption>
Report a bug
13.1.4 . Kerberos Aut hent icat ion for Picket Link IDP
The following sections explain how to set up Kerberos authentication for PicketLink ID P.
Pro ced u re 13.3. In st all JB o ss EAP 6 an d set u p K erb ero s
1. D ownload 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
unlimited JCE, the JBoss server cannot negotiate on the proper SPNEGO mechanism type
(using 1.3.6.1.5.2.5, which is G SS_IAKER B_MEC HANISM).
3. Use the example below to configure JBoss to use your desired Java version.
e xport JAVA_HOME=JDK/JRE_directory
Pro ced u re 13.4 . T est yo u r K erb ero s set u p u sin g JB o ss N eg o t iat io n T o o lkit
1. Use the JBoss Negotiation Toolkit available at Github
2. Modify the configuration files and use the mvn cl ean i nstal l command to build the
project.
3. Copy the file jbo ss-neg o ti ati o n-to o l ki t/targ et/jbo ss-neg o ti ati o nto o l ki t. war to $JBO SS_HO ME/stand al o ne/d epl o yments/.
4. Verify that all the three sections pass through the JBoss Negotiation Toolkit.
Pro ced u re 13.5. Set u p Picket Lin k ID P
C h an g es t o i d p. war
The example provided uses the i d p. war and empl o yee. war archives, which can be located in the
PicketLink Quickstarts repository. Modify the files in i d p. war as described below.
1. Add o rg . jbo ss. securi ty. neg o ti ati o n module to
$JBO SS_HO ME/stand al o ne/d epl o yments/i d p. war/MET A-INF/jbo ssd epl o yment-structure. xml because ID P is using the JBoss Negotiation module.
182
<jboss-deployment-structure>
<deployment>

<dependencies>
<module name="org.picketlink" />
<module name="org.jboss.security.negotiation" />
</dependencies>
</deployment>
</jboss-deployment-structure>
2. Add an additional valve
o rg . jbo ss. securi ty. neg o ti ati o n. Neg o ti ati o nAuthenti cato r for SPNEGO to
$JBO SS_HO ME/stand al o ne/d epl o yments/i d p. war/WEB-INF/jbo ss-web. xml .
3. Change securi ty-d o mai n from i d p to SP NEG O in
$JBO SS_HO ME/stand al o ne/d epl o yments/i d p. war/WEB-INF/jbo ss-web. xml as
follows:
< jboss-web>
<context-root>idp</context-root>
<valve>
<classname>org.picketlink.identity.federation.bindings.tomcat.idp.IDPWebB
rowserSSOValve</class-name>
<param>
<param-name>passUserPrincipalToAttributeManager</paramname>
</param>
</valve>
<valve>
<classname>org.jboss.security.negotiation.NegotiationAuthenticator</class
-name>
</valve>
< /jboss-web>
4. Add or change the security-role added to your principal by Kerberos server setup to
$JBO SS_HO ME/stand al o ne/d epl o yments/i d p. war/WEB-INF/web. xml .
5. Modify the file $JBO SS_HO ME/stand al o ne/d epl o yments/i d p. war/WEBINF/pi cketl i nk. xml as follows:
< PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
<PicketLinkIDP xmlns="urn:picketlink:identityfederation: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:identityfederation:handler:config:2.1">
183
<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.SAML2Is
suerTrustHandler" />
<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.SAML2Lo
gOutHandler" />
<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.SAML2A
uthenticationHandler" />
<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.RolesG
enerationHandler" />
</Handlers>

<PicketLinkSTS xmlns="urn:picketlink:identityfederation:config:1.0" TokenTimeout="5000" ClockSkew="0">
<TokenProviders>
<TokenProvider
ProviderClass="org.picketlink.identity.federation.core.saml.v1.prov
iders.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.prov
iders.SAML20AssertionTokenProvider"
TokenType="urn:oasis:names:tc:SAML:2.0:assertion"
TokenElement="Assertion"
TokenElementNS="urn:oasis:names:tc:SAML:2.0:assertion" />
</TokenProviders>
</PicketLinkSTS>
< /PicketLink>
6. Change Id enti tyUR L to match the host name of server you are running ID P on.
7. Change T rust to contain the domain names trusted by the Identity Provider.
8. Modify the empl o yee. war. Add or change security-roles added to your principal by
Kerberos server setup to
$JBO SS_HO ME/stand al o ne/d epl o yments/empl o yee. war/WEB-INF/web. xml .
9. Modify the securi ty d o mai n configuration in the file
$JBO SS_HO ME/stand al o ne/co nfi g urati o n/stand al o ne. xml . Role mapping
configuration is the same as that in normal security domain configurations.
< security-domain name="host" cache-type="default">
<authentication>
value="HTTP/something.com@ yourdomain.COM"/>
<module-option
184
name="storeKey" value="true"/>
<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.SAML2L
oginModule"
flag="required" />
</authentication>
< /security-domain>
Note
In case of using IBM JD K, options for Kerberos module are different. You must set the system
property jbo ss. securi ty. d i sabl e. secd o mai n. o pti o n to true. Refer to
Section 13.2.2, Configure Authentication in a Security D omain for details. Update the login
module to the following:
< login-module code="Kerberos" flag="required">

value="HTTP/something.com@ yourdomain.COM"/>
<module-option name="credsType" value="acceptor"/>
<module-option name="useKeytab" value="file:///root/keytab"/>
< /login-module>
Pro ced u re 13.6 . Verif y K erb ero s au t h en t icat io n set u p f o r Picket Lin k ID P
1. Start JBoss EAP server using $JBO SS_HO ME/bi n/stand al o ne. sh.
2. Setup your Kerberos system. There are a number of ways to do so. For example, using one of
the following options:
FreeIPA: there are multiple configuration options. You must choose the one that is suitable
to your setup.
ApacheD S
185
3. Setup your browser, for example Firefox, to use Kerberos. Follow the instructions provided
here: https://access.redhat.com/documentation/enUS/Red_Hat_Enterprise_Linux/5/html/D eployment_Guide/sso-config-firefox.html
4. Verify that you are able to access the http: //Y O UR _D O MAIN: 80 80 /empl o yee from
Firefox configured as mentioned above.
Report a bug
13.1.5. Login wit h Cert ificat e wit h Picket Link IDP

C o n f ig u re ID P t o Su p p o rt SSL
You can configure the PicketLink ID P to support SSL. The following procedure is an example
demonstrating how to configure a web application as an ID P supporting SSL client authentication.
There are two ways to configure the ID P to authenticate users:
If SSL is being used, the server will ask the client for a certificate and use this certificate to
authenticate the user.
If no certificate is provided by the client, a form-based authentication is performed.
Report a bug
1 3.1 .5 .1 . JBo ss EAP 6 .3 SSL Co nfigurat io n

The first thing you must do is create the certificates - the keystore and truststore that will be used
during the entire configuration procedure.
Pro ced u re 13.7. C reat e t h e cert if icat e, keyst o re, an d t ru st st o re f o r yo u r server
1. C reat e a C ert if icat e f o r Yo u r Server
Use the following command to create a certificate for your server:
keytool -genkey -alias server -keyalg RSA -keystore server.keystore
-storepass change_it -validity 365
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 D NS server name. For example, in
case of localhost you could use the following command:
keytool -genkey -alias server -keystore server.keystore -storepass
change_it -keypass password -dname
"CN=localhost,OU=QE,O=example.com,L=Brno,C=CZ"
2. C reat e t h e C lien t C ert if icat e
You will use this client certificate to authenticate against the server when accessing a
resource through SSL.
keytool -genkey -alias client -keystore client.keystore -storepass
change_it -validity 365 -keyalg RSA -keysize 2048 -storetype pkcs12
3. C reat e t h e T ru st st o re
186
Export the client's certificate and create a truststore by importing this certificate:
keytool -exportcert -keystore client.keystore -storetype pkcs12 storepass change_it -alias client -keypass change_it -file
client.keystore
keytool -import -file client.keystore -alias client -keystore
client.truststore
4. C h an g e t h e JB o ss EAP 6 .3 Server In st allat io n t o En ab le SSL
Add the following connector to the web subsystem to enable SSL:
<connector name="https" protocol="HTTP/1.1" scheme="https" socketbinding="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-certificatefile="${jboss.server.config.dir}/client.truststore"/>
</connector>
5. R est art t h e Server
Restart the server and verify that it is responding on: https://localhost:8443
6. T ru st t h e C ert if icat e
You will be prompted to trust the server certificate.
C o n f ig u re t h e C lien t C ert if icat e in yo u r B ro wser
Before accessing the application, you must import the cl i ent. keysto re to your browser. This file
holds the client certificate. When you access the application, the browser prompts you to select the
certificate you need to use to authenticate with the server. Select the desired certificate.
Secu rit y D o main C o n f ig u rat io n
Add the following security domain to your server installation. If you're in standalone mode, you must
add it to the JBO SS_HO ME/stand al o ne/co nfi g urati o n/stand al o ne. xml :
<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.RegExUserNam
eLoginModule" flag="optional">
<module-option name="regex" value="CN=(.*?),"/>
</login-module>
187
<login-module code="UsersRoles" flag="required">

<module-option name="usersProperties" value="users.properties"/>
<module-option name="rolesProperties" value="roles.properties"/>
</login-module>
</authentication>
<jsse keystore-password="change_it" keystoreurl="${jboss.server.config.dir}" truststore-password="change_it"
truststore-url="${jboss.server.config.dir}" client-auth="true"/>
</security-domain>
The configuration example above validates any provided certificate. If no certificate is provided or if
the authentication fails, the procedure falls back to a user/password based authentication.
R eg u lar Exp ressio n U ser N ame Lo g in Mo d u le
The Regular Expression User Name Login module can be used after Certificate Login Modules to
extract a username, UID or other field from the principal name so that roles can be obtained from
LD AP. The module has an option named reg ex which specifies the regular expression to be applied
to the principal name, the result of which is passed on to the subsequent login module.
In this example, an input principal name of UID = 0 0 7,
EMAILAD D R ESS= so methi ng @ so methi ng , C N= James Bo nd , O = SpyAg ency would result in
the output UID = 0 0 7.
Examp le 13.5. Examp le o f R eg u lar Exp ressio n U ser N ame Lo g in Mo d u le
< login-module
code="org.picketlink.identity.federation.bindings.jboss.auth.RegExUserN
ameLoginModule" flag="required">
<module-option name="regex" value="UID=(.*?),"/>
< /login-module>
For further details about regular expressions, see java. uti l . reg ex. P attern class
documentation at http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html.
Report a bug
13.2. Aut hent icat ion

13.2.1. About Aut hent icat ion
Authentication refers to identifying a subject and verifying the authenticity of the identification. The
most common authentication mechanism is a username and password combination. Other common
authentication mechanisms use shared keys, smart cards, or fingerprints. The outcome of a
successful authentication is referred to as a principal, in terms of Java Enterprise Edition declarative
security.
188
JBoss EAP 6 uses a pluggable system of authentication modules to provide flexibility and integration
with the authentication systems you already use in your organization. Each security domain
contains one or more configured authentication modules. Each module includes additional
configuration parameters to customize its behavior. The easiest way to configure the authentication
subsystem is within the web-based management console.
Authentication is not the same as authorization, although they are often linked. Many of the included
authentication modules can also handle authorization.
Report a bug
13.2.2. Configure Aut hent icat ion in a Securit y Domain

To configure authentication settings for a security domain, log into the management console and
follow this procedure.
Pro ced u re 13.8. Set u p Au t h en t icat io n Set t in g s f o r a Secu rit y D o main
1. O p en t h e secu rit y d o main ' s d et ailed view.
a. Click the C o nfi g urati o n label at the top of the management console.
b. Select the profile to modify from the P ro fi l e selection box at the top left of the Profile
view.
c. Expand the Securi ty menu, and select Securi ty D o mai ns.
d. Click the Vi ew link for the security domain you want to edit.
2. N avig at e t o t h e Au t h en t icat io n su b syst em co n f ig u rat io n .
Select the Authenti cati o n label at the top of the view if it is not already selected.
The configuration area is divided into two areas: Lo g i n Mo d ul es and D etai l s. The login
module is the basic unit of configuration. A security domain can include several login
modules, each of which can include several attributes and options.
3. Ad d an au t h en t icat io n mo d u le.
Click Ad d to add a JAAS authentication module. Fill in the details for your module.
The C o d e is the class name of the module. The Fl ag setting controls how the module relates
to other authentication modules within the same security domain.
Exp lan at io n o f t h e Flag s
The Java Enterprise Edition 6 specification provides the following explanation of the flags for
security modules. The following list is taken from
http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html#App
endixA. Refer to that document for more detailed information.
Flag
D et ails
required
The LoginModule is required to succeed. If it

succeeds or fails, authentication still
continues to proceed down the LoginModule
list.
189
Flag
D et ails
requisite
LoginModule is required to succeed. If it

succeeds, authentication continues down
the LoginModule list. If it fails, control
immediately returns to the application
(authentication does not proceed down the
LoginModule list).
The LoginModule is not required to succeed.
If it does succeed, control immediately
returns to the application (authentication
does not proceed down the LoginModule
list). If it fails, authentication continues down
the LoginModule list.
If it succeeds or fails, authentication still
list.
sufficient
optional
4. Ed it au t h en t icat io n set t in g s
After you have added your module, you can modify its C o d e or Fl ag s by clicking Ed i t in
the D etai l s section of the screen. Be sure the Attri butes tab is selected.
5. O p t io n al: Ad d o r remo ve mo d u le o p t io n s.
If you need to add options to your module, click its entry in the Lo g i n Mo d ul es list, and
select the Mo d ul e O pti o ns tab in the D etai l s section of the page. Click the Ad d button,
and provide the key and value for the option. Use the R emo ve button to remove an option.
R esu lt
Your authentication module is added to the security domain, and is immediately available to
applications which use the security domain.
T h e jbo ss. securi ty. securi ty_d o mai n Mo d u le O p t io n
By default, each login module defined in a security domain has the
jbo ss. securi ty. securi ty_d o mai n module option added to it automatically. This option
causes problems with login modules which check to make sure that only known options are defined.
The IBM Kerberos login module, co m. i bm. securi ty. auth. mo d ul e. Krb5Lo g i nMo d ul e is one
of these.
You can disable the behavior of adding this module option by setting the system property to true
when starting 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,
you can set system properties in the P ro fi l e section of the configuration. In a managed domain,
you can set system properties for each server group.
Report a bug
13.3. JAAS - Java Aut hent icat ion and Aut horiz at ion Service
190
13.3.1. About JAAS

JAAS is the Java Authentication and Authorization Service. It is part of the Java EE Spec, and allows
for pluggable 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) framework and 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 remain
independent from underlying authentication technologies, and allows the security manager to work
in different security infrastructures. Integration with a security infrastructure is achievable without
changing the security manager implementation. You need only change the configuration of the
authentication stack JAAS uses.
Refer to the Java EE JAAS D ocumentation for further information on JAAS.
The JBoss Enterprise Application Platform 6 security subsystem is based on the JAAS API.
Report a bug
13.3.2. JAAS Core Classes

The JAAS core classes can be broken down into three categories: common, authentication, and
authorization. The following list presents only the common and authentication classes because
these are the specific classes used to implement the functionality of the EAP security subsystem
covered in this chapter.
These are the common classes:
Subject (javax. securi ty. auth. Subject)
These are the authentication classes:
C o nfi g urati o n (javax. securi ty. auth. l o g i n. C o nfi g urati o n)
Lo g i nC o ntext (javax. securi ty. auth. l o g i n. Lo g i nC o ntext)
These are the associated interfaces:
P ri nci pal (java. securi ty. P ri nci pal )
C al l back (javax. securi ty. auth. cal l back. C al l back)
C al l backHand l er (javax. securi ty. auth. cal l back. C al l backHand l er)
Lo g i nMo d ul e (javax. securi ty. auth. spi . Lo g i nMo d ul e)
Report a bug
13.3.3. Subject and Principal classes

To authorize access to resources, applications must first authenticate the request's source. The JAAS
framework defines the term subject to represent a request's source. The Subject class is the central
class in JAAS. A Subject represents information for a single entity, such as a person or service. It
encompasses the entity's principals, public credentials, and private credentials. The JAAS API uses
the existing Java 2 java. securi ty. P ri nci pal interface to represent a principal, which is
essentially a typed name.
191
D uring the authentication process, a subject is populated with associated identities, or principals. A
subject may have many principals. For example, a person may have a name principal (John D oe), a
social security number principal (123-45-6789), and a user name principal (johnd), all of which help
distinguish the subject from other subjects. To retrieve the principals associated with a subject, two
methods are available:
p ublic Set getPrincipals() {...}

p ublic Set getPrincipals(Class c) {...}
g etP ri nci pal s() returns all principals contained in the subject. g etP ri nci pal s(C l ass c)
returns only those principals that are instances of class c or one of its subclasses. An empty set is
returned if the subject has no matching principals.
Note that the java. securi ty. acl . G ro up interface is a sub-interface of
java. securi ty. P ri nci pal , so an instance in the principals set may represent a logical
grouping of other principals or groups of principals.
Report a bug
13.3.4 . Subject Aut hent icat ion

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 Lo g i nC o ntext and passes in the name of the login
configuration and a C al l backHand l er to populate the C al l back objects, as required by
the configuration Lo g i nMo d ul es.
2. The Lo g i nC o ntext consults a C o nfi g urati o n to load all the Lo g i nMo d ul es included
in the named login configuration. If no such named configuration exists the o ther
configuration is used as a default.
3. The application invokes the Lo g i nC o ntext. l o g i n method.
4. The login method invokes each loaded Lo g i nMo d ul e. As each Lo g i nMo d ul e attempts to
authenticate the subject, it invokes the handle method on the associated C al l backHand l er
to obtain the information required for the authentication process. The required information is
passed to the handle method in the form of an array of C al l back objects. Upon success, the
Lo g i nMo d ul es associate relevant principals and credentials with the subject.
5. The Lo g i nC o ntext returns the authentication status to the application. Success is
represented by a return from the login method. Failure is represented through a
LoginException being thrown by the login method.
6. If authentication succeeds, the application retrieves the authenticated subject using the
Lo g i nC o ntext. g etSubject method.
7. After the scope of the subject authentication is complete, all principals and related
information associated with the subject by the l o g i n method can be removed by invoking
the Lo g i nC o ntext. l o g o ut method.
The Lo g i nC o ntext class provides the basic methods for authenticating subjects and offers a way
to develop an application that is independent of the underlying authentication technology. The
Lo g i nC o ntext consults a C o nfi g urati o n to determine the authentication services configured for
a particular application. Lo g i nMo d ul e classes represent the authentication services. Therefore,
192
you can plug different login modules into an application without changing the application itself. The
following code shows the steps required by an application to authenticate a subject.
C allbackHandler handler = new MyHandler();

LoginContext lc = new LoginContext("some-config", handler);
t ry {
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 info
t ry {
lc.logout();
} catch(LoginException e) {
System.out.println("logout failed");
e.printStackTrace();
/ / A sample MyHandler class

c lass 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");
}
D evelopers integrate with an authentication technology by creating an implementation of the
Lo g i nMo d ul e interface. This allows an administrator to plug different authentication technologies
into an application. You can chain together multiple Lo g i nMo d ul es to allow for more than one
authentication technology to participate in the authentication process. For example, one
Lo g i nMo d ul e may perform user name/password-based authentication, while another may interface
to hardware devices such as smart card readers or biometric authenticators.
193
The life cycle of a Lo g i nMo d ul e is driven by the Lo g i nC o ntext object against which the client
creates and issues the login method. The process consists of two phases. The steps of the process
are as follows:
The Lo g i nC o ntext creates each configured Lo g i nMo d ul e using its public no-arg
constructor.
Each Lo g i nMo d ul e is initialized with a call to its initialize method. The Subject argument is
guaranteed to be non-null. The signature of the initialize method is: publ i c vo i d
i ni ti al i ze(Subject subject, C al l backHand l er cal l backHand l er, Map
shared State, Map o pti o ns)
The l o g i n method is called to start the authentication process. For example, a method
implementation might prompt the user for a user name and password and then verify the
information against data stored in a naming service such as NIS or LD AP. Alternative
implementations might interface to smart cards and biometric devices, or simply extract user
information from the underlying operating system. The validation of user identity by each
Lo g i nMo d ul e is considered phase 1 of JAAS authentication. The signature of the l o g i n
method is bo o l ean l o g i n() thro ws Lo g i nExcepti o n . A Lo g i nExcepti o n indicates
failure. A return value of true indicates that the method succeeded, whereas a return value of false
indicates that the login module should be ignored.
If the Lo g i nC o ntext's overall authentication succeeds, co mmi t is invoked on each
Lo g i nMo d ul e. If phase 1 succeeds for a Lo g i nMo d ul e, then the commit method continues
with phase 2 and associates the relevant principals, public credentials, and/or private credentials
with the subject. If phase 1 fails for a Lo g i nMo d ul e, then co mmi t removes any previously
stored authentication state, such as user names or passwords. The signature of the co mmi t
method is: bo o l ean co mmi t() thro ws Lo g i nExcepti o n . Failure to complete the commit
phase is indicated by throwing a Lo g i nExcepti o n. A return of true indicates that the method
succeeded, whereas a return of false indicates that the login module should be ignored.
If the Lo g i nC o ntext's overall authentication fails, then the abo rt method is invoked on each
Lo g i nMo d ul e. The abo rt method removes or destroys any authentication state created by the
login or initialize methods. The signature of the abo rt method is bo o l ean abo rt() thro ws
Lo g i nExcepti o n . Failure to complete the abo rt phase is indicated by throwing a
Lo g i nExcepti o n. A return of true indicates that the method succeeded, whereas a return of
false indicates that the login module should be ignored.
To remove the authentication state after a successful login, the application invokes l o g o ut on
the Lo g i nC o ntext. This in turn results in a l o g o ut method invocation on each
Lo g i nMo d ul e. The l o g o ut method removes the principals and credentials originally
associated with the subject during the co mmi t operation. Credentials should be destroyed upon
removal. The signature of the l o g o ut method is: bo o l ean l o g o ut() thro ws
Lo g i nExcepti o n . Failure to complete the logout process is indicated by throwing a
Lo g i nExcepti o n. A return of true indicates that the method succeeded, whereas a return of
false indicates that the login module should be ignored.
When a Lo g i nMo d ul e must communicate with the user to obtain authentication information, it uses
a C al l backHand l er object. Applications implement the CallbackHandler interface and pass it to
the Lo g i nC o ntext, which send the authentication information directly to the underlying login
modules.
Login modules use the C al l backHand l er both to gather input from users, such as a password or
smart card PIN, and to supply information to users, such as status information. By allowing the
application to specify the C al l backHand l er, underlying Lo g i nMo d ul es remain independent
from the different ways applications interact with users. For example, a C al l backHand l er's
194
implementation for a GUI application might display a window to solicit user input. On the other hand,
a C al l backHand l er implementation for a non-GUI environment, such as an application server,
might simply obtain credential information by using an application server API. The CallbackHandler
interface has one method to implement:
v oid handle(Callback[] callbacks)
throws java.io.IOException,
UnsupportedCallbackException;
The C al l back interface is the last authentication class we will look at. This is a tagging interface for
which several default implementations are provided, including the NameC al l back and
P asswo rd C al l back used in an earlier example. A Lo g i nMo d ul e uses a C al l back to request
information required by the authentication mechanism. Lo g i nMo d ul es pass an array of
C al l backs directly to the C al l backHand l er. hand l e method during the authentication's login
phase. If a cal l backhand l er does not understand how to use a C al l back object passed into the
handle method, it throws an Unsuppo rted C al l backExcepti o n to abort the login call.
Report a bug
13.4 . Java Aut hent icat ion SPI for Cont ainers (JASPI)
13.4 .1. About Java Aut hent icat ion SPI for Cont ainers (JASPI) Securit y
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=196 for details about the specification.
Report a bug
13.4 .2. Configure Java Aut hent icat ion SPI for Cont ainers (JASPI) Securit y
To authenticate against a JASPI provider, add a <authenti cati o n-jaspi > element to your
security domain. The configuration is similar to a standard authentication module, but login module
elements are enclosed in a <l o g i n-mo d ul e-stack> element. The structure of the configuration is:
Examp le 13.6 . St ru ct u re o f t h e authenti cati o n-jaspi elemen t
< 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>
The login module itself is configured in exactly the same way as a standard authentication module.
195
Because the web-based management console does not expose the configuration of JASPI
authentication modules, you need to stop JBoss EAP 6 completely before adding the configuration
directly to EAP_HOME/d o mai n/co nfi g urati o n/d o mai n. xml or
EAP_HOME/stand al o ne/co nfi g urati o n/stand al o ne. xml .
Report a bug
13.5. Aut horiz at ion

13.5.1. About Aut horiz at ion
Authorization is a mechanism for granting or denying access to a resource based on identity. It is
implemented 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 can contain
one or more authorization policies. Each policy has a basic module which defines its behavior. It is
configured through specific flags and attributes. The easiest way to configure the authorization
subsystem is by using the web-based management console.
Authorization is different from authentication, and usually happens after authentication. Many of the
authentication modules also handle authorization.
Report a bug
13.5.2. Configure Aut horiz at ion in a Securit y Domain

To configure authorization settings for a security domain, log into the management console and
Pro ced u re 13.9 . Set u p Au t h o riz at io n in a Secu rit y D o main
b. In a managed domain, select the profile to modify from the P ro fi l e drop down box
at the top left.
c. Expand the Securi ty menu item, and select Securi ty D o mai ns.
d. Click the Vi ew link for the security domain you want to edit.
2. N avig at e t o t h e Au t h o riz at io n su b syst em co n f ig u rat io n .
Select the Autho ri zati o n label at the top of the screen.
The configuration area is divided into two areas: P o l i ci es and D etai l s. The login
module is the basic unit of configuration. A security domain can include several
authorization policies, each of which can include several attributes and options.
3. Ad d a p o licy.
Click Ad d to add a JAAS authorization policy module. Fill in the details for your module.
The C o d e is the class name of the module. The Fl ag controls how the module relates to
other authorization policy modules within the same security domain.
196
Exp lan at io n o f t h e Flag s

The Java Enterprise Edition 6 specification provides the following explanation of the flags for
security modules. The following list is taken from
http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html#App
endixA. Refer to that document for more detailed information.
Flag
D et ails
required
The LoginModule is required to succeed. If it

succeeds or fails, authorization still
list.
LoginModule is required to succeed. If it
succeeds, authorization continues down the
LoginModule list. If it fails, control
immediately returns to the application
(authorization does not proceed down the
LoginModule list).
If it does succeed, control immediately
returns to the application (authorization
does not proceed down the LoginModule
list). If it fails, authorization continues down
the LoginModule list.
If it succeeds or fails, authorization still
list.
requisite
sufficient
optional
4. Ed it au t h o riz at io n set t in g s
After you have added your module, you can modify its C o d e or Fl ag s by clicking Ed i t in
the D etai l s section of the screen. Be sure the Attri butes tab is selected.
5. O p t io n al: Ad d o r remo ve mo d u le o p t io n s.
If you need to add options to your module, click its entry in the P o l i ci es list, and select the
Mo d ul e O pti o ns tab in the D etai l s section of the page. Click Ad d and provide the key
and value for the option. Use the R emo ve button to remove an option.
R esu lt
Your authorization policy module is added to the security domain, and is immediately available to
Report a bug
13.6. Java Aut horiz at ion Cont ract for Cont ainers (JACC)
13.6.1. About Java Aut horiz at ion Cont ract for Cont ainers (JACC)
Java Authorization Contract for Containers (JACC) is a standard which defines a contract between
containers and authorization service providers, which results in the implementation of providers for
use by containers. It was defined in JSR-115, which can be found on the Java Community Process
website at http://jcp.org/en/jsr/detail?id=115. It has been part of the core Java Enterprise Edition (Java
197
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
13.6.2. Configure Java Aut horiz at ion Cont ract for Cont ainers (JACC) Securit y
To configure Java Authorization Contract for Containers (JACC), you need to configure your security
domain with the correct module, and then modify your jbo ss-web. xml to include the correct
parameters.
Ad d JAC C Su p p o rt t o t h e Secu rit y D o main
To add JACC support to the security domain, add the JAC C authorization policy to the authorization
stack of the security domain, with the req ui red flag set. The following is an example of a security
domain with JACC support. However, the security domain is configured in the Management Console
or Management CLI, rather than directly in the XML.
< security-domain name="jacc" cache-type="default">
<authentication>
</login-module>
</authentication>
<authorization>
<policy-module code="JACC" flag="required"/>
</authorization>
< /security-domain>
C o n f ig u re a Web Ap p licat io n t o U se JAC C
The jbo ss-web. xml is located in the WEB-INF/ directory of your deployment, and contains
overrides and additional JBoss-specific configuration for the web container. To use your JACCenabled security domain, you need to include the <securi ty-d o mai n> element, and also set the
<use-jbo ss-autho ri zati o n> element to true. The following application is properly configured
to use the JACC security domain above.
< jboss-web>
<security-domain>jacc</security-domain>
<use-jboss-authorization>true</use-jboss-authorization>
< /jboss-web>
C o n f ig u re an EJB Ap p licat io n t o U se JAC C
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 <metho d -permi ssi o n> elements contain
information about JACC roles. Refer to the example configuration for more details. The
EJBMetho d P ermi ssi o n class is part of the Java Enterprise Edition 6 API, and is documented at
http://docs.oracle.com/javaee/6/api/javax/security/jacc/EJBMethodPermission.html.
Examp le 13.7. Examp le JAC C Met h o d Permissio n s in an EJB
198
< ejb-jar>
<method-permission>
<description>The employee and temp-employee roles may access any

<method>
</method>
< /ejb-jar>
You can also constrain the authentication and authorization mechanisms for an EJB by using a
security domain, just as you can do for a web application. Security domains are declared in the
jbo ss-ejb3. xml descriptor, in the <securi ty> child element. In addition to the security domain,
you can also specify the run-as principal, which changes the principal the EJB runs as.
Examp le 13.8. Examp le Secu rit y D o main D eclarat io n in an EJB

< ejb-jar>
<security>
<ejb-name>*</ejb-name>
<security-domain>myDomain</security-domain>
<run-as-principal>myPrincipal</run-as-principal>
</security>
< /ejb-jar>
Report a bug
13.6.3. Fine Grained Aut horiz at ion Using XACML

1 3.6 .3.1 . Abo ut Fine Graine d Aut ho rizat io n and XACML
Fine Grained Authorization caters to the changing requirements and multiple variables involved in
the decision 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 standards
based solution to the complex nature of achieving Fine Grained Authorization. XACML defines a
policy language and an architecture for decision making. The XACML architecture includes a Policy
Enforcement Point (PEP), which intercepts any requests in a normal program flow, then asks a Policy
D ecision Point (PD P) to make an access decision based on the policies associated with the PD P.
The PD P evaluates the XACML request created by the PEP and runs through the policies to make
one of the following access decisions:
PERMIT - The access is approved.
199
D ENY - The access is denied.

IND ETERMINATE - There is an error at the PD P.
NOTAPPLICABLE - There is some attribute missing in the request or there is no policy match.
The following are the features of the XACML:
Oasis XACML v2.0 library
JAXB v2.0 based object model
ExistD B Integration for storing/retrieving XACML Policies and Attributes
Report a bug
1 3.6 .3.2 . Co nfigure XACML fo r Fine Graine d Aut ho rizat io n

The following is the procedure to configure XACML.
Pro ced u re 13.10. C o n f ig u re XAC ML
1. D ownload the library which is a single jar file.
2. C reat e o n e o r mo re p o licy f iles f o r XAC ML
Under the WEB-INF/cl asses, create a po l i ci es directory to save all your policies.
Create a po l i cyC o nfi g . xml under WEB-INF/cl asses directory.
The following are the two types of policy sets can be defined:
Role Permission Policy Sets (RPS)
Permission Policy Sets (PPS)
Examp le 13.9 . R o le Permissio n Po licy Set s ( R PS)

Emp lo yee
<PolicySet
xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os"
PolicySetId="RPS:employee:role"
PolicyCombiningAlgId="urn:oasis:names:tc:xacml:1.0:policycombining-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</Attr
ibuteValue>
<SubjectAttributeDesignator
AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role"
DataType="http://www.w3.org/2001/XMLSchema#anyURI"/>
200
</SubjectMatch>
</Subject>
</Subjects>
</Target>

<PolicySetIdReference>PPS:employee:role</PolicySetIdReference>
</PolicySet>
Man ag er
<PolicySet xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os"
PolicySetId="RPS:manager:role"
<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</Attri
buteValue>
<SubjectAttributeDesignator
DataType="http://www.w3.org/2001/XMLSchema#anyURI"/>
</SubjectMatch>
</Subject>
</Subjects>
</Target>

<PolicySetIdReference>PPS:manager:role</PolicySetIdReference>
</PolicySet>
Examp le 13.10. Permissio n Po licy Set s ( PPS)

Emp lo yee
<PolicySet
xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os"
PolicySetId="PPS:employee:role"
<Target />

<Policy
PolicyId="Permissions:specifically:for:the:employee:role"
RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combiningalgorithm:permit-overrides">
<Target />

<Rule RuleId="Permission:to:create:a:purchase:order"
201
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
<AttributeValue
DataType="http://www.w3.org/2001/XMLSchema#string">create</Attrib
uteValue>
<ActionAttributeDesignator
AttributeId="urn:action-id"
</ActionMatch>
</Action>
</Actions>
</Target>
</Rule>
</Policy>

<Policy
PolicyId="Permission:to:have:employee:role:permissions"
RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rulecombining-algorithm:permit-overrides">
<Target />

<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</Attr
ibuteValue>
DataType="http://www.w3.org/2001/XMLSchema#anyURI" />
</Apply>
202
<Apply
<AttributeValue
DataType="http://www.w3.org/2001/XMLSchema#anyURI">urn:oasis:name
s:tc:xacml:2.0:actions:hasPrivilegesOfRole
</AttributeValue>
AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id"
</Apply>
</Apply>
</Condition>
</Rule>
</Policy>
</PolicySet>
Man ag er
<PolicySet xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os"
PolicySetId="PPS:manager:role"
<Target />

<Policy
PolicyId="Permissions:specifically:for:the:manager:role"
RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combiningalgorithm:permit-overrides">
<Target />

<Rule RuleId="Permission:to:sign:a:purchase:order"
Effect="Permit">
<Target>
<Resources>
<Resource>
<ResourceMatch
<AttributeValue
DataType="http://www.w3.org/2001/XMLSchema#string">purchase order
</AttributeValue>
AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id"
</ResourceMatch>
</Resource>
</Resources>
<Actions>
<Action>
<ActionMatch
203
<AttributeValue
DataType="http://www.w3.org/2001/XMLSchema#string">sign</Attribut
eValue>
AttributeId="urn:action-id"
</ActionMatch>
</Action>
</Actions>
</Target>
</Rule>
</Policy>

<Policy
PolicyId="Permission:to:have:manager:role:permissions"
RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rulecombining-algorithm:permit-overrides">
<Target />

<Rule RuleId="Permission:to:have:manager:permissions"
Effect="Permit">
<Condition>
<Apply
FunctionId="urn:oasis:names:tc:xacml:1.0:function:and">
<Apply
<AttributeValue
DataType="http://www.w3.org/2001/XMLSchema#anyURI">manager</Attri
buteValue>
</Apply>
<Apply
<AttributeValue
DataType="http://www.w3.org/2001/XMLSchema#anyURI">urn:oasis:name
s:tc:xacml:2.0:actions:hasPrivilegesOfRole
</AttributeValue>
</Apply>
</Apply>
</Condition>
</Rule>
</Policy>

<login-module code="SPNEGO" flag="requisite">
<module-option name="serverSecurityDomain" value="host"/>
</login-module>

value="useFirstPass" />
<module-option name="usersProperties" value="spnegousers.properties" />
<module-option name="rolesProperties" value="spnegoroles.properties" />
</login-module>
</authentication>
< /security-domain>
3. Sp ecif y t h e secu rit y- co n st rain t an d lo g in - co n f ig in t h e web. xml
The web. xml descriptor contain information about security constraints and login
configuration. The following are example values for each.
< security-constraint>
<display-name>Security Constraint on Conversation</display-name>
<web-resource-name>examplesWebApp</web-resource-name>
<auth-constraint>
<role-name>RequiredRole</role-name>
</auth-constraint>
220
< /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>
4. Sp ecif y t h e secu rit y d o main an d o t h er set t in g s in t h e jbo ss-web. xml d escrip t o r.
Specify the name of the client-side security domain (the second one in this example) in the
jbo ss-web. xml descriptor of your deployment, to direct your application to use this
security domain.
You can no longer override authenticators directly. Instead, you can add the
NegotiationAuthenticator as a valve to your jbo ss-web. xml descriptor, if you need to. The
<jacc-star-ro l e-al l o w> allows you to use the asterisk (*) character to match multiple
role names, and is optional.
< jboss-web>
<valve>
<classname>org.jboss.security.negotiation.NegotiationAuthenticator</class
-name>
</valve>
<jacc-star-role-allow>true</jacc-star-role-allow>
< /jboss-web>
5. Ad d a d ep en d en cy t o yo u r ap p licat io n ' s MANIFEST . MF, t o lo cat e t h e N eg o t iat io n
classes.
The web application needs a dependency on class o rg . jbo ss. securi ty. neg o ti ati o n
to be added to the deployment's MET A-INF/MANIFEST . MF manifest, in order to locate the
JBoss Negotiation classes. The following shows a properly-formatted entry.
Build-Jdk: 1.6.0_24
Dependencies: org.jboss.security.negotiation
A. As an alternative, add a dependency to your application by editing the MET AINF/jbo ss-d epl o yment-structure. xml file:
< ?xml version="1.0" encoding="UTF-8"?>
< jboss-deployment-structure>
<deployment>
<dependencies>
221
<module name='org.jboss.security.negotiation'/>
</dependencies>
</deployment>
< /jboss-deployment-structure>
R esu lt
Your web application accepts and authenticates credentials against your Kerberos, Microsoft Active
D irectory, or other SPNEGO-compatible directory service. If the user runs the application from a
system which is already logged into the directory service, and where the required roles are already
applied to the user, the web application does not prompt for authentication, and SSO capabilities are
achieved.
Report a bug
14 .9. Configure SPNEGO Fall Back t o Form Aut hent icat ion
Follow the procedure below to setup a SPNEGO fall back to form authentication.
Pro ced u re 14 .2. SPN EG O secu rit y wit h f all b ack t o f o rm au t h en t icat io n
1. Set u p SPN EG O
Refer the procedure described in Section 14.8, Configure Kerberos or Microsoft Active
D irectory D esktop SSO for Web Applications
2. Mo d if y web. xml
Add a l o g i n-co nfi g element to your application and setup the login and error pages in
web.xml:
<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>
</login-config>
3. Ad d web co n t en t
Add references of l o g i n. html and erro r. html to web. xml . These files are added to web
application archive to the place specified in fo rm-l o g i n-co nfi g configuration. For more
information refer Enable Form-based Authentication section in the Security Guide for JBoss EAP
6. A typical l o g i n. html looks like this:
<html>
<head>
<title>Vault Form Authentication</title>
</head>
<body>
<h1>Vault Login Page</h1>
<p>
222
<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>
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 browser sends an
NTLM token.
Report a bug
223
Chapter 15. Single Sign-On with SAML

15.1. About Securit y T oken Service (ST S)
The Security Token Service generates and manages the security tokens. It does not issue tokens of a
specific 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 for each 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
KeySto re. g etInstance("P KC S11") calls and the key and trust store are initialized.
Configuration for this new support is beyond the scope of EAP documentation. Users who
wish to utilize this feature should familiarize themselves with the correct installation of
PKCS#11 hardware and software as well as the correct entries required in the
java. securi ty policy file. Oracle's Java PKCs#11 Reference Guide document may be a
useful resource for this information.
The token request message is sent in the body of the SOAP message. All information related to the
token request is enclosed in the R eq uestSecuri tyT o ken element. The sample request contains
two other WS-Trust elements: R eq uestT ype, which specifies that this request is an Issue request,
and T o kenT ype, which specifies the type of the token to be issued.
The following is an example of the WS-Trust request message.
Examp le 15.1. WS- T ru st secu rit y t o ken req u est messag e

<S11:Envelope xmlns:S11=".." xmlns:wsu=".." xmlns:wst="..">
<S11:Header>
...
</S11:Header>
<S11:Body wsu:Id="body">
<wst:RequestSecurityToken Context="context">
224
Chapt er 1 5. Single Sign- O n wit h SAML
<wst:TokenType>http://www.tokens.org/SpecialToken</wst:TokenType>
<wst:RequestType>
http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
</wst:RequestType>
</wst:RequestSecurityToken>
</S11:Body>
</S11:Envelope>
The following is an example of a security token response.
Examp le 15.2. Secu rit y t o ken resp o n se messag e

<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>
In the example for the security token response, the T o kenT ype element specifies the type of the
issued token, while the R eq uested Securi tyT o ken element contains the token itself. The format of
the token depends on the type of the token. The Li feti me element specifies when the token was
created and when it expires.
Secu rit y T o ken R eq u est Pro cessin g
The following are the steps in which the security token requests are processed:
A client sends a security token request to P i cketLi nkST S.
P i cketLi nkST S parses the request message, generating a JAXB object model.
P i cketLi nkST S reads the configuration file and creates the ST SC o nfi g urati o n object, if
needed. Then it obtains a reference to the WST rustR eq uestHand l er from the configuration and
delegates the request processing to the handler instance.
The request handler uses the ST SC o nfi g urati o n to set default values when needed (for
example, when the request doesn't specify a token lifetime value).
The WST rustR eq uestHand l er creates the WST rustR eq uestC o ntext, setting the JAXB request
object and the caller principal it received from P i cketLi nkST S.
The WST rustR eq uestHand l er uses the ST SC o nfi g urati o n to get the
Securi tyT o kenP ro vi d er that must be used to process the request based on the type of the
token that is being requested. Then it invokes the provider, passing the constructed
WST rustR eq uestC o ntext as a parameter.
225
The Securi tyT o kenP ro vi d er instance process the token request and stores the issued token
in the request context.
The WST rustR eq uestHand l er obtains the token from the context, encrypts it if needed, and
constructs the WS-Trust response object containing the security token.
P i cketLi nkST S dictates the response generated by the request handler and returns it to the
client.
Report a bug
15.2. Configure Securit y T oken Service (ST S)

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
some properties via configuration. All STS configurations are specified in the pi cketl i nk. xml file,
which belongs in the WEB-INF directory of the deployed application. The following are the elements
that can be configured in the pi cketl i nk. xml file.
Note
In the following text, a service provider refers to the Web service that requires a security token to
be presented by its clients.
P i cketLi nkST S: This is the root element. It defines some properties that allows the STS
administrator to set a the following default values:
ST SName: A string representing the name of the security token service. If not specified, the
default P i cketLi nkST S value is used.
T o kenT i meo ut: The token lifetime value in seconds. If not specified, the default value of 3600
(one hour) is used.
EncryptT o ken: A boolean specifying whether issued tokens are to be encrypted or not. The
default value is false.
KeyP ro vi d er: This element and all its sub elements are used to configure the keystore that are
used by PicketLink STS to sign and encrypt tokens. Properties like the keystore location, its
password, and the signing (private key) alias and password are all configured in this section.
R eq uestHand l er: This element specifies the fully qualified name of the
WST rustR eq uestHand l er implementation to be used. If not specified, the default
o rg . pi cketl i nk. i d enti ty. fed erati o n. co re. wstrust. Stand ard R eq uestHand l er is
used.
T o kenP ro vi d er: This section specifies the T o kenP ro vi d er implementations that must be
used to handle each type of security token. In the example we have two providers - one that
handles tokens of type Speci al T o ken and one that handles tokens of type SAMLV2. 0 . The
WST rustR eq uestHand l er calls the g etP ro vi d erFo rT o kenT ype(String type) method of
ST SC o nfi g urati o n to obtain a reference to the appropriate T o kenP ro vi d er.
T o kenT i meo ut: This is used by the WST rustR eq uestHand l er when no Lifetime has been
specified in the WS-Trust request. It creates a Lifetime instance that has the current time as the
creation time and expires after the specified number of seconds.
226
Servi ceP ro vi d ers: This section specifies the token types that must be used for each service
provider (the Web service that requires a security token). When a WS-Trust request does not
contain the token type, the WST rustR eq uestHand l er must use the service provider endpoint to
find out the type of the token that must be issued.
EncryptT o ken: This is used by the WST rustR eq uestHand l er to decide if the issued token
must be encrypted or not. If true, the public key certificate (PKC) of the service provider is used to
encrypt the token.
The following is an example of STS configuration.
Examp le 15.3. ST S C o n f ig u rat io n

<PicketLinkSTS xmlns="urn:picketlink:identity-federation:config:1.0"
STSName="Test STS" TokenTimeout="7200" EncryptToken="true">
<KeyProvider
ClassName="org.picketlink.identity.federation.bindings.tomcat.KeyStoreK
eyManager">
<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.Standa
rdRequestHandler</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.s
aml.SAML20TokenProvider"
TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-tokenprofile-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-profile1.1#SAMLV2.0"
TruststoreAlias="service2"/>
</ServiceProviders>
</PicketLinkSTS>
Report a bug
15.3. About Picket Link ST S Login Modules

227
A PicketLink Login Module is typically configured as part of the security setup of a JEE container to
use a Security Token Service for authenticating users. The STS may be collocated on the same
container as the Login Module or be accessed remotely through Web Service calls or another
technology. PicketLink Login Modules support non-PicketLink STS implementations through
standard WS-Trust calls.
T yp es o f ST S Lo g in Mo d u les
The following are the different types of STS Login Modules.
ST SIssu in g Lo g in Mo d u le
Calls the configured STS and requests for a security token. Upon successfully receiving the
R eq uested Securi tyT o ken, it marks the authentication as successful.
A call to STS typically requires authentication. This Login Module uses credentials from one of the
following sources:
Its properties file, if the useO pti o nsC red enti al s module option is set to true.
Previous login module credentials if the passwo rd -stacki ng module option is set to
useFi rstP ass.
From the configured C al l backHand l er by supplying a Name and Password Callback.
Upon successful authentication, the Saml C red enti al is inserted in the Subject's public
credentials if one with the same Assertion is not found to be already present there.
ST SValid at in g Lo g in Mo d u le
Calls the configured STS and validates an available security token.
A call to STS typically requires authentication. This Login Module uses credentials from one of the
following sources:
Its properties file, if the useO pti o nsC red enti al s module option is set to true.
Previous login module credentials if the passwo rd -stacki ng module option is set to
useFi rstP ass.
From the configured C al l backHand l er by supplying a Name and Password Callback.
Upon successful authentication, the SamlCredential is inserted in the Subject's public credentials
if one with the same Assertion is not found to be already present there.
SAML2ST SLo g in Mo d u le
This Login Module supplies a O bjectC al l back to the configured C al l backHand l er and
expects a Saml C red enti al 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 stacked on
top of another Login Module that is successfully authenticated.
Upon successful authentication, the Saml C red enti al is inspected for a NameID and a multivalued role attribute that is respectively set as the ID and roles of the user.
SAML2Lo g in Mo d u le
228
This login module is used in conjunction with other components for SAML authentication and
performs no authentication itself.
The SP R ed i rectFo rmAuthenti cato r uses this login module in PicketLink's implementation of
the SAML v2 HTTP Redirect Profile.
The Tomcat authenticator valve performs authentication through redirecting to the identity
provider and getting a SAML assertion.
This login module is used to pass the user ID and roles to the JBoss security framework to be
populated in the JAAS subject.
Report a bug
15.4 . Configure ST SIssuingLoginModule

The ST SIssui ng Lo g i nMo d ul e uses a user name and password to authenticate the user against
an STS by retrieving a token.
Examp le 15.4 . C o n f ig u re ST SIssu in g Lo g in Mo d u le

<security-domain name="saml-issue-token">
<authentication>
<login-module
code="org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLo
ginModule" 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.ST
SPrincipalMappingProvider"
type="principal" />
<mapping-module
SGroupMappingProvider"
type="role" />
</mapping>
</security-domain>
Most configurations can switch to the configuration sited in the above example by:
changing their declared security-domain
specifying a Principal mapping provider
specifying a RoleGroup mapping provider
229
The specified Principal mapping provider and the RoleGroup mapping provider results in an
authenticated Subject being populated that enables coarse-grained and role-based authorization.
After authentication, the Security Token is available and may be used to invoke other services by
Single Sign-On.
Report a bug
15.5. Configure ST SValidat ingLoginModule

The STSValidatingLoginModule uses a TokenCallback to ask the configured CallbackHandler an
STS by retrieving a token.
Examp le 15.5. C o n f ig u re ST SValid at in g Lo g in Mo d u le

<security-domain name="saml-validate-token">
<authentication>
<login-module
code="org.picketlink.identity.federation.core.wstrust.auth.STSValidatin
gLoginModule" flag="required">
<module-option name="configFile">./picketlink-stsclient.properties</module-option>
<module-option
name="endpointURI">http://security_saml/endpoint</module-option>
</login-module>
</authentication>
<mapping>
<mapping-module
SPrincipalMappingProvider"
type="principal" />
<mapping-module
SGroupMappingProvider"
type="role" />
</mapping>
</security-domain>
The configuration cited in the example enables Single Sign-On for your applications and services. A
token once issued, either by directly contacting the STS or through a token-issuing login module,
can be used to authenticate against multiple applications and services by employing the setup
provided in the example. Providing a Principal mapping provider and a RoleGroup mapping
provider result in an authenticated Subject being populated that enables coarse-grained and rolebased authorization. After authentication, the Security Token is available and can be used to invoke
other services by Single Sign-On.
Report a bug
15.6. ST S Client Pooling
230
The PicketLink provides a pool of STS clients on the server. This removes STS Client creation as a
bottleneck.
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
i ni ti al NumberO fC l i ents login module option.
The STSClientPoolFactory class
o rg . pi cketl i nk. i d enti ty. fed erati o n. bi nd i ng s. stspo o l . ST SC l i entP o o l Facto ry
provides client pool functionality to applications.
Using ST SClient PoolFact ory

STS clients are inserted into sub pools using their configuration as a key. Obtain STSClientPool
instance and then initialize a sub pool based on configuration, optionally with initial number of STS
clients or rely on default number.
final STSClientPool pool = STSClientPoolFactory.getPoolInstance();

p ool.createPool(20, stsClientConfig);
final STSClient client = pool.getClient(stsClientConfig);
When you are done with a client, you can return it to the pool like so:
pool.returnClient();
To check if a subpool already exists for a given configuration:
if (! pool.configExists(stsClientConfig) {
pool.createPool(stsClientConfig);
}
When the PicketLink Federation subsystem is enabled, all client pools created for a deployment are
destroyed automatically during the undeploy process. To manually destroy a pool:
pool.destroyPool(stsClientConfig);
Report a bug
15.7. SAML Web Browser Based SSO

15.7.1. About SAML Web Browser Based SSO
PicketLink in JBoss EAP provides a platform to implement federated identity based services. This
includes centralized identity services and Single Sign-On (SSO) for applications.
231
The SAML profile has support for both the HTTP/POST and the HTTP/Redirect bindings with
centralized identity services to enable web SSO for your applications. The architecture for the SAML
v2 based Web SSO follows the hub and spoke architecture of identity management. In this
architecture an identity provider (ID P) 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 ID P, the ID P does not distinguish
between the different SPs. If you make requests to different SPs that point to the same ID P, the
ID P handles the most recent request from an SP and sends back SAML assertion about the
authenticated user. To get back to the an older SP request, you will need to reenter the SP URL
in the browser.
Report a bug
15.7.2. Set up 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 an
end 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 about a
user via an electronic user credential, leaving the service provider to manage access control and
dissemination based on a trusted set of user credential assertions.
Report a bug
15.7.3. Configure Ident it y Provider

The Identity Provider (ID P) is a JBoss EAP server instance.
Pro ced u re 15.1. C o n f ig u re Id en t it y Pro vid er ( ID P)
1. C o n f ig u re t h e web ap p licat io n secu rit y f o r t h e ID P
Configure a web application as the Identity provider.
Note
The use of FORM based web application security is recommended as it gives you the
ability to customize the login page.
The following is an example of the web. xml configuration
Examp le 15.6 . web. xml C o n f ig u rat io n f o r ID P

<display-name>IDP</display-name>
<description>IDP</description>
232

<web-resource-name>Images</web-resource-name>
<url-pattern>/images/*</url-pattern>

<web-resource-name>IDP</web-resource-name>
<auth-constraint>
<role-name>manager</role-name>
</auth-constraint>

<login-config>
<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>
</login-config>

<security-role>
<description>
The role that is required to log in to the IDP Application
</description>
</security-role>
</web-app>
2. C reat e Secu rit y D o main f o r ID P

Create a Security D omain with authentication and authorization mechanisms defined for the
ID P. Refer to Section 13.9, Use a Security D omain in Your Application for further details.
3. C o n f ig u re t h e ID P Valves
Create a jbo ss-web. xml file in the WEB-INF directory of your ID P web application to
configure the valves for the ID P. The following is an example of jbo ss-web. xml file.
Examp le 15.7. jbo ss-web. xml File C o n f ig u rat io n f o r ID P Valves

<jboss-web>
<security-domain>idp</security-domain>
<context-root>idp</context-root>
<valve>
<class-
233
name>org.picketlink.identity.federation.bindings.tomcat.idp.IDPWe
bBrowserSSOValve</class-name>
</valve>
</jboss-web>
4. C o n f ig u re t h e Picket Lin k C o n f ig u rat io n File ( pi cketl i nk. xml )

The following is an example of pi cketl i nk. xml configuration. In this configuration file
you provide the URL that gets added as the issuer in the outgoing SAML2 assertions to the
service providers and the ID P.
Examp le 15.8. pi cketl i nk. xml C o n f ig u rat io n

<PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
<PicketLinkIDP xmlns="urn:picketlink:identityfederation:config:2.1">
<IdentityURL>http://localhost:8080/idp/</IdentityURL>
</PicketLinkIDP>
<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.SAML
2IssuerTrustHandler" />
<Handler
2LogOutHandler" />
<Handler
2AuthenticationHandler" />
<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.Role
sGenerationHandler" />
</Handlers>
</PicketLink>
By default, pi cketl i nk. xml is located in the WEB-INF directory of your ID P web
application. However, you can configure a custom path to a pi cketl i nk. xml that is
external to the application:
a. O p t io n al: C o n f ig u rin g a cu st o m p at h t o pi cketl i nk. xml
Add two paramaters to the valve element in your application's WEB-INF/jbo ssweb. xml : co nfi g Fi l e specifying for the path to pi cketl i nk. xml , and
ti merInterval which specifies the interval in milliseconds to reload the
configuration. For example:
<valve>
<class-name>...</class-name>
<param>
<param-name>timerInterval</param-name>
<param-value>5000</param-value>
</param>
<param>
234
<param-name>configFile</param-name>
<param-value>path-to/picketlink.xml</param-value>
</param>
</valve>
5. D eclare d ep en d en cies o n Picket Lin k mo d u le ( MET A-INF/MANIFEST . MF, o r jbo ssd epl o yment-structure. xml )
The web application also requires a dependency defining in MET A-INF/MANIFEST . MF or
jbo ss-d epl o yment-structure. xml , so that the PicketLink classes can be located.

Build-Jdk: 1.6.0_24
Dependencies: org.picketlink
Examp le 15.10. D ef in e D ep en d en cy in MET A-INF/jbo ss-d epl o ymentstructure. xml

<deployment>
<dependencies>
</dependencies>
</deployment>
Report a bug
15.7.4 . Configure Service Provider using HT T P/REDIRECT Binding

The Service Provider (SP) can be a JBoss EAP server instance.
Pro ced u re 15.2. C o n f ig u re Service Pro vid er ( SP)
1. C o n f ig u re t h e Web Ap p licat io n Secu rit y Fo r t h e SP
The web application to be configured as a SP should have FORM based security enabled in
its web. xml file.
Examp le 15.11. web. xml C o n f ig u rat io n f o r SP

<display-name>SP</display-name>
<description>SP</description>

<web-resource-name>Images</web-resource-name>
235
<url-pattern>/images/*</url-pattern>

<web-resource-name>SP</web-resource-name>
<auth-constraint>
</auth-constraint>

<login-config>
<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>
</login-config>

<security-role>
<description>
The role that is required to log in to the SP Application
</description>
</security-role>
</web-app>
2. C reat e Secu rit y D o main f o r SP

Create a Security D omain that uses SAML2Lo g i nMo d ul e. Here is an example configuration:
<security-domain name="sp" cache-type="default">
<authentication>
<login-module
code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2L
oginModule" flag="required"/>
</authentication>
</security-domain>
3. C o n f ig u re t h e SP Valve
To configure the valve for the SP, create a jbo ss-web. xml in the WEB-INF directory of your
SP web application.
Examp le 15.12. jbo ss-web. xml File C o n f ig u rat io n f o r SP Valves

<jboss-web>
<security-domain>sp</security-domain>
<context-root>sales-post</context-root>
236
<valve>
<classname>org.picketlink.identity.federation.bindings.tomcat.sp.Servic
eProviderAuthenticator</class-name>
</valve>
</jboss-web>
4. C o n f ig u re t h e Picket Lin k C o n f ig u rat io n File ( pi cketl i nk. xml )

The following is an example of pi cketl i nk. xml configuration for the SP. In this
configuration file you provide the URL for the SP and for the ID P, with corresponding
handlers for the SP.
Examp le 15.13. pi cketl i nk. xml C o n f ig u rat io n

<PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
<PicketLinkSP xmlns="urn:picketlink:identityfederation:config:2.1" ServerEnvironment="tomcat"
BindingType="REDIRECT">
<IdentityURL>${idp.url::http://localhost:8080/idp/}
</IdentityURL>
<ServiceURL>${sales-post.url::http://localhost:8080/salespost/}</ServiceURL>
</PicketLinkSP>
<Handler
2LogOutHandler" />
<Handler
2AuthenticationHandler" />
<Handler
class="org.picketlink.identity.federation.web.handlers.saml2.Role
sGenerationHandler" />
</Handlers>
</PicketLink>
By default, pi cketl i nk. xml is located in the WEB-INF directory of your application.
However, you can configure a custom path to a pi cketl i nk. xml that is external to the
application:
a. O p t io n al: C o n f ig u rin g a cu st o m p at h t o pi cketl i nk. xml
Add two paramaters to the valve element in your application's WEB-INF/jbo ssweb. xml : co nfi g Fi l e specifying for the path to pi cketl i nk. xml , and
ti merInterval which specifies the interval in milliseconds to reload the
configuration. For example:
<valve>
<class-name>...</class-name>
<param>
<param-name>timerInterval</param-name>
237
<param-value>5000</param-value>
</param>
<param>
<param-name>configFile</param-name>
<param-value>path-to/picketlink.xml</param-value>
</param>
</valve>
5. D eclare d ep en d en cies o n Picket Lin k mo d u le ( MET A-INF/MANIFEST . MF, o r jbo ssd epl o yment-structure. xml )
The web application also requires a dependency defining in MET A-INF/MANIFEST . MF or
jbo ss-d epl o yment-structure. xml , so that the PicketLink classes can be located.

Build-Jdk: 1.6.0_24
Dependencies: org.picketlink
Examp le 15.15. D ef in e D ep en d en cy in MET A-INF/jbo ss-d epl o ymentstructure. xml

<deployment>
<dependencies>
</dependencies>
</deployment>
Report a bug
15.7.5. Set up SAML v2 based Web SSO using HT T P/POST Binding

HTTP/POST binding is the recommended binding for obtaining the web browser based SSO.
Pro ced u re 15.3. Set u p SAML v2 b ased Web SSO u sin g H T T P/PO ST B in d in g
1. C o n f ig u re t h e Id en t it y Pro vid er ( ID P) .
The steps to configure ID P for HTTP/POST Binding are same as that of the HTTP/Redirect
Binding. For more information on configuring the ID P, see Section 15.7.2, Setup SAML v2
based Web SSO
2. C o n f ig u re t h e Service Pro vid er ( SP)
The steps to configure SP for HTTP/POST Binding are the same as that of the HTTP/Redirect
Binding, except for a single variation in the pi cketl i nk. xml file of the SP. Change
Bi nd i ng T ype= "R ED IR EC T " to Bi nd i ng T ype= "P O ST ".
238
For more information on configuring the SP, see Section 15.7.4, Configure Service Provider
using HTTP/RED IRECT Binding
Report a bug
15.7.6. Configure Dynamic Account Chooser at a Service Provider

Prereq u isit es:
Section 15.7.3, Configure Identity Provider
Section 15.7.4, Configure Service Provider using HTTP/RED IRECT Binding
If a Service Provider (SP) is configured with multiple Identity Providers (ID Ps), PicketLink can be
configured to prompt the user to choose which ID P to use to authenticate their credentials.
Pro ced u re 15.4 . C o n f ig u re D yn amic Acco u n t C h o o ser at a Service Pro vid er
1. Configure the account chooser valve in jbo ss-web. xml in the WEB-INF directory of your
SP web application.
Examp le 15.16 . jbo ss-web. xml File C o n f ig u rat io n f o r SP Acco u n t C h o o ser

<jboss-web>
<security-domain>sp</security-domain>
<context-root>accountchooser</context-root>
<valve>
<classname>org.picketlink.identity.federation.bindings.tomcat.sp.Accoun
tChooserValve</class-name>
</valve>
<valve>
<classname>org.picketlink.identity.federation.bindings.tomcat.sp.Servic
eProviderAuthenticator</class-name>
</valve>
</jboss-web>
Acco untC ho o serVal ve has the following configurable options:

D o main N ame
The domain name to be used for the cookie that is sent to the user's browser.
C o o kieExp iry
The cookie expiry in seconds. D efault is -1, which means the cookie expires when
the browser is closed.
Acco u n t ID PMap Pro vid er
The fully-qualified name of the implementation for ID P Mapping. D efault is a
properties file i d pmap. pro perti es in the WEB-INF directory of your SP web
application. This implementation must implement
o rg . pi cketl i nk. i d enti ty. fed erati o n. bi nd i ng s. to mcat. sp. Abstrac
tAcco untC ho o serVal ve. Acco untID P MapP ro vi d er.
239
Acco u n t C h o o serPag e
The name of the HTML/JSP page for listing the different ID P accounts. D efault is
/acco untC ho o ser. html .
2. D efine the mapping for the ID Ps. By default, this is a properties file i d pmap. pro perti es in
the WEB-INF directory of your SP web application.
Examp le 15.17. i d pmap. pro perti es C o n f ig u rat io n

DomainA=http://localhost:8080/idp1/
DomainB=http://localhost:8080/idp2/
3. Create a HTML page in your SP web application for the user to choose the ID P. By default,
this file is acco untC ho o ser. html . The URL to each of ID P must have the parameter i d p
that specifies the name of the ID P listed in i d pmap. pro perti es.
Examp le 15.18. acco untC ho o ser. html C o n f ig u rat io n

<html>
...
<a href="?idp=DomainA">DomainA</a>
<hr/>
<a href="?idp=DomainB">DomainB</a>
...
</html>
Report a bug
15.7.7. Configurat ion of IDP-init iat ed SSO

Prereq u isit es:
Usually in PicketLink, the SP starts the flow by sending an authentication request to the ID P, which in
turns sends an SAML response to SP with a valid assertion. This flow is called SP-initiated SSO. But
the SAML 2.0 specs also defines another flow, called ID P-initiated or Unsolicited Response SSO. In
this scenario, the SP does not initiate the authentication flow and receives an SAML response from
the ID P. The flow starts on the ID P-side and once authenticated, the user can choose a specific SP
from a list and then get redirected to its URL.
Walkt h ro u g h
1. User accesses the ID P.
2. The ID P seeing that there is neither SAML request nor response, assumes an ID P first
scenario using SAML.
3. The ID P challenges the user to authenticate.
24 0
4. Upon authentication, the ID P shows the hosted section where the user gets a page that links
to all the SP applications.
5. The user chooses an SP application.
6. The ID P redirects the user to the service provider with an SAML assertion in the query
parameter, SAML response.
7. The SP checks the SAML assertion and provides access.
C o n f ig u rat io n
No special configuration is necessary to get Unsolicited Responses supported, you can configure
your ID P and SPs as usual. For more information about how to configure ID P and SP, refer to:
H o w t o U se
Once the user is authenticated, the ID P shows a page with links to all service provider applications.
A link will usually look like this:
<a href="http://localhost:8080/idp?
SAML_VERSION=2.0& TARGET=http://localhost:8080/sales-post/">Sales</a>
Note that the link above redirects the user to the ID P passing the TARGET query parameter, whose
value is the URL to the target SP application. Once the user clicks the link above, the ID P extracts the
TARGET parameter from the request, builds an SAML v2.0 response, and redirects the user to the
target URL. 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 by
the ID P to create the SAML response. SAML_VERSION parameter can have the possible options as
2.0 and 1.1.
Report a bug
15.8. Configure SAML Global Logout Profile

A Global Logout initiated at one service provider logs out the user from the Identity Provider (ID P)
and all the service providers.
Note
For a Global Logout to function appropriately ensure that you have only up to five Service
Providers per Identity Provider.
Pro ced u re 15.5. C o n f ig u re G lo b al Lo g o u t

1. C o n f ig u re p icket lin k- h an d lers.xml
Add the SAML2Lo g O utHand l er in the picketlink-handlers.xml.
24 1
2. C o n f ig u re Service Pro vid er web p ag e

Append G LO = true to the link at the end of your web page of the service provider.
Examp le 15.19 . Lin k t o G lo b al Lo g o u t

<a href="?GLO=true">Click to Globally LogOut</a>
3. C reat e a l o g o ut. jsp p ag e

As part of the logout process, PicketLink will redirect the user to a l o g o ut. jsp page located
in the root directory of your Service Provider application. Ensure that this page is created.
Report a bug
24 2
Chapter 16. Login Modules

Report a bug
16.1. Using Modules

JBoss EAP 6 includes several bundled login modules suitable for most user management needs.
JBoss EAP 6 can read user information from a relational database, an LD AP server, or flat files. In
addition to these core login modules, JBoss EAP 6 provides other login modules that provide user
information for very customized needs.
More login modules and their options can be found in Appendix A.1.
Report a bug
16.1.1. Password St acking

Multiple login modules can be chained together in a stack, with each login module providing both
the credentials verification and role assignment during authentication. This works for many use
cases, but sometimes credentials verification and role assignment are split across multiple user
management stores.
Section 16.1.4, Ldap Login Module describes how to combine LD AP and a relational database,
allowing a user to be authenticated by either system. Consider the case where users are managed in
a central LD AP server but application-specific roles are stored in the application's relational
database. The password-stacking module option captures this relationship.
To use password stacking, each login module should set the <module-option> passwo rd stacki ng attribute to useFi rstP ass. If a previous module configured for password stacking has
authenticated the user, all the other stacking modules will consider the user authenticated and only
attempt to provide a set of roles for the authorization step.
When passwo rd -stacki ng option is set to useFi rstP ass, this module first looks for a shared
user name and password under the property names javax.security.auth.login.name and
javax.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
name and password are set by this login module and stored under the property names
javax.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 all modules
are considered, and have the chance to contribute roles to the authorization process.
Examp le 16 .1. Passwo rd St ackin g Samp le

This management CLI example shows how password stacking could be used.
/subsystem=security/securitydomain=pwdStack/authentication=classic/login-module=Ldap:add( \
code=Ldap, \
24 3
flag=required, \
module-options=[ \
("password-stacking"=>"useFirstPass"), \
... Ldap login module configuration
])
/subsystem=security/securitydomain=pwdStack/authentication=classic/login-module=Database:add( \
code=Database, \
flag=required, \
module-options=[ \
("password-stacking"=>"useFirstPass"), \
... Database login module configuration
])
Report a bug
16.1.2. Password Hashing

Most login modules must compare a client-supplied password to a password stored in a user
management system. These modules generally work with plain text passwords, but can be configured
to support 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 only supports
SHA-256 for password hashing.
Examp le 16 .2. Passwo rd H ash in g

The following is a login module configuration that assigns unauthenticated users the principal
name no bo d y and contains based64-encoded, SHA-256 hashes of the passwords in a
usersb6 4 . pro perti es file. The usersb6 4 . pro perti es file is part of the deployment
classpath.
/subsystem=security/security-domain=testUsersRoles:add
/subsystem=security/securitydomain=testUsersRoles/authentication=classic:add
/subsystem=security/securitydomain=testUsersRoles/authentication=classic/loginmodule=UsersRoles:add( \
code=UsersRoles, \
flag=required, \
module-options=[ \
("usersProperties"=>"usersb64.properties"), \
("rolesProperties"=>"test-users-roles.properties"), \
("unauthenticatedIdentity"=>"nobody"), \
("hashAlgorithm"=>"SHA-256"), \
("hashEncoding"=>"base64") \
])
h ash Alg o rit h m
24 4
Chapt er 1 6 . Login Modules
Name of the java. securi ty. Messag eD i g est algorithm to use to hash the password.
There is no default so this option must be specified to enable hashing. Typical values are
SHA-256 , SHA-1 and MD 5.
h ash En co d in g
String that specifies one of three encoding types: base6 4 , hex or rfc26 17. The default is
base6 4 .
h ash C h arset
Encoding character set used to convert the clear text password to a byte array. The platform
default encoding is the default.
h ash U serPasswo rd
Specifies the hashing algorithm must be applied to the password the user submits. The
hashed user password is compared against the value in the login module, which is
expected to be a hash of the password. The default is true.
h ash St o rePasswo rd
Specifies the hashing algorithm must be applied to the password stored on the server side.
This is used for digest authentication, where the user submits a hash of the user password
along with a request-specific tokens from the server to be compare. The hash algorithm (for
digest, this would be rfc26 17) is utilized to compute a server-side hash, which should
match the hashed value sent from the client.
If you must generate passwords in code, the o rg . jbo ss. securi ty. auth. spi . Uti l class
provides a static helper method that will hash a password using the specified encoding. The
following example produces a base64-encoded, MD 5 hashed password.
S tring hashedPassword = Util.createPasswordHash("SHA-256",

Util.BASE64_ENCODING, null, null, "password");
OpenSSL provides an alternative way to quickly generate hashed passwords at the command-line.
The following example also produces a base64-encoded, SHA-256 hashed password. Here the
password in plain text - passwo rd - is piped into the OpenSSL digest function then piped into
another OpenSSL function to convert into base64-encoded format.
echo -n password | openssl dgst -sha256 -binary | openssl base64
In both cases, the hashed version of the password is the same:
Xo hImNo o BHFR 0 O VvjcY pJ3Ng P Q 1q q 73WKhHvch0 VQ tg = . This value must be stored in the users'
properties file specified in the security domain - usersb6 4 . pro perti es - in the example above.
Report a bug
16.1.3. Unaut hent icat ed Ident it y

Not all requests are received in an authenticated format. unauthenti cated Id enti ty is a login
module configuration option that assigns a specific identity (guest, for example) to requests that are
made with no associated authentication information. This can be used to allow unprotected servlets
to invoke methods on EJBs that do not require a specific role. Such a principal has no associated
roles and so can only access either unsecured EJBs or EJB methods that are associated with the
unchecked permission constraint.
24 5
u n au t h en t icat ed Id en t it y: This defines the principal name that should be assigned to requests
that contain no authentication information.
Report a bug
16.1.4 . Ldap Login Module

Ld ap login module is a Lo g i nMo d ul e implementation that authenticates against a Lightweight
D irectory Access Protocol (LD AP) server. Use the Ld ap login module if your user name and
credentials are stored in an LD AP server that is accessible using a Java Naming and D irectory
Interface (JND I) LD AP provider.
AdvancedLDAP Login Module

If you wish to use LD AP with the SPNEGO authentication or skip some of the authentication
phases while using an LD AP server, consider using the Ad vanced Ld ap login module
chained with the SPNEGO login module or only the Ad vanced Ld ap login module.
D ist in g u ish ed N ame ( D N )
In Lightweight D irectory Access Protocol (LD AP), the distinguished name uniquely identifies
an object in 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 such as common names, organization unit, among others.
The combination of these values results in a unique string required by the LD AP.
Note
This login module also supports unauthenticated identity and password stacking.
The LD AP connectivity information is provided as configuration options that are passed through to
the environment object used to create JND I initial context. The standard LD AP JND I properties used
include the following:
java.n amin g .f act o ry.in it ial
Ini ti al C o ntextFacto ry implementation class name. This defaults to the Sun LD AP
provider implementation co m. sun. jnd i . l d ap. Ld apC txFacto ry.
java.n amin g .p ro vid er.u rl
LD AP URL for the LD AP server.
java.n amin g .secu rit y.au t h en t icat io n
Security protocol level to use. The available values include no ne, si mpl e, and stro ng . If
the property is undefined, the behavior is determined by the service provider.
java.n amin g .secu rit y.p ro t o co l
Transport protocol to use for secure access. Set this configuration option to the type of
service provider (for example, SSL). If the property is undefined, the behavior is determined
by the service provider.
24 6
java.n amin g .secu rit y.p rin cip al

Specifies the identity of the Principal for authenticating the caller to the service. This is built
from other properties as described below.
java.n amin g .secu rit y.cred en t ials
Specifies the credentials of the Principal for authenticating the caller to the service.
Credentials can take the form of a hashed password, a clear-text password, a key, or a
certificate. If the property is undefined, the behavior is determined by the service provider.
For details of Ldap login module configuration options see Section A.1, Included Authentication
Modules .
Note
In certain directory schemas (e.g., Microsoft Active D irectory), role attributes in the user object
are stored as D Ns to role objects instead of simple names. For implementations that use this
schema type, roleAttributeIsD N must be set to true.
User authentication is performed by connecting to the LD AP server, based on the login module
configuration options. Connecting to the LD AP server is done by creating an
Ini ti al Ld apC o ntext with an environment composed of the LD AP JND I properties described
previously in this section.
The Context.SECURITY_PRINCIPAL is set to the distinguished name of the user obtained by the
callback handler in combination with the principalD NPrefix and principalD NSuffix option values,
and the Context.SECURITY_CRED ENTIALS property is set to the respective String password.
Once authentication has succeeded (Ini ti al Ld apC o ntext instance is created), the user's roles
are queried by performing a search on the ro l esC txD N location with search attributes set to the
roleAttributeName and uidAttributeName option values. The roles names are obtaining by invoking
the to Stri ng method on the role attributes in the search result set.
Examp le 16 .3. LD AP Lo g in Mo d u le Secu rit y D o main

This management CLI example shows how to use the parameters in a security domain
authentication configuration.
/subsystem=security/security-domain=testLDAP:add(cache-type=default)
/subsystem=security/security-domain=testLDAP/authentication=classic:add
/subsystem=security/securitydomain=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"), \
24 7
("matchOnUserDN"=>true), \
("roleAttributeID"=>"cn"), \
("roleAttributeIsDN"=>false) \
])
The java.naming.factory.initial, java.naming.factory.url and

java.naming.security options in the testLD AP security domain configuration indicate the
following conditions:
The Sun LD AP JND I provider implementation will be used
The LD AP server is located on host l d apho st. jbo ss. o rg on port 1389
The LD AP simple authentication method will be use to connect to the LD AP server.
The login module attempts to connect to the LD AP server using a D istinguished Name (D N)
representing the user it is trying to authenticate. This D N is constructed from the passed
principalD NPrefix, the user name of the user and the principalD NSuffix as described above. In
Example 16.4, LD IF File Example , the user name jsmi th would map to
ui d = jsmi th,o u= P eo pl e,d c= jbo ss,d c= o rg .
Note
The example assumes the LD AP server authenticates users using the userP asswo rd attribute
of the user's entry (thed uke in this example). Most LD AP servers operate in this manner,
however if your LD AP server handles authentication differently you must ensure LD AP is
configured according to your production environment requirements.
Once authentication succeeds, the roles on which authorization will be based are retrieved by
performing a subtree search of the ro l esC txD N for entries whose uidAttributeID match the user. If
matchOnUserD N is true, the search will be based on the full D N of the user. Otherwise the search will
be based on the actual user name entered. In this example, the search is under
o u= R o l es,d c= jbo ss,d c= o rg for any entries that have a member attribute equal to
ui d = jsmi th,o u= P eo pl e,d c= jbo ss,d c= o rg . The search would locate cn= JBo ssAd mi n
under the roles entry.
The search returns the attribute specified in the roleAttributeID option. In this example, the attribute is
cn. The value returned would be JBo ssAd mi n, so the jsmi th user is assigned to the JBo ssAd mi n
role.
A local LD AP server often provides identity and authentication services, but is unable to use
authorization services. This is because application roles do not always map well onto LD AP groups,
and LD AP administrators are often hesitant to allow external application-specific data in central
LD AP servers. The LD AP authentication module is often paired with another login module, such as
the database login module, that can provide roles more suitable to the application being developed.
An LD AP D ata Interchange Format (LD IF) file representing the structure of the directory this data
operates against is shown in Example 16.4, LD IF File Example .
LD AP D at a In t erch an g e Fo rmat ( LD IF)
Plain text data interchange format used to represent LD AP directory content and update
requests. D irectory content is represented as one record for each object or update request.
Content consists of add, modify, delete, and rename requests.
24 8
Examp le 16 .4 . LD IF File Examp le

dn: dc=jboss,dc=org
objectclass: top
objectclass: dcObject
objectclass: organization
dc: jboss
o: JBoss
dn: ou=People,dc=jboss,dc=org
objectclass: top
objectclass: organizationalUnit
ou: People
dn: uid=jsmith,ou=People,dc=jboss,dc=org
objectclass: top
objectclass: uidObject
objectclass: person
uid: jsmith
cn: John
sn: Smith
userPassword: theduke
dn: ou=Roles,dc=jboss,dc=org
objectclass: top
ou: Roles
dn: cn=JBossAdmin,ou=Roles,dc=jboss,dc=org
objectclass: top
objectclass: groupOfNames
cn: JBossAdmin
member: uid=jsmith,ou=People,dc=jboss,dc=org
description: the JBossAdmin group
Report a bug
16.1.5. LdapExt ended Login Module

D ist in g u ish ed N ame ( D N )
In Lightweight D irectory Access Protocol (LD AP), the distinguished name uniquely identifies
an object in 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 such as common names, organization unit, among others.
The combination of these values results in a unique string required by the LD AP.
The LdapExtended (o rg . jbo ss. securi ty. auth. spi . Ld apExtLo g i nMo d ul e) searches for
the user to bind, as well as the associated roles, for authentication. The roles query recursively
follows D Ns to navigate a hierarchical role structure.
The LoginModule options include whatever options are supported by the chosen LD AP JND I
provider supports. Examples of standard property names are:
Context.INITIAL_CONTEXT_FACTORY = " java.naming.factory.initial"
24 9
Context.SECURITY_PROTOCOL = " java.naming.security.protocol"

Context.PROVID ER_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 LD AP server bind is authenticated using the bindD N and bindCredential
properties. The bindD N is a user with permissions to search both the baseCtxD N and
rolesCtxD N trees for the user and roles. The user D N to authenticate against is queried using
the filter specified by the baseFilter property.
2. The resulting userD N is authenticated by binding to the LD AP server using the userD N as the
InitialLdapContext environment Context.SECURITY_PRINCIPAL. The
Context.SECURITY_CRED ENTIALS property is either set to the String password obtained by
the callback handler.
3. If this is successful, the associated user roles are queried using the rolesCtxD N,
roleAttributeID , roleAttributeIsD N, roleNameAttributeID , and roleFilter options.
For details of LdapExtended login module options see Section A.1, Included Authentication
Modules .
Fig u re 16 .1. LD AP St ru ct u re Examp le
Examp le 16 .5. Examp le 2 LD AP C o n f ig u rat io n

version: 1
dn: o=example2,dc=jboss,dc=org
objectClass: top
objectClass: organization
250
o: example2
dn: ou=People,o=example2,dc=jboss,dc=org
objectClass: top
objectClass: organizationalUnit
ou: People
dn: uid=jduke,ou=People,o=example2,dc=jboss,dc=org
objectClass: top
objectClass: person
cn: Java Duke
employeeNumber: judke-123
sn: Duke
uid: jduke
userPassword:: dGhlZHVrZQ==
dn: uid=jduke2,ou=People,o=example2,dc=jboss,dc=org
objectClass: top
objectClass: person
cn: Java Duke2
employeeNumber: judke2-123
sn: Duke2
uid: jduke2
userPassword:: dGhlZHVrZTI=
dn: ou=Roles,o=example2,dc=jboss,dc=org
objectClass: top
ou: Roles
dn: uid=jduke,ou=Roles,o=example2,dc=jboss,dc=org
objectClass: top
objectClass: groupUserEx
memberOf: cn=Echo,ou=Roles,o=example2,dc=jboss,dc=org
memberOf: cn=TheDuke,ou=Roles,o=example2,dc=jboss,dc=org
uid: jduke
dn: uid=jduke2,ou=Roles,o=example2,dc=jboss,dc=org
objectClass: top
memberOf: cn=Echo2,ou=Roles,o=example2,dc=jboss,dc=org
memberOf: cn=TheDuke2,ou=Roles,o=example2,dc=jboss,dc=org
uid: jduke2
dn: cn=Echo,ou=Roles,o=example2,dc=jboss,dc=org
objectClass: top
objectClass: groupOfNames
cn: Echo
description: the echo role
member: uid=jduke,ou=People,dc=jboss,dc=org
dn: cn=TheDuke,ou=Roles,o=example2,dc=jboss,dc=org
251
objectClass: top
cn: TheDuke
description: the duke role
member: uid=jduke,ou=People,o=example2,dc=jboss,dc=org
dn: cn=Echo2,ou=Roles,o=example2,dc=jboss,dc=org
objectClass: top
cn: Echo2
description: the Echo2 role
member: uid=jduke2,ou=People,dc=jboss,dc=org
dn: cn=TheDuke2,ou=Roles,o=example2,dc=jboss,dc=org
objectClass: top
cn: TheDuke2
description: the duke2 role
member: uid=jduke2,ou=People,o=example2,dc=jboss,dc=org
dn: cn=JBossAdmin,ou=Roles,o=example2,dc=jboss,dc=org
objectClass: top
cn: JBossAdmin
member: uid=jduke,ou=People,dc=jboss,dc=org
The module configuration for this LD AP structure example is outlined in the following management
CLI command.
/subsystem=security/securitydomain=testLdapExample2/authentication=classic/loginmodule=LdapExtended:add( \
code=LdapExtended, \
flag=required, \
module-options=[ \
("java.naming.provider.url"=>"ldap://ldaphost.jboss.org"), \
("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") \
])
Examp le 16 .6 . Examp le 3 LD AP C o n f ig u rat io n
252
objectclass: top
o: example3
objectclass: top
ou: People
objectclass: top
objectclass: uidObject
objectclass: person
uid: jduke
employeeNumber: judke-123
cn: Java Duke
sn: Duke
userPassword: theduke
objectClass: top
ou: Roles
dn: uid=jduke,ou=Roles,o=example3,dc=jboss,dc=org
objectClass: top
memberOf: cn=Echo,ou=Roles,o=example3,dc=jboss,dc=org
memberOf: cn=TheDuke,ou=Roles,o=example3,dc=jboss,dc=org
uid: jduke
dn: cn=Echo,ou=Roles,o=example3,dc=jboss,dc=org
objectClass: top
cn: Echo
dn: cn=TheDuke,ou=Roles,o=example3,dc=jboss,dc=org
objectClass: top
cn: TheDuke
The module configuration for this LD AP structure example is outlined in the following management
CLI command.
253
flag=required, \
module-options=[ \
("java.naming.factory.initial"=>"com.sun.jndi.ldap.LdapCtxFactory"),
\
("baseFilter"=>"(cn={0})"), \
("roleFilter"=>"(member={1})"), \
("roleAttributeID"=>"cn") \
])
Examp le 16 .7. Examp le 4 LD AP C o n f ig u rat io n
objectclass: top
o: example4
objectclass: top
ou: People
objectClass: top
objectClass: person
cn: Java Duke
employeeNumber: jduke-123
sn: Duke
uid: jduke
userPassword:: dGhlZHVrZQ==
objectClass: top
ou: Roles
dn: cn=RG1,ou=Roles,o=example4,dc=jboss,dc=org
objectClass: top
cn: RG1
member: cn=empty
dn: cn=RG2,cn=RG1,ou=Roles,o=example4,dc=jboss,dc=org
objectClass: top
cn: RG2
member: cn=RG1,ou=Roles,o=example4,dc=jboss,dc=org
254
dn: cn=RG3,cn=RG1,ou=Roles,o=example4,dc=jboss,dc=org
objectClass: top
cn: RG3
member: cn=RG1,ou=Roles,o=example4,dc=jboss,dc=org
dn: cn=R1,ou=Roles,o=example4,dc=jboss,dc=org
objectClass: top
cn: R1
member: cn=RG2,cn=RG1,ou=Roles,o=example4,dc=jboss,dc=org
objectClass: top
cn: R2
objectClass: top
cn: R3
objectClass: top
cn: R4
objectClass: top
cn: R5
The module configuration for this LD AP structure example is outlined in the code sample.
flag=required, \
module-options=[ \
255
("baseFilter"=>"(cn={0})"), \
("roleRecursion"=>"1"), \
("roleAttributeID"=>"memberOf") \
])
Examp le 16 .8. D ef au lt Act ive D irect o ry C o n f ig u rat io n

The example below represents the configuration for a default Active D irectory configuration.
Some Active D irectory configurations may require searching against the Global Catalog on port
3268 instead of the usual port 389. This is most likely when the Active D irectory forest includes
multiple domains.
/subsystem=security/securitydomain=AD_Default/authentication=classic/login-module=LdapExtended:add(
\
flag=required, \
module-options=[ \
("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") \
])
Examp le 16 .9 . R ecu rsive R o les Act ive D irect o ry C o n f ig u rat io n

The example below implements a recursive role search within Active D irectory. The key difference
between this example and the default Active D irectory example is that the role search has been
replaced to search the member attribute using the D N of the user. The login module then uses the
D N of the role to find groups of which the group is a member.
/subsystem=security/securitydomain=AD_Recursive/authentication=classic/loginmodule=LdapExtended:add( \
flag=required, \
module-options=[ \
("java.naming.referral"=>"follow"), \
("bindDN"=>"JBOSS\searchuser"), \
256
("bindCredential"=>"password"), \
("baseCtxDN"=>"CN=Users,DC=jboss,DC=org"), \
("baseFilter"=>"(sAMAccountName={0})"), \
("rolesCtxDN"=>"CN=Users,DC=jboss,DC=org"), \
("roleAttributeID"=>"cn"), \
("roleAttributeIsDN"=>"false"), \
("roleRecursion"=>"2"), \
("searchScope"=>"ONELEVEL_SCOPE"), \
("allowEmptyPasswords"=>"false") \
])
Report a bug
16.1.6. UsersRoles Login Module

UsersR o l es login module is a simple login module that supports multiple users and user roles
loaded from Java properties files. The default username-to-password mapping filename is
users. pro perti es and the default username-to-roles mapping filename is ro l es. pro perti es.
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, into the WEB-INF/cl asses folder in the WAR archive), or into any directory on the server
classpath. The primary purpose of this login module is to easily test the security settings of multiple
users and roles using properties files deployed with the application.
Examp le 16 .10. U serR o les Lo g in Mo d u le

/subsystem=security/security-domain=ejb3sampleapp/authentication=classic/login-module=UsersRoles:add( \
code=UsersRoles, \
flag=required, \
module-options=[ \
("usersProperties"=>"ejb3-sampleapp-users.properties"), \
("rolesProperties"=>"ejb3-sampleapp-roles.properties") \
])
In Example 16.10, UserRoles Login Module , the ejb3-sampl eapp-users. pro perti es file uses
a username= passwo rd format with each user entry on a separate line:
username1=password1
username2=password2
...
The ejb3-sampl eapp-ro l es. pro perti es file referenced in Example 16.10, UserRoles Login
Module uses the pattern username= ro l e1,ro l e2, with an optional group name value. For
example:
257
username1=role1,role2,...
username1.RoleGroup1=role3,role4,...
username2=role1,role3,...
The user name.XXX property name pattern present in ejb3-sampl eapp-ro l es. pro perti es is
used to assign the user name roles to a particular named group of roles where the XXX portion of the
property name is the group name. The user name=... form is an abbreviation for user name.Roles=...,
where the R o l es group name is the standard name the JBo ssAutho ri zati o nManag er expects to
contain the roles which define the permissions of users.
The following would be equivalent definitions for the jd uke user name:
jduke=TheDuke,AnimatedCharacter
jduke.Roles=TheDuke,AnimatedCharacter
Report a bug
16.1.7. Dat abase Login Module

The D atabase login module is a Java D atabase Connectivity-based (JD BC) login module that
supports authentication and role mapping. Use this login module if you have your user name,
password and role information stored in a relational database.
Note
This module supports password stacking, password hashing and unauthenticated identity.
The D atabase login module is based on two logical tables:
Table Principals(PrincipalID text, Password text)
Table Roles(PrincipalID text, Role text, RoleGroup text)
The P ri nci pal s table associates the user P ri nci pal ID with the valid password and the R o l es
table associates the user P ri nci pal ID with its role sets. The roles used for user permissions must
be contained in rows with a R o l eG ro up column value of R o l es.
The tables are logical in that you can specify the SQL query that the login module uses. The only
requirement is that the java. sq l . R esul tSet has the same logical structure as the P ri nci pal s
and R o l es tables described previously. The actual names of the tables and columns are not
relevant as the results are accessed based on the column index.
To clarify this notion, consider a database with two tables, P ri nci pal s and R o l es, as already
declared. The following statements populate the tables with the following data:
P ri nci pal ID java with a P asswo rd of echo man in the P ri nci pal s table
P ri nci pal ID java with a role named Echo in the R o l esR o l eG ro up in the R o l es table
P ri nci pal ID java with a role named cal l er_java in the C al l erP ri nci pal R o l eG ro up in
the R o l es table
258
INSERT INTO Principals VALUES('java', 'echoman')

INSERT INTO Roles VALUES('java', 'Echo', 'Roles')
INSERT INTO Roles VALUES('java', 'caller_java', 'CallerPrincipal')
For details of D atabase login module options see Section A.1, Included Authentication Modules .
An example D atabase l o g i n mo d ul e configuration could be constructed as follows:
CREATE TABLE Users(username VARCHAR(64) PRIMARY KEY, passwd VARCHAR(64))
CREATE TABLE UserRoles(username VARCHAR(64), role VARCHAR(32))
A corresponding login module configuration in a security domain:
/subsystem=security/security-domain=testDB/authentication=classic/loginmodule=Database:add( \
code=Database, \
flag=required, \
module-options=[ \
("dsJndiName"=>"java:/MyDatabaseDS"), \
("principalsQuery"=>"select passwd from Users where username=?"), \
("rolesQuery"=>"select role, 'Roles' from UserRoles where
username=?") \
])
Report a bug
16.1.8. Cert ificat e Login Module

C erti fi cate login module authenticates users based on X509 certificates. A typical use case for
this login module is C LIENT -C ER T authentication in the web tier.
This login module only performs authentication: you must combine it with another login module
capable of acquiring authorization roles to completely define access to a secured web or EJB
component. Two subclasses of this login module, C ertR o l esLo g i nMo d ul e and
D atabaseC ertLo g i nMo d ul e extend the behavior to obtain the authorization roles from either a
properties file or database.
For details of C erti fi cate login module options see Section A.1, Included Authentication
Modules .
The C erti fi cate login module needs a KeySto re to perform user validation. This is obtained from
a JSSE configuration of linked security domain as shown in the following configuration fragment:
/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/securitydomain=testCert/authentication=classic/login-module=Certificate:add( \
code=Certificate, \
259
flag=required, \
module-options=[ \
("securityDomain"=>"trust-domain"), \
])
Pro ced u re 16 .1. Secu re Web Ap p licat io n s wit h C ert if icat es an d R o le- b ased
Au t h o riz at io n
This procedure describes how to secure a web application, such as the user-app. war, using client
certificates and role-based authorization. In this example the C erti fi cateR o l es login module is
used for authentication and authorization. Both the trusted -cl i ents. keysto re and the appro l es. pro perti es 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 D N
specified in Example 16.11, Certificate Example .
1. D eclare R eso u rces an d R o les
Modify web. xml to declare the resources to be secured along with the allowed roles and
security domain to be used for authentication and authorization.
<?xml version="1.0" encoding="UTF-8"?>

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<web-resource-name>Protect App</webresource-name>
<auth-constraint>
<role-name>Admin</role-name>
</auth-constraint>
<login-config>
<auth-method>CLIENT-CERT</auth-method>
<realm-name>Secured area</realm-name>
</login-config>
<security-role>
</security-role>
</web-app>
2. Sp ecif y t h e Secu rit y D o main
In the jbo ss-web. xml file, specify the required security domain.
260
< jboss-web>
<security-domain>app-sec-domain</security-domain>
< /jboss-web>
3. C o n f ig u re Lo g in Mo d u le
D efine the login module configuration for the app-sec-d o mai n domain you just specified
using the management CLI.
[
/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-secdomain/authentication=classic:add
/subsystem=security/security-domain=app-secdomain/authentication=classic/login-module=CertificateRoles:add( \
code=CertificateRoles, \
flag=required, \
module-options=[ \
("securityDomain"=>"trust-domain"), \
("rolesProperties"=>"app-roles.properties") \
])
Examp le 16 .11. C ert if icat e Examp le

[conf]$ keytool -printcert -file valid-client-cert.crt
Owner: CN=valid-client, OU=Security QE, OU=JBoss, O=Red Hat, C=CZ
Issuer: CN=EAP Certification Authority, OU=Security QE, OU=JBoss, O=Red
Hat, C=CZ
Serial number: 2
Valid from: Mon Mar 24 18:21:55 CET 2014 until: Tue Mar 24 18:21:55 CET
2015
Certificate 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 -cl i ents. keysto re would need the certificate in Example 16.11, Certificate
Example stored with an alias of C N= val i d -cl i ent, O U= Securi ty Q E, O U= JBo ss, O = R ed
Hat, C = C Z. The app-ro l es. pro perti es must have the same entry. Since the D N contains
characters that are normally treated as delimiters, you must escape the problem characters using a
261
backslash ('\') as illustrated below.

# A sample app-roles.properties file
CN\=valid-client,\ OU\=Security\ QE,\ OU\=JBoss,\ O\=Red\ Hat,\ C\=CZ
Report a bug
16.1.9. Ident it y Login Module

Id enti ty login module is a simple login module that associates a hard-coded user name to any
subject authenticated against the module. It creates a Si mpl eP ri nci pal instance using the name
specified by the pri nci pal option.
Note
This module supports password stacking.
This login module is useful when you need to provide a fixed identity to a service, and in
development environments 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 principal
named jd uke and assigns role names of T heD uke, and Ani mated C haracter:.
/subsystem=security/security-domain=testIdentity:add
/subsystem=security/securitydomain=testIdentity/authentication=classic:add
/subsystem=security/securitydomain=testIdentity/authentication=classic/login-module=Identity:add( \
code=Identity, \
flag=required, \
module-options=[ \
("principal"=>"jduke"), \
("roles"=>"TheDuke,AnimatedCharacter") \
])
Report a bug
16.1.10. RunAs Login Module

R unAs login module is a helper module that pushes a run as role onto the stack for the duration of
the login phase of authentication, then pops the run as role from the stack in either the commit or
abort phase.
The purpose of this login module is to provide a role for other login modules that must access
secured resources in order to perform their authentication (for example, a login module that accesses
a secured EJB). R unAs login module must be configured ahead of the login modules that require a
run as role established.
For details of RunAs login module options see Section A.1, Included Authentication Modules .
262
Report a bug
1 6 .1 .1 0 .1 . RunAsIde nt it y Cre at io n
In order for JBoss EAP 6 to secure access to EJB methods, the identity of the user must be known at
the time the method call is made.
A user's identity in the server is represented either by a javax. securi ty. auth. Subject instance
or an o rg . jbo ss. securi ty. R unAsId enti ty instance. Both these classes store one or more
principals that represent the identity and a list of roles that the identity possesses. In the case of the
javax. securi ty. auth. Subject a list of credentials is also stored.
In the <assembly-descriptor> section of the ejb-jar. xml deployment descriptor, you specify one or
more roles that a user must have to access the various EJB methods. A comparison of these lists
reveals whether the user has one of the roles necessary to access the EJB method.
Examp le 16 .12. o rg .jb o ss.secu rit y.R u n AsId en t it y C reat io n

In the ejb-jar. xml file, you specify a <security-identity> element with a <run-as> role defined as
a child of the <session> element.
< session>
...
<security-identity>
<run-as>
</run-as>
...
< /session>
This declaration signifies that an Ad mi n RunAsIdentity role must be created.
To name a principal for the Ad mi n role, you define a <run-as-pri nci pal > element in the
jbo ss-ejb3. xml file.
< 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">
<s:security>
<ejb-name>WhoAmIBean</ejb-name>
<s:run-as-principal>John</s:run-as-principal>
</s:security>
< /jboss:ejb-jar>
The <securi ty-i d enti ty> element in both the ejb-jar. xml and <securi ty> element in the
jbo ss-ejb3. xml files are parsed at deployment time. The <run-as> role name and the <runas-pri nci pal > name are then stored in the
o rg . jbo ss. metad ata. ejb. spec. Securi tyId enti tyMetaD ata class.
263
Examp le 16 .13. Assig n in g mu lt ip le ro les t o a R u n AsId en t it y

You can assign more roles to RunAsIdentity by mapping roles to principals in the jbo ssejb3. xml deployment descriptor <assembl y-d escri pto r> element group.
< jboss:ejb-jar xmlns:sr="urn:security-role"
...>
...
<sr:security-role>
<sr:role-name>Support</sr:role-name>
<sr:principal-name>John</sr:principal-name>
<sr:principal-name>Jill</sr:principal-name>
<sr:principal-name>Tony</sr:principal-name>
</sr:security-role>
< /jboss:ejb-jar>
In Example 16.12, org.jboss.security.RunAsIdentity Creation , the <run-as-pri nci pal > of
Jo hn was created. The configuration in this example extends the Ad mi n role, by adding the
Suppo rt role. The new role contains extra principals, including the originally defined principal
Jo hn.
The <securi ty-ro l e> element in both the ejb-jar. xml and jbo ss-ejb3. xml files are
parsed at deployment time. The <ro l e-name> and the <pri nci pal -name> data is stored in the
o rg . jbo ss. metad ata. ejb. spec. Securi tyId enti tyMetaD ata class.
Report a bug
16.1.11. Client Login Module

C l i ent login module (o rg . jbo ss. securi ty. C l i entLo g i nMo d ul e) is an implementation of
Lo g i nMo d ul e for use by JBoss clients when establishing caller identity and credentials. This
creates a new Securi tyC o ntext assigns it a principal and a credential and sets the
Securi tyC o ntext to the T hread Lo cal security context.
C l i ent 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 the security environment has not been configured to use the EAP security subsystem
transparently) must use C l i ent login module.
Note that this login module does not perform any authentication. It merely copies the login
information provided to it into the server EJB invocation layer for subsequent authentication on the
server. If you need to perform client-side authentication of users you would need to configure another
login module in addition to the C l i ent login module.
For details of Client login module options see Section A.1, Included Authentication Modules .
Report a bug
16.1.12. SPNEGO Login Module
264
SP NEG O login module

(o rg . jbo ss. securi ty. neg o ti ati o n. spneg o . SP NEG O Lo g i nMo d ul e) is an implementation
of Lo g i nMo d ul e that establishes caller identity and credentials with a KD C. The module implements
SPNEGO (Simple and Protected GSSAPI Negotiation mechanism) and is a part of the JBoss
Negotiation project. This authentication can be used in the chained configuration with the
Ad vanced Ld ap login module to allow cooperation with an LD AP 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.
To use the SP NEG O or Ad vanced Ld ap login modules in your project, you must add the dependency
manually by editing the MET A-INF/jbo ss-d epl o yment-structure. xml deployment descriptor
file.
Examp le 16 .14 . Ad d JB o ss N eg o t iat io n Mo d u le as a D ep en d en cy
< jboss-deployment-structure>
<deployment>
<dependencies>
<module name="org.jboss.security.negotiation" />
</dependencies>
</deployment>
< /jboss-deployment-structure>
Report a bug
16.1.13. RoleMapping Login Module

R o l eMappi ng login module supports mapping roles, that are the end result of the authentication
process, to one or more declarative roles. For example, if the authentication process has determined
that the user " A" has the roles " ldapAdmin" and " testAdmin" , and the declarative role defined in the
web. xml or ejb-jar. xml file for access is ad mi n, then this login module maps the ad mi n roles to
the user A.
For details of R o l eMappi ng login module options see Section A.1, Included Authentication
Modules .
The R o l eMappi ng login module must be defined as an optional module to a login module
configuration as it alters mapping of the previously mapped roles.
Examp le 16 .15. D ef in in g map p ed ro les

/subsystem=security/security-domain=test-domain-2/:add
/subsystem=security/security-domain=test-domain2/authentication=classic:add
/subsystem=security/security-domain=test-domain2/authentication=classic/login-module=test-2-lm/:add(\
flag=required,\
code=UsersRoles,\
module-options=[("usersProperties"=>"users.properties"),
("rolesProperties"=>"roles.properties")]\
265
)
/subsystem=security/security-domain=test-domain2/authentication=classic/login-module=test2-map/:add(\
flag=optional,\
code=RoleMapping,\
module-options=[("rolesProperties"=>"rolesMapping-roles.properties")]\
)
Another example achieving the same result, but using the mapping module. This is the preferred
method of role mapping:
Examp le 16 .16 . Pref erred met h o d o f d ef in in g map p ed ro les

/subsystem=security/security-domain=test-domain-2/:add
/subsystem=security/security-domain=test-domain2/authentication=classic:add
/subsystem=security/security-domain=test-domain2/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-domain2/mapping=classic/mapping-module=test2-map/:add(\
code=PropertiesRoles,type=role,\
module-options=[("rolesProperties"=>"rolesMapping-roles.properties")]\
)
Examp le 16 .17. Pro p ert ies File u sed b y a R o leMap p in g Lo g in Mo d u le

ldapAdmin=admin, testAdmin
If the authenticated subject contains role l d apAd mi n, then the roles ad mi n and testAd mi n are
added to or substitute the authenticated subject depending on the replaceRole property value.
Report a bug
16.1.14 . bindCredent ial Module Opt ion

The bi nd C red enti al module option is used to store the credentials for the D N and can be used by
several login and mapping modules. There are several methods for obtaining the password.
Plain t ext in a man ag emen t C LI co mman d .
The password for the bi nd C red enti al module may be provided in plaintext, in a
management CLI command. For example: ("bi nd C red enti al "= >"secret1"). For
security reasons, the password should be encrypted using the JBoss EAP vault
mechanism.
U se an ext ern al co mman d .
266
To obtain the password from the output of an external command, use the format {EXT }. . .
where the . . . is the external command. The first line of the command output is used as the
password.
To improve performance, the {EXT C [: expi rati o n_i n_mi l l i s]} variant caches the
password for a 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 EXT C variant is only supported by the Ld apExtend ed login module.
Examp le 16 .18. O b t ain a p asswo rd f ro m an ext ern al co mman d

{EXT}cat /mysecretpasswordfile
Examp le 16 .19 . O b t ain a p asswo rd f ro m an ext ern al f ile an d cach e it f o r 500

milliseco n d s
{EXTC:500}cat /mysecretpasswordfile
Report a bug
16.2. Cust om Modules

If the login modules bundled with the EAP security framework do not work with your security
environment, you can write your own custom login module implementation. The
Authenti cati o nManag er requires a particular usage pattern of the Subject principals set. You
must understand the JAAS Subject class's information storage features and the expected usage of
these features to write a login module that works with the Authenti cati o nManag er.
This section examines this requirement and introduces two abstract base Lo g i nMo d ul e
implementations that can help you implement custom login modules.
You can obtain security information associated with a Subject by using the following methods:
j ava.util.Set
j ava.util.Set
j ava.util.Set
j ava.util.Set
j ava.util.Set
j ava.util.Set
getPrincipals()
getPrincipals(java.lang.Class c)
getPrivateCredentials()
getPrivateCredentials(java.lang.Class c)
getPublicCredentials()
getPublicCredentials(java.lang.Class c)
For Subject identities and roles, EAP has selected the most logical choice: the principals sets
obtained via g etP ri nci pal s() and g etP ri nci pal s(java. l ang . C l ass). The usage pattern
is as follows:
User identities (for example; user name, social security number, employee ID ) are stored as
java. securi ty. P ri nci pal objects in the SubjectP ri nci pal s set. The P ri nci pal
implementation that represents the user identity must base comparisons and equality on the name
of the principal. A suitable implementation is available as the
o rg . jbo ss. securi ty. Si mpl eP ri nci pal class. Other P ri nci pal instances may be added
to the SubjectP ri nci pal s set as needed.
267
Assigned user roles are also stored in the P ri nci pal s set, and are grouped in named role sets
using java. securi ty. acl . G ro up instances. The G ro up interface defines a collection of
P ri nci pal s and/or G ro ups, and is a subinterface of java. securi ty. P ri nci pal .
Any number of role sets can be assigned to a Subject.
The EAP security framework uses two well-known role sets with the names R o l es and
C al l erP ri nci pal .
The R o l es group is the collection of P ri nci pal s for the named roles as known in the
application domain under which the Subject has been authenticated. This role set is used by
methods like the EJBC o ntext. i sC al l erInR o l e(Stri ng ), which EJBs can use to see if
the current caller belongs to the named application domain role. The security interceptor logic
that performs method permission checks also uses this role set.
The C al l erP ri nci pal G ro up consists of the single P ri nci pal identity assigned to the
user in the application domain. The EJBC o ntext. g etC al l erP ri nci pal () method uses
the C al l erP ri nci pal to allow the application domain to map from the operation
environment identity to a user identity suitable for the application. If a Subject does not have
a C al l erP ri nci pal G ro up, the application identity is the same as operational environment
identity.
Report a bug
16.2.1. Subject Usage Pat t ern Support

To simplify correct implementation of the Subject usage patterns described in Section 16.2,
Custom Modules , EAP includes login modules that populate the authenticated Subject with a
template pattern that enforces correct Subject usage.
Ab st ract ServerLo g in Mo d u le
The most generic of the two is the
o rg . jbo ss. securi ty. auth. spi . AbstractServerLo g i nMo d ul e class.
It provides an implementation of the javax. securi ty. auth. spi . Lo g i nMo d ul e interface and
offers abstract methods for the key tasks specific to an operation environment security infrastructure.
The key details of the class are highlighted in Example 16.20, AbstractServerLoginModule Class
Fragment . The JavaD oc comments detail the responsibilities of subclasses.
Important
The l o g i nO k instance variable is pivotal. This must be set to true if the log in succeeds, or
fal se by any subclasses that override the log in method. If this variable is incorrectly set, 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.
Examp le 16 .20. Ab st ract ServerLo g in Mo d u le C lass Frag men t

p ackage org.jboss.security.auth.spi;
/ **
268
* 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.
*/
p ublic 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;
/**
* 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)
269
// ...
/**
* 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()
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;
U sern amePasswo rd Lo g in Mo d u le
The second abstract base login module suitable for custom login modules is the
o rg . jbo ss. securi ty. auth. spi . UsernameP asswo rd Lo g i nMo d ul e.
This login module further simplifies custom login module implementation by enforcing a string-based
user name as the user identity and a char[] password as the authentication credentials. It also
supports the mapping of anonymous users (indicated by a null user name and password) to a
principal with no roles. The key details of the class are highlighted in the following class fragment.
The JavaD oc comments detail the responsibilities of subclasses.
Examp le 16 .21. U sern amePasswo rd Lo g in Mo d u le C lass Frag men t
270
p ackage 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.
*/
p ublic 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
*/
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.
271
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)
{
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;
Su b classin g Lo g in Mo d u les
The choice of sub-classing the AbstractServerLo g i nMo d ul e versus
UsernameP asswo rd Lo g i nMo d ul e is based on whether a string-based user name and credentials
are usable for the authentication technology you are writing the login module for. If the string-based
semantic is valid, then subclass UsernameP asswo rd Lo g i nMo d ul e, otherwise subclass
AbstractServerLo g i nMo d ul e.
Su b classin g St ep s
The steps your custom login module must execute depend on which base login module class you
choose. When writing a custom login module that integrates with your security infrastructure, you
should start by sub-classing AbstractServerLo g i nMo d ul e or
UsernameP asswo rd Lo g i nMo d ul e to ensure that your login module provides the authenticated
P ri nci pal information in the form expected by the EAP security manager.
When sub-classing the AbstractServerLo g i nMo d ul e, you must override the following:
272
vo i d i ni ti al i ze(Subject, C al l backHand l er, Map, Map): if you have custom

options to parse.
bo o l ean l o g i n(): to perform the authentication activity. Be sure to set the l o g i nO k instance
variable to true if log in succeeds, false if it fails.
P ri nci pal g etId enti ty(): to return the P ri nci pal object for the user authenticated by the
l o g () step.
G ro up[] g etR o l eSets(): to return at least one G ro up named R o l es that contains the roles
assigned to the P ri nci pal authenticated during l o g i n(). A second common G ro up is named
C al l erP ri nci pal and provides the user's application identity rather than the security domain
identity.
When sub-classing the UsernameP asswo rd Lo g i nMo d ul e, you must override the following:
vo i d i ni ti al i ze(Subject, C al l backHand l er, Map, Map): if you have custom
options to parse.
G ro up[] g etR o l eSets(): to return at least one G ro up named R o l es that contains the roles
assigned to the P ri nci pal authenticated during l o g i n(). A second common G ro up is named
C al l erP ri nci pal and provides the user's application identity rather than the security domain
identity.
Stri ng g etUsersP asswo rd (): to return the expected password for the current user name
available via the g etUsername() method. The g etUsersP asswo rd () method is called from
within l o g i n() after the cal l backhand l er returns the user name and candidate password.
Report a bug
16.2.2. Cust om LoginModule Example

The following information will help you to create a custom Login Module example that extends the
UsernameP asswo rd Lo g i nMo d ul e and obtains a user's password and role names from a JND I
lookup.
At the end of this section you will have created a custom JND I context login module that will return a
user's password if you perform a lookup on the context using a name of the form
passwo rd /<username> (where <username> is the current user being authenticated). Similarly, a
lookup of the form ro l es/<username> returns the requested user's roles. In Example 16.22,
JndiUserAndPassLoginModule Custom Login Module is the source code for the
Jnd i UserAnd P assLo g i nMo d ul e custom login module.
Note that because this extends the JBoss UsernameP asswo rd Lo g i nMo d ul e, the
Jnd i UserAnd P assLo g i nMo d ul e obtains the user's password and roles from the JND I store. The
Jnd i UserAnd P assLo g i nMo d ul e does not interact with the JAAS LoginModule operations.
Examp le 16 .22. Jn d iU serAn d PassLo g in Mo d u le C u st o m Lo g in Mo d u le

p ackage org.jboss.book.security.ex2;
i mport
i mport
i mport
i mport
i mport
i mport
java.security.acl.Group;
java.util.Map;
javax.naming.InitialContext;
javax.naming.NamingException;
javax.security.auth.Subject;
javax.security.auth.callback.CallbackHandler;
273
i mport javax.security.auth.login.LoginException;
i mport org.jboss.logging.Logger;
i mport org.jboss.security.SimpleGroup;
i mport org.jboss.security.SimplePrincipal;
i mport 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
*/
p ublic 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 */
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));
}
}
/**
274
* 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));
}
}
Examp le 16 .23. D ef in it io n o f secu rit y- ex2 secu rit y d o main wit h t h e n ewly- creat ed
cu st o m lo g in mo d u le
/subsystem=security/security-domain=security-ex2/:add
/subsystem=security/security-domain=securityex2/authentication=classic:add
/subsystem=security/security-domain=securityex2/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")]\
)
The choice of using the Jnd i UserAnd P assLo g i nMo d ul e custom login module for the server side
authentication of the user is determined by the login configuration for the example security domain.
The EJB JAR MET A-INF/jbo ss-ejb3. xml descriptor sets the security domain. For a web
application it is part of the WEB-INF/jbo ss-web. xml file.
Examp le 16 .24 . jbo ss-ejb3. xml Examp le

< ?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">
<s:security>
<ejb-name>*</ejb-name>
<s:security-domain>security-ex2</s:security-domain>
</s:security>
< /jboss:ejb-jar>
275
Examp le 16 .25. jbo ss-web. xml exampl e

< ?xml version="1.0"?>
< jboss-web>
<security-domain>security-ex2</security-domain>
< /jboss-web>
Report a bug
276
Chapter 17. Role-Based Security in Applications

17.1. Java Aut hent icat ion and Aut horiz at ion Service (JAAS)
Java Authentication and Authorization Service (JAAS) is a security API which consists of a set of Java
packages designed for user authentication and authorization. The API is a Java implementation of
the standard Pluggable Authentication Modules (PAM) framework. It extends the Java Enterprise
Edition access control architecture to support user-based authorization.
In JBoss EAP 6, JAAS only provides declarative role-based security. For more information about
declarative security, refer to Section 10.2, D eclarative Security .
JAAS is independent of any underlying authentication technologies, such as Kerberos or LD AP. You
can change your underlying security structure without changing your application. You only need to
change the JAAS configuration.
Report a bug
17.2. About Java Aut hent icat ion and Aut horiz at ion Service (JAAS)
The security architecture of JBoss EAP 6 is comprised of the security configuration subsystem, and
application-specific security configurations which are included in several configuration files within
the application.
D o main , Server G ro u p , an d Server Sp ecif ic C o n f ig u rat io n
Server groups (in a managed domain) and servers (in a standalone server) include the configuration
for security domains. A security domain includes information about a combination of authentication,
authorization, mapping, and auditing modules, with configuration details. An application specifies
which security domain it requires, by name, in its jbo ss-web. xml .
Ap p licat io n - sp ecif ic C o n f ig u rat io n
Application-specific configuration takes place in one or more of the following four files.
T ab le 17.1. Ap p licat io n - Sp ecif ic C o n f ig u rat io n Files
File
D escrip t io n
ejb-jar.xml
The deployment descriptor for an Enterprise

JavaBean (EJB) application, located in the
MET A-INF directory of the archive. Use the
ejb-jar. xml to specify roles and map them to
principals, at the application level. You can also
limit specific methods and classes to certain
roles. It is also used for other EJB-specific
configuration not related to security.
277
File
D escrip t io n
web.xml
The deployment descriptor for a Java Enterprise

Edition (EE) web application. Use the web. xml
to declare the resource and transport
constraints for the application, such as limiting
the type of HTTP requests that are allowed. You
can also configure simple web-based
authentication in this file. It is also used for other
application-specific configuration not related to
security. The security domain the application
uses for authentication and authorization is
defined in jbo ss-web. xml .
Contains JBoss-specific extensions to the ejbjar. xml descriptor.
Contains JBoss-specific extensions to the
web. xml descriptor.
jboss-ejb3.xml
jboss-web.xml
Note
The ejb-jar. xml and web. xml are defined in the Java Enterprise Edition (Java EE)
specification. The jbo ss-ejb3. xml provides JBoss-specific extensions for the ejbjar. xml , and the jbo ss-web. xml provides JBoss-specific extensions for the web. xml .
Report a bug
17.3. Use a Securit y Domain in Your Applicat ion

O verview
To use a security domain in your application, first you need to define the security domain in the
server's configuration and then enable it for an application in the application's deployment
descriptor. Then you must add the required annotations to the EJB that uses it. This topic covers the
steps required to use a security domain in your application.
Warning
If an application is part of a security domain that uses an authentication cache, user
authentications for that application will also be available to other applications in that security
domain.
Pro ced u re 17.1. C o n f ig u re Yo u r Ap p licat io n t o U se a Secu rit y D o main

1. D ef in e t h e Secu rit y D o main
You need to define the security domain in the server's configuration file, and then enable it for
an application in the application's descriptor file.
a. C o n f ig u re t h e secu rit y d o main in t h e server' s co n f ig u rat io n f ile
The security domain is configured in the securi ty subsystem of the server's
278
Chapt er 1 7 . Role- Based Securit y in Applicat ions
configuration file. If the JBoss EAP 6 instance is running in a managed domain, this
is the d o mai n/co nfi g urati o n/d o mai n. xml file. If the JBoss EAP 6 instance is
running as a standalone server, this is the
stand al o ne/co nfi g urati o n/stand al o ne. xml file.
The o ther, jbo ss-web-po l i cy, and jbo ss-ejb-po l i cy security domains are
provided by default in JBoss EAP 6. The following XML example was copied from the
securi ty subsystem in the server's configuration file.
The cache-type attribute of a security domain specifies a cache for faster
authentication checks. Allowed values are d efaul t to use a simple map as the
cache, or i nfi ni span to use an Infinispan cache.
<security-domains>
<authentication>
<login-module code="Remoting"
flag="optional">
</login-module>
<login-module code="RealmDirect"
flag="required">
</login-module>
</authentication>
</security-domain>
<security-domain name="jboss-web-policy" cachetype="default">
<authorization>
flag="required"/>
</authorization>
</security-domain>
<security-domain name="jboss-ejb-policy" cachetype="default">
<authorization>
flag="required"/>
</authorization>
</security-domain>
</security-domains>
< /subsystem>
You can configure additional security domains as needed using the Management
Console or CLI.
b. En ab le t h e secu rit y d o main in t h e ap p licat io n ' s d escrip t o r f ile
The security domain is specified in the <securi ty-d o mai n> child element of the
<jbo ss-web> element in the application's WEB-INF/jbo ss-web. xml file. The
following example configures a security domain named my-d o mai n.
279
< jboss-web>
<security-domain>my-domain</security-domain>
< /jboss-web>
This is only one of many settings which you can specify in the WEB-INF/jbo ssweb. xml descriptor.
2. Ad d t h e R eq u ired An n o t at io n t o t h e EJB
You configure security in the EJB using the @ Securi tyD o mai n and @ R o l esAl l o wed
annotations. The following EJB code example limits access to the o ther security domain by
users in the g uest role.
p ackage example.ejb3;
i mport
i mport
i mport
i mport
javax.annotation.Resource;
javax.annotation.security.RolesAllowed;
javax.ejb.SessionContext;
javax.ejb.Stateless;
i mport 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" })
p ublic 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();
}
For more code examples, see the ejb-securi ty quickstart in the JBoss EAP 6 Quickstarts
bundle, which is available from the Red Hat Customer Portal.
Report a bug
17.4 . Use Role-Based Securit y In Servlet s

280
To add security to a servlet, you map each servlet to a URL pattern, and create security constraints
on the 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 jbo ss-web. xml .
Prereq u isit es
Before you use role-based security in a servlet, the security domain used to authenticate and
authorize access needs to be configured in the JBoss EAP 6 container.
Pro ced u re 17.2. Ad d R o le- B ased Secu rit y t o Servlet s
1. Ad d map p in g s b et ween servlet s an d U R L p at t ern s.
Use <servl et-mappi ng > elements in the web. xml to map individual servlets to URL
patterns. The following example maps the servlet called D i spl ayO pR esul t to the URL
pattern /D i spl ayO pR esul t.
< servlet-mapping>
<servlet-name>DisplayOpResult</servlet-name>
<url-pattern>/DisplayOpResult</url-pattern>
< /servlet-mapping>
2. Ad d secu rit y co n st rain t s t o t h e U R L p at t ern s.

To map the URL pattern to a security constraint, use a <securi ty-co nstrai nt>. The
following example constrains access from the URL pattern /D i spl ayO pR esul t to be
accessed by principals with the role eap_ad mi n. The role needs to be present in the security
domain.
<display-name>Restrict access to role eap_admin</display-name>
<web-resource-name>Restrict access to role eap_admin</webresource-name>
<url-pattern>/DisplayOpResult/*</url-pattern>
<auth-constraint>
<role-name>eap_admin</role-name>
</auth-constraint>
< /security-constraint>
< security-role>
< /security-role>
< login-config>
< /login-config>
281
You need to specify the authentication method, which can be any of the following: BASIC ,
FO R M, D IG EST , C LIENT -C ER T , SP NEG O . This example uses BASIC authentication.
3. Sp ecif y t h e secu rit y d o main in t h e WAR ' s jbo ss-web. xml
Add the security domain to the WAR's jbo ss-web. xml in order to connect the servlets to the
configured security domain, which knows how to authenticate and authorize principals
against the security constraints. The following example uses the security domain called
acme_d o mai n.
< jboss-web>
...
<security-domain>acme_domain</security-domain>
...
< /jboss-web>
Examp le 17.1. Examp le web. xml wit h R o le- B ased Secu rit y C o n f ig u red
< web-app xmlns="http://java.sun.com/xml/ns/javaee"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
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>
<display-name>Restrict access to role eap_admin</display-name>
<web-resource-name>Restrict access to role eap_admin</webresource-name>
<url-pattern>/DisplayOpResult/*</url-pattern>
<auth-constraint>
</auth-constraint>
282
<security-role>
</security-role>
<login-config>
</login-config>
< /web-app>
Report a bug
17.5. Use A T hird-Part y Aut hent icat ion Syst em In Your Applicat ion
You can integrate third-party security systems with JBoss EAP 6. These types of systems are usually
token-based. The external system performs the authentication and passes a token back to the Web
application through the request headers. This is often referred to as perimeter authentication. To
configure perimeter authentication in your application, add a custom authentication valve. If you
have a valve from a third-party provider, be sure it is in your classpath and follow the examples
below, along with 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
co ntext. xml deployment descriptor. Valves are configured directly in the jbo ss-web. xml
descriptor instead. The co ntext. xml is now ignored.
Examp le 17.2. B asic Au t h en t icat io n Valve

< jboss-web>
<valve>
<classname>org.jboss.security.negotiation.NegotiationAuthenticator</classname>
</valve>
< /jboss-web>
This valve is used for Kerberos-based SSO. It also shows the most simple pattern for specifying a
third-party authenticator for your Web application.
Examp le 17.3. C u st o m Valve Wit h H ead er At t rib u t es Set

< jboss-web>
<valve>
<classname>org.jboss.web.tomcat.security.GenericHeaderAuthenticator</classname>
<param>
<param-name>httpHeaderForSSOAuth</param-name>
<param-value>sm_ssoid,ct-remote-user,HTTP_OBLIX_UID</param-value>
</param>
<param>
283
<param-name>sessionCookieForSSOAuth</param-name>
<param-value>SMSESSION,CTSESSION,ObSSOCookie</param-value>
</param>
</valve>
< /jboss-web>
This example shows how to set custom attributes on your valve. The authenticator checks for the
presence of the header ID and the session key, and passes them into the JAAS framework which
drives the security layer, as the username and password value. You need a custom JAAS login
module which can process the username and password and populate the subject with the correct
roles. If no header values match the configured values, regular form-based authentication
semantics apply.
Writ in g a C u st o m Au t h en t icat o r
Writing your own authenticator is out of scope of this document. However, the following Java code is
provided as an example.
Examp le 17.4 . G en ericH ead erAu t h en t icat o r.java

/ *
* 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.
*
* 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.
*/
p ackage org.jboss.web.tomcat.security;
i mport java.io.IOException;
i mport java.util.StringTokenizer;
i mport
i mport
i mport
i mport
i mport
284
javax.management.JMException;
javax.management.ObjectName;
javax.servlet.http.Cookie;
javax.servlet.http.HttpServletRequest;
javax.servlet.http.HttpServletResponse;
i mport
i mport
i mport
i mport
i mport
i mport
i mport
org.apache.catalina.Realm;
org.apache.catalina.Session;
org.apache.catalina.authenticator.Constants;
org.apache.catalina.connector.Request;
org.apache.catalina.connector.Response;
org.apache.catalina.deploy.LoginConfig;
org.jboss.logging.Logger;
i mport 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
*/
p ublic class GenericHeaderAuthenticator extends
ExtendedFormAuthenticator {
protected static Logger log = Logger
.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;
}
285
/**
* <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
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) {
286
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);
// 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
287
*
* @ 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
*
* @ 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");
288
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(
"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());
289
return cookie.getValue();
}
return null;
}
}
Report a bug
290
Chapter 18. Migration

18.1. Configure Applicat ion Securit y Changes
C o n f ig u re secu rit y f o r b asic au t h en t icat io n
In previous versions of JBoss EAP, properties files placed in the
EAP_HOME/server/SERVER_NAME/co nf/ directory were on classpath and could be easily found
by the UsersR o l esLo g i nMo d ul e. In JBoss EAP 6, the directory structure has changed. Properties
files must 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 be
persisted on server restart.
To configure security for basic authentication, add a new security domain under securi tyd o mai ns to the stand al o ne/co nfi g urati o n/stand al o ne. xml or the
d o mai n/co nfi g urati o n/d o mai n. xml server configuration file:
< security-domain name="example">
<authentication>
<module-option name="usersProperties"
value="${jboss.server.config.dir}/exampleusers.properties"/>
<module-option name="rolesProperties"
value="${jboss.server.config.dir}/exampleroles.properties"/>
</login-module>
</authentication>
< /security-domain>
If the JBoss EAP 6 instance is running as a standalone server, ${jbo ss. server. co nfi g . d i r}
refers to the EAP_HOME/stand al o ne/co nfi g urati o n/ directory. If the instance is running in a
managed domain, ${jbo ss. server. co nfi g . d i r} refers to the
EAP_HOME/d o mai n/co nfi g urati o n/ directory.
Mo d if y secu rit y d o main n ames
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 the
jbo ss-web. xml .
For Enterprise applications, you must remove this prefix from the security domain configurations
in the jbo ss-ejb3. xml file. This file has replaced the jbo ss. xml in JBoss EAP 6.
Report a bug
291
Reference
A.1. Included Aut hent icat ion Modules
The following authentication modules are included in JBoss EAP 6. Some of these handle
authorization as well as authentication. These usually include the word R o l e within the C o d e name.
When you configure these modules, use the C o d e value or the full (package qualified) name to refer
to the module.
Au t h en t icat io n Mo d u les
Table A.1, R eal mD i rect
Table A.2, R eal mD i rect Module Options
Table A.3, C l i ent
Table A.4, C l i ent Module Options
Table A.5, R emo ti ng
Table A.6, R emo ti ng Module Options
Table A.7, C erti fi cate
Table A.8, C erti fi cate Module Options
Table A.9, C erti fi cateR o l es
Table A.10, C erti fi cateR o l es Module Options
Table A.11, D atabase
Table A.12, D atabase Module Options
Table A.13, D atabaseC erti fi cate
Table A.14, D atabaseC erti fi cate Module Options
Table A.15, Id enti ty
Table A.16, Id enti ty Module Options
Table A.17, Ld ap
Table A.18, Ld ap Module Options
Table A.19, Ld apExtend ed
Table A.20, Ld apExtend ed Module Options
Table A.21, R o l eMappi ng
Table A.22, R o l eMappi ng Module Options
Table A.23, R unAs
Table A.24, R unAs Options
292
Reference
Table A.25, Si mpl e

Table A.26, C o nfi g ured Id enti ty
Table A.27, C o nfi g ured Id enti ty Module Options
Table A.28, SecureId enti ty
Table A.29, SecureId enti ty Module Options
Table A.30, P ro perti esUsers
Table A.31, Si mpl eUsers
Table A.32, Ld apUsers
Table A.33, Kerbero s
Table A.34, Kerbero s Module Options
Table A.35, SP NEG O
Table A.36, SP NEG O Module Options
Table A.37, Ad vanced Ld ap
Table A.38, Ad vanced Ld ap Module Options
Table A.39, Ad vanced AD Ld ap
Table A.40, UsersR o l es
Table A.41, UsersR o l es Module Options
Custom Authentication Modules
T ab le A.1. R eal mD i rect
Code
Class
R eal mD i rect
o rg . jbo ss. as. securi ty. R eal mD i rectLo
g i nMo d ul e
A login module implementation to interface
directly with the security realm. This login
module allows all interactions with the backing
store to be delegated to the realm removing the
need for any duplicate and synchronized
definitions. Used for remoting calls and
management interface.
D escription
T ab le A.2. R eal mD i rect Mo d u le O p t io n s

O p t io n
T yp e
D ef au lt
D escrip t io n
real m
string
Appl i cati o nR eal m
Name of the desired

realm.
T ab le A.3. C l i ent
Code
C l i ent
293
Class
o rg . jbo ss. securi ty. C l i entLo g i nMo d u

le
This login module is designed to establish caller
identity and credentials when JBoss EAP 6 is
acting as a client. It should never be used as
part of a security domain used for server
authentication.
D escription
T ab le A.4 . C l i ent Mo d u le O p t io n s
O p t io n
T yp e
D ef au lt
D escrip t io n
mul ti -thread ed
true or fal se
fal se
passwo rd -stacki ng
useFi rstP ass or

fal se
fal se
resto re-l o g i ni d enti ty
true or fal se
fal se
Set to true if each

thread has its own
principal and
credential storage. Set
to false to indicate that
all threads in the VM
share the same identity
and credential.
Set to useFi rstP ass
to indicate that this
login module should
look for information
stored in the
Lo g i nC o ntext to use
as the identity. This
option can be used
when stacking other
login modules with this
one.
Set to true if the identity
and credential seen at
the start of the
l o g i n() method
should be restored
after the l o g o ut()
method is invoked.
T ab le A.5. R emo ti ng
Code
Class
D escription
T ab le A.6 . R emo ti ng Mo d u le O p t io n s
294
R emo ti ng
o rg . jbo ss. as. securi ty. remo ti ng . R emo
ti ng Lo g i nMo d ul e
This login module is used to check if the request
currently being authenticated is a request
received over a Remoting connection, and if so
the identity that was created during the
Remoting authentication process is used and
associated with the current request. If the
request did not arrive over a Remoting
connection this module does nothing and
allows the JAAS based login to continue to the
next module.
Reference
T ab le A.6 . R emo ti ng Mo d u le O p t io n s
O p t io n
T yp e
D ef au lt
D escrip t io n
useFi rstP ass or

fal se
fal se
pri nci pal C l ass
A fully-qualified
classname.
none
unauthenti cated Id
enti ty
A principal name.
none
A value of
useFi rstP ass
indicates that this login
module should first
look to the information
stored in the
Lo g i nC o ntext for the
identity. This option
can be used when
stacking other login
modules with this one.
A P ri nci pal
implementation class
which contains a
constructor that takes
String arguments for
the principal name.
D efines the principal
name assigned to
requests which contain
no authentication
information. This can
allow unprotected
servlets to invoke
methods on EJBs that
do not require a
specific role. Such a
principal has no
associated roles and
can only access
unsecured EJBs or
EJB methods that are
associated with the
unchecked
permi ssi o n
constraint.
T ab le A.7. C erti fi cate

Code
Class
C erti fi cate
o rg . jbo ss. securi ty. auth. spi . BaseC er
tLo g i nMo d ul e
This login module is designed to authenticate
users based on X50 9 C erti fi cates. A use
case for this is C LIENT -C ER T authentication of
a web application.
D escription
T ab le A.8. C erti fi cate Mo d u le O p t io n s

O p t io n
T yp e
D ef au lt
D escrip t io n
295
O p t io n
T yp e
D ef au lt
D escrip t io n
securi tyD o mai n
string
o ther
veri fi er
class
none
Name of the security

domain that has the
JSSE configuration for
the truststore holding
the trusted certificates.
The class name of the
o rg . jbo ss. securi t
y. auth. certs. X50 9
C erti fi cateVeri fi
er to use for
verification of the login
certificate.
T ab le A.9 . C erti fi cateR o l es

Code
Class
C erti fi cateR o l es
o rg . jbo ss. securi ty. auth. spi . C ertR o l
esLo g i nMo d ul e
This login module extends the Certificate login
module to add role mapping capabilities from a
properties file. It takes all of the same options as
the Certificate login module, and adds the
following options.
D escription
T ab le A.10. C erti fi cateR o l es Mo d u le O p t io n s

O p t io n
T yp e
D ef au lt
D escrip t io n
ro l esP ro perti es
string
ro l es. pro perti es
The name of the

resource or file
containing the roles to
assign to each user.
The role properties file
must be in the format
username= ro l e1,ro
l e2 where the
username is the D N of
the certificate,
escaping any =
(equals) and space
characters. The
following example is in
the correct format:
CN\=unittests-client,\
OU\=Red\ Hat\
Inc.,\ O\=Red\
Hat\ Inc.,\
ST\=North\
Carolina,\
C\=US
296
Reference
O p t io n
T yp e
D ef au lt
D escrip t io n
d efaul tR o l esP ro p
erti es
string
d efaul tR o l es. pro

perti es
ro l eG ro upSeparato
r
A single character.
. (a single period)
Name of the resource

or file to fall back to if
the
file cannot be found.
Which character to use
as the role group
separator in the
file.
T ab le A.11. D atabase
Code
Class
D atabase
o rg . jbo ss. securi ty. auth. spi . D atabas
eServerLo g i nMo d ul e
A JD BC-based login module that supports
authentication and role mapping. It is based on
two logical tables, with the following definitions.
D escription
P ri nci pal s: P ri nci pal ID (text),

P asswo rd (text)
R o l es: P ri nci pal ID (text), R o l e
(text), R o l eG ro up (text)
T ab le A.12. D atabase Mo d u le O p t io n s
O p t io n
T yp e
D ef au lt
D escrip t io n
d i g estC al l ba
ck
A fully-qualified
classname
none
d sJnd i Name
A JND I resource
java: /D efaul t
DS
hashAl g o ri thm
String
Use plain
passwords
hashC harset
String
The platform's
default encoding

D i g estC al l back implementation
that includes pre/post digest content
like salts for hashing the input
password. Only used if
hashAl g o ri thm has been specified.
The name of the JND I resource storing
the authentication information. This
option is required.
The message digest algorithm used to
hash passwords. Supported
algorithms depend on the Java
Security Provider, but the following
are supported: MD 5, SHA-1, and SHA256 .
The name of the charset/encoding to
use when converting the password
String to a byte array. This includes
all supported Java charset names.
The string encoding format to use.
A flag indicating if the password
comparison should ignore case.
hashEnco d i ng
String
i g no reP asswo r boolean
d C ase
Base64
false
297
O p t io n
T yp e
D ef au lt
D escrip t io n
i nputVal i d ato
r
A fully-qualified
classname
none
pri nci pal sQ ue

ry
prepared SQL
statement
The instance of the InputValidator

implementation used to validate the
username and password supplied by
the client.
The prepared SQL query to obtain the
information about the principal.
ro l esQ uery
prepared SQL
statement
sto reD i g estC a

l l back
A fully-qualified
classname
suspend R esume
boolean
thro wVal i d ato

rErro r
boolean
transacti o nMa
nag erJnd i Name
JND I Resource
sel ect
P asswo rd fro m
P ri nci pal s
where
P ri nci pal ID = ?
none
The prepared SQL query to obtain the
information about the roles. It should
be equivalent to sel ect R o l e,
R o l eG ro up fro m R o l es where
P ri nci pal ID = ?, where Role is the
role name and the RoleGroup column
value should always be either R o l es
with a capital R or
none
D i g estC al l back implementation
that includes pre/post digest content
like salts for hashing the
store/expected password. Only used if
hashSto reP asswo rd or
hashUserP asswo rd is true and
hashAl g o ri thm has been specified.
true
Whether any existing JTA transaction
should be suspended during
database operations.
false
A flag that indicates whether
validation errors should be exposed
to clients or not
java:/Transaction The JND I name of the transaction
Manager
manager used by the login module.
T ab le A.13. D atabaseC erti fi cate

Code
Class
D atabaseC erti fi cate

o rg . jbo ss. securi ty. auth. spi . D atabas
eC ertLo g i nMo d ul e
This login module extends the Certificate login
module to add role mapping capabilities from a
database table. It has the same options plus
these additional options:
D escription
T ab le A.14 . D atabaseC erti fi cate Mo d u le O p t io n s

O p t io n
T yp e
D ef au lt
D escrip t io n
d sJnd i Name
A JND I resource
java: /D efaul tD S
The name of the JND I

resource storing the
authentication
information. This
option is required.
298
Reference
O p t io n
T yp e
D ef au lt
D escrip t io n
ro l esQ uery
prepared SQL
statement
sel ect
R o l e,R o l eG ro up
fro m R o l es where
P ri nci pal ID = ?
suspend R esume
true or fal se
true
SQL prepared
statement to be
executed in order to
map roles. It should be
an equivalent to
sel ect R o l e,
R o l eG ro up fro m
R o l es where
P ri nci pal ID = ?,
where Role is the role
name and the
RoleGroup column
value should always
be either R o l es with a
capital R or
Whether any existing
JTA transaction should
be suspended during
database operations.
T ab le A.15. Id enti ty
Code
Class
Id enti ty
o rg . jbo ss. securi ty. auth. spi . Id enti t
yLo g i nMo d ul e
Associates the principal specified in the module
options with any subject authenticated against
the module. The type of Principal class used is
o rg . jbo ss. securi ty. Si mpl eP ri nci pal .
If no principal option is specified a principal
with the name of g uest is used.
D escription
T ab le A.16 . Id enti ty Mo d u le O p t io n s
O p t io n
T yp e
D ef au lt
D escrip t io n
pri nci pal
String
g uest
ro l es
comma-separated list
of strings
none
The name to use for the

principal.
A comma-delimited list
of roles which will be
assigned to the
subject.
T ab le A.17. Ld ap
Code
Class
Ld ap
o rg . jbo ss. securi ty. auth. spi . Ld apLo g
i nMo d ul e
299
D escription
Authenticates against an LD AP server, when the

username and password are stored in an LD AP
server that is accessible using a JND I LD AP
provider. Many of the options are not required,
because they are determined by the LD AP
provider or the environment.
T ab le A.18. Ld ap Mo d u le O p t io n s
O p t io n
T yp e
D ef au lt
java. nami ng . fact

o ry. i ni ti al
class name
co m. sun. jnd i . l d a
p. Ld apC txFacto ry
java. nami ng . pro v

i d er. url
l d ap: // URL
java. nami ng . secu

ri ty. authenti cati
on
ri ty. pro to co l
no ne, si mpl e, or the

name of a SASL
mechanism
transport protocol

ri ty. pri nci pal
string

ri ty. cred enti al s
credential type
300
D escrip t io n
Ini ti al C o ntextFac
to ry implementation
class name.
If the value of
URL for the LD AP
java. nami ng . secur server.
i ty. pro to co l is
SSL,
l d ap: //l o cal ho st
: 6 36 , otherwise
: 389
si mpl e
The security level to
use to bind to the
LD AP server.
If unspecified,
The transport protocol
determined by the
to use for secure
provider.
access, such as SSL.
none
The name of the
principal for
authenticating the
caller to the service.
This is built from other
properties described
below.
none
The type of credential
used by the
authentication scheme.
Some examples
include hashed
password, clear-text
password, key, or
certificate. If this
property is unspecified,
the behavior is
determined by the
service provider.
Reference
O p t io n
T yp e
pri nci pal D NP refi

x
string
pri nci pal D NSuffi

x
string
useO bjectC red enti

al
true or fal se
false
ro l esC txD N
fully-qualified D N
none
userR o l esC txD NAtt attribute

ri buteName
ro l eAttri buteID
attribute
D ef au lt
none
ro l es
D escrip t io n
Prefix added to the
username to form the
user D N. You can
prompt the user for a
username and build
the fully-qualified D N
by using the
pri nci pal D NP refi x
and
pri nci pal D NSuffi x
.
Suffix added to the
username to form the
user D N. You can
prompt the user for a
username and build
the fully-qualified D N
by using the
pri nci pal D NP refi x
and
pri nci pal D NSuffi x
.
Whether the credential
should be obtained as
an opaque Object
using the
o rg . jbo ss. securi t
y. auth. cal l back.
O bjectC al l back
type of Callback rather
than as a char[]
password using a
JAAS
PasswordCallback.
This allows for passing
no n-char[]
credential information
to the LD AP server.
The fully-qualified D N
for the context to
search for user roles.
The attribute in the
user object that
contains the D N for the
context to search for
user roles. This differs
from ro l esC txD N in
that the context to
search for a user's
roles may be unique
for each user.
Name of the attribute
containing the user
roles.
301
O p t io n
T yp e
D ef au lt
D escrip t io n
ro l eAttri buteIsD N
true or fal se
fal se
ro l eNameAttri bute
ID
attribute
name
ui d Attri buteID
attribute
ui d
matchO nUserD N
true or fal se
fal se
al l o wEmptyP asswo
rd s
true or fal se
fal se
Whether or not the

ro l eAttri buteID
contains the fullyqualified D N of a role
object. If false, the role
name is taken from the
value of the
Id attribute of the
context name. Certain
directory schemas,
such as Microsoft
Active D irectory,
require this attribute to
be set to true.
within the ro l eC txD N
context which contains
the role name. If the
property is set to true,
this property is used to
find the role object's
name attribute.
Name of the attribute in
the
UserR o l esAttri but
eD N that corresponds
to the user ID . This is
used to locate the user
roles.
Whether or not the
search for user roles
should match on the
user's fullydistinguished D N or
the username only. If
true, the full user D N
is used as the match
value. If fal se, only
the username is used
as the match value
against the
ui d Attri buteName
attribute.
Whether to allow empty
passwords. Most LD AP
servers treat empty
passwords as
anonymous login
attempts. To reject
empty passwords, set
this to fal se.
T ab le A.19 . Ld apExtend ed
302
Reference
T ab le A.19 . Ld apExtend ed
Code
Class
Ld apExtend ed
o rg . jbo ss. securi ty. auth. spi . Ld apExt
Lo g i nMo d ul e
An alternate LD AP login module implementation
that uses searches to locate the bind user and
associated roles. The roles query recursively
follows D Ns to navigate a hierarchical role
structure. It uses the same java. nami ng
options as the Ldap module, and uses the
following options instead of the other options of
the Ldap module.
D escription
The authentication happens in 2 steps:

1. An initial bind to the LD AP server is done
using the bindD N and
bi nd C red enti al options. The
bi nd D N is a LD AP user with the ability
to search both the baseCtxD N and
ro l esC txD N trees for the user and
roles. The user D N to authenticate
against is queried using the filter
specified by the baseFi l ter attribute.
2. The resulting user D N is authenticated
by binding to the LD AP server using the
user D N as the Ini ti al Ld apC o ntext
environment
C o ntext. SEC UR IT Y _P R INC IP AL.
The
C o ntext. SEC UR IT Y _C R ED ENT IALS
property is set to the String password
obtained by the callback handler.
T ab le A.20. Ld apExtend ed Mo d u le O p t io n s
O p t io n
T yp e
D ef au lt
D escrip t io n
baseC txD N
fully-qualified D N
none
bi nd C red enti al
string, optionally
encrypted
none
bi nd D N
fully-qualified D N
none
The fixed D N of the

top-level context to
begin the user search.
See Section 16.1.14,
bindCredential
Module Option for
details.
The D N used to bind
against the LD AP
server for the user and
roles queries. This D N
needs read and search
permissions on the
baseC txD N and
ro l esC txD N values.
303
O p t io n
T yp e
D ef au lt
D escrip t io n
baseFi l ter
LD AP filter string
none
ro l esC txD N
fully-qualified D N
none
ro l eFi l ter
LD AP filter string
none
A search filter used to

locate the context of
the user to
authenticate. The input
username or userD N
obtained from the login
module callback is
substituted into the
filter anywhere a {0 }
expression is used. A
common example for
the search filter is
(ui d = {0 }).
The fixed D N of the
context to search for
user roles. This is not
the D N where the
actual roles are, but
the D N where the
objects containing the
user roles are. For
example, in a Microsoft
Active D irectory server,
this is the D N where the
user account is.
A search filter used to
locate the roles
associated with the
authenticated user.
The input username or
userD N obtained from
the login module
callback is substituted
into the filter anywhere
a {0 } expression is
used. The
authenticated userD N
is substituted into the
filter anywhere a {1} is
used. An example
search filter that
matches on the input
username is (member=
{0 }). An alternative
that matches on the
authenticated userD N
is (member= {1}).
304
Reference
O p t io n
T yp e
D ef au lt
D escrip t io n
true or fal se
fal se
d efaul tR o l e
Role name
none
Whether or not the

ro l eAttri buteID
contains the fullyqualified D N of a role
object. If false, the role
name is taken from the
value of the
Id attribute of the
context name. Certain
directory schemas,
such as Microsoft
Active D irectory,
require this attribute to
be set to true.
A role included for all
authenticated users
A flag indicating if the
D N returned by a query
contains the
roleNameAttributeID . If
set to true, the D N is
checked for the
roleNameATtributeID . If
set to fal se, the D N is
not checked for the
roleNameAttributeID .
This flag can improve
the performance of
LD AP queries.
A flag indicating if the
D N is to be parsed for
the username. If set to
true, the D N is parsed
for the username. If set
to fal se the D N is not
parsed for the
username. This option
is used together with
usernameBeginString
and
usernameEndString.
D efines the string
which is to be removed
from the start of the D N
to reveal the username.
This option is used
together with
usernameEnd Stri ng .
parseR o l eNameFro m true or fal se

DN
fal se
parseUsername
true or fal se
fal se
usernameBeg i nStri
ng
string
none
305
O p t io n
T yp e
D ef au lt
D escrip t io n
usernameEnd Stri ng
string
none
ID
attribute
name
d i sti ng ui shed Nam

eAttri bute
attribute
d i sti ng ui shed Nam

e
ro l eR ecursi o n
integer
searchT i meLi mi t
integer
10 0 0 0 (10 seconds)
searchSco pe
One of:
O BJEC T _SC O P E,
O NELEVEL_SC O P E,
SUBT R EE_SC O P E
true or fal se
SUBT R EE_SC O P E
D efines the string

which is to be removed
from the end of the D N
to reveal the username.
This option is used
together with
usernameBeg i nStri
ng .
within the ro l eC txD N
context which contains
the role name. If the
property is set to true,
this property is used to
find the role object's
name attribute.
The name of the
attribute in the user
entry that contains the
D N of the user. This
may be necessary if the
D N of the user itself
contains special
characters (backslash
for example) that
prevent correct user
mapping. If the
attribute does not exist,
the entry's D N is used.
The numbers of levels
of recursion the role
search will go below a
matching context.
D isable recursion by
setting this to 0 .
The timeout in
milliseconds for user or
role searches.
The search scope to
use.
al l o wEmptyP asswo
rd s
306
fal se
Whether to allow empty

passwords. Most LD AP
servers treat empty
passwords as
anonymous login
attempts. To reject
empty passwords, set
this to false.
Reference
O p t io n
T yp e
referral UserAttri b attribute

uteID T o C heck
D ef au lt
D escrip t io n
none
If you are not using

referrals, this option
can be ignored. When
using referrals, this
option denotes the
attribute name which
contains users defined
for a certain role (for
example, member), if
the role object is inside
the referral. Users are
checked against the
content of this attribute
name. If this option is
not set, the check will
always fail, so role
objects cannot be
stored in a referral tree.
T ab le A.21. R o l eMappi ng
Code
Class
R o l eMappi ng
o rg . jbo ss. securi ty. auth. spi . R o l eMap
pi ng Lo g i nMo d ul e
Maps a role which is the end result of the
authentication process to a declarative role.
This module must be flagged as o pti o nal
when you add it to the security domain.
D escription
T ab le A.22. R o l eMappi ng Mo d u le O p t io n s
O p t io n
T yp e
D ef au lt
D escrip t io n
The fully-qualified file

path and name of a
properties file or
resource
no ne
repl aceR o l e
true or fal se
fal se
The fully-qualified file

path and name of a
properties file or
resource which maps
roles to replacement
roles. The format is
o ri g i nal _ro l e= ro
l e1,ro l e2,ro l e3
Whether to add to the
current roles, or
replace the current
roles with the mapped
ones. Replaces if set to
true.
Note
The ro l esP ro perti es module option is required for RoleMapping.
307
T ab le A.23. R unAs
Code
Class
R unAs
o rg . jbo ss. securi ty. auth. spi . R unAsLo
g i nMo d ul e
A helper module that pushes a run as role onto
the stack for the duration of the login phase of
authentication, and pops the run as role off the
stack in either the commit or abort phase. This
login module provides a role for other login
modules that must access secured resources in
order to perform their authentication, such as a
login module which accesses a secured EJB.
R unAsLo g i nMo d ul e must be configured
before the login modules that require a run as
role to be established.
D escription
T ab le A.24 . R unAs O p t io n s
O p t io n
T yp e
D ef au lt
D escrip t io n
ro l eName
role name
no bo d y
pri nci pal Name
principal name
no bo d y
pri nci pal C l ass
A fully-qualified
classname.
none
The name of the role to

use as the run as role
during the login phase.
Name of the principal
to use as the run as
principal during login
phase. If not specified
a default of no bo d y is
used.
A P ri nci pal
implementation class
which contains a
constructor that takes
String arguments for
the principal name.
T ab le A.25. Si mpl e
Code
Class
D escription
Si mpl e
o rg . jbo ss. securi ty. auth. spi . Si mpl eS
erverLo g i nMo d ul e
A module for quick setup of security for testing
purposes. It implements the following simple
algorithm:
If the password is null, authenticate the user
and assign an identity of g uest and a role
of g uest.
Otherwise, if the password is equal to the
user, assign an identity equal to the
username and both ad mi n and g uest roles.
Otherwise, authentication fails.
Si mpl e Mo d u le O p t io n s
308
Reference
Si mpl e Mo d u le O p t io n s
The Si mpl e module has no options.
T ab le A.26 . C o nfi g ured Id enti ty
Code
Class
C o nfi g ured Id enti ty

o rg . pi cketbo x. d ataso urce. securi ty. C
o nfi g ured Id enti tyLo g i nMo d ul e
Associates the principal specified in the module
options with any subject authenticated against
the module. The type of Principal class used is
o rg . jbo ss. securi ty. Si mpl eP ri nci pal .
D escription
T ab le A.27. C o nfi g ured Id enti ty Mo d u le O p t io n s

O p t io n
T yp e
D ef au lt
D escrip t io n
username
string
none
passwo rd
encrypted string
""
The username for

authentication.
The password to use
for authentication. To
encrypt the password,
use the module directly
at the command line.
java
o rg . pi cketbo x
. d ataso urce. s
ecuri ty. Secure
Id enti tyLo g i n
Mo d ul e
password_to_en
crypt
Paste the result of this
command into the
module option's value
field. The default value
is an empty string.
pri nci pal
Name of a principal
no ne
The principal which

will be associated with
any subject
authenticated against
the module.
T ab le A.28. SecureId enti ty

Code
Class
SecureId enti ty
o rg . pi cketbo x. d ataso urce. securi ty. S
ecureId enti tyLo g i nMo d ul e
309
D escription
This module is provided for legacy purposes. It

allows you to encrypt a password and then use
the encrypted password with a static principal. If
your application uses SecureId enti ty,
consider using a password vault mechanism
instead.
T ab le A.29 . SecureId enti ty Mo d u le O p t io n s

O p t io n
T yp e
D ef au lt
D escrip t io n
username
string
none
passwo rd
encrypted string
""
The username for

authentication.
The password to use
for authentication. To
encrypt the password,
use the module directly
at the command line.
java
o rg . pi cketbo x
. d ataso urce. s
ecuri ty. Secure
Id enti tyLo g i n
Mo d ul e
password_to_en
crypt
Paste the result of this
command into the
module option's value
field. The default value
is an empty string.
manag ed C o nnecti o
nFacto ryName
JCA resource
none
The name of the JCA

connection factory for
your datasource.
T ab le A.30. P ro perti esUsers

Code
Class
D escription
P ro perti esUsers
o rg . jbo ss. securi ty. auth. spi . P ro pert
i esUsersLo g i nMo d ul e
Uses a properties file to store usernames and
passwords for authentication. No authorization
(role mapping) is provided. This module is only
appropriate for testing.
T ab le A.31. Si mpl eUsers

Code
Class
310
Si mpl eUsers
o rg . jbo ss. securi ty. auth. spi . Si mpl eU
sersLo g i nMo d ul e
Reference
D escription
This login module stores the username and

clear-text password using module-option.
module-option's name and value attributes
specify a username and password. It is included
for testing only, and is not appropriate for a
production environment.
T ab le A.32. Ld apUsers
Code
Class
Ld apUsers
o rg . jbo ss. securi ty. auth. spi . Ld apUse
rsLo g i nMo d ul e
The Ld apUsers module is superseded by the
Extend ed LD AP and Ad vanced Ld ap modules.
D escription
T ab le A.33. Kerbero s
Code
Class
Kerbero s
co m. sun. securi ty. auth. mo d ul e. Krb5Lo
g i nMo d ul e. In the IBM JD K the classname is
co m. i bm. securi ty. auth. mo d ul e. Krb5Lo
g i nMo d ul e.
Performs Kerberos login authentication, using
GSSAPI. This module is part of the security
framework from the API provided by Sun
Microsystems. D etails can be found at
http://docs.oracle.com/javase/7/docs/jre/api/sec
urity/jaas/spec/com/sun/security/auth/module/Kr
b5LoginModule.html. This module needs to be
paired with another module which handles the
authentication and roles mapping.
D escription
T ab le A.34 . Kerbero s Mo d u le O p t io n s
O p t io n
T yp e
D ef au lt
D escrip t io n
sto rekey
true or fal se
false
d o No tP ro mpt
true or fal se
false
useT i cketC ache
Boolean value of true

or fal se .
false
Whether or not to add

the Kerbero sKey to
the subject's private
credentials.
If set to true, the user
is not prompted for the
password.
If true, the TGT is
obtained from the ticket
cache. If fal se, the
ticket cache is not
used.
311
O p t io n
T yp e
D ef au lt
D escrip t io n
ti cketcache
A file or resource
representing a
Kerberos ticket cache.
The default depends

on which operating
system you use.
The location of the

ticket cache.
Red Hat Enterprise

Linux / Solaris:
/tmp/krb5cc_uid,
using the numeric
UID value of the
operating system.
Microsoft Windows
Server: uses the
Local Security
Authority (LSA) API
to find the
ticketcache.
useKeyT ab
true or fal se
false
keytab
A file or resource
representing a
Kerberos keytab.
pri nci pal
string
the location in the

operating system's
Kerberos configuration
file, or
/ho me/user/krb5. k
eytab
none
useFi rstP ass
true or fal se
false
312
Whether to obtain the

principal's key from a
key table file.
The location of the key
table file.
The name of the

principal. This can
either be a simple user
name or a service
name such as
ho st/testserver. ac
me. co m. Use this
instead of obtaining
the principal from the
key table, or when the
key table contains
more than one
principal.
Whether to retrieve the
username and
password from the
module's shared state,
using
javax. securi ty. au
th. l o g i n. name and
javax. securi ty. au
th. l o g i n. passwo r
d as the keys. If
authentication fails, no
retry attempt is made.
Reference
O p t io n
T yp e
D ef au lt
D escrip t io n
tryFi rstP ass
true or fal se
false
sto reP ass
true or fal se
false
cl earP ass
true or fal se
false
Same as
useFi rstP ass, but if
authentication fails, the
module uses the
C al l backHand l er to
retrieve a new
username and
password. If the
second authentication
fails, the failure is
reported to the calling
application.
Whether to store the
username and
password in the
module's shared state.
This does not happen
if the keys already exist
in the shared state, or if
authentication fails.
Set this to true to clear
the username and
password from the
shared state after both
phases of
authentication
complete.
T ab le A.35. SP NEG O
Code
Class
SP NEG O
o rg . jbo ss. securi ty. neg o ti ati o n. spne
g o . SP NEG O Lo g i nMo d ul e
Allows SPNEGO authentication to a Microsoft
Active D irectory server or other environment
which supports SPNEGO. SPNEGO can also
carry Kerberos credentials. This module needs
to be paired with another module which handles
authentication and role mapping.
D escription
T ab le A.36 . SP NEG O Mo d u le O p t io n s
O p t io n
T yp e
D ef au lt
D escrip t io n
serverSecuri tyD o m
ai n
stri ng
nul l .
D efines the domain

that is used to retrieve
the identity of the
server service through
the kerberos login
module. This property
must be set.
313
O p t io n
T yp e
D ef au lt
D escrip t io n
remo veR eal mFro mP r bo o l ean

i nci pal
fal se
usernameP asswo rd D
o mai n
nul l
Specifies that the

Kerberos realm should
be removed from the
principal before further
processing.
Specifies another
security domain within
the configuration that
should be used as a
failover login when
Kerberos fails.
stri ng
T ab le A.37. Ad vanced Ld ap
Code
Class
Ad vanced Ld ap
o rg . jbo ss. securi ty. neg o ti ati o n. Ad va
nced Ld apLo g i nMo d ul e
A module which provides additional
functionality, such as SASL and the use of a
JAAS security domain.
D escription
T ab le A.38. Ad vanced Ld ap Mo d u le O p t io n s
O p t io n
T yp e
D ef au lt
bi nd Authenti cati o
n
string
none
java. nami ng . pro v

i d er. url
stri ng
baseC txD N
fully-qualified D N
baseFi l ter
String representing a
LD AP search filter.
ro l eAttri buteID
String value
representing an LD AP
attribute.
true or fal se
314
D escrip t io n
The type of SASL

authentication to use
for binding to the
directory server.
If the value of
The URI of the directory
java. nami ng . secur server.
i ty. pro to co l is
SSL,
: 6 86 , otherwise
: 389
none
The distinguished
name to use as the
base for searches.
none
The filter to use to
narrow down search
results.
none
The LD AP attribute
which contains the
names of authorization
roles.
fal se
Whether the role
attribute is a
D istinguished Name
(D N).
Reference
O p t io n
T yp e
D ef au lt
D escrip t io n
ID
String representing an
LD AP attribute.
none
recurseR o l es
true or fal se
fal se
The attribute contained

within the
R o l eAttri buteId
which contains the
actual role attribute.
Whether to recursively
search the
R o l eAttri buteId for
roles.
If you are not using
referrals, this option
can be ignored. When
using referrals, this
option denotes the
attribute name which
contains users defined
for a certain role (for
example, member), if
the role object is inside
the referral. Users are
checked against the
content of this attribute
name. If this option is
not set, the check will
always fail, so role
objects cannot be
stored in a referral tree.
referral UserAttri b attribute

uteID T o C heck
none
T ab le A.39 . Ad vanced AD Ld ap
Code
Class
Ad vanced AD Ld ap
o rg . jbo ss. securi ty. neg o ti ati o n. Ad va
nced AD Lo g i nMo d ul e
This module extends the Ad vanced Ld ap login
module, and adds extra parameters that are
relevant to Microsoft Active D irectory.
D escription
T ab le A.4 0. UsersR o l es
Code
Class
UsersR o l es
o rg . jbo ss. securi ty. auth. spi . UsersR o
l esLo g i nMo d ul
A simple login module that supports multiple
users and user roles stored in two different
properties files.
D escription
T ab le A.4 1. UsersR o l es Mo d u le O p t io n s
O p t io n
T yp e
D ef au lt
D escrip t io n
315
O p t io n
T yp e
D ef au lt
D escrip t io n
usersP ro perti es
Path to a file or
resource.
users. pro perti es
Path to a file or
resource.
ro l es. pro perti es
useFi rstP ass or

fal se
fal se
hashAl g o ri thm
String representing a
password hashing
algorithm.
no ne
hashEnco d i ng
base6 4 or hex
base6 4
The file or resource

which contains the
user-to-password
mappings. The format
of the file is
username= password
The file or resource
which contains the
user-to-role mappings.
The format of the file is
username= ro l e1,ro
l e2,ro l e3
A value of
useFi rstP ass
indicates that this login
module should first
look to the information
stored in the
Lo g i nC o ntext for the
identity. This option
can be used when
stacking other login
modules with this one.
The name of the
java. securi ty. Mes
sag eD i g est
algorithm to use to
hash the password.
There is no default so
this option must be
explicitly set to enable
hashing. When
hashAl g o ri thm is
specified, the clear text
password obtained
from the
C al l backHand l er is
hashed before it is
passed to
UsernameP asswo rd L
o g i nMo d ul e. val i d
ateP asswo rd as the
i nputP asswo rd
argument. The
password stored in the
users. pro perti es
file must be
comparably hashed.
The string format for
the hashed password,
if hashAlgorithm is
also set.
316
Reference
O p t io n
T yp e
D ef au lt
D escrip t io n
hashC harset
string
The default encoding

set in the container's
runtime environment
unauthenti cated Id
enti ty
principal name
none
The encoding used to

convert the clear-text
password to a byte
array.
D efines the principal
name assigned to
requests which contain
no authentication
information. This can
allow unprotected
servlets to invoke
methods on EJBs that
do not require a
specific role. Such a
principal has no
associated roles and
can only access
unsecured EJBs or
EJB methods that are
associated with the
unchecked
permi ssi o n
constraint.
C u st o m Au t h en t icat io n Mo d u les
Authentication modules are implementations of javax. securi ty. auth. spi . Lo g i nMo d ul e.
Refer to the API documentation for more information about creating a custom authentication module.
Report a bug
A.2. Included Aut horiz at ion Modules

The following modules provide authorization services.
Code
C lass
D enyAll
org.jboss.security.authorization.modules.AllD en
yAuthorizationModule
org.jboss.security.authorization.modules.AllPer
mitAuthorizationModule
org.jboss.security.authorization.modules.D eleg
atingAuthorizationModule
org.jboss.security.authorization.modules.web.W
ebAuthorizationModule
org.jboss.security.authorization.modules.JACCA
uthorizationModule
org.jboss.security.authorization.modules.XACM
LAuthorizationModule
PermitAll
D elegating
Web
JACC
XACML
AllD en yAu t h o riz at io n Mo d u le

This is a simple authorization module that always denies an authorization request. No configuration
options are available.
317
AllPermit Au t h o riz at io n Mo d u le
This is a simple authorization module that always permits an authorization request. No configuration
options are available.
D eleg at in g Au t h o riz at io n Mo d u le
This is the default authorization module that delegates decision making to the configured delegates.
Web Au t h o riz at io n Mo d u le
This is the default web authorization module with the default Tomcat authorization logic (permit all).
JAC C Au t h o riz at io n Mo d u le
This module enforces JACC semantics using two delegates (WebJACCPolicyModuleD elegate for web
container authorization requests and EJBJACCPolicyModuleD elegate for EJB container requests).
No configuration options available.
XAC MLAu t h o riz at io n Mo d u le
This module enforces XACML authorization using two delegates for web and EJB containers
(WebXACMLPolicyModuleD elegate and EJBXACMLPolicyModuleD elegate). It creates a PD P object
based on registered policies and evaluates web or EJB requests against it.
Ab st ract Au t h o riz at io n Mo d u le
This is the base authorization module which has to be overridden and provides a facility for
delegating to other authorization modules.
Report a bug
A.3. Included Securit y Mapping Modules

The following security mapping roles are provided in JBoss EAP 6.
Code
C lass
PropertiesRoles
o rg . jbo ss. securi ty. mappi ng . pro vi d er

s. ro l e. P ro perti esR o l esMappi ng P ro vi
d er
s. ro l e. Si mpl eR o l esMappi ng P ro vi d er
s. D epl o ymentR o l esMappi ng P ro vi d er
s. ro l e. D atabaseR o l esMappi ng P ro vi d er
s. ro l e. Ld apR o l esMappi ng P ro vi d er
s. attri bute. Ld apAttri buteMappi ng P ro v
i d er
SimpleRoles
D eploymentRoles
D atabaseRoles
LdapRoles
LdapAttributes
D ep lo ymen t R o lesMap p in g Pro vid er
318
Reference
A Role Mapping Module that takes into consideration a principal to roles mapping that can be done
in jbo ss-web. xml and jbo ss-app. xml deployment descriptors.
Examp le A.1. Examp le
< jboss-web>
. ..
<security-role>
<role-name>Support</role-name>
<principal-name>Mark</principal-name>
<principal-name>Tom</principal-name>
</security-role>
. ..
< /jboss-web>
o rg .jb o ss.secu rit y.map p in g .p ro vid ers.D ep lo ymen t R o leT o R o lesMap p in g Pro vid er
A Role to Roles Mapping Module that takes into consideration a principal to roles mapping that can
be done in the deployment descriptors jbo ss-web. xml and jbo ss-app. xml . In this case
principal-name denotes role to map other roles.
<jboss-web>
...
<security-role>
<role-name>Employee</role-name>
<principal-name>Support</principal-name>
<principal-name>Sales</principal-name>
</security-role>
...
</jboss-web>
Which means that each principal having role Support or Sales will also have role Employee
assigned.
o rg .jb o ss.secu rit y.map p in g .p ro vid ers.O p t io n sR o leMap p in g Pro vid er

Role Mapping Provider that picks up the roles from the options and then appends them to the passed
Group. Takes the properties style mapping of role name (key) with a comma separated list of roles
(values).
o rg .jb o ss.secu rit y.map p in g .p ro vid ers.p rin cip al.Simp lePrin cip alMap p in g Pro vid er
A principal mapping provider that takes in a SimplePrincipal and converts into SimplePrincipal with
a different principal name.
D at ab aseR o lesMap p in g Pro vid er
319
A MappingProvider that reads roles from a database.

Options:
d sJnd i Name: JND I name of data source used to map roles to the user.
ro l esQ uery: This option should be a prepared statement equivalent to " select RoleName from
Roles where User=?" ? is substituted with current principal name.
suspend R esume: Boolean - To suspend and later resume transaction associated with current
thread while performing search for roles.
transacti o nManag erJnd i Name: JND I name of Transaction mamager (default is
java:/TransactionManager)
Ld ap R o lesMap p in g Pro vid er
A mapping provider that assigns roles to an user using a LD AP server to search for the roles.
Options:
bi nd D N: The D N used to bind against the LD AP server for the user and roles queries. This D N
needs read and search permissions on the baseCtxD N and rolesCtxD N values.
bi nd C red enti al : The password for the bindD N. This can be encrypted if the
jaasSecurityD omain is specified.
ro l esC txD N: The fixed D N of the context to search for user roles. This is not the D N where the
actual roles are, but the D N where the objects containing the user roles are. For example, in a
Microsoft Active D irectory server, this is the D N where the user account is.
ro l eAttri buteID : The LD AP attribute which contains the names of authorization roles.
ro l eAttri buteIsD N: Whether or not the ro l eAttri buteID contains the fully-qualified D N of a
role object. If false, the role name is taken from the value of the ro l eNameAttri buteId attribute
of the context name. Certain directory schemas, such as Microsoft Active D irectory, require this
attribute to be set to true.
ro l eNameAttri buteID : Name of the attribute within the ro l eC txD N context which contains the
role name. If the ro l eAttri buteIsD N property is set to true, this property is used to find the role
object's name attribute.
parseR o l eNameFro mD N: A flag indicating if the D N returned by a query contains the
roleNameAttributeID . If set to true, the D N is checked for the roleNameATtributeID . If set to fal se,
the D N is not checked for the roleNameAttributeID . This flag can improve the performance of LD AP
queries.
ro l eFi l ter: A search filter used to locate the roles associated with the authenticated user. The
input username or userD N obtained from the login module callback is substituted into the filter
anywhere a {0 } expression is used. The authenticated userD N is substituted into the filter
anywhere a {1} is used. An example search filter that matches on the input username is
(member= {0 }). An alternative that matches on the authenticated userD N is (member= {1}).
ro l eR ecursi o n: The numbers of levels of recursion the role search will go below a matching
context. D isable recursion by setting this to 0 .
searchT i meLi mi t: The timeout in milliseconds for the user/role searches. D efaults to 10000 (10
seconds).
searchSco pe: The search scope to use.
320
Reference
Pro p ert iesR o lesMap p in g Pro vid er

A MappingProvider that reads roles from a properties file in the following format:
username=role1,role2,...
Options:
ro l esP ro perti es: Properties formatted file name. Expansion of JBoss variables can be used in
form of ${jbo ss. vari abl e}.
Simp leR o lesMap p in g Pro vid er
A simple MappingProvider that reads roles from the options map. The option attribute name is the
name of principal to assign roles to and the attribute value is the comma separated role names to
assign to the principal.
< module-option name="JavaDuke" value="JBossAdmin,Admin"/>

< module-option name="joe" value="Users"/>
o rg .jb o ss.secu rit y.map p in g .p ro vid ers.at t rib u t e.D ef au lt At t rib u t eMap p in g Pro vid er
Checks module and locates principal name from mapping context to create attribute e-mail address
from module option named principalName + " .email" and maps it to the given principal.
Ld ap At t rib u t eMap p in g Pro vid er
Maps attributes from LD AP to the subject. The options include whatever options your LD AP JND I
provider supports.
Examp le A.4 . Examp les o f st an d ard p ro p ert y n ames in clu d e:
C ontext.INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial"
C ontext.SECURITY_PROTOCOL = "java.naming.security.protocol"
C ontext.PROVIDER_URL = "java.naming.provider.url"
C ontext.SECURITY_AUTHENTICATION =
"java.naming.security.authentication"
Options:
bi nd D N: The D N used to bind against the LD AP server for the user and roles queries. This D N
needs read and search permissions on the baseCtxD N and rolesCtxD N values.
bi nd C red enti al : The password for the bindD N. This can be encrypted if the
jaasSecurityD omain is specified.
baseC txD N: The fixed D N of the context to start the user search from.
321
baseFi l ter: A search filter used to locate the context of the user to authenticate. The input
username or userD N as obtained from the login module callback is substituted into the filter
anywhere a {0 } expression is used. This substituion behavior comes from the standard
__D i rC o ntext. search(Name, Stri ng , O bject[], SearchC o ntro l s co ns)__ method.
An common example search filter is (ui d = {0 }).
searchT i meLi mi t: The timeout in milliseconds for the user/role searches. D efaults to 10000 (10
seconds).
attri buteLi st: A comma-separated list of attributes for the user. For example,
mail,cn,sn,employeeType,employeeNumber.
jaasSecuri tyD o mai n: The JaasSecurityD omain to use to decrypt the
java. nami ng . securi ty. pri nci pal . The encrypted form of the password is that returned by
the JaasSecuri tyD o mai n#encrypt6 4 (byte[]) method. The
o rg . jbo ss. securi ty. pl ug i ns. P BEUti l s can also be used to generate the encrypted form.
Report a bug
A.4 . Included Securit y Audit ing Provider Modules

JBoss EAP 6 provides one security auditing provider.
Code
C lass
LogAuditProvider
org.jboss.security.audit.providers.LogAuditProvi
der
Report a bug
A.5. jboss-web.xml Configurat ion Reference

In t ro d u ct io n
The jbo ss-web. xml is a file within your deployment's WEB-INF directory. It contains configuration
information about features the JBoss Web container adds to the Servlet 3.0 specification. Settings
specific to the Servlet 3.0 specification are placed into web. xml in the same directory.
The top-level element in the jbo ss-web. xml file is the <jbo ss-web> element.
Map p in g G lo b al R eso u rces t o WAR R eq u iremen t s
Many of the available settings map requirements set in the application's web. xml to local resources.
The explanations of the web. xml settings can be found at
http://docs.oracle.com/cd/E13222_01/wls/docs81/webapp/web_xml.html.
For instance, if the web. xml requires jd bc/MyD ataSo urce, the jbo ss-web. xml may map the
global datasource java: /D efaul tD S to fulfill this need. The WAR uses the global datasource to fill
its need for jd bc/MyD ataSo urce.
T ab le A.4 2. C o mmo n T o p - Level At t rib u t es
At t rib u t e
D escrip t io n
env-entry
A mapping to an env-entry required by the

web. xml .
322
Reference
At t rib u t e
D escrip t io n
ejb-ref
A mapping to an ejb-ref required by the

web. xml .
A mapping to an ejb-l o cal -ref required by
the web. xml .
A mapping to a servi ce-ref required by the
web. xml .
A mapping to a reso urce-ref required by the
web. xml .
A mapping to a reso urce-env-ref required
by the web. xml .
A mapping to a messag e-d esti nati o n-ref
required by the web. xml .
A mapping to a persi stence-co ntext-ref
A mapping to a persi stence-uni t-ref
A mapping to a po st-co ntext required by the
web. xml .
A mapping to a pre-d estro y required by the
web. xml .
A mapping to a d ata-so urce required by the
web. xml .
The root context of the application. The default
value is the name of the deployment without the
. war suffix.
The name of the HTTP virtual-host the
application accepts requests from. It refers to the
contents of the HTTP Ho st header.
D escribes an annotation used by the
application. Refer to <annotation> for more
information.
D escribes a listener used by the application.
Refer to <listener> for more information.
This element fills the same function as the
<sessi o n-co nfi g > element of the web. xml
and is included for compatibility only.
D escribes a valve used by the application. Refer
to <valve> for more information.
The name of an overlay to add to the
application.
The name of the security domain used by the
application. The security domain itself is
configured in the web-based management
console or the management CLI.
This element fills the same function as the
<securi ty-ro l e> element of the web. xml
and is included for compatibility only.
ejb-local-ref
service-ref
resource-ref
resource-env-ref
message-destination-ref
persistence-context-ref
persistence-unit-ref
post-construct
pre-destroy
data-source
context-root
virtual-host
annotation
listener
session-config
valve
overlay
security-domain
security-role
323
At t rib u t e
D escrip t io n
use-jboss-authorization
If this element is present and contains the case

insensitive value " true" , the JBoss web
authorization stack is used. If it is not present or
contains any value that is not " true" , then only
the authorization mechanisms specified in the
Java Enterprise Edition specifications are used.
This element is new to JBoss EAP 6.
Set this boolean element to fal se to enable
and true to disable web auditing. Web security
auditing is not part of the Java EE specification.
This element is new to JBoss EAP 6.
If fal se, the application is able to call another
application context. D efaults to true.
disable-audit
disable-cross-context
The following elements each have child elements.

<an n o t at io n >
D escribes an annotation used by the application. The following table lists the child elements of an
<anno tati o n>.
T ab le A.4 3. An n o t at io n C o n f ig u rat io n Elemen t s
At t rib u t e
D escrip t io n
class-name
servlet-security
Name of the class of the annotation

The element, such as @ Servl etSecuri ty,
which represents servlet security.
The element, such as @ R unAs, which represents
the run-as information.
The element, such as @ Mul ti P art, which
represents the multipart-config information.
run-as
multipart-config
<list en er>
D escribes a listener. The following table lists the child elements of a <l i stener>.
T ab le A.4 4 . List en er C o n f ig u rat io n Elemen t s
At t rib u t e
D escrip t io n
class-name
Name of the class of the listener
324
Reference
At t rib u t e
D escrip t io n
listener-type
List of co nd i ti o n elements, which indicate

what kind of listener to add to the Context of the
application. Valid choices are:
C O N T AIN ER
Adds a ContainerListener to the
Context.
LIFEC YC LE
Adds a LifecycleListener to the Context.
SER VLET _IN ST AN C E
Adds an InstanceListener to the
Context.
SER VLET _C O N T AIN ER
Adds a WrapperListener to the Context.
SER VLET _LIFEC YC LE
Adds a WrapperLifecycle to the
Context.
module
The name of the module containing the listener

class.
A parameter. Contains two child elements,
<param-name> and <param-val ue>.
param
<valve>
D escribes a valve of the application. Similar to the <listener>, has class-name, module and param
elements.
Report a bug
A.6. EJB Securit y Paramet er Reference

T ab le A.4 5. EJB secu rit y p aramet er elemen t s
Elemen t
D escrip t io n
<securi ty-i d enti ty>
Contains child elements pertaining to the

security identity of an EJB.
Indicates that the EJB uses the same security
identity as the caller.
Contains a <ro l e-name> element.
If present, indicates the principal assigned to
outgoing calls. If not present, outgoing calls are
assigned to a principal named ano nymo us.
Specifies the role the EJB should run as.
D escribes the role named in <ro l e-name> .
<use-cal l er-i d enti ty />

<run-as>
<run-as-pri nci pal >
<ro l e-name>
<d escri pti o n>
Examp le A.5. Secu rit y id en t it y examp les
This example shows each tag described in Table A.45, EJB security parameter elements . They
can also be used inside a <sessi o n>.
< ejb-jar>
325
<enterprise-beans>
<session>
<security-identity>
</session>
<session>
<security-identity>
<run-as>
</run-as>
</session>
<session>
<security-identity>
</session>
</enterprise-beans>
< /ejb-jar>
Report a bug
326
Reference
Revision History
R evisio n 6 .3.0- 50
T u esd ay N o vemb er 18 2014 R u ssell D icken so n
Red Hat JBoss Enterprise Application Platform 6.3.0 Continuous Release
R evisio n 6 .3.0- 4 3
Frid ay Au g u st 8 2014
Lu cas C o st i
Red Hat JBoss Enterprise Application Platform 6.3.0 Continuous Release
R evisio n 6 .3.0- 4 2
Wed n esd ay, Ju ly 30 2014
Red Hat JBoss Enterprise Application Platform 6.3.0.GA
R u ssell D icken so n
327

JBoss Enterprise Application Platform 6.3 Security Guide en US

Uploaded by

Copyright:

Available Formats

JBoss Enterprise Application Platform 6.3 Security Guide en US

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

JBoss Enterprise Application Platform 6.3 Security Guide en US

Uploaded by

Copyright:

Available Formats

JBoss Enterprise Application

For Use with Red Hat JBoss Enterprise Application Platform 6

Red Hat Customer Content Services

JBoss Enterprise Application Platform 6.3 Security Guide

For Use with Red Hat JBoss Enterprise Application Platform 6

T able of Cont ent s

2 .5. IBM JRE and the Java Sec urity Manag er

3 .3. Ad d a Us er to a Sec urity Realm

4 .4. Ab o ut Enc ryp tio n

4 .8 . SSL Co nnec to r Referenc e

O verview o f Ad vanc ed Manag ement Interfac e Co nfig uratio n

5 .6 . Co nfig ure Sec urity Realms fo r the Manag ement Interfac es

JBoss Ent erprise Applicat ion Plat form 6 .3 Securit y G uide

6 .8 .1. O verview o f RBAC Co nfig uratio n Tas ks

6 .8 .3. Chang ing the Permis s io n Co mb inatio n Po lic y

6 .9 . Manag ing Ro les

6 .9 .2. Co nfig ure Us er Ro le As s ig nment

6 .9 .4. Ab o ut Ro les and Us er G ro up s

6 .9 .5. Co nfig ure G ro up Ro le As s ig nment

6 .9 .7. Ab o ut Autho riz atio n and G ro up Lo ad ing with LDAP

G eneral G ro up Searc hing

6 .10 . Co nfig uring Co ns traints

7 .4. Co nfig ure JBo s s EAP 6 to Us e the Pas s wo rd Vault

T able of Cont ent s

9 .3. Sub s c rib e to Patc h Mailing Lis ts

9 .4. Ins tall Patc hes in Zip Fo rm

9 .5. Patc hing an RPM Ins tallatio n

9 .6 . Severity and Imp ac t Rating o f JBo s s Sec urity Patc hes

10 .2.1. Java EE Dec larative Sec urity O verview

10 .2.2. Sec urity Referenc es

10 .2.4. Sec urity Ro les

10 .2.5. EJB Metho d Permis s io ns

10 .2.7. Web Co ntent Sec urity Co ns traints

10 .2.9 . Enab le Dec larative Sec urity

11.2. EJB Ap p lic atio n Sec urity

11.2.1.1. Ab o ut EJB Sec urity Id entity

11.2.1.2. Set the Sec urity Id entity o f an EJB

11.2.2.1. Ab o ut EJB Metho d Permis s io ns

11.2.2.2. Us e EJB Metho d Permis s io ns

11.2.3. EJB Sec urity Anno tatio ns

11.2.3.2. Us e EJB Sec urity Anno tatio ns

11.2.4. Remo te Ac c es s to EJBs

11.2.4.1. Ab o ut Remo te Metho d Ac c es s

11.2.4.2. Ab o ut Remo ting Callb ac ks

11.2.4.4. Co nfig ure the Remo ting Sub s ys tem

11.2.4.5. Us e Sec urity Realms with Remo te EJB Clients

11.2.4.6 . Ad d a New Sec urity Realm

11.2.4.7. Ad d a Us er to a Sec urity Realm

11.3. JAX-RS Ap p lic atio n Sec urity

11.3.1. Enab le Ro le-Bas ed Sec urity fo r a RESTEas y JAX-RS Web Servic e

11.3.2. Sec ure a JAX-RS Web Servic e us ing Anno tatio ns

JBoss Ent erprise Applicat ion Plat form 6 .3 Securit y G uide

12.3. Co nfig uring the Sec urity Sub s ys tem

12.3.1. Co nfig ure the Sec urity Sub s ys tem

12.3.2. Sec urity Manag ement

12.3.2.1. Ab o ut Deep Co p y Sub jec t Mo d e

2.3.2.2. Enab le Deep Co p y Sub jec t Mo d e

12.3.3.1. Ab o ut Sec urity Do mains

12.3.3.2. CLI O p eratio ns Related to Sec urity Do mains

13.1.1. Ab o ut Kerb ero s and SPNEG O Integ ratio n

"so cannot be deassigned\n", func);