org.apache.hc.client5.http.auth

## Interface AuthScheme

- All Known Implementing Classes:
    BasicScheme, DigestScheme, GGSSchemeBase, KerberosScheme, NTLMScheme, SPNegoScheme, WindowsNegotiateScheme

      public interface AuthScheme

  This interface represents an abstract challenge-response oriented authentication scheme.

  Authentication schemes can be either request or connection based. The former are expected to provide an authorization response with each request message while the latter is executed only once and applies to the underlying connection for its entire life span. Care must be taken when re-using connections authorized through a connection based authentication scheme and they may carry a particular security context and be authorized for a particular user identity. It is important that such schemes always provide the user identity they represent through the `getPrincipal()` method.

  Authentication scheme are expected to transition through a series of standard phases or states.

  Authentication scheme starts off its life cycle with no context and no specific state.

  The `processChallenge(AuthChallenge, HttpContext)` method is called to process an authentication challenge received either from the target server or a proxy. The authentication scheme transitions to CHALLENGED state and is expected to validate the token passed to it as a parameter and initialize its internal state based on challenge details. Standard authentication schemes are expected to provide a realm attribute in the challenge. `getRealm()` can be called to obtain an identifier of the realm that requires authorization.

  Once the challenge has been fully processed the `isResponseReady(HttpHost, CredentialsProvider, HttpContext)` method to determine whether the scheme is capable of generating a authorization response based on its current state and it holds user credentials required to do so. If this method returns `false` the authentication is considered to be in FAILED state and no authorization response. Otherwise the scheme is considered to be in RESPONSE_READY state.

  Once the scheme is ready to respond to the challenge the `generateAuthResponse( HttpHost, HttpRequest, HttpContext)` method to generate a response token, which will be sent to the opposite endpoint in the subsequent request message.

  Certain non-standard schemes may involve multiple challenge / response exchanges to fully establish a shared context and complete the authentication process. Authentication schemes are required to return `true` `isChallengeComplete()` once the handshake is considered complete.

  The authentication scheme is considered successfully completed and in SUCCESS state if the opposite endpoint accepts the request message containing the authorization response and responds with a message indicating no authentication failure . If the opposite endpoint sends status code 401 or 407 in response to a request message containing the terminal authorization response, the scheme is considered unsuccessful and in FAILED state.

  Since:
    4.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `generateAuthResponse(org.apache.hc.core5.http.HttpHost host, org.apache.hc.core5.http.HttpRequest request, org.apache.hc.core5.http.protocol.HttpContext context)` Generates an authorization response based on the current state.
    `String` | `getName()` Returns textual designation of the given authentication scheme.
    `Principal` | `getPrincipal()` Returns `Principal` whose credentials are used to generate an authentication response.
    `String` | `getRealm()` Returns authentication realm.
    `boolean` | `isChallengeComplete()` Authentication process may involve a series of challenge-response exchanges.
    `boolean` | `isConnectionBased()` Determines if the authentication scheme is expected to provide an authorization response on a per connection basis instead of the standard per request basis
    `boolean` | `isResponseReady(org.apache.hc.core5.http.HttpHost host, CredentialsProvider credentialsProvider, org.apache.hc.core5.http.protocol.HttpContext context)` Determines whether or not an authorization response can be generated based on the actual authentication state.
    `void` | `processChallenge(AuthChallenge authChallenge, org.apache.hc.core5.http.protocol.HttpContext context)` Processes the given auth challenge.

- - ### Method Detail

    - #### getName

          String getName()

      Returns textual designation of the given authentication scheme.
      Returns:
        the name of the given authentication scheme

    - #### isConnectionBased

          boolean isConnectionBased()

      Determines if the authentication scheme is expected to provide an authorization response on a per connection basis instead of the standard per request basis
      Returns:
        `true` if the scheme is connection based, `false` if the scheme is request based.

    - #### processChallenge

          void processChallenge(AuthChallenge authChallenge,
                              org.apache.hc.core5.http.protocol.HttpContext context)
                                throws MalformedChallengeException

      Processes the given auth challenge. Some authentication schemes may involve multiple challenge-response exchanges. Such schemes must be able to maintain internal state when dealing with sequential challenges
      Parameters:
        `authChallenge` - the auth challenge
        `context` - HTTP context
      Throws:
        `MalformedChallengeException` - in case the auth challenge is incomplete, malformed or otherwise invalid.
      Since:
        5.0

    - #### isChallengeComplete

          boolean isChallengeComplete()

      Authentication process may involve a series of challenge-response exchanges. This method tests if the authorization process has been fully completed (either successfully or unsuccessfully), that is, all the required authorization challenges have been processed in their entirety.
      Returns:
        `true` if the authentication process has been completed, `false` otherwise.
      Since:
        5.0

    - #### getRealm

          String getRealm()

      Returns authentication realm. If the concept of an authentication realm is not applicable to the given authentication scheme, returns `null`.
      Returns:
        the authentication realm

    - #### isResponseReady

          boolean isResponseReady(org.apache.hc.core5.http.HttpHost host,
                                CredentialsProvider credentialsProvider,
                                org.apache.hc.core5.http.protocol.HttpContext context)
                                  throws AuthenticationException

      Determines whether or not an authorization response can be generated based on the actual authentication state. Generally the outcome of this method will depend upon availability of user credentials necessary to produce an authorization response.
      Parameters:
        `credentialsProvider` - The credentials to be used for authentication
        `context` - HTTP context
      Returns:
        `true` if an authorization response can be generated and the authentication handshake can proceed, `false` otherwise.
      Throws:
        `AuthenticationException` - if authorization string cannot be generated due to an authentication failure
      Since:
        5.0

    - #### getPrincipal

          Principal getPrincipal()

      Returns `Principal` whose credentials are used to generate an authentication response. Connection based schemes are required to return a user `Principal` if authorization applies to for the entire life span of connection.
      Returns:
        user principal
      Since:
        5.0
      See Also:
        `isConnectionBased()`

    - #### generateAuthResponse

          String generateAuthResponse(org.apache.hc.core5.http.HttpHost host,
                                    org.apache.hc.core5.http.HttpRequest request,
                                    org.apache.hc.core5.http.protocol.HttpContext context)
                                      throws AuthenticationException

      Generates an authorization response based on the current state. Some authentication schemes may need to load user credentials required to generate an authorization response from a `CredentialsProvider` prior to this method call.
      Parameters:
        `request` - The request being authenticated
        `context` - HTTP context
      Returns:
        authorization header
      Throws:
        `AuthenticationException` - if authorization string cannot be generated due to an authentication failure
      Since:
        5.0
      See Also:
        `isResponseReady(HttpHost, CredentialsProvider, HttpContext)`

Copyright © 1999–2022 The Apache Software Foundation. All rights reserved.