Package: OpenIdAuthenticationMechanismDefinition$OpenIdAuthenticationMechanism

OpenIdAuthenticationMechanismDefinition$OpenIdAuthenticationMechanism

Coverage

1: /*
2: * Copyright (c) 2021, 2024 Contributors to the Eclipse Foundation
3: *
4: * This program and the accompanying materials are made available under the
5: * terms of the Eclipse Public License v. 2.0, which is available at
6: * http://www.eclipse.org/legal/epl-2.0.
7: *
8: * This Source Code may also be made available under the following Secondary
9: * Licenses when the conditions for such availability set forth in the
10: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
11: * version 2 with the GNU Classpath Exception, which is available at
12: * https://www.gnu.org/software/classpath/license.html.
13: *
14: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
15: *
16: */
17:
18: /*
19: *
20: * Contributors:
21: * 2021 : Payara Foundation and/or its affiliates
22: * Initially authored in Security Connectors
23: */
24: package jakarta.security.enterprise.authentication.mechanism.http;
25:
26: import static jakarta.security.enterprise.authentication.mechanism.http.openid.OpenIdConstant.CODE;
27: import static jakarta.security.enterprise.authentication.mechanism.http.openid.OpenIdConstant.EMAIL_SCOPE;
28: import static jakarta.security.enterprise.authentication.mechanism.http.openid.OpenIdConstant.OPENID_SCOPE;
29: import static jakarta.security.enterprise.authentication.mechanism.http.openid.OpenIdConstant.PROFILE_SCOPE;
30: import static java.lang.annotation.ElementType.FIELD;
31: import static java.lang.annotation.ElementType.METHOD;
32: import static java.lang.annotation.ElementType.PARAMETER;
33: import static java.lang.annotation.ElementType.TYPE;
34: import static java.lang.annotation.RetentionPolicy.RUNTIME;
35:
36: import jakarta.enterprise.util.AnnotationLiteral;
37: import jakarta.inject.Qualifier;
38: import jakarta.security.enterprise.authentication.mechanism.http.openid.ClaimsDefinition;
39: import jakarta.security.enterprise.authentication.mechanism.http.openid.DisplayType;
40: import jakarta.security.enterprise.authentication.mechanism.http.openid.LogoutDefinition;
41: import jakarta.security.enterprise.authentication.mechanism.http.openid.OpenIdProviderMetadata;
42: import jakarta.security.enterprise.authentication.mechanism.http.openid.PromptType;
43: import jakarta.security.enterprise.identitystore.IdentityStoreHandler;
44: import java.lang.annotation.Repeatable;
45: import java.lang.annotation.Retention;
46: import java.lang.annotation.Target;
47:
48:
49:
50: /**
51: * Annotation used to define a container authentication mechanism that implements
52: * the Authorization Code flow and Refresh tokens as defined by the OpenId Connect specification
53: * and make that implementation available as an enabled CDI bean.
54: *
55: * <p>
56: * Attributes on this annotation make up the OpenID connect client configuration. Expression Language
57: * expressions in attributes of type <code>String</code> are evaluated.
58: *
59: * <p>
60: * It can make use of the user endpoint for retrieving claims about the user.
61: *
62: * <p>
63: * Note that in the OpenID terminology the authentication mechanism becomes a "Relying Party" (RP)
64: * that redirects the "End-User" (caller) to an "OpenId Connect Provider" (Identity Provider).
65: * Authentication takes place between the user and the Identity Provider, where the result of this
66: * authentication is communicated back to the authentication mechanism.
67: *
68: * <p>
69: * This is depicted in the following non-normative diagram:
70: *
71: * <pre>
72: * +--------+ +--------+
73: * | | | |
74: * | |---------------(1) Authentication Request------------->| |
75: * | | | |
76: * | | +--------+ | |
77: * | | | End- |<--(2) Authenticates the End-User---->| |
78: * | RP | | User | | OP |
79: * | | +--------+ | |
80: * | | | |
81: * | |<---------(3) Returns Authorization code---------------| |
82: * | | | |
83: * | |---------(3b) | |
84: * | | | Redirect to original resource (if any) | |
85: * | |<----------+ | |
86: * | | | |
87: * | |------------------------------------------------------>| |
88: * | | (4) Request to TokenEndpoint for Access / Id Token | |
89: * | OpenId |<------------------------------------------------------| OpenId |
90: * | Connect| | Connect|
91: * | Client | ----------------------------------------------------->|Provider|
92: * | | (5) Fetch JWKS to validate ID Token | |
93: * | |<------------------------------------------------------| |
94: * | | | |
95: * | |------------------------------------------------------>| |
96: * | | (6) Request to UserInfoEndpoint for End-User Claims | |
97: * | |<------------------------------------------------------| |
98: * | | | |
99: * +--------+ +--------+
100: * </pre>
101: *
102: * <p>
103: * Because of the way this authentication mechanism and protocol works, there is no
104: * requirement to explicitly define an identity store. However, the authentication
105: * mechanism MUST validate the token received from the "TokenEndpoint" by calling
106: * the {@link IdentityStoreHandler}. This allows for extra identity stores and/or
107: * a custom IdentityStoreHandler to participate in the final authentication result
108: * (e.g. adding extra groups).
109: *
110: *
111: * @see https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth
112: * @see https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens
113: *
114: * @author Gaurav Gupta
115: * @author Rudy De Busscher
116: */
117: @Target({TYPE, METHOD})
118: @Retention(RUNTIME)
119: @Repeatable(OpenIdAuthenticationMechanismDefinition.List.class)
120: public @interface OpenIdAuthenticationMechanismDefinition {
121:
122: /**
123: * Required, unless providerMetadata is specified.
124: * The provider URI to read / discover the metadata of the openid provider.
125: *
126: * @see http://openid.net/specs/openid-connect-discovery-1_0.html
127: *
128: * @return provider URI to read from which to read metadata
129: */
130: String providerURI() default "";
131:
132: /**
133: * To override the openid connect provider's metadata property discovered
134: * via providerUri.
135: *
136: * @return OpenIdProviderMetadata instance.
137: */
138: OpenIdProviderMetadata providerMetadata() default @OpenIdProviderMetadata;
139:
140: /**
141: * Required. The client identifier issued when the application was
142: * registered.
143: *
144: * @return the client identifier
145: */
146: String clientId() default "";
147:
148: /**
149: * Required. The client secret.
150: *
151: * <p>
152: * Note that it is strongly recommended to set this using an Expression so that the value
153: * is not hardcoded within the code.
154: *
155: * @return The client secret
156: */
157: String clientSecret() default "";
158:
159: /**
160: * Optional. The claims definition defines the custom claims mapping of
161: * caller name and groups.
162: *
163: * @return
164: */
165: ClaimsDefinition claimsDefinition() default @ClaimsDefinition;
166:
167: /**
168: * Optional. The Logout definition defines the logout and Relaying Party session
169: * management configuration.
170: *
171: * @return
172: */
173: LogoutDefinition logout() default @LogoutDefinition;
174:
175: /**
176: * The redirect URI (callback URI) to which the response will be sent by the OpenId
177: * Connect Provider. This URI must be absolute and must exactly match one of the Redirection URI values
178: * for the Client pre-registered at the OpenID Provider.
179: * <p>
180: * The value can be a Jakarta Expression Language 3.0 expression, which can contain
181: * the implicit String variable baseURL. This variable contains the host and context path of the application
182: * for which the OpenID Connect authentication mechanism is installed. This variable makes it easier to compose
183: * an absolute URL as required by the OpenID Connect specification.
184: *
185: * <p>
186: * Examples:
187: * <ul>
188: * <li>{@code redirectURI = "${baseURL}/Callback"} - concatenates the `baseURL` variable and the "/Callback" string
189: * in a composite expression.
190: * </li>
191: * <li>{@code redirectURI = "${baseURL += oidcConfig.redirectCallback}"} - concatenates the `baseURL` variable and the
192: * `redirectCallback` property on bean `oidcConfig` in a single expression
193: * </li>
194: * <li>{@code redirectURI = "${baseURL}#{oidcConfig.redirectCallback}"} - concatenates the `baseURL` variable and the
195: * `redirectCallback` property on bean `oidcConfig` in a composite expression. The `redirectCallback` property would
196: * be evaluated as a deferred expression during each request.
197: * </li>
198: * </ul>
199: *
200: * @return
201: */
202: String redirectURI() default "${baseURL}/Callback";
203:
204: /**
205: * Optional. Automatically redirects the caller (the end-user) from
206: * the redirect URI defined by the <code>redirectURI</code> attribute
207: * to the resource the end-user originally requested in a "login to continue"
208: * scenario.
209: *
210: * <p>
211: * After arriving at the original requested resource, the runtime restores
212: * the request as it originally happened, including cookies, headers, the
213: * request method and the request parameters in the same way as done when
214: * using the {@link LoginToContinue} feature.
215: *
216: * @return
217: */
218: boolean redirectToOriginalResource() default false;
219:
220: /**
221: * Optional. Allows the <code>redirectToOriginalResource</code> to be specified as
222: * Jakarta Expression Language expression.
223: * If set, overrides the value defined by the <code>redirectToOriginalResource</code> value.
224: *
225: * @return
226: */
227: String redirectToOriginalResourceExpression() default "";
228:
229: /**
230: * Optional. The scope value defines the access privileges. The basic (and
231: * required) scope for OpenID Connect is the openid scope.
232: *
233: * @return
234: */
235: String[] scope() default {OPENID_SCOPE, EMAIL_SCOPE, PROFILE_SCOPE};
236:
237: /**
238: * Optional. Allows The scope value to be specified as Jakarta Expression Language expression.
239: * If Set, overrides any values set by scope.
240: *
241: * @return
242: */
243: String scopeExpression() default "";
244:
245: /**
246: * Optional. Response Type value defines the processing flow to be used. By
247: * default, the value is code (Authorization Code Flow).
248: *
249: * @return
250: */
251: String responseType() default CODE;
252:
253: /**
254: * Optional. Informs the Authorization Server of the mechanism to be used
255: * for returning parameters from the Authorization Endpoint.
256: *
257: * @return
258: */
259: String responseMode() default "";
260:
261: /**
262: * Optional. The prompt value specifies whether the authorization server
263: * prompts the user for reauthentication and consent. If no value is
264: * specified and the user has not previously authorized access, then the
265: * user is shown a consent screen.
266: *
267: * @return
268: */
269: PromptType[] prompt() default {};
270:
271: /**
272: * Optional. Allows the prompt value to be specified as Jakarta Expression Language expression.
273: * If Set, overirdes the value defined by the prompt value.
274: *
275: * @return
276: */
277: String promptExpression() default "";
278:
279: /**
280: * Optional. The display value specifying how the authorization server
281: * displays the authentication and consent user interface pages.
282: *
283: * @return
284: */
285: DisplayType display() default DisplayType.PAGE;
286:
287: /**
288: * Optional. Allows the display value to be specified as Jakarta Expression Language expression.
289: * If set, overrides the value defined by display.
290: *
291: * @return
292: */
293: String displayExpression() default "";
294:
295: /**
296: * Optional. Enables string value used to mitigate replay attacks.
297: *
298: * @return
299: */
300: boolean useNonce() default true;
301:
302: /**
303: * Optional. Allows the nonce activation to be specified as Jakarta Expression Language expression.
304: * If set, overrides the value defined by the useNonce value.
305: *
306: * @return
307: */
308: String useNonceExpression() default "";
309:
310: /**
311: * Optional. If enabled the state, nonce values and original requested resource data are stored in an HTTP session
312: * otherwise in cookies.
313: *
314: * @return
315: */
316: boolean useSession() default true;
317:
318: /**
319: * Optional. Allows the configuration of the session through a Jakarta Expression Language expression.
320: * If set, overwrites the value of useSession value.
321: *
322: * @return
323: */
324: String useSessionExpression() default "";
325:
326: /**
327: * An array of extra options that will be sent to the OAuth provider.
328: * <p>
329: * These must be in the form of {@code "key=value"} i.e.
330: * <code> extraParameters={"key1=value", "key2=value2"} </code>
331: *
332: * @return
333: */
334: String[] extraParameters() default {};
335:
336: /**
337: * Allows the extra parameters to be defined as a Jakarta Expression Language expression.
338: * If set, overrides the extraParameters value.
339: *
340: * @return
341: */
342: String extraParametersExpression() default "";
343:
344: /**
345: * Optional. Sets the connect timeout(in milliseconds) for Remote JWKS
346: * retrieval. Value must not be negative and if value is zero then infinite
347: * timeout.
348: *
349: * @return
350: */
351: int jwksConnectTimeout() default 500;
352:
353: /**
354: * Optional. Allows the connect timeout(in milliseconds) for Remote JWKS to be defined as
355: * Jakarta Expression Language expression.
356: * If set, overwrites the jwksConnectTimeout value.
357: *
358: * @return
359: */
360: String jwksConnectTimeoutExpression() default "";
361:
362: /**
363: * Optional. Sets the read timeout(in milliseconds) for Remote JWKS
364: * retrieval. Value must not be negative and if value is zero then infinite
365: * timeout.
366: *
367: * @return
368: */
369: int jwksReadTimeout() default 500;
370:
371: /**
372: * Optional. Allows the read timeout(in milliseconds) for Remote JWKS
373: * retrieval to be defined as Jakarta Expression Language expression.
374: * If set, overwrites the jwksReadTimeout value.
375: *
376: * @return
377: */
378: String jwksReadTimeoutExpression() default "";
379:
380: /**
381: * Optional. Enables or disables the automatically performed refresh of
382: * Access and Refresh Token.
383: *
384: * @return {@code true}, if Access and Refresh Token shall be refreshed
385: * automatically when they are expired.
386: */
387: boolean tokenAutoRefresh() default false;
388:
389: /**
390: * Optional. Allows the automatically performed refresh of
391: * Access and Refresh Token to be defined as Jakarta Expression Language expression.
392: * If set, overwrites the value of tokenAutoRefresh.
393: */
394: String tokenAutoRefreshExpression() default "";
395:
396: /**
397: * Optional. Sets the minimum validity time in milliseconds the Access Token
398: * must be valid before it is considered expired. Value must not be
399: * negative.
400: *
401: * @return
402: */
403: int tokenMinValidity() default 10 * 1000;
404:
405: /**
406: * Optional. Allows the minimum validity time in milliseconds the Access Token
407: * must be valid before it is considered expired to be defined as Jakarta Expression Language expression.
408: * If Set, overwrites the tokenMinValidity value.
409: *
410: * @return
411: */
412: String tokenMinValidityExpression() default "";
413:
414: /**
415: * List of {@link Qualifier qualifier annotations}.
416: *
417: * <p>
418: * An {@link HttpAuthenticationMechanism} injection point
419: * with these qualifier annotations injects a bean that is
420: * produced by this {@code OpenIdAuthenticationMechanismDefinition}.</p>
421: *
422: * <p>
423: * The default value is {@code OpenIdAuthenticationMechanism}, indicating that
424: * this {@code OpenIdAuthenticationMechanismDefinition} produces
425: * bean instances of type {@link HttpAuthenticationMechanism} qualified by
426: * {@code OpenIdAuthenticationMechanism}.
427: *
428: * @return list of qualifiers.
429: * @since 4.0
430: */
431: Class<?>[] qualifiers() default { OpenIdAuthenticationMechanism.class };
432:
433: /**
434: * Enables multiple <code>OpenIdAuthenticationMechanismDefinition</code>
435: * annotations on the same type.
436: */
437: @Retention(RUNTIME)
438: @Target(TYPE)
439: public @interface List {
440: OpenIdAuthenticationMechanismDefinition[] value();
441: }
442:
443: @Qualifier
444: @Retention(RUNTIME)
445: @Target({FIELD, METHOD, TYPE, PARAMETER})
446: public static @interface OpenIdAuthenticationMechanism {
447:
448: /**
449: * Supports inline instantiation of the {@link OpenIdAuthenticationMechanism} qualifier.
450: *
451: * @since 4.0
452: */
453: public static final class Literal extends AnnotationLiteral<OpenIdAuthenticationMechanism> implements OpenIdAuthenticationMechanism {
454: private static final long serialVersionUID = 1L;
455:
456: /**
457: * Instance of the {@link OpenIdAuthenticationMechanism} qualifier.
458: */
459: public static final Literal INSTANCE = new Literal();
460: }
461:
462: }
463: }