Skip to content

Commit cefdab5

Browse files
bbuerklebbuerkle
committed
Will and Vinay review comments.
1 parent d83c355 commit cefdab5

5 files changed

Lines changed: 49 additions & 46 deletions

File tree

‎src/main/jbake/content/security-advanced007.adoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,10 @@ it from being read in transit.
8282
Specifying Non-Default Principal-to-Role Mapping in the Deployment Descriptor
8383
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8484

85+
The Java EE Security API requires that group principal names be mapped to
86+
roles of the same name by default. However, implementations of the standard
87+
can provide mechanisms to configure a different default.
88+
8589
To map a role name permitted by the application or module to principals
8690
(users) and groups defined on the server, use the
8791
`security-role-mapping` element in the runtime deployment descriptor

‎src/main/jbake/content/security-api003.adoc‎

Lines changed: 33 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,8 @@ Overview of the Identity Store Interfaces
1212
The Identity Store Interfaces are described in the following sections:
1313

1414
* link:#the-identitystore-interface[The IdentityStore Interface]
15-
* link:#the-identitystorehandler-interface[The IdentityStoreHandler Interface]
16-
* link:#the-passwordhash-interface[The PasswordHash Interface]
1715
* link:#the-remembermeidentitystore-interface[The RememberMeIdentityStore Interface]
16+
* link:#the-passwordhash-interface[The PasswordHash Interface]
1817
1918
[[the-identitystore-interface]]
2019
The IdentityStore Interface
@@ -39,10 +38,15 @@ and/or lookup user groups.
3938
4039
* `DatabaseIdentityStoreDefinition` -- configures an identity store with the
4140
parameters necessary to connect to an external database, validate user credentials,
42-
and/or lookup user groups.
41+
and/or lookup user groups. You must supply a PasswordHash implementation when
42+
configuring a Database Identity Store. See link:#the-passwordhash-interface[The PasswordHash Interface].
4343
44-
link:security-api004.html#running-the-built-in-database-identity-store-example[Running the Built-In Database Identity Store Example]
45-
demonstrates usage of the built-in database identity store.
44+
An application can provide its own custom identity store, or use the built-in LDAP or database
45+
identity stores. For examples of both types, see:
46+
47+
* link:security-api004.html#running-the-built-in-database-identity-store-example[Running the Built-In Database Identity Store Example]
48+
49+
* link:security-api005.html#running-the-custom-identity-store-example[Running the Custom Identity Store Example]
4650
4751
Multiple implementations of `IdentityStore` may be present; if so, they are invoked
4852
in priority order, based on each identity store's self-declared priority and
@@ -52,10 +56,9 @@ IdentityStores are primarily intended for use by implementations of
5256
`HttpAuthenticationMechanisms`, but this is not a requirement.
5357
They can be used by other types of authentication mechanisms as well, or by containers.
5458

55-
[[the-identitystorehandler-interface]]
56-
The IdentityStoreHandler Interface
57-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58-
59+
[[identitystorehandler]]
60+
IdentityStoreHandler
61+
^^^^^^^^^^^^^^^^^^^^
5962
Authentication mechanisms do not interact with `IdentityStore` directly; instead,
6063
they call an `IdentityStoreHandler`. An implementation of the `IdentityStoreHandler`
6164
interface provides a single method, `validate(Credential)`, which, when invoked,
@@ -81,7 +84,9 @@ An application may also supply its own `IdentityStoreHandler`, which can use any
8184
desired algorithm to select and invoke on IdentityStores, and return an
8285
aggregated (or non-aggregated) result.
8386

84-
IdentityStore Interface Details:
87+
[[identitystoreinterface-methods]]
88+
IdentityStore Interface Methods
89+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8590

8691
The IdentityStore interface itself has four methods:
8792

@@ -108,24 +113,6 @@ IdentityStores do check for this permission, if a SecurityManager is configured,
108113
and the built-in IdentityStoreHandler invokes the `getCallerGroups()` method in
109114
the context of a `PrivilegedAction` block.
110115

111-
[[the-passwordhash-interface]]
112-
The PasswordHash Interface
113-
~~~~~~~~~~~~~~~~~~~~~~~~~~
114-
115-
Unlike some types of identity stores, for example LDAP directories,
116-
databases can store and retrieve user passwords, but can't verify them natively.
117-
Therefore, the built-in Database identity store must verify user passwords itself.
118-
Most often, this involves generating a hash of the user's password for comparison
119-
with a hash value stored in the database.
120-
121-
In order to provide maximum flexibility and interoperability, the Database identity
122-
store does not implement any specific password hashing algorithms. Instead, it
123-
defines the PasswordHash interface, and expects the application to provide an
124-
implementation of PasswordHash that can verify passwords from the specific store
125-
the application will use. The PasswordHash implementation must be made available
126-
as a dependent scoped bean, and is configured by providing the fully-qualified
127-
name of the desired type as a hashAlgorithm value on the DatabaseIdentityStoreDefinition.
128-
129116
[[the-remembermeidentitystore-interface]]
130117
The RememberMeIdentityStore Interface
131118
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -191,6 +178,24 @@ as securely as possible (but does not necessarily need to be reliably persisted
191178
the only impact of a "forgotten" session is that the user will be prompted to
192179
log in again).
193180

181+
[[the-passwordhash-interface]]
182+
The PasswordHash Interface
183+
~~~~~~~~~~~~~~~~~~~~~~~~~~
184+
185+
Unlike some types of identity stores, for example LDAP directories,
186+
databases can store and retrieve user passwords, but can't verify them natively.
187+
Therefore, the built-in Database identity store must verify user passwords itself.
188+
Most often, this involves generating a hash of the user's password for comparison
189+
with a hash value stored in the database.
190+
191+
In order to provide maximum flexibility and interoperability, the Database identity
192+
store does not implement any specific password hashing algorithms. Instead, it
193+
defines the PasswordHash interface, and expects the application to provide an
194+
implementation of PasswordHash that can verify passwords from the specific store
195+
the application will use. The PasswordHash implementation must be made available
196+
as a dependent scoped bean, and is configured by providing the fully-qualified
197+
name of the desired type as a hashAlgorithm value on the DatabaseIdentityStoreDefinition.
198+
194199
The PasswordHash algorithm defines three methods:
195200

196201
* `initialize(Map<String,String> parameters)` -- initialize the PasswordHash with

‎src/main/jbake/content/security-javaee002.adoc‎

Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -380,22 +380,11 @@ Programmatic security, code that is embedded in a business method, is
380380
used to access a caller's identity programmatically and uses this
381381
information to make security decisions within the method itself.
382382

383-
The following topic is addressed here:
384-
385-
* link:#GJGCR[Accessing an Enterprise Bean Caller's Security Context]
386-
387-
[[GJGCR]]
388-
389-
[[accessing-an-enterprise-bean-callers-security-context]]
390-
Accessing an Enterprise Bean Caller's Security Context
391-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
392-
393383
In general, security management should be enforced by the container in a
394384
manner that is transparent to the enterprise bean's business methods.
395385
The security API described in this section should be used only in the
396386
less frequent situations in which the enterprise bean business methods
397-
need to access the security context information, such as when you want
398-
to restrict access to a particular time of day.
387+
need to access the security context information.
399388

400389
The `SecurityContext` interface, as specified in the Java EE Security API specification,
401390
defines three methods
@@ -407,7 +396,9 @@ of the authenticated caller.
407396
This is the container-specific representation of the caller principal,
408397
and the type may differ from the type of the caller principal originally
409398
established by an `HttpAuthenticationMechanism`. This method returns null for an
410-
unauthenticated caller.
399+
unauthenticated caller. Note that this behavior differs from the behavior of
400+
the `EJBContext.getCallerPrincipal()` method,
401+
which returns a (vendor-specific) special principal to represent an anonymous caller.
411402
412403
* `getPrincipalsByType()` retrieves all principals of the given type from the
413404
authenticated caller's Subject. This method returns an empty
@@ -429,7 +420,12 @@ caller.
429420

430421
* `getCallerPrincipal` allows the enterprise bean methods to obtain the
431422
current caller principal's name. The methods might, for example, use the
432-
name as a key to information in a database.
423+
name as a key to information in a database. This method never returns null. Instead,
424+
it returns a principal with a special (platform-dependent) username to indicate
425+
an anonymous/unauthenticated caller.
426+
Note that this behavior differs
427+
from the behavior of the `SecurityContext.getCallerPrincipal()` method, which
428+
returns null for an unauthenticated caller.
433429
+
434430
The following code sample illustrates the use of the
435431
`getCallerPrincipal` method:

‎src/main/jbake/content/security-javaee003.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -288,8 +288,8 @@ Enterprise Beans"] and is found in the
288288
the example by adding the necessary elements to secure the application
289289
by using the `getCallerPrincipal` and `isCallerInRole` methods, which
290290
are discussed in more detail in
291-
link:security-javaee002.html#GJGCR[Accessing an Enterprise Bean Caller's
292-
Security Context].
291+
link:security-javaee002.html#securing-an-enterprise-bean-programmatically
292+
[Securing an Enterprise Bean Programmatically].
293293

294294
In general, the following steps are necessary when using the
295295
`getCallerPrincipal` and `isCallerInRole` methods with an enterprise

‎src/main/jbake/content/toc.adoc‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2676,8 +2676,6 @@ Mechanism and Secure Connection]
26762676
26772677
** link:security-javaee002.html#GJGCS[Securing an Enterprise Bean
26782678
Programmatically]
2679-
*** link:security-javaee002.html#GJGCR[Accessing an Enterprise Bean
2680-
Caller's Security Context]
26812679
26822680
** link:security-javaee002.html#BNBYR[Propagating a Security Identity
26832681
(Run-As)]

0 commit comments

Comments
 (0)