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
- type SSOTokenProvider
- 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.
Variables ¶
This section is empty.
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 ¶ added in v1.44.298
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 ¶ added in v1.44.298
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 ¶ added in v1.44.298
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 ¶ added in v1.44.298
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 ¶ added in v1.44.298
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 ¶ added in v1.44.298
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.
Source Files