ssocreds

Documentation

Overview

Package ssocreds provides a credential provider for retrieving temporary AWS credentials using an SSO access token.

IMPORTANT: The provider in this package does not initiate or perform the AWS SSO login flow. The SDK provider expects that you have already performed the SSO login flow using AWS CLI using the "aws sso login" command, or by some other mechanism. The provider must find a valid non-expired access token for the AWS SSO user portal URL in ~/.aws/sso/cache. If a cached token is not found, it is expired, or the file is malformed an error will be returned.

Loading AWS SSO credentials with the AWS shared configuration file

You can use configure AWS SSO credentials from the AWS shared configuration file by specifying the required keys in the profile and referencing an sso-session:

sso_session
sso_account_id
sso_role_name

For example, the following defines a profile "devsso" and specifies the AWS SSO parameters that defines the target account, role, sign-on portal, and the region where the user portal is located. Note: all SSO arguments must be provided, or an error will be returned.

[profile devsso]
sso_session = dev-session
sso_role_name = SSOReadOnlyRole
sso_account_id = 123456789012

[sso-session dev-session]
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

Using the config module, you can load the AWS SDK shared configuration, and specify that this profile be used to retrieve credentials. For example:

config, err := config.LoadDefaultConfig(context.TODO(), config.WithSharedConfigProfile("devsso"))
if err != nil {
    return err
}

Programmatically loading AWS SSO credentials directly

You can programmatically construct the AWS SSO Provider in your application, and provide the necessary information to load and retrieve temporary credentials using an access token from ~/.aws/sso/cache.

ssoClient := sso.NewFromConfig(cfg)
ssoOidcClient := ssooidc.NewFromConfig(cfg)
tokenPath, err := ssocreds.StandardCachedTokenFilepath("dev-session")
if err != nil {
    return err
}

var provider aws.CredentialsProvider
provider = ssocreds.New(ssoClient, "123456789012", "SSOReadOnlyRole", "https://my-sso-portal.awsapps.com/start", func(options *ssocreds.Options) {
  options.SSOTokenProvider = ssocreds.NewSSOTokenProvider(ssoOidcClient, tokenPath)
})

// Wrap the provider with aws.CredentialsCache to cache the credentials until their expire time
provider = aws.NewCredentialsCache(provider)

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

It is important that you wrap the Provider with aws.CredentialsCache if you are programmatically constructing the provider directly. This prevents your application from accessing the cached access token and requesting new credentials each time the credentials are used.

Additional Resources

Configuring the AWS CLI to use AWS Single Sign-On: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html

AWS Single Sign-On User Guide: https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html

Index

• Constants
• func StandardCachedTokenFilepath(key string) (string, error)
• type CreateTokenAPIClient
• type GetRoleCredentialsAPIClient
• type InvalidTokenError
  • func (i *InvalidTokenError) Error() string
  • func (i *InvalidTokenError) Unwrap() error
• type Options
• type Provider
  • func New(client GetRoleCredentialsAPIClient, accountID, roleName, startURL string, ...) *Provider
  • func (p *Provider) Retrieve(ctx context.Context) (aws.Credentials, error)
• type SSOTokenProvider
  • func NewSSOTokenProvider(client CreateTokenAPIClient, cachedTokenFilepath string, ...) *SSOTokenProvider
  • func (p SSOTokenProvider) RetrieveBearerToken(ctx context.Context) (bearer.Token, error)
• type SSOTokenProviderOptions

Constants

const ProviderName = "SSOProvider"

ProviderName is the name of the provider used to specify the source of credentials.

Functions

func StandardCachedTokenFilepath

func StandardCachedTokenFilepath(key string) (string, error)

StandardCachedTokenFilepath returns the filepath for the cached SSO token file, or error if unable get derive the path. Key that will be used to compute a SHA1 value that is hex encoded.

Derives the filepath using the Key as:

~/.aws/sso/cache/<sha1-hex-encoded-key>.json

Types

type CreateTokenAPIClient

type CreateTokenAPIClient interface {
	CreateToken(context.Context, *ssooidc.CreateTokenInput, ...func(*ssooidc.Options)) (
		*ssooidc.CreateTokenOutput, error,
	)
}

CreateTokenAPIClient provides the interface for the SSOTokenProvider's API client for calling CreateToken operation to refresh the SSO token.

type GetRoleCredentialsAPIClient

type GetRoleCredentialsAPIClient interface {
	GetRoleCredentials(context.Context, *sso.GetRoleCredentialsInput, ...func(*sso.Options)) (
		*sso.GetRoleCredentialsOutput, error,
	)
}

GetRoleCredentialsAPIClient is a API client that implements the GetRoleCredentials operation.

type InvalidTokenError

type InvalidTokenError struct {
	Err error
}

InvalidTokenError is the error type that is returned if loaded token has expired or is otherwise invalid. To refresh the SSO session run AWS SSO login with the corresponding profile.

func (*InvalidTokenError) Error

func (i *InvalidTokenError) Error() string

func (*InvalidTokenError) Unwrap

func (i *InvalidTokenError) Unwrap() error

type Options

type Options struct {
	// The Client which is configured for the AWS Region where the AWS SSO user
	// portal is located.
	Client GetRoleCredentialsAPIClient

	// The AWS account that is assigned to the user.
	AccountID string

	// The role name that is assigned to the user.
	RoleName string

	// The URL that points to the organization's AWS Single Sign-On (AWS SSO)
	// user portal.
	StartURL string

	// The filepath the cached token will be retrieved from. If unset Provider will
	// use the startURL to determine the filepath at.
	//
	//    ~/.aws/sso/cache/<sha1-hex-encoded-startURL>.json
	//
	// If custom cached token filepath is used, the Provider's startUrl
	// parameter will be ignored.
	CachedTokenFilepath string

	// Used by the SSOCredentialProvider if a token configuration
	// profile is used in the shared config
	SSOTokenProvider *SSOTokenProvider
}

Options is the Provider options structure.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider is an AWS credential provider that retrieves temporary AWS credentials by exchanging an SSO login token.

func New

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

New returns a new AWS Single Sign-On (AWS SSO) credential provider. The provided client is expected to be configured for the AWS Region where the AWS SSO user portal is located.

func (*Provider) Retrieve

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

Retrieve retrieves temporary AWS credentials from the configured Amazon Single Sign-On (AWS SSO) user portal by exchanging the accessToken present in ~/.aws/sso/cache. However, if a token provider configuration exists in the shared config, then we ought to use the token provider rather then direct access on the cached token.

type SSOTokenProvider

type SSOTokenProvider struct {
	// contains filtered or unexported fields
}

SSOTokenProvider provides an utility for refreshing SSO AccessTokens for Bearer Authentication. The SSOTokenProvider can only be used to refresh already cached SSO Tokens. This utility cannot perform the initial SSO create token.

The SSOTokenProvider is not safe to use concurrently. It must be wrapped in a utility such as smithy-go's auth/bearer#TokenCache. The SDK's config.LoadDefaultConfig will automatically wrap the SSOTokenProvider with the smithy-go TokenCache, if the external configuration loaded configured for an SSO session.

The initial SSO create token should be preformed with the AWS CLI before the Go application using the SSOTokenProvider will need to retrieve the SSO token. If the AWS CLI has not created the token cache file, this provider will return an error when attempting to retrieve the cached token.

This provider will attempt to refresh the cached SSO token periodically if needed when RetrieveBearerToken is called.

A utility such as the AWS CLI must be used to initially create the SSO session and cached token file. https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html

func NewSSOTokenProvider

func NewSSOTokenProvider(client CreateTokenAPIClient, cachedTokenFilepath string, optFns ...func(o *SSOTokenProviderOptions)) *SSOTokenProvider

NewSSOTokenProvider returns an initialized SSOTokenProvider that will periodically refresh the SSO token cached stored in the cachedTokenFilepath. The cachedTokenFilepath file's content will be rewritten by the token provider when the token is refreshed.

The client must be configured for the AWS region the SSO token was created for.

func (SSOTokenProvider) RetrieveBearerToken

func (p SSOTokenProvider) RetrieveBearerToken(ctx context.Context) (bearer.Token, error)

RetrieveBearerToken returns the SSO token stored in the cachedTokenFilepath the SSOTokenProvider was created with. If the token has expired RetrieveBearerToken will attempt to refresh it. If the token cannot be refreshed or is not present an error will be returned.

A utility such as the AWS CLI must be used to initially create the SSO session and cached token file. https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html

type SSOTokenProviderOptions

type SSOTokenProviderOptions struct {
	// Client that can be overridden
	Client CreateTokenAPIClient

	// The set of API Client options to be applied when invoking the
	// CreateToken operation.
	ClientOptions []func(*ssooidc.Options)

	// The path the file containing the cached SSO token will be read from.
	// Initialized the NewSSOTokenProvider's cachedTokenFilepath parameter.
	CachedTokenFilepath string
}

SSOTokenProviderOptions provides the options for configuring the SSOTokenProvider.