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:

sess, err := session.NewSessionWithOptions(session.Options{
    SharedConfigState: session.SharedConfigEnable,
    Profile:           "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.

svc := sso.New(sess, &aws.Config{
    Region: aws.String("us-west-2"), // Client Region must correspond to the AWS SSO user portal region
})

provider := ssocreds.NewCredentialsWithClient(svc, "123456789012", "SSOReadOnlyRole", "https://my-sso-portal.awsapps.com/start")

credentials, err := provider.Get()
if err != nil {
    return err
}

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 NewCredentials(configProvider client.ConfigProvider, accountID, roleName, startURL string, ...) *credentials.Credentials
• func NewCredentialsWithClient(client ssoiface.SSOAPI, accountID, roleName, startURL string, ...) *credentials.Credentials
• func StandardCachedTokenFilepath(key string) (string, error)
• type CreateTokenAPIClient
• type Provider
  • func (p *Provider) Retrieve() (credentials.Value, error)
  • func (p *Provider) RetrieveWithContext(ctx credentials.Context) (credentials.Value, error)
• type SSOTokenProvider
  • func NewSSOTokenProvider(client CreateTokenAPIClient, cachedTokenFilepath string, ...) *SSOTokenProvider
  • func (p *SSOTokenProvider) RetrieveBearerToken(ctx aws.Context) (bearer.Token, error)
• type SSOTokenProviderOptions

Constants

const ErrCodeSSOProviderInvalidToken = "SSOProviderInvalidToken"

ErrCodeSSOProviderInvalidToken is the code 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.

const ProviderName = "SSOProvider"

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

Functions

func NewCredentials

func NewCredentials(configProvider client.ConfigProvider, accountID, roleName, startURL string, optFns ...func(provider *Provider)) *credentials.Credentials

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

func NewCredentialsWithClient

func NewCredentialsWithClient(client ssoiface.SSOAPI, accountID, roleName, startURL string, optFns ...func(provider *Provider)) *credentials.Credentials

NewCredentialsWithClient 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 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(input *ssooidc.CreateTokenInput) (*ssooidc.CreateTokenOutput, error)
}

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

type Provider

type Provider struct {
	credentials.Expiry

	// The Client which is configured for the AWS Region where the AWS SSO user portal is located.
	Client ssoiface.SSOAPI

	// 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
	TokenProvider bearer.TokenProvider
}

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

func (*Provider) Retrieve

func (p *Provider) Retrieve() (credentials.Value, 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.

func (*Provider) RetrieveWithContext

func (p *Provider) RetrieveWithContext(ctx credentials.Context) (credentials.Value, error)

RetrieveWithContext retrieves temporary AWS credentials from the configured Amazon Single Sign-On (AWS SSO) user portal by exchanging the accessToken present in ~/.aws/sso/cache.

type SSOTokenProvider

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

SSOTokenProvider provides a 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 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 aws.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 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.