Authenticating a Request When Using HTTP 1.1
For HTTP 1.1, to authenticate an HTTP request, in most cases, just set the Username and Password properties of the instance of %Net.HttpRequestOpens in a new tab. When an instance of %Net.HttpRequestOpens in a new tab receives a 401 HTTP status code and WWW-Authenticate header, it attempts to respond with an Authorization header that contains a supported authentication scheme. The first scheme that is supported and configured for InterSystems IRIS is used. By default, it considers these authentication schemes, in order:
-
Negotiate (SPNEGO and Kerberos, per RFC 4559Opens in a new tab and RFC 4178Opens in a new tab)
-
NTLM (NT LAN Manager Authentication Protocol)
-
Basic (Basic Access Authentication as described in RFC 2617Opens in a new tab)
Important:
If there is a chance that Basic authentication will be used, make sure to also use SSL (see Using SSL to Connect). In Basic authentication, the credentials are sent in base-64 encoded form and thus can be easily read.
On Windows, if the Username property is not specified, InterSystems IRIS can instead use the current login context. Specifically, if the server responds with a 401 status code and a WWW-Authenticate header for SPNEGO, Kerberos, or NTLM, then InterSystems IRIS uses the current operating system username and password to create the Authorization header.
The details are different from the HTTP 1.0 case, as follows:
-
If authentication succeeds, InterSystems IRIS updates the CurrentAuthenticationScheme property of the %Net.HttpRequestOpens in a new tab instance to indicate the authentication scheme that it used for the most recent authentication.
-
If an attempt to get an authentication handle or token for a scheme fails, InterSystems IRIS saves the underlying error to the AuthenticationErrors property of the %Net.HttpRequestOpens in a new tab instance. The value of this property is a $LIST, in which each item has the form scheme ERROR: message
Negotiate and NTLM are supported only for HTTP 1.1 because these schemes require multiple round trips, and HTTP 1.0 requires the connection to be closed after each request/response pair.
Variations
If you know the authentication scheme or schemes allowed by the server, you can bypass the initial round trip from the server by including an Authorization header that contains the initial token for the server for a chosen scheme. To do this, set the InitiateAuthentication property of the %Net.HttpRequestOpens in a new tab instance. For the value of this property, specify the name of a single authorization scheme allowed by the server. Use one of the following values (case-sensitive):
If you want to customize the authentication schemes to use (or change their order in which they are considered), set the AuthenticationSchemes of the %Net.HttpRequestOpens in a new tab instance. For the value of this property, specify a comma-separated list of authentication scheme names (using the exact values given in the previous list).
