com.azure.core.credential.AzureSasCredential Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of azure-core Show documentation
This package contains core types for Azure Java clients.
There is a newer version: 1.54.1
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

package com.azure.core.credential;

import com.azure.core.util.logging.ClientLogger;

import java.util.Objects;
import java.util.function.Function;

/**
 * 
 * Represents a credential that uses a shared access signature to authenticate to an Azure Service.
 * It is used for authenticating and authorizing access to Azure services using a shared access signature.
 * 
 *
 * 
 * A shared access signature is a string-based token that grants limited permissions and access to specific
 * resources within an Azure service for a specified period. It allows you to provide time-limited access to your
 * resources without sharing your account key or other sensitive credentials.
 * 
 *
 * 
 * The {@link AzureSasCredential} enables you to authenticate and access Azure services that
 * support shared access signatures. By creating an instance of the {@link AzureSasCredential} class and providing the
 * SAS token as a parameter, you can use this credential to authenticate requests to Azure services.
 * 
 *
 * 
 * To use the Credential, you typically pass it to the appropriate Azure client or service client
 * builder during instantiation. The library internally handles the authentication process and includes the
 * SAS token in the HTTP requests made to the Azure service, allowing you to access the resources specified in
 * the SAS token.
 * 
 *
 * 
 * The {@link AzureSasCredential} is particularly useful when you need to grant temporary and limited access to
 * specific resources, such as Azure Storage containers, blobs, queues, or files, without exposing
 * your account key.
 * 
 *
 * 
 * It's important to note that the availability and usage of the {@link AzureSasCredential} may depend on the
 * specific Azure service and its support for shared access signatures. Additionally, the format and content of the
 * SAS token may vary depending on the service and resource you are targeting.
 * 
 *
 * 
 * Sample: Azure SAS Authentication
 * 
 *
 * 
 * The following code sample demonstrates the creation of a {@link com.azure.core.credential.AzureSasCredential},
 * using the sas token to configure it.
 * 
 *
 * 
 *  * AzureSasCredential azureSasCredential =
 *     new AzureSasCredential("AZURE-SERVICE-SAS-KEY");
 * 
 * 
 *
 * @see com.azure.core.credential
 */
public final class AzureSasCredential {
    // AzureSasCredential is a commonly used credential type, use a static logger.
    private static final ClientLogger LOGGER = new ClientLogger(AzureSasCredential.class);
    private final Function signatureEncoder;

    private volatile String signature;

    /**
     * Creates a credential that authorizes request with the given shared access signature.
     * 
     * The {@code signature} passed is assumed to be encoded. This constructor is effectively the same as calling {@link
     * #AzureSasCredential(String, Function) new AzureSasCredential(signature, null))}.
     *
     * @param signature The shared access signature used to authorize requests.
     * @throws NullPointerException If {@code signature} is {@code null}.
     * @throws IllegalArgumentException If {@code signature} is an empty string.
     */
    public AzureSasCredential(String signature) {
        this(signature, null);
    }

    /**
     * Creates a credential that authorizes request within the given shared access signature.
     * 
     * If {@code signatureEncoder} is non-null the {@code signature}, and all {@link #update(String) updated
     * signatures}, will be encoded using the function. {@code signatureEncoder} should be as idempotent as possible to
     * reduce the chance of double encoding errors.
     *
     * @param signature The shared access signature used to authorize requests.
     * @param signatureEncoder An optional function which encodes the {@code signature}.
     * @throws NullPointerException If {@code signature} is {@code null}.
     * @throws IllegalArgumentException If {@code signature} is an empty string.
     */
    public AzureSasCredential(String signature, Function signatureEncoder) {
        Objects.requireNonNull(signature, "'signature' cannot be null.");
        if (signature.isEmpty()) {
            throw LOGGER.logExceptionAsError(new IllegalArgumentException("'signature' cannot be empty."));
        }

        this.signatureEncoder = signatureEncoder;
        this.signature = (signatureEncoder == null) ? signature : signatureEncoder.apply(signature);
    }

    /**
     * Retrieves the shared access signature associated to this credential.
     *
     * @return The shared access signature being used to authorize requests.
     */
    public String getSignature() {
        return signature;
    }

    /**
     * Rotates the shared access signature associated to this credential.
     *
     * @param signature The new shared access signature to be associated with this credential.
     * @return The updated {@code AzureSasCredential} object.
     * @throws NullPointerException If {@code signature} is {@code null}.
     * @throws IllegalArgumentException If {@code signature} is an empty string.
     */
    public AzureSasCredential update(String signature) {
        Objects.requireNonNull(signature, "'signature' cannot be null.");
        if (signature.isEmpty()) {
            throw LOGGER.logExceptionAsError(new IllegalArgumentException("'signature' cannot be empty."));
        }

        this.signature = (signatureEncoder == null) ? signature : signatureEncoder.apply(signature);
        return this;
    }
}