Constructor
new AuthorizationV2Builder(token, environmentopt)
Constructor.
The reset() method is invoked to set up default values for this instance.
Name | Type | Attributes | 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 |
- Source
Members
environment :module:net~Environment
The SolarNet environment.
- Source
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).
- boolean
- Source
httpHeaders :module:net~HttpHeaders
The signed HTTP headers.
- Source
parameters :module:util~MultiMap
The HTTP query parameters.
- Source
(readonly) requestDateHeaderValue :string
The authorization request date as a HTTP header string value.
- string
- Source
(readonly) signingKeyExpirationDate :Date
Get the saved signing key expiration date.
This will return the expiration date the signing key saved via key() or saveSigningKey().
- Date
- Source
(readonly) signingKeyValid :boolean
Test if a signing key is present and not expired.
- boolean
- Source
tokenId :string
The SolarNet auth token value.
- string
- Source
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.
- boolean
- Source
Methods
build(tokenSecret) → {string}
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.
Name | Type | Description |
---|---|---|
tokenSecret | string | the secret to sign the authorization with |
- Source
the SNWS2 HTTP Authorization header value
- Type:
- string
buildCanonicalRequestData() → {string}
Compute the canonical request data that will be included in the data to sign with the request.
- Source
the canonical request data
- Type:
- string
buildWithKey(signingKey) → {string}
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).
Name | Type | Description |
---|---|---|
signingKey | CryptoJS#WordArray | the key to sign the computed signature data with |
- Source
the SNWS2 HTTP Authorization header value
- Type:
- string
buildWithSavedKey() → {string}
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().
- Source
the SNWS2 HTTP Authorization header value.
- Type:
- string
canonicalContentSHA256() → {string}
Get the canonical request content SHA256 digest, hex encoded.
- Source
the hex-encoded SHA256 digest of the request content
- Type:
- string
canonicalHeaderNames() → {Array.<string>}
Compute the canonical HTTP header names to include in the signature.
- Source
the sorted, lower-cased HTTP header names to include
- Type:
- Array.<string>
canonicalHeaders(sortedLowercaseHeaderNames) → {string}
Compute the canonical HTTP headers string value.
Name | Type | Description |
---|---|---|
sortedLowercaseHeaderNames | Array.<string> | the sorted, lower-cased HTTP header names to include |
- Source
the canonical headers string value
- Type:
- string
canonicalQueryParameters() → {string}
Compute the canonical query parameters.
- Source
the canonical query parameters string value
- Type:
- string
computeContentDigest(content) → {module:net~AuthorizationV2Builder}
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 httpHeaders
property.
Name | Type | Description |
---|---|---|
content | string | the request body content to compute a SHA-256 digest value from |
- Source
this object
computeSigningKey(secretKey) → {CryptoJS#WordArray}
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.
Name | Type | Description |
---|---|---|
secretKey | string | the secret key string |
- Source
the computed key
- Type:
- CryptoJS#WordArray
contentSHA256(digest) → {module:net~AuthorizationV2Builder}
Set the HTTP request body content SHA-256 digest value.
Name | Type | Description |
---|---|---|
digest | string | | the digest value to use; if a string it is assumed to be Hex encoded |
- Source
this object
contentType(val) → {module:net~AuthorizationV2Builder}
Set the HTTP content type.
This is a shortcut for calling HttpHeaders.put() with the key HttpHeaders.CONTENT_TYPE.
Name | Type | Description |
---|---|---|
val | string | the HTTP content type value to use |
- Source
this object
date(val) → {module:net~AuthorizationV2Builder}
Set the authorization request date.
Name | Type | Description |
---|---|---|
val | Date | the date to use; typically the current time, e.g. |
- Source
this object
header(headerName, headerValue) → {module:net~AuthorizationV2Builder}
Set a HTTP header value.
This is a shortcut for calling HttpHeaders#put(headerName, val)
.
Name | Type | Description |
---|---|---|
headerName | string | the header name to set |
headerValue | string | the header value to set |
- Source
this object
headers(headers) → {module:net~AuthorizationV2Builder}
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.
Name | Type | Description |
---|---|---|
headers | HttpHeaders | the HTTP headers to use |
- Source
this object
host(val) → {module:net~AuthorizationV2Builder}
Set the HTTP host.
This is a shortcut for calling HttpHeaders#put(HttpHeaders.HOST, val)
.
Name | Type | Description |
---|---|---|
val | string | the HTTP host value to use |
- Source
this object
key(key, dateopt) → {CryptoJS#WordArray|module:net~AuthorizationV2Builder}
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.
Name | Type | Attributes | 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 |
- Source
when used as a getter, the current saved signing key value, otherwise this object
- Type:
- CryptoJS#WordArray |
module:net~AuthorizationV2Builder
method(val) → {module:net~AuthorizationV2Builder}
Set the HTTP method (verb) to use.
Name | Type | Description |
---|---|---|
val | string | the method to use; see the HttpMethod enum for possible values |
- Source
this object
path(val) → {module:net~AuthorizationV2Builder}
Set the HTTP request path to use.
Name | Type | Description |
---|---|---|
val | string | the request path to use |
- Source
this object
queryParams(params) → {module:net~AuthorizationV2Builder}
Set the HTTP GET
query parameters, or POST
form-encoded parameters.
Name | Type | Description |
---|---|---|
params | MultiMap | | the parameters to use, as either a MultiMap or simple |
- Source
this object
reset() → {module:net~AuthorizationV2Builder}
Reset to defalut property values.
Any previously saved signing key via saveSigningKey() or key() is preserved. The following items are reset:
- method() is set to
GET
- host() is set to
this.environment.host
- path() is set to
/
- date() is set to the current date
- contentSHA256() is cleared
- headers() is cleared
- queryParams() is cleared
- signedHttpHeaders() is set to a new empty array
- Source
this object
saveSigningKey(tokenSecret) → {module:net~AuthorizationV2Builder}
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.
Name | Type | Description |
---|---|---|
tokenSecret | string | the secret to sign the digest with |
- Source
this object
signedHttpHeaders(signedHeaderNames) → {module:net~AuthorizationV2Builder}
Set additional HTTP header names to sign with the authentication.
Name | Type | Description |
---|---|---|
signedHeaderNames | Array.<sring> | additional HTTP header names to include in the signature |
- Source
this object
snDate(enabled) → {module:net~AuthorizationV2Builder}
Set the useSnDate
property.
Name | Type | Description |
---|---|---|
enabled | boolean |
|
- Source
this object
url(url, ignoreHostopt) → {module:net~AuthorizationV2Builder}
Set the host, path, and query parameters via a URL string.
Name | Type | Attributes | Description |
---|---|---|---|
url | string | the URL value to use | |
ignoreHost | boolean | <optional> | if |
- Source
this object