Package com.appliedolap.essbase

Interface EssAuthentication

All Known Implementing Classes:
BasicAuthentication, BearerTokenAuthentication, SessionAuthentication, SessionCookieAuthentication
public interface EssAuthentication
How a client proves who it is to Essbase.

Essbase's REST API accepts more than one answer to that question. A username and password over HTTP Basic is the obvious one, but the API also honours a plain session - once a request has been authenticated, the JSESSIONID and _WL_AUTHCOOKIE_JSESSIONID cookies it returns are sufficient on their own, with no Authorization header at all (verified against Essbase 21.7). That matters well beyond tidiness: a deployment fronted by an external identity provider may have no password this API can check, because a federated user's credentials live at the identity provider and never reach Essbase. Being able to present a session that was established some other way is the difference between supporting such a deployment and not.

Implementations may be consulted from several threads, since one client is shared, and must be safe for that.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    authorizationHeader()
    The value for the Authorization header, or null to send none.
    static EssAuthentication
    basic(String username, String password)
    Username and password on every request, with no session.
    static EssAuthentication
    bearerToken(String token)
    A bearer token, sent as Authorization: Bearer <token>.
    default String
    cookieHeader()
    The value for the Cookie header, or null to send none.
    default void
    observeSetCookies(List<String> setCookieHeaders)
    Offers the Set-Cookie headers from a response, so an implementation that establishes a session as it goes can pick one up.
    static EssAuthentication
    session(String username, String password)
    Username and password until the server returns a session, then the session thereafter.
    static EssAuthentication
    sessionCookie(String sessionId, String weblogicAuthCookie)
    An existing session, presented as cookies, with no username or password anywhere.
    default void
    sessionEnded()
    Told that the session this was using has been ended server-side, so that any session state held here is discarded rather than being presented again after it has stopped being valid.
    default Optional<Instant>
    sessionExpiry()
    When the current session expires, if that is known.
    default Optional<String>
    username()
    The user being authenticated as, where this strategy knows it.

  • Method Details

    • authorizationHeader

      String authorizationHeader()
      The value for the Authorization header, or null to send none. Null is meaningful rather than a degenerate case - a cookie-borne session needs no Authorization header.

    • cookieHeader

      default String cookieHeader()
      The value for the Cookie header, or null to send none.

    • observeSetCookies

      default void observeSetCookies(List<String> setCookieHeaders)
      Offers the Set-Cookie headers from a response, so an implementation that establishes a session as it goes can pick one up. Called for every response; most implementations ignore it.

      Takes the raw header values rather than the response so that the decision this makes - which is the subtle part - can be tested without a server or an HttpResponse.

      Parameters:
      setCookieHeaders - every Set-Cookie header value on the response, possibly empty

    • username

      default Optional<String> username()
      The user being authenticated as, where this strategy knows it.

      Empty for a strategy that only carries a session or a token: those identify a user to the server without the client necessarily knowing who it is. A caller that needs the name regardless has to ask the server - but should prefer this, because asking is a round trip and, on Essbase 26.1, GET /session answers 500.

    • sessionEnded

      default void sessionEnded()
      Told that the session this was using has been ended server-side, so that any session state held here is discarded rather than being presented again after it has stopped being valid.

      What that leaves behind depends on the strategy. One holding a username and password falls back to them and will establish a fresh session on the next call; one that only ever had a session has nothing to fall back to, and subsequent calls will be rejected - correctly, because signing off is exactly what the caller asked for.

    • sessionExpiry

      default Optional<Instant> sessionExpiry()
      When the current session expires, if that is known. Essbase reports it in a sessionExpiry cookie alongside the session itself, so it is only ever known for a session this library established.

    • basic

      static EssAuthentication basic(String username, String password)
      Username and password on every request, with no session. Corresponds to what this library has always called "stateless".

    • session

      static EssAuthentication session(String username, String password)
      Username and password until the server returns a session, then the session thereafter. The default, and what this library has always done in its normal (non-stateless) mode.

    • sessionCookie

      static EssAuthentication sessionCookie(String sessionId, String weblogicAuthCookie)
      An existing session, presented as cookies, with no username or password anywhere.

      For a session established outside this library - most obviously by a user signing in through an external identity provider, where there is no password for Essbase to check.

      Parameters:
      sessionId - the JSESSIONID value
      weblogicAuthCookie - the _WL_AUTHCOOKIE_JSESSIONID value, or null if there isn't one

    • bearerToken

      static EssAuthentication bearerToken(String token)
      A bearer token, sent as Authorization: Bearer <token>.

      Provided for deployments whose REST endpoint accepts an OAuth token from an identity provider. Whether a given Essbase accepts one is a property of that deployment: an on-premises 21.7 instance rejects bearer tokens outright, while an Oracle Analytics Cloud instance fronted by IDCS may not. Test against the server in question before relying on it.