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 providing the specifying the required keys in the profile:

sso_account_id
sso_region
sso_role_name
sso_start_url

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_start_url = https://my-sso-portal.awsapps.com/start
sso_role_name = SSOReadOnlyRole
sso_region = us-east-1
sso_account_id = 123456789012

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.

client := sso.NewFromConfig(cfg)

var provider aws.CredentialsProvider
provider = ssocreds.New(client, "123456789012", "SSOReadOnlyRole", "us-east-1", "https://my-sso-portal.awsapps.com/start")

// 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
• 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)

Constants

const ProviderName = "SSOProvider"

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

Types

type GetRoleCredentialsAPIClient

type GetRoleCredentialsAPIClient interface {
	GetRoleCredentials(ctx context.Context, params *sso.GetRoleCredentialsInput, optFns ...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
}

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.