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:
- Configure the HTTP Challenge Scheme
- Configure a Chain of Login Modules
- Configure a Challenge Handler on the Client
- Configure Authorization
To Configure the HTTP Challenge Scheme
- On the server, update the Gateway configuration (for example, by editing
GATEWAY_HOME/conf/gateway-config.xmlin a text editor).
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 …
Browser Username and password
Client Username and password
Browser A Negotiated scheme per RFC 4559*
Client A Negotiated scheme per RFC 4559*
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
** If you are configuring a custom login module on the Gateway, then you must code the accompanying custom challenge handler in the client.
securitysection of the Gateway configuration and define a realm that includes the
realmelement is a part of the
securityelement 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 Tokenin the
http-challenge-schemeelement, 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>
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
- Use the
Application Basicschemes to provide a quick and easy-to-implement method, requiring only a username and password for authentication. However, these are the least secure schemes and are subject to several threats, not least of which is the fact that the username/password can easily be sniffed in transit by an attacker.
- Use the
Application Negotiateschemes when using Kerberos Network Authentication. For more information, see Configuring Kerberos V5 Network Authentication.
- Use the
Application Tokenscheme when you need a custom token to be presented to your custom login module. See Create a Custom Login Module for configuration information.
Application Tokenprovides strong authentication because you can implement your own custom scheme that is cryptographically protected to challenge the client. When you configure custom authentication with the
Application Tokenelement, you must also:
- Configure a custom login module in the Gateway that defines how to encode/decode the token challenge data, and code the matching challenge handler on the client. See Create a Custom Login Module for more information.
- Create a custom challenge handler on the client to support the custom login module. See Configure a Challenge Handler on the Client for more information.
- In addition to securing networking with the Gateway as described in Secure Network Traffic with the Gateway, using a cryptographic hash function such as bcrypt or a key derivation function such as PBKDF2 to protect passwords is highly recommended.