Module jakarta.security

Package jakarta.security.enterprise.authentication.mechanism.http

Annotation Interface OpenIdAuthenticationMechanismDefinition

@Target({TYPE,METHOD})
@Retention(RUNTIME)
@Repeatable(OpenIdAuthenticationMechanismDefinition.List.class)
public @interface OpenIdAuthenticationMechanismDefinition

Annotation used to define a container authentication mechanism that implements the Authorization Code flow and Refresh tokens as defined by the OpenId Connect specification and make that implementation available as an enabled CDI bean.

Attributes on this annotation make up the OpenID connect client configuration. Expression Language expressions in attributes of type String are evaluated.

It can make use of the user endpoint for retrieving claims about the user.

Note that in the OpenID terminology the authentication mechanism becomes a "Relying Party" (RP) that redirects the "End-User" (caller) to an "OpenId Connect Provider" (Identity Provider). Authentication takes place between the user and the Identity Provider, where the result of this authentication is communicated back to the authentication mechanism.

This is depicted in the following non-normative diagram:

  +--------+                                                       +--------+
  |        |                                                       |        |
  |        |---------------(1) Authentication Request------------->|        |
  |        |                                                       |        |
  |        |       +--------+                                      |        |
  |        |       |  End-  |<--(2) Authenticates the End-User---->|        |
  |   RP   |       |  User  |                                      |   OP   |
  |        |       +--------+                                      |        |
  |        |                                                       |        |
  |        |<---------(3) Returns Authorization code---------------|        |
  |        |                                                       |        |
  |        |---------(3b)                                          |        |
  |        |           | Redirect to original resource (if any)    |        |
  |        |<----------+                                           |        |
  |        |                                                       |        |
  |        |------------------------------------------------------>|        |
  |        |   (4) Request to TokenEndpoint for Access / Id Token  |        |
  | OpenId |<------------------------------------------------------| OpenId |
  | Connect|                                                       | Connect|
  | Client | ----------------------------------------------------->|Provider|
  |        |   (5) Fetch JWKS to validate ID Token                 |        |
  |        |<------------------------------------------------------|        |
  |        |                                                       |        |
  |        |------------------------------------------------------>|        |
  |        |   (6) Request to UserInfoEndpoint for End-User Claims |        |
  |        |<------------------------------------------------------|        |
  |        |                                                       |        |
  +--------+                                                       +--------+
 

Because of the way this authentication mechanism and protocol works, there is no requirement to explicitly define an identity store. However, the authentication mechanism MUST validate the token received from the "TokenEndpoint" by calling the IdentityStoreHandler. This allows for extra identity stores and/or a custom IdentityStoreHandler to participate in the final authentication result (e.g. adding extra groups).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static @interface	OpenIdAuthenticationMechanismDefinition.List	Enables multiple OpenIdAuthenticationMechanismDefinition annotations on the same type.
static @interface	OpenIdAuthenticationMechanismDefinition.OpenIdAuthenticationMechanism

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
ClaimsDefinition	claimsDefinition	Optional.
String	clientId	Required.
String	clientSecret	Required.
DisplayType	display	Optional.
String	displayExpression	Optional.
String[]	extraParameters	An array of extra options that will be sent to the OAuth provider.
String	extraParametersExpression	Allows the extra parameters to be defined as a Jakarta Expression Language expression.
int	jwksConnectTimeout	Optional.
String	jwksConnectTimeoutExpression	Optional.
int	jwksReadTimeout	Optional.
String	jwksReadTimeoutExpression	Optional.
LogoutDefinition	logout	Optional.
PromptType[]	prompt	Optional.
String	promptExpression	Optional.
OpenIdProviderMetadata	providerMetadata	To override the openid connect provider's metadata property discovered via providerUri.
String	providerURI	Required, unless providerMetadata is specified.
Class<?>[]	qualifiers	List of qualifier annotations.
boolean	redirectToOriginalResource	Optional.
String	redirectToOriginalResourceExpression	Optional.
String	redirectURI	The redirect URI (callback URI) to which the response will be sent by the OpenId Connect Provider.
String	responseMode	Optional.
String	responseType	Optional.
String[]	scope	Optional.
String	scopeExpression	Optional.
boolean	tokenAutoRefresh	Optional.
String	tokenAutoRefreshExpression	Optional.
int	tokenMinValidity	Optional.
String	tokenMinValidityExpression	Optional.
boolean	useNonce	Optional.
String	useNonceExpression	Optional.
boolean	useSession	Optional.
String	useSessionExpression	Optional.

Element Details

providerURI

String providerURI

Required, unless providerMetadata is specified. The provider URI to read / discover the metadata of the openid provider.

Returns:

provider URI to read from which to read metadata

Default:

""

providerMetadata

OpenIdProviderMetadata providerMetadata

To override the openid connect provider's metadata property discovered via providerUri.

Returns:

OpenIdProviderMetadata instance.

Default:

@jakarta.security.enterprise.authentication.mechanism.http.openid.OpenIdProviderMetadata

clientId

String clientId

Required. The client identifier issued when the application was registered.

Returns:

the client identifier

Default:

""

clientSecret

String clientSecret

Required. The client secret.

Note that it is strongly recommended to set this using an Expression so that the value is not hardcoded within the code.

Returns:

The client secret

Default:

""

claimsDefinition

ClaimsDefinition claimsDefinition

Optional. The claims definition defines the custom claims mapping of caller name and groups.

Returns:

Default:

@jakarta.security.enterprise.authentication.mechanism.http.openid.ClaimsDefinition

logout

LogoutDefinition logout

Optional. The Logout definition defines the logout and Relaying Party session management configuration.

Returns:

Default:

@jakarta.security.enterprise.authentication.mechanism.http.openid.LogoutDefinition

redirectURI

String redirectURI

The redirect URI (callback URI) to which the response will be sent by the OpenId Connect Provider. This URI must be absolute and must exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider.

The value can be a Jakarta Expression Language 3.0 expression, which can contain the implicit String variable baseURL. This variable contains the host and context path of the application for which the OpenID Connect authentication mechanism is installed. This variable makes it easier to compose an absolute URL as required by the OpenID Connect specification.

Examples:

• redirectURI = "${baseURL}/Callback" - concatenates the `baseURL` variable and the "/Callback" string in a composite expression.
• redirectURI = "${baseURL += oidcConfig.redirectCallback}" - concatenates the `baseURL` variable and the `redirectCallback` property on bean `oidcConfig` in a single expression
• redirectURI = "${baseURL}#{oidcConfig.redirectCallback}" - concatenates the `baseURL` variable and the `redirectCallback` property on bean `oidcConfig` in a composite expression. The `redirectCallback` property would be evaluated as a deferred expression during each request.

Returns:

Default:

"${baseURL}/Callback"

redirectToOriginalResource

boolean redirectToOriginalResource

Optional. Automatically redirects the caller (the end-user) from the redirect URI defined by the redirectURI attribute to the resource the end-user originally requested in a "login to continue" scenario.

After arriving at the original requested resource, the runtime restores the request as it originally happened, including cookies, headers, the request method and the request parameters in the same way as done when using the LoginToContinue feature.

Returns:

Default:

false

redirectToOriginalResourceExpression

String redirectToOriginalResourceExpression

Optional. Allows the redirectToOriginalResource to be specified as Jakarta Expression Language expression. If set, overrides the value defined by the redirectToOriginalResource value.

Returns:

Default:

""

scope

String[] scope

Optional. The scope value defines the access privileges. The basic (and required) scope for OpenID Connect is the openid scope.

Returns:

Default:

{"openid", "email", "profile"}

scopeExpression

String scopeExpression

Optional. Allows The scope value to be specified as Jakarta Expression Language expression. If Set, overrides any values set by scope.

Returns:

Default:

""

responseType

String responseType

Optional. Response Type value defines the processing flow to be used. By default, the value is code (Authorization Code Flow).

Returns:

Default:

"code"

responseMode

String responseMode

Optional. Informs the Authorization Server of the mechanism to be used for returning parameters from the Authorization Endpoint.

Returns:

Default:

""

prompt

PromptType[] prompt

Optional. The prompt value specifies whether the authorization server prompts the user for reauthentication and consent. If no value is specified and the user has not previously authorized access, then the user is shown a consent screen.

Returns:

Default:

{}

promptExpression

String promptExpression

Optional. Allows the prompt value to be specified as Jakarta Expression Language expression. If Set, overirdes the value defined by the prompt value.

Returns:

Default:

""

display

DisplayType display

Optional. The display value specifying how the authorization server displays the authentication and consent user interface pages.

Returns:

Default:

PAGE

displayExpression

String displayExpression

Optional. Allows the display value to be specified as Jakarta Expression Language expression. If set, overrides the value defined by display.

Returns:

Default:

""

useNonce

boolean useNonce

Optional. Enables string value used to mitigate replay attacks.

Returns:

Default:

true

useNonceExpression

String useNonceExpression

Optional. Allows the nonce activation to be specified as Jakarta Expression Language expression. If set, overrides the value defined by the useNonce value.

Returns:

Default:

""

useSession

boolean useSession

Optional. If enabled the state, nonce values and original requested resource data are stored in an HTTP session otherwise in cookies.

Returns:

Default:

true

useSessionExpression

String useSessionExpression

Optional. Allows the configuration of the session through a Jakarta Expression Language expression. If set, overwrites the value of useSession value.

Returns:

Default:

""

extraParameters

String[] extraParameters

An array of extra options that will be sent to the OAuth provider.

These must be in the form of "key=value" i.e. extraParameters={"key1=value", "key2=value2"}

Returns:

Default:

{}

extraParametersExpression

String extraParametersExpression

Allows the extra parameters to be defined as a Jakarta Expression Language expression. If set, overrides the extraParameters value.

Returns:

Default:

""

jwksConnectTimeout

int jwksConnectTimeout

Optional. Sets the connect timeout(in milliseconds) for Remote JWKS retrieval. Value must not be negative and if value is zero then infinite timeout.

Returns:

Default:

500

jwksConnectTimeoutExpression

String jwksConnectTimeoutExpression

Optional. Allows the connect timeout(in milliseconds) for Remote JWKS to be defined as Jakarta Expression Language expression. If set, overwrites the jwksConnectTimeout value.

Returns:

Default:

""

jwksReadTimeout

int jwksReadTimeout

Optional. Sets the read timeout(in milliseconds) for Remote JWKS retrieval. Value must not be negative and if value is zero then infinite timeout.

Returns:

Default:

500

jwksReadTimeoutExpression

String jwksReadTimeoutExpression

Optional. Allows the read timeout(in milliseconds) for Remote JWKS retrieval to be defined as Jakarta Expression Language expression. If set, overwrites the jwksReadTimeout value.

Returns:

Default:

""

tokenAutoRefresh

boolean tokenAutoRefresh

Optional. Enables or disables the automatically performed refresh of Access and Refresh Token.

Returns:

true, if Access and Refresh Token shall be refreshed automatically when they are expired.

Default:

false

tokenAutoRefreshExpression

String tokenAutoRefreshExpression

Optional. Allows the automatically performed refresh of Access and Refresh Token to be defined as Jakarta Expression Language expression. If set, overwrites the value of tokenAutoRefresh.

Default:

""

tokenMinValidity

int tokenMinValidity

Optional. Sets the minimum validity time in milliseconds the Access Token must be valid before it is considered expired. Value must not be negative.

Returns:

Default:

10000

tokenMinValidityExpression

String tokenMinValidityExpression

Optional. Allows the minimum validity time in milliseconds the Access Token must be valid before it is considered expired to be defined as Jakarta Expression Language expression. If Set, overwrites the tokenMinValidity value.

Returns:

Default:

""

qualifiers

Class<?>[] qualifiers

List of qualifier annotations.

An HttpAuthenticationMechanism injection point with these qualifier annotations injects a bean that is produced by this OpenIdAuthenticationMechanismDefinition.

The default value is OpenIdAuthenticationMechanism, indicating that this OpenIdAuthenticationMechanismDefinition produces bean instances of type HttpAuthenticationMechanism qualified by OpenIdAuthenticationMechanism.

Returns:

list of qualifiers.

Since:

4.0

Default:

{jakarta.security.enterprise.authentication.mechanism.http.OpenIdAuthenticationMechanismDefinition.OpenIdAuthenticationMechanism.class}