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 and Inner Type Summary

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

Method Summary

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

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

Method Detail

claimsDefinition	back to summary
public ClaimsDefinition claimsDefinition() Optional. The claims definition defines the custom claims mapping of caller name and groups.

clientId	back to summary
public String clientId() Required. The client identifier issued when the application was registered. Returns:String the client identifier

clientId

back to summary

public String clientId()

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

Returns:String: the client identifier

clientSecret	back to summary
public 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:String The client secret

clientSecret

back to summary

public 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:String: The client secret

display	back to summary
public DisplayType display() Optional. The display value specifying how the authorization server displays the authentication and consent user interface pages.

displayExpression	back to summary
public String displayExpression() Optional. Allows the display value to be specified as Jakarta Expression Language expression. If set, overrides the value defined by display.

extraParameters back to summary

extraParameters	back to summary
public 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"}`

public 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"}

extraParametersExpression	back to summary
public String extraParametersExpression() Allows the extra parameters to be defined as a Jakarta Expression Language expression. If set, overrides the extraParameters value.

jwksConnectTimeout	back to summary
public 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.

jwksConnectTimeoutExpression	back to summary
public 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.

jwksReadTimeout	back to summary
public 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.

jwksReadTimeoutExpression	back to summary
public 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.

logout	back to summary
public LogoutDefinition logout() Optional. The Logout definition defines the logout and Relaying Party session management configuration.

prompt	back to summary
public 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.

promptExpression	back to summary
public 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.

providerMetadata

back to summary

public OpenIdProviderMetadata providerMetadata()

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

Returns:OpenIdProviderMetadata: OpenIdProviderMetadata instance.

providerURI	back to summary
public String providerURI() Required, unless providerMetadata is specified. The provider URI to read / discover the metadata of the openid provider. Returns:String provider URI to read from which to read metadata See Also http://openid.net/specs/openid-connect-discovery-1_0.html

providerURI

back to summary

public String providerURI()

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

Returns:String: provider URI to read from which to read metadata
See Also: http://openid.net/specs/openid-connect-discovery-1_0.html

qualifiers back to summary

qualifiers	back to summary
public 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:Class<?>[] list of qualifiers. Since 4.0

public 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:Class<?>[]: list of qualifiers.
Since: 4.0

redirectToOriginalResource back to summary

redirectToOriginalResource	back to summary
public 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.

public 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.

redirectToOriginalResourceExpression	back to summary
public String redirectToOriginalResourceExpression() Optional. Allows the `redirectToOriginalResource` to be specified as Jakarta Expression Language expression. If set, overrides the value defined by the `redirectToOriginalResource` value.

redirectURI back to summary

redirectURI	back to summary
public 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.

public 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.

responseMode	back to summary
public String responseMode() Optional. Informs the Authorization Server of the mechanism to be used for returning parameters from the Authorization Endpoint.

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

scope	back to summary
public String[] scope() Optional. The scope value defines the access privileges. The basic (and required) scope for OpenID Connect is the openid scope.

scopeExpression	back to summary
public String scopeExpression() Optional. Allows The scope value to be specified as Jakarta Expression Language expression. If Set, overrides any values set by scope.

tokenAutoRefresh back to summary

tokenAutoRefresh	back to summary
public boolean tokenAutoRefresh() Optional. Enables or disables the automatically performed refresh of Access and Refresh Token. Returns:boolean `true`, if Access and Refresh Token shall be refreshed automatically when they are expired.

public boolean tokenAutoRefresh()

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

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

tokenAutoRefreshExpression	back to summary
public 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.

tokenMinValidity	back to summary
public 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.

tokenMinValidityExpression	back to summary
public 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.

useNonce	back to summary
public boolean useNonce() Optional. Enables string value used to mitigate replay attacks.

useNonceExpression	back to summary
public 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.

useSession	back to summary
public boolean useSession() Optional. If enabled the state, nonce values and original requested resource data are stored in an HTTP session otherwise in cookies.

useSessionExpression	back to summary
public String useSessionExpression() Optional. Allows the configuration of the session through a Jakarta Expression Language expression. If set, overwrites the value of useSession value.

jakarta.security.enterprise.authentication.mechanism.http back to summary

public @Interface OpenIdAuthenticationMechanismDefinition.List

Annotations

extends Annotation

@Retention:RUNTIME
@Target:TYPE

Enables multiple OpenIdAuthenticationMechanismDefinition annotations on the same type.

Method Summary

Modifier and Type	Method and Description
public OpenIdAuthenticationMechanismDefinition[]	value()

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

Method Detail

value	back to summary
public OpenIdAuthenticationMechanismDefinition[] value()

jakarta.security.enterprise.authentication.mechanism.http back to summary

public @Interface OpenIdAuthenticationMechanismDefinition.OpenIdAuthenticationMechanism

Known Direct Implementers

extends Annotationjakarta.security.enterprise.authentication.mechanism.http.OpenIdAuthenticationMechanismDefinition.OpenIdAuthenticationMechanism.Literal

Annotations

@Qualifier
@Retention:RUNTIME
@Target:FIELD, METHOD, TYPE, PARAMETER

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	OpenIdAuthenticationMechanismDefinition.OpenIdAuthenticationMechanism.Literal Supports inline instantiation of the `OpenIdAuthenticationMechanism` qualifier.

Method Summary

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

jakarta.security.enterprise.authentication.mechanism.http back to summary

public final Class OpenIdAuthenticationMechanismDefinition.OpenIdAuthenticationMechanism.Literal

Class Inheritance

extends AnnotationLiteral<OpenIdAuthenticationMechanismDefinition.OpenIdAuthenticationMechanism>
implements OpenIdAuthenticationMechanism

java.lang.Object
jakarta.enterprise.util.AnnotationLiteral
jakarta.security.enterprise.authentication.mechanism.http.OpenIdAuthenticationMechanismDefinition.OpenIdAuthenticationMechanism.Literal

All Implemented Interfaces

jakarta.security.enterprise.authentication.mechanism.http.OpenIdAuthenticationMechanismDefinition.OpenIdAuthenticationMechanism, java.lang.annotation.Annotation

Supports inline instantiation of the OpenIdAuthenticationMechanism qualifier.

Since: 4.0

Field Summary

Modifier and Type	Field and Description
public static final OpenIdAuthenticationMechanismDefinition.OpenIdAuthenticationMechanism.Literal	INSTANCE Instance of the `OpenIdAuthenticationMechanism` qualifier.
private static final long	serialVersionUID Hides jakarta.enterprise.util.AnnotationLiteral.serialVersionUID.

Constructor Summary

Access	Constructor and Description
public	Literal()

Method Summary

Inherited from jakarta.enterprise.util.AnnotationLiteral:: annotationType equals hashCode toString

Field Detail

INSTANCE	back to summary
public static final OpenIdAuthenticationMechanismDefinition.OpenIdAuthenticationMechanism.Literal INSTANCE Instance of the `OpenIdAuthenticationMechanism` qualifier.

serialVersionUID	back to summary
private static final long serialVersionUID Hides jakarta.enterprise.util.AnnotationLiteral.serialVersionUID.

Constructor Detail

Literal	back to summary
public Literal()