Skip to content

Commit c5668d4

Browse files
bbuerklebbuerkle
committed
Addressed Will review comments and added examples procedures.
1 parent f88412a commit c5668d4

8 files changed

Lines changed: 456 additions & 210 deletions

File tree

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

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,26 @@
11
type=page
22
status=published
3-
title=Java API for Security
3+
title=Using the Java EE Security API
44
next=security-api001.html
55
prev=security-javaee003.html
66
~~~~~~
7-
= Java API for Security
7+
= Using the Java EE Security API
88

99

1010

11-
[[java-api-for-security]]
12-
53 Java API for Security
13-
------------------------
11+
[[using-the-java-ee-security-api]]
12+
53 Using the Java EE Security API
13+
---------------------------------
1414

1515

16-
This chapter primarily describes the authentication and credential validation
16+
This chapter describes the authentication and credential validation
1717
functionality provided by the Java EE Security API. The API also
1818
defines a SecurityContext access point for programmatic security.
1919

2020

2121
The following topics are addressed here:
2222

23-
* link:security-api001.html#about-the-java-api-for-security[About the Java API for Security]
23+
* link:security-api001.html#about-the-java-ee-security-api[About the Java EE Security API]
2424
* link:security-api002.html#overview-of-the-http-auth-mech-int[Overview of the HTTP Authentication Mechanism Interface]
2525
* link:security-api003.html#overview-of-the-identity-store-interfaces[Overview of the Identity Store Interfaces]
2626
* link:security-api004.html#running-the-built-in-database-identity-store-example[Running the Built-In Database Identity Store Example]

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

Lines changed: 77 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,144 +1,161 @@
11
type=page
22
status=published
3-
title=Java API for Security
3+
title=About the Java EE Security API
44
next=security-api002.html
55
prev=security-api.html
66
~~~~~~
7-
= About the Java API for Security
8-
9-
10-
11-
[[about-the-java-api-for-security]]
12-
About the Java API for Security
13-
-------------------------------
7+
= About the Java EE Security API
148

9+
[[about-the-java-ee-security-api]]
10+
About the Java EE Security API
11+
------------------------------
1512

1613
Java EE includes support for JSR 375, which defines portable, plug-in interfaces
1714
for authentication and identity stores, and a new injectable-type SecurityContext
1815
interface that provides an access point for programmatic security. You can use
1916
the built-in implementations of these APIs, or define custom
2017
implementations.
2118

22-
The Java API for Security contains the following packages:
19+
The Java EE Security API contains the following packages:
2320

2421
* The `javax.security.enterprise` package is the main Java EE security API package
2522
and contains classes and interfaces that span authentication, authorization, and
2623
identity concerns. link:#main-classes-and-interfaces-in-enterprise[Table 51-1] lists
2724
the main class and interfaces in this package.
2825
2926
* The `javax.security.enterprise.authentication.mechanism.http` package contains
30-
classes and interfaces associated with authentication mechanisms that specifically
31-
target HTTP as an environment to interact with a caller (challenge/response, obtain
32-
credentials). This API is specified only for use in the servlet container.
27+
classes and interfaces associated with HTTP-based authentication mechanisms that
28+
can interact with a caller or third-parties as part of an authentication protocol.
3329
link:#main-classes-and-interfaces-in-authentication[Table 51-2] lists the main classes
3430
and interfaces in this package.
3531
3632
* The `javax.javax.security.enterprise.credential` package contains classes and
37-
interfaces associated with submitting credentials. link:#main-classes-and-interfaces-in-credential[Table 51-3]
33+
interfaces for representing user credentials. link:#main-classes-and-interfaces-in-credential[Table 51-3]
3834
lists the main classes and interfaces in this package.
3935
4036
* The `javax.security.enterprise.identitystore` package contains classes and
41-
interfaces associated with the identity store, which validate the credentials of the
42-
Caller, and access a Caller's identity attributes. link:#main-classes-and-interfaces-in-identitystore[Table 51-4]
37+
interfaces associated with identity stores that validate a caller's credentials
38+
and lookup caller groups. link:#main-classes-and-interfaces-in-identitystore[Table 51-4]
4339
lists the main classes and interfaces in this package.
4440
4541
42+
4643
[[main-classes-and-interfaces-in-enterprise]]
4744

4845
*Table 51-1 Main Classes and Interfaces in javax.security.enterprise*
4946

50-
[width=99%,cols="25%,75%"]
47+
[width=99%,cols="35%,65%"]
5148
|=======================================================================
5249
|*Class or Interface* |*Description*
53-
|`SecurityContext` | Injectable-type interface that provides an access point for
50+
51+
|`SecurityContext` |Injectable-type interface that provides an access point for
5452
programmatic security intended to be used by application code to query and interact
5553
with the Java EE Security API.
5654

57-
|`CallerPrincipal` | Principal type that represents the identity of the
55+
|`CallerPrincipal` |Principal type that can represent the identity of the
5856
application caller.
5957

60-
|`AuthenticationStatus` | Enum used as a return value, primarily by the
61-
`HttpAuthenticationMechanism` to indicate the result of the authentication process.
58+
|`AuthenticationStatus` |Enum used to indicate the return value from an authentication
59+
mechanism.
6260

63-
|`AuthenticationException` | Indicates that a problem occurred during the
61+
|`AuthenticationException` |Indicates that a problem occurred during the
6462
authentication process.
6563
|=======================================================================
6664

6765
[[main-classes-and-interfaces-in-authentication]]
6866

67+
6968
*Table 51-2 Main Classes and Interfaces in javax.security.enterprise.authentication.mechanism.http*
70-
[width=99%,cols="25%,75%"]
69+
[width=99%,cols="35%,65%"]
7170
|=======================================================================
7271
|*Class or Interface* |*Description*
73-
|`HttpAuthenticationMechanism` | Interface used to obtain a caller's credentials in some way,
74-
using the HTTP protocol where necessary.
7572

76-
|`HttpMessageContext` | Interface that contains all of the per-request state
77-
information and encapsulates the client request, server response,
78-
container handler for authentication callbacks, and the subject representing
79-
the caller.
73+
|`HttpAuthenticationMechanism` |Interface representing an HTTP authentication mechanism.
74+
Developers can provide their own implementation of this interface, or use one of
75+
several built-in HTTP authentication mechanisms.
76+
77+
|`HttpMessageContext` |Interface representing the parameters passed to/from methods
78+
of an `HttpAuthenticationMechanism` at runtime.
8079

81-
|`AuthenticationParameters` | Parameters that are provided with the authentication
82-
request.
80+
|`AuthenticationParameters` |Class that carries parameters passed to the
81+
`SecurityContext.authenticate()` method.
8382

84-
|`HttpMessageContextWrapper` | Class that is an implementation of the
85-
HttpMessageContext interface that can be subclassed by developers wishing to
86-
provide extra or different functionality.
83+
|`HttpMessageContextWrapper` |Abstract class developers can extend to
84+
customize `HttpMessageContext` behavior.
85+
|=======================================================================
86+
87+
[width="100%",cols="100%",]
88+
|=======================================================================
89+
a|
90+
*Note:*
91+
92+
The 'javax.security.enterprise.authentication.mechanism.http' package also includes
93+
a number of annotation classes that can be used to configure/enable the built-in
94+
authentication mechanisms or modify that behavior of an authentication mechanism.
8795
|=======================================================================
8896

8997

9098
[[main-classes-and-interfaces-in-credential]]
9199

92100
*Table 51-3 Main Classes and Interfaces in javax.security.enterprise.credential*
93-
[width=99%,cols="25%,75%"]
101+
[width=99%,cols="35%,65%"]
94102
|=======================================================================
95103
|*Class or Interface* |*Description*
96-
|`Credential` | Represents the credential the caller uses to authenticate.
97104

98-
|`AbstractClearableCredential` | Class that contains behavior common to `credential`
99-
implementations that can be meaningfully cleared.
105+
|`Credential` |Interface that represents a generic credential and defines
106+
several methods to operate on credentials. All other classes in this package
107+
are implementations of the Credential interface.
108+
109+
|`AbstractClearableCredential` |Abstract class implementing behavior common to
110+
Credentials that can be meaningfully cleared.
100111

101-
|`BasicAuthenticationCredential` | Class that extends `UsernamePasswordCredential`
112+
|`BasicAuthenticationCredential` |Class that extends `UsernamePasswordCredential`
102113
to represent credentials used by HTTP Basic Authentication.
103114

104-
|`CallerOnlyCredential` | Class that represents a credential that contains only a
105-
caller name and no secret of any kind.
115+
|`CallerOnlyCredential` |Credential that contains a caller name only; can be
116+
used to assert an identity, but not to authenticate a user, due to the lack of
117+
any secret or other credential that can be validated.
106118

107-
|`Password` | Class that represents a text-based password, and includes a built-in
108-
mechanism for securely clearing the value.
119+
|`Password` |Class that represents a text-based password.
109120

110-
|`RememberMeCredential` | Class that represents a credential presented as a token,
121+
|`RememberMeCredential` |Class that represents a credential presented as a token,
111122
for the explicit usage with the JSR 375 remember me function.
112123

113-
|`UsernamePasswordCredential` | Class that represents the credentials typically
124+
|`UsernamePasswordCredential` |Class that represents the credentials typically
114125
used by standard caller name/password authentication.
115126
|=======================================================================
116127

117128
[[main-classes-and-interfaces-in-identitystore]]
118129

119130
*Table 51-4 Main Classes and Interfaces in javax.security.enterprise.identitystore*
120-
[width=99%,cols="25%,75%"]
131+
[width=99%,cols="35%,65%"]
121132
|=======================================================================
122133
|*Class or Interface* |*Description*
123-
|`IdentityStore` | Mechanism for validating a caller's credentials and
124-
accessing a caller's identity attributes.
125134

126-
|`IdentityStoreHandler` | Mechanism for validating a caller's credentials,
127-
and accessing a caller's identity attributes, by consulting a set of one or more
128-
'IdentityStore's.
135+
|`IdentityStore` |Interface representing an Identity Store.
136+
Developers can provide their own implementation of this interface, or use one of
137+
the built-in Identity Stores.
138+
139+
|`IdentityStoreHandler` |Interface that defines the method applications use to
140+
interact with Identity Stores. Applications can use the built-in
141+
IdentityStoreHandler, or supply their own implementation if custom behavior is desired.
129142

130-
|`PasswordHash` | Interface for objects that can generate and verify password hashes.
143+
|`PasswordHash` |Interface defining methods for generating and
144+
validating password hashes, needed to securely validate passwords when using
145+
the built-in Database Identity Store. Developers can implement this interface
146+
to generate/validate password hashes using any desired algorithm.
131147

132-
|`Pbkdf2PasswordHash` | Interface that represents the built-in `Pbkdf2PasswordHash`
133-
implementation.
148+
|`Pbkdf2PasswordHash` |Marker interface implemented by the built-in PBKDF2
149+
PasswordHash implementation. Developers can use this interface to select the
150+
built-in PBKDF2 algorithm when configuring the Database Identity Store.
134151

135-
|`RememberMeIdentityStore` | Mechanism for validating a caller's credentials and
136-
accessing a caller's identity attributes. This interface is specifically tailored
137-
for the "remember me" feature.
152+
|`RememberMeIdentityStore` |Interface defining a special type of Identity Store,
153+
used in conjunction with the RememberMe annotation to provide RememberMe
154+
behavior for an application.
138155

139-
|`CredentialValidationResult` | Class that represents the result from an attempt
140-
to validate an instance of `Credential`.
156+
|`CredentialValidationResult` |Class that represents the result from an attempt
157+
to validate a Credential.
141158

142-
|`IdentityStorePermission` | Class for IdentityStore permissions. The permission
143-
name currently defined is `getGroups`.
159+
|`IdentityStorePermission` |Permission required to invoke the `getGroups` method of an
160+
IdentityStore, when a SecurityManager is configured.
144161
|=======================================================================

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

Lines changed: 65 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
type=page
22
status=published
3-
title=Java API for Security
3+
title=Overview of the HTTP Authentication Mechanism Interface
44
next=security-api003.html
55
prev=security-api001.html
66
~~~~~~
@@ -10,6 +10,67 @@ prev=security-api001.html
1010
[[overview-of-the-http-auth-mech-int]]
1111
Overview of the HTTP Authentication Mechanism Interface
1212
-------------------------------------------------------
13-
Include a discussion about how the standard HTTPAuthenticationMechanism interface
14-
implementations can be used, and how you can create a custom
15-
HttpAuthenticationMechanism if desired.
13+
14+
The `HttpAuthenticationMechanism` interface defines an SPI for writing
15+
authentication mechanisms that can be provided with an application and
16+
deployed using CDI. Developers can write their own implementations of `HttpAuthenticationMechanism`
17+
to support specific authentication token types or protocols. There are also several
18+
built-in authentication mechanisms that perform BASIC, FORM, and Custom FORM
19+
authentication.
20+
21+
The built-in authentication mechanisms are enabled and configured through the use
22+
of one of the following annotations:
23+
24+
* BasicAuthenticationMechanismDefinition -- implements BASIC authentication that
25+
conforms to the behavior of the servlet container when BASIC <auth-method> is
26+
declared in web.xml.
27+
28+
* FormAuthenticationMechanismDefinition -- implements FORM authentication that
29+
conforms to the behavior of the servlet container when the FORM <auth-method>
30+
is declared in web.xml.
31+
32+
* CustomFormAuthenticationMechanismDefinition -- implements a modified version of
33+
FORM authentication in which custom handling replaces the POST to j_security_check.
34+
35+
An implementation of HttpAuthenticationMechanism must be a CDI bean to be
36+
recognized and deployed at runtime, and is assumed to be normal scoped.
37+
During bean discovery, the servlet container looks for a bean that implements
38+
`HttpAuthenticationMechanism` -- there should be only one per application -- and,
39+
if found, arranges for it to be deployed to authenticate the application's callers.
40+
41+
The servlet container leverages JASPIC, the Java Authentication Service
42+
Provider Interface for Containers, to deploy authentication mechanisms.
43+
The container provides a JASPIC Server Auth Module (SAM) that can delegate to an
44+
`HttpAuthenticationMechanism`, and arranges for that "bridge" SAM to be registered
45+
with the JASPIC `AuthConfigFactory`. At runtime, normal JASPIC processing invokes
46+
the bridge SAM, which then delegates to the `HttpAuthenticationMechanism` to
47+
perform the authentication and drive any necessary dialog with the caller, or with
48+
third parties involved in the authentication protocol flow.
49+
50+
The HttpAuthenticationMechanism interface defines the following three methods,
51+
which correspond to the three methods defined by the JASPIC ServerAuth interface.
52+
When one of the JASPIC methods is invoked on the bridge SAM, it delegates to the
53+
corresponding method of the `HttpAuthenticationMechanism`. Although the method names
54+
are identical, the method signatures are not; the bridge SAM maps back and forth
55+
between the parameters passed to it by the JASPIC framework, and the parameters
56+
expected by an `HttpAuthenticationMechanism`.
57+
58+
* `validateRequest()` -- validate an incoming request and authenticates the caller.
59+
* `secureResponse()` -- (optional if default is sufficient) secure a response message.
60+
* `cleanSubject()` -- (optional if default is sufficient) clear the provided Subject of
61+
principals and credentials.
62+
63+
Only the `validateRequest()` method must be implemented by an `HttpAuthenticationMechanism`;
64+
the interface includes default implementations for secureResponse()` and `cleanSubject()` that will
65+
often be sufficient.
66+
67+
The following annotations can be used to add additional behaviors to an `HttpAuthenticationMechanism`:
68+
69+
* `AutoApplySession` -- indicates that the JASPIC `registerSession` functionality
70+
should be enabled such that the the caller's authenticated identity is
71+
persisted in the caller's servlet session.
72+
* `LoginToContinue` -- mechanism to specify properties for FORM login --
73+
login page, error page, etc. The built-in FORM authentication mechanisms use
74+
LoginToContinue to configure the necessary parameters.
75+
* `RememberMe` -- specifies that a `RememberMe` identity store should be used to
76+
enable `RememberMe` functionality for the authentication mechanism.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
type=page
22
status=published
3-
title=Java API for Security
3+
title=Overview of the Identity Store Interfaces
44
next=security-api004.html
55
prev=security-api002.html
66
~~~~~~

0 commit comments

Comments
 (0)