Providing Authentication

If the destination server requires login credentials, your HTTP request can include an HTTP Authorization header that provides the credentials. The following subsections provide the details:

If you are using a proxy server, you can also specify login credentials for the proxy server; to do so, set the ProxyAuthorization property; see Using a Proxy Server. For details, see the class documentation for %Net.HttpRequestOpens in a new tab.

Authenticating a Request When Using HTTP 1.0

For HTTP 1.0, to authenticate an HTTP request, set the Username and Password properties of the instance of %Net.HttpRequestOpens in a new tab. The instance then creates the HTTP Authorization header based on that username and password, using the Basic Access Authentication (RFC 2617Opens in a new tab). Any subsequent request sent by this %Net.HttpRequestOpens in a new tab will include this header.

Important:

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.

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):

Negotiate
NTLM
Basic

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).

Specifying the Authorization Header Directly

For either HTTP 1.0 or HTTP 1.1 (if applicable to your scenario), you can specify the HTTP Authorization header directly. Specifically, you set the Authorization property equal to the authentication information required by the user agent for the resource that you are requesting.

If you specify the Authorization property, the Username and Password properties are ignored.

Enabling Logging for HTTP Authentication

To enable logging for the HTTP authentication, enter the following in the Terminal:

  set $namespace="%SYS"
  kill ^ISCLOG
  set ^%ISCLOG=2
  set ^%ISCLOG("Category","HttpRequest")=5

Log entries are written to the ^ISCLOG global. To write the log to a file (for easier readability), enter the following (still within the %SYS namespace):

 do ##class(%OAuth2.Utils).DisplayLog("filename")

Where filename is the name of the file to create. The directory must already exist. If the file already exists, it is overwritten.

To stop logging, enter the following (still within the %SYS namespace):

 set ^%ISCLOG=0
 set ^%ISCLOG("Category","HttpRequest")=0

Specifying Other HTTP Request Properties

Introduction to HTTP Requests