or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

credentials.mdec2rolecreds.mdendpointcreds.mdindex.mdlogincreds.mdprocesscreds.mdssocreds.mdstscreds.md
tile.json

tessl/golang-github-com-aws-aws-sdk-go-v2--credentials

Credential management for AWS SDK Go v2, providing retrieval from multiple sources including static credentials, EC2 instance roles, SSO, STS, external processes, and HTTP endpoints

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
golangpkg:golang/github.com/aws/aws-sdk-go-v2/credentials@v1.19.2

To install, run

npx @tessl/cli install tessl/golang-github-com-aws-aws-sdk-go-v2--credentials@1.19.0

index.mddocs/

AWS SDK for Go v2 - credentials

The credentials package provides a comprehensive credential management system for the AWS SDK for Go v2. It enables applications to retrieve AWS credentials from multiple sources with a consistent provider-based architecture.

Package Information

  • Package Name: github.com/aws/aws-sdk-go-v2/credentials
  • Package Type: golang
  • Language: Go
  • Version: 1.19.2
  • License: Apache-2.0
  • Installation: go get github.com/aws/aws-sdk-go-v2/credentials@v1.19.2

Core Imports

import (
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds"
    "github.com/aws/aws-sdk-go-v2/credentials/endpointcreds"
    "github.com/aws/aws-sdk-go-v2/credentials/logincreds"
    "github.com/aws/aws-sdk-go-v2/credentials/processcreds"
    "github.com/aws/aws-sdk-go-v2/credentials/ssocreds"
    "github.com/aws/aws-sdk-go-v2/credentials/stscreds"
)

Basic Usage

package main

import (
    "context"
    "fmt"
    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/credentials"
)

func main() {
    // Create static credentials
    provider := credentials.NewStaticCredentialsProvider(
        "AKIAIOSFODNN7EXAMPLE",
        "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        "",
    )

    // Retrieve credentials
    creds, err := provider.Retrieve(context.TODO())
    if err != nil {
        panic(err)
    }

    fmt.Printf("Access Key: %s\n", creds.AccessKeyID)
}

Architecture

The credentials package follows a provider-based architecture where all credential providers implement the aws.CredentialsProvider interface. Key patterns include:

  • Provider Interface: All providers implement Retrieve(context.Context) (aws.Credentials, error)
  • Credential Chain Tracking: Providers support ProviderSources() for debugging credential resolution
  • Caching: Most providers should be wrapped with aws.CredentialsCache for concurrency safety and performance
  • Functional Options: All providers use functional options pattern for configuration

Capabilities

Static Credentials

Create credentials from explicit access key, secret key, and optional session token.

func NewStaticCredentialsProvider(key, secret, session string) StaticCredentialsProvider

type StaticCredentialsProvider struct {
    Value  aws.Credentials
    Source []aws.CredentialSource
}

func (s StaticCredentialsProvider) Retrieve(_ context.Context) (aws.Credentials, error)
func (s StaticCredentialsProvider) ProviderSources() []aws.CredentialSource

Static Credentials Provider

EC2 Instance Role Credentials

Retrieve credentials from Amazon EC2 Instance Metadata Service (IMDS) for EC2 instances with attached IAM roles.

func New(optFns ...func(*Options)) *Provider

type Provider struct {
    // Has unexported fields
}

func (p *Provider) Retrieve(ctx context.Context) (aws.Credentials, error)

EC2 Role Credentials

HTTP Endpoint Credentials

Retrieve credentials from arbitrary HTTP endpoints, supporting both static and refreshable credentials.

func New(endpoint string, optFns ...func(*Options)) *Provider

type Provider struct {
    // Has unexported fields
}

func (p *Provider) Retrieve(ctx context.Context) (aws.Credentials, error)

Endpoint Credentials

AWS Login Session Credentials

Retrieve credentials for sessions created via aws login command using cached OAuth2 tokens.

func New(client TokenAPIClient, path string, opts ...func(*Options)) *Provider

type Provider struct {
    // Has unexported fields
}

func (p *Provider) Retrieve(ctx context.Context) (aws.Credentials, error)

Login Credentials

External Process Credentials

Execute external commands/processes to retrieve credentials, useful for custom credential sources.

func NewProvider(command string, options ...func(*Options)) *Provider

type Provider struct {
    // Has unexported fields
}

func (p *Provider) Retrieve(ctx context.Context) (aws.Credentials, error)

Process Credentials

AWS SSO Credentials

Retrieve temporary credentials using AWS Single Sign-On (SSO) access tokens cached from AWS CLI.

func New(client GetRoleCredentialsAPIClient, accountID, roleName, startURL string, optFns ...func(options *Options)) *Provider

type Provider struct {
    // Has unexported fields
}

func (p *Provider) Retrieve(ctx context.Context) (aws.Credentials, error)

SSO Credentials

AWS STS Credentials

Retrieve temporary credentials via AWS Security Token Service (STS) by assuming IAM roles or using web identity tokens.

func NewAssumeRoleProvider(client AssumeRoleAPIClient, roleARN string, optFns ...func(*AssumeRoleOptions)) *AssumeRoleProvider

type AssumeRoleProvider struct {
    // Has unexported fields
}

func (p *AssumeRoleProvider) Retrieve(ctx context.Context) (aws.Credentials, error)

func NewWebIdentityRoleProvider(client AssumeRoleWithWebIdentityAPIClient, roleARN string, tokenRetriever IdentityTokenRetriever, optFns ...func(*WebIdentityRoleOptions)) *WebIdentityRoleProvider

type WebIdentityRoleProvider struct {
    // Has unexported fields
}

func (p *WebIdentityRoleProvider) Retrieve(ctx context.Context) (aws.Credentials, error)

STS Credentials

Common Types

aws.Credentials

The credentials structure returned by all providers:

type Credentials struct {
    AccessKeyID     string
    SecretAccessKey string
    SessionToken    string
    Source          string
    CanExpire       bool
    Expires         time.Time
}

aws.CredentialsProvider Interface

The interface implemented by all credential providers:

type CredentialsProvider interface {
    Retrieve(ctx context.Context) (Credentials, error)
}

aws.CredentialSource

For tracking credential chain information:

type CredentialSource struct {
    Name string
}

Error Handling

All credential providers return errors when credential retrieval fails. Common error scenarios include:

  • Invalid credentials: Empty or malformed credential values
  • Expired tokens: Cached tokens or credentials have expired
  • Network failures: Unable to reach metadata endpoints or external services
  • Permission errors: Insufficient permissions to assume roles or access resources
  • Timeout errors: Operations exceed configured timeout durations

Each provider returns descriptive errors that can be checked and handled appropriately.