Skip to content

Authentication Setup

This guide details how to configure credentials for cloud storage and secure HTTP endpoints.

HTTP Sources

The HttpRangeReader supports standard authentication schemes via builder methods or property configuration.

Basic Auth

For simple username/password protection.

var reader = HttpRangeReader.builder()
    .uri(URI.create("https://secure.example.com/data.bin"))
    .basicAuth("user", "pass")
    .build();

var props = new Properties();
props.setProperty("io.tileverse.rangereader.http.username", "user");
props.setProperty("io.tileverse.rangereader.http.password", "pass");

var reader = RangeReaderFactory.create(uri, props);

Bearer Tokens

Commonly used with OAuth2 and JWT.

var reader = HttpRangeReader.builder()
    .uri(URI.create("https://api.example.com/data"))
    .bearerToken(System.getenv("API_TOKEN"))
    .build();

Custom Headers / API Keys

For services requiring specific header schemes (e.g., X-API-Key).

var reader = HttpRangeReader.builder()
    .uri(URI.create("https://api.provider.com/data"))
    // Arguments: Header Name, Value, Prefix (optional)
    .apiKey("X-Custom-Auth", "secret-key-123", null) 
    .build();

AWS S3

The S3RangeReader integrates with the standard AWS SDK default credential chain.

Default Discovery Order

The library attempts to find credentials in the following order (standard AWS behavior):

  1. Environment Variables (AWS_ACCESS_KEY_ID, etc.)
  2. System Properties (aws.accessKeyId, etc.)
  3. Web Identity Token (for EKS/K8s)
  4. ~/.aws/credentials file
  5. EC2 Instance Profile

Explicit Configuration

To force a specific credential provider or profile:

// Use a specific profile from ~/.aws/credentials
var profileParams = ProfileCredentialsProvider.create("production");

var reader = S3RangeReader.builder()
    .uri(URI.create("s3://my-bucket/map.pmtiles"))
    .credentialsProvider(profileParams)
    .region(Region.US_EAST_1)
    .build();

Assume Role (STS)

To access cross-account resources via STS:

var stsClient = StsClient.builder().region(Region.US_EAST_1).build();

var roleProvider = StsAssumeRoleCredentialsProvider.builder()
    .stsClient(stsClient)
    .refreshRequest(req -> req
        .roleArn("arn:aws:iam::123456789012:role/CrossAccountAccess")
        .roleSessionName("tileverse-session"))
    .build();

var reader = S3RangeReader.builder()
    .uri(URI.create("s3://external-bucket/data"))
    .credentialsProvider(roleProvider)
    .build();

Azure Blob Storage

Shared Access Signatures provide granular control over access.

// Token typically generated by a backend service
var sasToken = "sv=2020-08-04&ss=b&srt=o&sp=r&se=2024-01-01...";

var reader = AzureBlobRangeReader.builder()
    .uri(URI.create("https://account.blob.core.windows.net/container/blob"))
    .sasToken(sasToken)
    .build();

Connection String

Useful for server-side applications with full access keys.

var conn = "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...";

var reader = AzureBlobRangeReader.builder()
    .uri(URI.create("https://account.blob.core.windows.net/container/blob"))
    .connectionString(conn)
    .build();

Managed Identity

For applications running within Azure infrastructure (VMs, App Service, AKS).

var credential = new DefaultAzureCredentialBuilder().build();

var reader = AzureBlobRangeReader.builder()
    .uri(URI.create("https://account.blob.core.windows.net/container/blob"))
    .credential(credential)
    .build();

Google Cloud Storage (GCS)

Application Default Credentials (ADC)

Recommended for most environments. The library automatically looks for:

  1. GOOGLE_APPLICATION_CREDENTIALS environment variable.
  2. Credentials set via gcloud auth application-default login.
  3. Attached Service Account (GCE, GKE, Cloud Run).
// No extra config needed if ADC is set up
var reader = GoogleCloudStorageRangeReader.builder()
    .uri(URI.create("gs://my-bucket/data"))
    .build();

Service Account Key (JSON)

If you need to manually load a key file:

try (var input = new FileInputStream("/path/to/key.json")) {
    var creds = ServiceAccountCredentials.fromStream(input);

    var reader = GoogleCloudStorageRangeReader.builder()
        .uri(URI.create("gs://my-bucket/data"))
        .credentials(creds)
        .build();
}