matlab.net.http.AuthInfo class

Package: matlab.net.http

Authentication or authorization information in HTTP messages

Description

MATLAB^® automatically handles authentication in request messages when you provide credentials in an HTTPOptions object. Use the AuthInfo class to examine authentication, to specify authorization information, or to implement an authentication protocol, such as OAuth, that is not handled automatically by the MATLAB HTTP interface.

The AuthInfo class represents one authentication challenge returned when:

• You call the AuthenticateField.convert method for a response message.

• You insert credentials in an AuthorizationField header field into a request message. When you store an AuthInfo object in an Authorization field, MATLAB automatically encloses values in quotes where required, and inserts escape characters as needed.

• A server returns auth-info data in an AuthenticationInfoField header field.

The AuthenticateField and AuthorizationField convert methods convert each name=value pair attribute in the field to parameter name-and-value pairs in the Parameters property. Escape characters and any quotes surrounding values are removed.

For more information, see RFC 7235 Authentication and RFC 2617 Host-Imp Interface (for Basic and Digest authentication).

Class Attributes

Sealed

true

For information on class attributes, see Class Attributes.

Creation

Description

obj = matlab.net.http.AuthInfo(Scheme,paramName,paramValue) creates an AuthInfo object that includes the Scheme property and optional paramName,paramValue parameters. You can specify several argument pairs in any order as paramName1,paramValue1,...,paramNameN,paramValueN.

obj = matlab.net.http.AuthInfo(paramName,paramValue) creates an AuthInfo object with an empty Scheme value.

obj = matlab.net.http.AuthInfo(pStruct) copies parameters and values from the fields of pStruct.

obj = matlab.net.http.AuthInfo(pStr) creates an AuthInfo from pStr.

Input Arguments

paramName — Parameter name

string | character vector

Parameter name, specified as a string or a character vector. The web service defines paramName,paramValue pairs that it accepts as part of a request. A paramName argument represents parameters that are converted to name=value parameters when you convert an AuthInfo object to a string.

Data Types: char | string

paramValue — Parameter value

type required by paramName

Parameter value, specified as a type required by paramName. There is no constraint on paramValue types, but values must support a string or char method.

pStruct — Parameters and values

MATLAB structure

Parameters and values, specified as fields in a MATLAB structure. The structure should have at least a Scheme field. MATLAB omits fields with empty values.

Data Types: struct

pStr — Parameters and values

string

Parameters and values, specified as strings. For pStr syntax:

• If pStr is a credential or challenge, then see RFC 7235, section 2.1.

• If pStr is an auth-info in an Authentication-Info header, then see RFC 2617, Section 3.2.3.

pStr is one of these formats. The values are optionally enclosed in quotes and escape characters are inserted as needed.

SCHEME token
SCHEME param1=value1, param2=value2, ...
param1=value1, param2=value2, ...

Data Types: string

Properties

Scheme — Authentication scheme

AuthenticationScheme.Basic (default) | matlab.net.http.AuthenticationScheme object | string | empty

Authentication scheme, specified as a matlab.net.http.AuthenticationScheme object or a string naming the scheme.

• If Scheme is a string, then MATLAB attempts to convert it to an AuthenticationScheme enumeration. MATLAB does not provide special processing for a Scheme with numeric value less than 0.

• If the AuthInfo object is a challenge in an AuthenticateField header field and Scheme is not an AuthenticationScheme enumeration, then Scheme is a string. Otherwise, Scheme is a AuthenticationScheme object.

• If AuthInfo is in an AuthorizationField header field, then Scheme is an AuthenticationScheme object.

• If AuthInfo is in an AuthenticationInfoField header field, then Scheme might be empty.

Attributes:

GetAccess	public
SetAccess	public

Parameters — Parameter names and values

n-by-2 cell array

Parameter names and values, specified as an n-by-2 cell array. Parameters{i,1} is the name of the ith parameter and is a string. Parameters{i,2} is its value. The type depends on the parameter. To get or set this property, use the getParameter or setParameter methods.

The Parameters property depends on the Scheme property and the attributes that follow Scheme in the header field. Parameter name matching is case-insensitive. Use the addParameter, setParameter, and removeParameter methods to access the values in the Parameters array.

Some parameter properties have special meanings and syntax, which MATLAB enforces based on the Scheme. Parameters with special meanings are listed here. All other parameters are string objects.

• If Scheme is AuthenticationScheme.Basic, then one parameter is expected.

  • In an AuthenticateField (a challenge from a server), the property name is realm. The server provides the realm for a user prompt, which is matched with the Credentials.Realm property. An AuthInfo returned by the AuthenticateField.convert method always has a realm parameter.

  • In an AuthorizationField (the credentials in a response from a client), the property name is encoded. The Encoded property is a base64-encoded sequence of characters representing the user name and password as it appears in the header field following Scheme. If you set this parameter, then you must encode it yourself using the base64encode function.

• If Scheme is AuthenticationScheme.Digest, then the number of properties is variable and corresponds to name=value attributes in the header field.

  • For an AuthenticateField, see properties listed in RFC 2617, section 3.2.1.

  • For an AuthorizationField, see properties listed in RFC 2617, section 3.2.2.

• If Scheme is any other AuthenticationScheme property or a string, then all attribute names and values are acceptable, as long as they can be converted to strings.

Attributes:

GetAccess	public
SetAccess	public
Dependent	true

Methods

Public Methods

getParameter	Return value of AuthInfo parameter
removeParameter	Remove AuthInfo parameter
setParameter	Set value of AuthInfo parameter

Specialized Operators and Functions

These methods specialize standard MATLAB operators and functions for objects in this class.

eq and isequal	Two AuthInfo objects are equal if: They have the same Scheme property and parameter names. Parameter name matching is case-insensitive. The parameter values are equal using isequal, regardless of the order of the parameters. Both values must be scalars.
string	AuthInfo as string as it appears in an Authorization or Authenticate header field
char	AuthInfo as character vector