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 Detail

      • 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 exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider.
        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:
        jakarta.security.enterprise.authentication.mechanism.http.openid.DisplayType.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:
        ""