Skip to content

Configure authentication

HttpJsonClient supports three outbound authentication mechanisms — bearer token, HTTP Basic, and NTLM (explicit credentials or the current process identity) — configured independently and attached automatically to subsequent requests.

Field Value
Operation ID OP-02
Trigger A consumer sets the BearerToken property, calls SetBasicAuthentication, or calls SetNtlmAuthentication on an initialized or uninitialized HttpJsonClient
Inputs Bearer token string; Basic username/password; NTLM username/password, or none for current identity
Outputs An HttpJsonClient instance configured to attach the selected credential(s) to outgoing requests
Primary components HttpJsonClient.BearerToken, HttpJsonClient.SetBasicAuthentication, HttpJsonClient.SetNtlmAuthentication, HttpJsonClient.EncodeForBasicAuthentication
Entry point src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/HttpJsonClient/HttpJsonClient.cs

Steps

  1. Bearer token: the consumer sets the BearerToken property to a non-empty string. The value is stored on the instance and attached as an Authorization header on every subsequent request, regardless of header-persistence settings, because it is a property rather than a Headers entry (BR-HTTP-08).
  2. HTTP Basic: the consumer calls SetBasicAuthentication(userName, password).
  3. The method Base64-encodes userName:password and adds Authorization: Basic <encoded> to the Headers dictionary (BR-HTTP-09).
  4. On failure: if an Authorization key already exists in Headers — for example because headers were persisted from a previous request — Headers.Add throws ArgumentException (BR-HTTP-16).
  5. If BearerToken is also set, both credentials are attached and two Authorization header entries are sent on the same request; how the receiving stack resolves the duplicate is unverified**.
  6. NTLM, explicit credentials: the consumer calls SetNtlmAuthentication(userName, password). The resulting NtlmAuthenticator is stored on the instance and assigned to every RestClient created for a request (BR-HTTP-10).
  7. NTLM, current identity: the consumer calls the parameterless SetNtlmAuthentication(). RestSharp's NtlmAuthenticator() maps to the process's default credentials*, and the resulting authenticator is likewise assigned to every RestClient created for a request (BR-HTTP-10).
  8. Credential persistence differs by mechanism: the BearerToken property and the NTLM authenticator are stored directly on the instance and are never cleared by the library, so they are attached to every subsequent request, including retries, for the instance's lifetime. The Basic Authorization header instead lives in the Headers dictionary, which is cleared after each request unless PersistHeadersAfterRequest is set to true (BR-HTTP-07) — so, with default options, Basic authentication must be re-applied with another SetBasicAuthentication call before each subsequent request, while bearer and NTLM credentials do not. See Execute request for how each mechanism is attached during request building.

Process flow

The following diagram visualizes the three independent authentication configuration paths and where each credential is attached.

flowchart TD
    Start([Consumer configures authentication]) --> Choice{Mechanism?}
    Choice -->|Bearer| Bearer["Set BearerToken property"]
    Choice -->|Basic| Basic["SetBasicAuthentication(user, pw)"]
    Choice -->|NTLM explicit| NtlmExp["SetNtlmAuthentication(user, pw)"]
    Choice -->|NTLM current identity| NtlmCur["SetNtlmAuthentication()"]
    Basic --> Exists{"Authorization key<br>already in Headers?"}
    Exists -->|Yes| Throw(["ArgumentException"])
    Exists -->|No| AddHeader["Add Authorization: Basic header"]
    Bearer --> AttachedBearer(["Attached on every request<br>(never cleared)"])
    AddHeader --> AttachedBasic(["Attached only until Headers<br>are cleared after the next request"])
    NtlmExp --> AttachedAuth(["Authenticator assigned<br>to every new RestClient"])
    NtlmCur --> AttachedAuth

Failure and edge-case behavior

  • SetBasicAuthentication throws ArgumentException when called twice on a persisted instance without first removing the existing Authorization entry (BR-HTTP-16).
  • Combining BearerToken with a Basic or custom Authorization header produces duplicate Authorization header entries on the wire; receiving-side behavior is unverified**.
  • No scheme check exists on the base URL, so Basic and bearer credentials can be sent over a plain http:// endpoint.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

  • src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/HttpJsonClient/HttpJsonClient.cs