SolarNetwork Core

Class: AuthorizationV2Builder

net~ AuthorizationV2Builder

A builder object for the SNWS2 HTTP authorization scheme.

This builder can be used to calculate a one-off header value, for example:

let authHeader = new AuthorizationV2Builder("my-token")
    .path("/solarquery/api/v1/pub/...")
    .build("my-token-secret");

Or the builder can be re-used for a given token:

// create a builder for a token
let builder = new AuthorizationV2Builder("my-token");

// elsewhere, re-use the builder for repeated requests
builder.reset()
    .path("/solarquery/api/v1/pub/...")
    .build("my-token-secret");

Additionally, a signing key can be generated and re-used for up to 7 days:

// create a builder for a token
let builder = new AuthorizationV2Builder("my-token")
  .saveSigningKey("my-token-secret");

// elsewhere, re-use the builder for repeated requests
builder.reset()
    .path("/solarquery/api/v1/pub/...")
    .buildWithSavedKey(); // note previously generated key used

Post requests

For handling POST or PUT requests, you must make sure to configure the properties of this class to match your actual HTTP request:

  1. Use the method() method to configure the HTTP verb (you can use the HttpMethod constants).
  2. Use the contentType() method to configure the same value that will be used for the HTTP Content-Type header (you can use the HttpContentType constants).
  3. If the content type is application/x-www-form-urlencoded then you should use the queryParams() method to configure the request parameters.
  4. If the content type is not application/x-www-form-urlencoded then you should use the computeContentDigest() method to configure a HTTP Digest header.
// create a builder for a token
let builder = new AuthorizationV2Builder("my-token")
  .saveSigningKey("my-token-secret");

// POST request with form data
builder.reset()
    .method(HttpHeaders.POST)
    .path("/solarquery/api/v1/pub/...")
    .contentType(HttpContentType.FORM_URLENCODED_UTF8)
    .queryParams({foo:"bar"})
    .buildWithSavedKey();

// PUT request with JSON data, with XHR style request
let reqJson = JSON.stringify({foo:"bar"});
builder.reset()
    .method(HttpHeaders.PUT)
    .path("/solarquery/api/v1/pub/...")
    .contentType(HttpContentType.APPLICATION_JSON_UTF8)
    .computeContentDigest(reqJson);

// when making actual HTTP request, re-use the computed HTTP Digest header:
xhr.setRequestHeader(
    HttpHeaders.DIGEST,
    builder.httpHeaders.firstValue(HttpHeaders.DIGEST)
);
xhr.setRequestHeader(HttpHeaders.X_SN_DATE, builder.requestDateHeaderValue);
xhr.setRequestHeader(HttpHeaders.AUTHORIZATION, builder.buildWithSavedKey());

new AuthorizationV2Builder(token [, environment])

Constructor.

The reset() method is invoked to set up default values for this instance.

Parameters:
Name Type Argument Description
token string

the auth token to use
environment module:net~Environment <optional>

the environment to use; if not provided a default environment will be created

Members

environment :module:net~Environment

The SolarNet environment.

Type:

forceHostPort :boolean

Force a port number to be added to host values, even if port would be implied.

This can be useful when working with a server behind a proxy, where the proxy is configured to always forward the port even if the port is implied (i.e. HTTPS is used on the standard port 443).

Type:
  • boolean

httpHeaders :module:net~HttpHeaders

The signed HTTP headers.

Type:

parameters :module:util~MultiMap

The HTTP query parameters.

Type:

<readonly> requestDateHeaderValue :string

The authorization request date as a HTTP header string value.

Type:
  • string

<readonly> signingKeyExpirationDate :Date

Get the saved signing key expiration date.

This will return the expiration date the signing key saved via key() or saveSigningKey().

Type:
  • Date

<readonly> signingKeyValid :boolean

Test if a signing key is present and not expired.

Type:
  • boolean

tokenId :string

The SolarNet auth token value.

Type:
  • string

useSnDate :boolean

Control using the X-SN-Date HTTP header versus the Date header.

Set to true to use the X-SN-Date header, false to use the Date header. This will return true if X-SN-Date has been added to the signedHeaderNames property or has been added to the httpHeaders property.

Type:
  • boolean

Methods

build(tokenSecret)

Compute a HTTP Authorization header value from the configured properties on the builder, computing a new signing key based on the configured module:net~AuthorizationV2Builder#date.

Parameters:
Name Type Description
tokenSecret string

the secret to sign the authorization with
Returns:

the SNWS2 HTTP Authorization header value

Type
string

buildCanonicalRequestData()

Compute the canonical request data that will be included in the data to sign with the request.

Returns:

the canonical request data

Type
string

buildWithKey(signingKey)

Compute a HTTP Authorization header value from the configured properties on the builder, using the provided signing key.

This method does not save the signing key for future use in this builder instance (see key() for that).

Parameters:
Name Type Description
signingKey CryptoJS#WordArray

the key to sign the computed signature data with
Returns:

the SNWS2 HTTP Authorization header value

Type
string

buildWithSavedKey()

Compute a HTTP Authorization header value from the configured properties on the builder, using a signing key configured from a previous call to saveSigningKey() or key().

Returns:

the SNWS2 HTTP Authorization header value.

Type
string

canonicalContentSHA256()

Get the canonical request content SHA256 digest, hex encoded.

Returns:

the hex-encoded SHA256 digest of the request content

Type
string

canonicalHeaderNames()

Compute the canonical HTTP header names to include in the signature.

Returns:

the sorted, lower-cased HTTP header names to include

Type
Array.<string>

canonicalHeaders(sortedLowercaseHeaderNames)

Compute the canonical HTTP headers string value.

Parameters:
Name Type Description
sortedLowercaseHeaderNames Array.<string>

the sorted, lower-cased HTTP header names to include
Returns:

the canonical headers string value

Type
string

canonicalQueryParameters()

Compute the canonical query parameters.

Returns:

the canonical query parameters string value

Type
string

computeContentDigest(content)

Compute the SHA-256 digest of the request body content and configure the result on this builder.

This method will compute the digest and then save the result via the contentSHA256() method. In addition, it will set the Digest HTTP header value via header(). This means you must also pass the Digest HTTP header with the request. After calling this method, you can retrieve the Digest HTTP header value via the httpHeadersproperty.

Parameters:
Name Type Description
content string

the request body content to compute a SHA-256 digest value from
Returns:

this object

Type
module:net~AuthorizationV2Builder

computeSigningKey(secretKey)

Compute the signing key, from a secret key and based on the configured date().

This method does not save the signing key for future use in this builder instance (see saveSigningKey() for that). Use this method if you want to compute a signing key that you can later pass to buildWithKey() on some other builder instance. Signing keys are valid for a maximum of 7 days, granular to whole days only. To make a signing key expire in fewer than 7 days, configure a date() value in the past before calling this method.

Parameters:
Name Type Description
secretKey string

the secret key string
Returns:

the computed key

Type
CryptoJS#WordArray

contentSHA256(digest)

Set the HTTP request body content SHA-256 digest value.

Parameters:
Name Type Description
digest string | module:crypto-js/enc-hex~WordArray

the digest value to use; if a string it is assumed to be Hex encoded
Returns:

this object

Type
module:net~AuthorizationV2Builder

contentType(val)

Set the HTTP content type.

This is a shortcut for calling HttpHeaders.put() with the key HttpHeaders.CONTENT_TYPE.

Parameters:
Name Type Description
val string

the HTTP content type value to use
Returns:

this object

Type
module:net~AuthorizationV2Builder

date(val)

Set the authorization request date.

Parameters:
Name Type Description
val Date

the date to use; typically the current time, e.g. new Date()
Returns:

this object

Type
module:net~AuthorizationV2Builder

Set a HTTP header value.

This is a shortcut for calling HttpHeaders#put(headerName, val).

Parameters:
Name Type Description
headerName string

the header name to set
headerValue string

the header value to set
Returns:

this object

Type
module:net~AuthorizationV2Builder

headers(headers)

Set the HTTP headers to use with the request.

The headers object must include all headers necessary by the authentication scheme, and any additional headers also configured via module:net~AuthorizationV2Builder#signedHttpHeaders.

Parameters:
Name Type Description
headers HttpHeaders

the HTTP headers to use
Returns:

this object

Type
module:net~AuthorizationV2Builder

host(val)

Set the HTTP host.

This is a shortcut for calling HttpHeaders#put(HttpHeaders.HOST, val).

Parameters:
Name Type Description
val string

the HTTP host value to use
Returns:

this object

Type
module:net~AuthorizationV2Builder

key(key [, date])

Get or set the signing key.

Use this method to save an existing signing key, for example one received via a refresh request. The date parameter is used to track the expirataion date of the key, as reported by the signingKeyValid property.

If you have an actual token secret value, use the saveSigningKey() method to save it rather than this method.

Parameters:
Name Type Argument Description
key CryptoJS#WordArray

the signing key to save
date Date <optional>

an optional date the signing key was generated with; if not provided the configured date() value will be used
See:
Returns:

when used as a getter, the current saved signing key value, otherwise this object

Type
CryptoJS#WordArray | module:net~AuthorizationV2Builder

method(val)

Set the HTTP method (verb) to use.

Parameters:
Name Type Description
val string

the method to use; see the HttpMethod enum for possible values
Returns:

this object

Type
module:net~AuthorizationV2Builder

path(val)

Set the HTTP request path to use.

Parameters:
Name Type Description
val string

the request path to use
Returns:

this object

Type
module:net~AuthorizationV2Builder

queryParams(params)

Set the HTTP GET query parameters, or POST form-encoded parameters.

Parameters:
Name Type Description
params MultiMap | Object

the parameters to use, as either a MultiMap or simple Object
Returns:

this object

Type
module:net~AuthorizationV2Builder

reset()

Reset to defalut property values.

Any previously saved signing key via saveSigningKey() or key() is preserved. The following items are reset:

Returns:

this object

Type
module:net~AuthorizationV2Builder

saveSigningKey(tokenSecret)

Compute and cache the signing key.

Signing keys are derived from the token secret and valid for 7 days, so this method can be used to compute a signing key so that build() can be called later. The signing date will be set to whatever date is currently configured via date(), which defaults to the current time for newly created builder instances.

If you have an externally computed signing key, such as one returned from a token refresh API call, use the key() method to save it rather than this method. If you want to compute the signing key, without caching it on this builder, use the computeSigningKey() method rather than this method.

Parameters:
Name Type Description
tokenSecret string

the secret to sign the digest with
Returns:

this object

Type
module:net~AuthorizationV2Builder

signedHttpHeaders(signedHeaderNames)

Set additional HTTP header names to sign with the authentication.

Parameters:
Name Type Description
signedHeaderNames Array.<sring>

additional HTTP header names to include in the signature
Returns:

this object

Type
module:net~AuthorizationV2Builder

snDate(enabled)

Set the useSnDate property.

Parameters:
Name Type Description
enabled boolean

true to use the X-SN-Date header, false to use Date
Returns:

this object

Type
module:net~AuthorizationV2Builder

url(url [, ignoreHost])

Set the host, path, and query parameters via a URL string.

Parameters:
Name Type Argument Description
url string

the URL value to use
ignoreHost boolean <optional>

if true then do not set the host() from the given URL; this can be useful when you do not want to override the configured environment host
Returns:

this object

Type
module:net~AuthorizationV2Builder