Configure the HTTP Challenge Scheme

In this procedure, you will learn how to configure authentication by defining the security element and specifying the HTTP challenge scheme that protects the service.

Before You Begin

This procedure is part of Configure Authentication and Authorization:

  1. Configure the HTTP Challenge Scheme
  2. Configure a Chain of Login Modules
  3. Configure a Challenge Handler on the Client
  4. Configure Authorization

To Configure the HTTP Challenge Scheme

  1. On the server, update the Gateway configuration (for example, by editing GATEWAY_HOME/conf/gateway-config.xml in a text editor).
  2. Determine the type of HTTP challenge scheme you want to configure.

    The following table summarizes the schemes you can configure and the affiliated authentication parameters with which the client or browser can respond to the Gateway’s challenge.

    HTTP Challenge Scheme Challenge is Handled By … Gateway Challenges the Client to Authenticate Itself Using … Client or Browser Responds to the Gateway Challenge Using …
    Basic Browser Username and password BasicChallengeHandler, ChallengeHandler
    Application Basic Client Username and password BasicChallengeHandler, ChallengeHandler, LoginHandler
    Negotiate Browser A Negotiated scheme per RFC 4559* NegotiateHandler, NegotiableHandler, LoginHandler
    Application Negotiate Client A Negotiated scheme per RFC 4559* NegotiateHandler, NegotiableHandler, LoginHandler
    Application Token Client A custom token or HTTP cookies, usually expected by a custom login module.** A custom-written challenge handler and/or login handler that can generate the expected token or cookie value.**

    * The HTTP Negotiate scheme is based on using Object Identifiers (OIDs) per RFC 4559 to identify kinds of tokens. If you use or register your own OID, then you can use that OID with the NegotiateHandler and NegotiableHandler challenge handlers.

    ** If you are configuring a custom login module on the Gateway, then you must code the accompanying custom challenge handler in the client.

  3. Locate the security section of the Gateway configuration and define a realm that includes the http-challenge-scheme.

    The realm element is a part of the security element in the Gateway configuration, and its job is to provide authentication information that associates an authenticated user with a set of authorized roles. You can think of a realm as a logical grouping of users, groups (roles), and access.

    For example, to configure a client to respond to a custom authentication challenge and require authentication with a third-party token for the demo realm, you would configure Application Token in the http-challenge-scheme element, as shown in the following example:

    <security>
      <keystore>
       <type>JCEKS</type>
       <file>keystore.db</file>
       <password-file>keystore.pw</password-file>
      </keystore>
    
      <truststore>
        <file>truststore.db</file>
      </truststore>
    
      <realm>
        <name>demo</name>
        <description>Demo</description>
        <authentication>
          <http-challenge-scheme>Application Token</http-challenge-scheme>
          <http-header>X-Custom-Authorization-Header</http-header>
          <http-query-parameter>myCustomAuthParam</http-query-parameter>
          <http-cookie>sampleCookie1</http-cookie>
        </authentication>  
      </realm>
    </security>
    
  4. Save gateway-config.xml.

The Gateway matches the gateway.hostname for this domain to look up the authentication scheme. The Gateway uses the cookie name defined by http-cookie element as the authentication token to log in. The cookie value become accessible in the login module that reads the cookies using the AuthenticationToken class.

Notes

Next Steps

Configure a Chain of Login Modules

See Also