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

Annotation Type OpenIdAuthenticationMechanismDefinition

@Target({TYPE,METHOD}) @Retention(RUNTIME) 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).

Author:
Gaurav Gupta, Rudy De Busscher

  • 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:
      ""