Chilkat.AuthAzureSAS Class Overview

Chilkat.AuthAzureSAS creates Azure Shared Access Signature authentication tokens. It defines the Azure SAS string-to-sign, supplies the account access key used for signing, and identifies which parameters should be included in the generated SAS token query string.

What the Class Is Used For

Use Chilkat.AuthAzureSAS when an application needs to authenticate Azure Storage REST requests with a Shared Access Signature. The object is commonly used as a way to specify Azure SAS credentials for the Chilkat.Rest class. It prepares the SAS token that can be added to REST requests so Azure can verify the request permissions, resource, expiration, protocol, and other signed values.

Define the String to Sign Use StringToSign to specify the ordered fields that make up the Azure SAS signature input.
Set the Signing Key Use AccessKey to provide the private base64 Azure access key used to sign the token.
Add Token Parameters Use SetTokenParam for values included in both the string-to-sign and the generated query token.
Add Signing-Only Values Use SetNonTokenParam for values included in the string-to-sign but not emitted as query parameters.

Use with Chilkat.Rest

AuthAzureSAS is used to specify Azure SAS credentials for requests made with Chilkat.Rest. The AuthAzureSAS object is configured with the signing key, the string-to-sign format, and the required SAS parameters. The generated token is then used by REST requests that access Azure Storage resources.

Responsibility Handled By Description
Build the SAS signing data AuthAzureSAS Defines the ordered fields used to create the Azure SAS string-to-sign.
Generate the SAS token AuthAzureSAS Uses the private access key and configured parameters to produce the SAS query token.
Send the Azure REST request Chilkat.Rest Uses the SAS credentials when making HTTP requests to Azure Storage.
Practical role: Think of AuthAzureSAS as the credential object that prepares Azure SAS authentication information for use by Chilkat.Rest.

Typical Workflow

  1. Create an AuthAzureSAS object.
  2. Set AccessKey to the private Azure Storage account access key.
  3. Set StringToSign to the comma-separated list of fields required for the Azure SAS signature.
  4. Add SAS fields with SetTokenParam when the value must be included in the string-to-sign and also appear in the token query parameters.
  5. Add signing-only fields with SetNonTokenParam when the value must be included in the string-to-sign but not included in the token query parameters.
  6. Call GenerateToken to produce the SAS token.
  7. Use the token with Azure Storage REST requests, typically through Chilkat.Rest.
  8. If something fails or behaves unexpectedly, inspect LastErrorText.

Core Concepts

Concept Meaning Important Members
Access Key The private base64 signing key used to generate the SAS signature. AccessKey
String-to-Sign Format A comma-separated list of field names that defines the order of values to be signed. StringToSign
Token Parameter A value included in the string-to-sign and also emitted in the SAS query token. SetTokenParam
Non-Token Parameter A value included in the string-to-sign but not emitted in the SAS query token. SetNonTokenParam
Generated SAS Token The final query-string token generated from the configured signing fields and access key. GenerateToken
Credential Reset Clears previously configured token and non-token parameters. Clear

Properties

Property Purpose Guidance
AccessKey The private Azure access key used to sign the SAS token. This is a base64 string and must be kept private. Do not log it, expose it in client-side code, or store it where unauthorized users can read it.
StringToSign Defines the format and order of the values that are signed. Set this to a comma-separated list of field names required by the Azure SAS token type being generated.
LastErrorText Diagnostic information for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Understanding StringToSign

StringToSign is a comma-separated list of parameter names. Chilkat builds the actual string-to-sign by taking the value for each named parameter and joining those values with line-feed \n characters in the exact order specified.

Example StringToSign
signedpermissions,signedstart,signedexpiry,canonicalizedresource,signedidentifier,signedIP,signedProtocol,signedversion,rscc,rscd,rsce,rscl,rsct
Resulting Value Order Separator
signedpermissions
signedstart
signedexpiry
canonicalizedresource
signedidentifier
signedIP
signedProtocol
signedversion
rscc
rscd
rsce
rscl
rsct 		Values are joined with LF line endings: \n
Ordering matters: SAS signatures are sensitive to both field order and exact values. The StringToSign property defines the order used when generating the signature.

Token vs Non-Token Parameters

Method Included in String-to-Sign? Included in Token Query Params? Use When
SetTokenParam Yes Yes Use for SAS values that must both participate in the signature and be sent to Azure as query parameters.
SetNonTokenParam Yes No Use for values needed only for signing, such as values that form part of the string-to-sign but should not be emitted in the generated token.
Auth parameter names: SetTokenParam takes both the internal signing name and the actual query parameter name to include in the generated token.

Methods

Method Purpose Important Details
SetTokenParam Adds a parameter value that is included in the string-to-sign and also included in the generated token query parameters. Takes a signing name, an auth/query parameter name, and a value.
SetNonTokenParam Adds a parameter value that is included in the string-to-sign but not included in the generated token query parameters. Use for signing-only values.
GenerateToken Generates and returns the SAS token. The token is based on AccessKey, StringToSign, and all configured token and non-token parameters.
Clear Clears all parameters previously set by SetTokenParam and SetNonTokenParam. Use before reusing the object for a different SAS token.

Method Summary by Category

Category Members Purpose
Signing configuration AccessKey, StringToSign Define the signing key and the ordered list of fields to sign.
Parameter setup SetTokenParam, SetNonTokenParam Add values used when building the string-to-sign and generated SAS token.
Token generation GenerateToken Produce the SAS token from the configured fields.
Reset Clear Remove all configured token and non-token parameters.
Diagnostics LastErrorText Read diagnostic information after failed or unexpected operations.

Security Notes

Item Security Guidance
AccessKey Treat the access key as a secret. It can be used to generate SAS tokens, so it should never be exposed to untrusted clients, logs, browser JavaScript, or public source control.
Generated SAS token Treat generated SAS tokens as credentials. A token may grant access until it expires or is otherwise invalidated.
Permissions and expiry Use the minimum permissions and shortest reasonable expiration for the task being performed.
Reuse Call Clear before reusing the object for a different token to avoid accidentally carrying over old parameters.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Generated token is rejected by Azure StringToSign, SetTokenParam, SetNonTokenParam Verify that the string-to-sign fields, order, values, and token parameter names match the SAS token type being generated.
Signature appears incorrect AccessKey, StringToSign Confirm the access key is the correct base64 signing key and that the string-to-sign contains exactly the expected values separated by LF characters.
Expected query parameter is missing SetTokenParam Use SetTokenParam for values that must appear in the generated SAS token query string.
Signing-only value appears in token SetNonTokenParam Use SetNonTokenParam for values that should be signed but not emitted as query parameters.
Old parameter values affect a new token Clear Clear the object before configuring it for a new SAS token.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected token generation or parameter-setting behavior.

Common Pitfalls

Pitfall Better Approach
Using the wrong field order in StringToSign. Set StringToSign to the exact comma-separated order required for the Azure SAS token being generated.
Putting a signing-only value in the generated token. Use SetNonTokenParam when the value should be included only in the string-to-sign.
Expecting SetNonTokenParam values to appear in the token. Use SetTokenParam when the value must also be emitted as a query parameter.
Reusing the object without clearing old parameters. Call Clear before configuring a different SAS token.
Logging or exposing AccessKey. Treat the access key as a private secret.
Checking only client-side generation and ignoring the Azure request result. After using the token with Chilkat.Rest, inspect the HTTP response from Azure to diagnose permission, expiry, resource, or signature errors.

Best Practices

Recommendation Reason
Keep AccessKey private. The access key can generate SAS tokens and should be protected as a secret.
Set StringToSign deliberately. The signature depends on the exact order and values used in the string-to-sign.
Use SetTokenParam only for values that belong in the token query string. This keeps the generated SAS token aligned with Azure's expected query parameters.
Use SetNonTokenParam for signing-only values. Some values may be needed for signing but should not be included as token query parameters.
Call Clear before generating a different token. It prevents old parameter values from affecting the next token.
Inspect LastErrorText after failures. It provides diagnostic detail for failed parameter setup or token generation.
After using the token with Chilkat.Rest, inspect Azure's HTTP response. Token generation may succeed even if Azure later rejects the request due to permissions, expiry, resource path, or signature mismatch.

Summary

Chilkat.AuthAzureSAS is the Chilkat helper class for generating Azure Shared Access Signature tokens. It is commonly used with Chilkat.Rest as a way to specify Azure SAS credentials for REST requests. The class uses a private AccessKey, a configured StringToSign, and token or non-token parameters to generate the SAS token.

The most important practical guidance is to keep the access key private, define the exact string-to-sign field order, distinguish token parameters from signing-only parameters, call Clear before reusing the object for a different token, and inspect both LastErrorText and the Azure HTTP response when troubleshooting.