1+ package javax .security .authentication .mechanism .http ;
2+
3+ import java .util .List ;
4+ import java .util .Map ;
5+
6+ import javax .security .auth .Subject ;
7+ import javax .security .auth .callback .CallbackHandler ;
8+ import javax .security .auth .message .AuthStatus ;
9+ import javax .security .auth .message .MessageInfo ;
10+ import javax .security .auth .message .config .ServerAuthContext ;
11+ import javax .security .auth .message .module .ServerAuthModule ;
12+ import javax .servlet .http .HttpServletRequest ;
13+ import javax .servlet .http .HttpServletResponse ;
14+
15+ public interface HttpMessageContext {
16+
17+ /**
18+ * Checks if the current request is to a protected resource or not. A protected resource
19+ * is a resource (e.g. a Servlet, JSF page, JSP page etc) for which a constraint has been defined
20+ * in e.g. <code>web.xml<code>.
21+ *
22+ * @return true if a protected resource was requested, false if a public resource was requested.
23+ */
24+ boolean isProtected ();
25+
26+ boolean isAuthenticationRequest ();
27+
28+ /**
29+ * Asks the container to register the given username and roles in order to make
30+ * them available to the application for use with {@link HttpServletRequest#isUserInRole(String)} etc.
31+ * <p>
32+ * This will also ask the runtime to register an authentication session that will live as long as the
33+ * HTTP session is valid.
34+ * <p>
35+ * Note that after this call returned, the authenticated identity will not be immediately active. This
36+ * will only take place (should not errors occur) after the {@link ServerAuthContext} or {@link ServerAuthModule}
37+ * in which this call takes place return control back to the runtime.
38+ *
39+ * @param username the user name that will become the caller principal
40+ * @param roles the roles associated with the caller principal
41+ */
42+ void registerWithContainer (String username , List <String > roles );
43+
44+ /**
45+ * Asks the container to register the given username and roles in order to make
46+ * them available to the application for use with {@link HttpServletRequest#isUserInRole(String)} etc.
47+ * <p>
48+ * This will optionally (on the basis of the registerSession parameter) ask the runtime to register an
49+ * authentication session that will live as long as the HTTP session is valid.
50+ * <p>
51+ * Note that after this call returned, the authenticated identity will not be immediately active. This
52+ * will only take place (should not errors occur) after the {@link ServerAuthContext} or {@link ServerAuthModule}
53+ * in which this call takes place return control back to the runtime.
54+ *
55+ * @param username the user name that will become the caller principal
56+ * @param roles the roles associated with the caller principal
57+ * @param registerSession if true asks the container to register an authentication setting, if false does not ask this.
58+ */
59+ void registerWithContainer (String username , List <String > roles , boolean registerSession );
60+
61+ /**
62+ * Checks if during the current request code has asked the runtime to register an authentication session.
63+ *
64+ * @return true if code has asked to register an authentication session, false otherwise.
65+ */
66+ boolean isRegisterSession ();
67+
68+ /**
69+ * Asks the runtime to register an authentication session. This will automatically remember the logged-in status
70+ * as long as the current HTTP session remains valid. Without this being asked, a SAM has to manually re-authenticate
71+ * with the runtime at the start of each request.
72+ * <p>
73+ * Note that the user name and roles being asked is an implementation detail; there is no portable way to have
74+ * an auth context read back the user name and roles that were processed by the {@link CallbackHandler}.
75+ *
76+ * @param username the user name for which authentication should be be remembered
77+ * @param roles the roles for which authentication should be remembered.
78+ */
79+ void setRegisterSession (String username , List <String > roles );
80+
81+ void cleanClientSubject ();
82+
83+ /**
84+ * Returns the parameters that were provided with the SecurityContect#authenticate(AuthParameters) call.
85+ *
86+ * @return the parameters that were provided with the SecurityContect#authenticate(AuthParameters) call, or a default instance. Never null.
87+ */
88+ AuthenticationParameters getAuthParameters ();
89+
90+ /**
91+ * Returns the handler that the runtime provided to auth context.
92+ *
93+ * @return the handler that the runtime provided to auth context.
94+ */
95+ CallbackHandler getHandler ();
96+
97+ /**
98+ * Returns the module options that were set on the auth module to which this context belongs.
99+ *
100+ * @return the module options that were set on the auth module to which this context belongs.
101+ */
102+ Map <String , String > getModuleOptions ();
103+
104+ /**
105+ * Returns the named module option that was set on the auth module to which this context belongs.
106+ *
107+ * @return the named module option that was set on the auth module to which this context belongs, or null if no option with that name was set.
108+ */
109+ String getModuleOption (String key );
110+
111+ /**
112+ * Returns the message info instance for the current request.
113+ *
114+ * @return the message info instance for the current request.
115+ */
116+ MessageInfo getMessageInfo ();
117+
118+ /**
119+ * Returns the subject for which authentication is to take place.
120+ *
121+ * @return the subject for which authentication is to take place.
122+ */
123+ Subject getClientSubject ();
124+
125+ /**
126+ * Returns the request object associated with the current request.
127+ *
128+ * @return the request object associated with the current request.
129+ */
130+ HttpServletRequest getRequest ();
131+
132+ /**
133+ * Returns the response object associated with the current request.
134+ *
135+ * @return the response object associated with the current request.
136+ */
137+ HttpServletResponse getResponse ();
138+
139+ /**
140+ * Sets the response status to 401 (not found).
141+ * <p>
142+ * As a convenience this method returns SEND_FAILURE, so this method can be used in
143+ * one fluent return statement from an auth module.
144+ *
145+ * @return {@link AuthStatus#SEND_FAILURE}
146+ */
147+ AuthStatus responseUnAuthorized ();
148+
149+ /**
150+ * Sets the response status to 404 (not found).
151+ * <p>
152+ * As a convenience this method returns SEND_FAILURE, so this method can be used in
153+ * one fluent return statement from an auth module.
154+ *
155+ * @return {@link AuthStatus#SEND_FAILURE}
156+ */
157+ AuthStatus responseNotFound ();
158+
159+ /**
160+ * Asks the container to register the given username and roles in order to make
161+ * them available to the application for use with {@link HttpServletRequest#isUserInRole(String)} etc.
162+ *
163+ * <p>
164+ * Note that after this call returned, the authenticated identity will not be immediately active. This
165+ * will only take place (should not errors occur) after the {@link ServerAuthContext} or {@link ServerAuthModule}
166+ * in which this call takes place return control back to the runtime.
167+ *
168+ * <p>
169+ * As a convenience this method returns SUCCESS, so this method can be used in
170+ * one fluent return statement from an auth module.
171+ *
172+ * @param username the user name that will become the caller principal
173+ * @param roles the roles associated with the caller principal
174+ * @return {@link AuthStatus#SUCCESS}
175+ *
176+ */
177+ AuthStatus notifyContainerAboutLogin (String username , List <String > roles );
178+
179+ /**
180+ * Instructs the container to "do nothing".
181+ *
182+ * <p>
183+ * This is a somewhat peculiar requirement of JASPIC, which incidentally almost no containers actually require
184+ * or enforce.
185+ *
186+ * <p>
187+ * When intending to do nothing, most JASPIC auth modules simply return "SUCCESS", but according to
188+ * the JASPIC spec the handler MUST have been used when returning that status. Because of this JASPIC
189+ * implicitly defines a "protocol" that must be followed in this case;
190+ * invoking the CallerPrincipalCallback handler with a null as the username.
191+ *
192+ * <p>
193+ * As a convenience this method returns SUCCESS, so this method can be used in
194+ * one fluent return statement from an auth module.
195+ *
196+ * @return {@link AuthStatus#SUCCESS}
197+ */
198+ AuthStatus doNothing ();
199+
200+ }
0 commit comments