solarnetwork-api-core
    Preparing search index...

    Class 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());
    Index

    Constructors

    constructor

    Properties

    environment forceHostPort httpHeaders parameters tokenId? EMPTY_STRING_SHA256_HEX SNWS2_AUTH_SCHEME

    Accessors

    requestDateHeaderValue signingKeyExpirationDate signingKeyValid useSnDate

    Methods

    build buildCanonicalRequestData buildWithKey buildWithSavedKey canonicalContentSHA256 canonicalHeaderNames canonicalHeaders canonicalQueryParameters computeContentDigest computeSignatureData computeSigningKey contentSHA256 contentType date header headers host key method path queryParams reset saveSigningKey signedHttpHeaders snDate url

    Constructors

    Properties

    environment: HostConfig

    The SolarNet environment.

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

    httpHeaders: HttpHeaders

    The signed HTTP headers.

    parameters: MultiMap

    The HTTP query parameters.

    tokenId?: string

    The SolarNet auth token value.

    EMPTY_STRING_SHA256_HEX: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

    The hex-encoded value for an empty SHA256 digest value.

    SNWS2_AUTH_SCHEME: "SNWS2"

    The SolarNetwork V2 authorization scheme.

    Accessors

    • get requestDateHeaderValue(): undefined | string

      The authorization request date as a HTTP header string value.

      Returns undefined | string

    • get signingKeyExpirationDate(): undefined | Date

      Get the saved signing key expiration date.

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

      Returns undefined | Date

    • get signingKeyValid(): boolean

      Test if a signing key is present and not expired.

      Returns boolean

    • get 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.

      Returns boolean

    • set useSnDate(enabled: boolean): void

      Parameters

      • enabled: boolean

      Returns void

    Methods

    • Compute a HTTP Authorization header value from the configured properties on the builder, computing a new signing key based on the configured Net.AuthorizationV2Builder#date.

      Parameters

      • tokenSecret: string

        the secret to sign the authorization with

      Returns string

      the SNWS2 HTTP Authorization header value

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

      Returns string

      the canonical request data

    • 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

      • signingKey: WordArray

        the key to sign the computed signature data with

      Returns string

      the SNWS2 HTTP Authorization header value

    • 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 string

      the SNWS2 HTTP Authorization header value.

      Error if a saved signing key is not configured

    • Get the canonical request content SHA256 digest, hex encoded.

      Returns string

      the hex-encoded SHA256 digest of the request content

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

      Returns string[]

      the sorted, lower-cased HTTP header names to include

    • Compute the canonical HTTP headers string value.

      Parameters

      • sortedLowercaseHeaderNames: string[]

        the sorted, lower-cased HTTP header names to include

      Returns string

      the canonical headers string value

    • Compute the canonical query parameters.

      Returns string

      the canonical query parameters string value

    • 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

      • content: string

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

      Returns this

      this object

    • Compute the data to be signed by the signing key.

      The signature data takes this form:

      SNWS2-HMAC-SHA256
      20170301T120000Z
      Hex(SHA256(canonicalRequestData))

      Parameters

      Returns string

      the data to sign

    • 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

      • secretKey: string

        the secret key string

      Returns WordArray

      the computed key

    • Get the authorization request date.

      Returns Date

      the request date

    • Set the authorization request date.

      Parameters

      • val: Date

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

      Returns this

      this object

    • Set a HTTP header value.

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

      Parameters

      • headerName: string

        the header name to set

      • headerValue: string

        the header value to set

      Returns this

      this object

    • Set the HTTP host.

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

      Parameters

      • val: string

        the HTTP host value to use

      Returns this

      this object

    • Get the saved signing key.

      Returns undefined | WordArray

      the current saved signing key value

    • 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

      • key: WordArray

        the signing key to save

      • Optionaldate: Date

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

      Returns this

      this object

      Net.AuthorizationV2Builder#signingKeyExpirationDate

    • Get the HTTP method (verb) to use.

      Returns string

      the HTTP method to use

    • Set the HTTP method (verb) to use.

      Parameters

      • val: string

        the method to use; see the Net.HttpMethod enum for possible values

      Returns this

      this object

    • Get the HTTP request path to use.

      Returns string

      the request path to use

    • Set the HTTP request path to use.

      Parameters

      • val: string

        the request path to use

      Returns this

      this object

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

      Parameters

      • params: Record<string, any> | MultiMap

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

      Returns this

      this object

    • 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

      • tokenSecret: string

        the secret to sign the digest with

      Returns this

      this object

    • Get additional HTTP header names to sign with the authentication.

      Returns undefined | string[]

      the current signed header names

    • Set additional HTTP header names to sign with the authentication.

      Parameters

      • signedHeaderNames: string[]

        additional HTTP header names to include in the signature

      Returns this

      this object

    • Set the useSnDate property.

      Parameters

      • enabled: boolean

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

      Returns this

      this object

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

      Parameters

      • url: string

        the URL value to use

      • OptionalignoreHost: boolean

        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 AuthorizationV2Builder

      this object

    Settings

    Member Visibility

    On This Page

    Post requests
    Constructors
    Properties
    Accessors
    Methods