1// Package ssocreds provides a credential provider for retrieving temporary AWS
 2// credentials using an SSO access token.
 3//
 4// IMPORTANT: The provider in this package does not initiate or perform the AWS
 5// SSO login flow. The SDK provider expects that you have already performed the
 6// SSO login flow using AWS CLI using the "aws sso login" command, or by some
 7// other mechanism. The provider must find a valid non-expired access token for
 8// the AWS SSO user portal URL in ~/.aws/sso/cache. If a cached token is not
 9// found, it is expired, or the file is malformed an error will be returned.
10//
11// # Loading AWS SSO credentials with the AWS shared configuration file
12//
13// You can use configure AWS SSO credentials from the AWS shared configuration file by
14// specifying the required keys in the profile and referencing an sso-session:
15//
16//	sso_session
17//	sso_account_id
18//	sso_role_name
19//
20// For example, the following defines a profile "devsso" and specifies the AWS
21// SSO parameters that defines the target account, role, sign-on portal, and
22// the region where the user portal is located. Note: all SSO arguments must be
23// provided, or an error will be returned.
24//
25//	[profile devsso]
26//	sso_session = dev-session
27//	sso_role_name = SSOReadOnlyRole
28//	sso_account_id = 123456789012
29//
30//	[sso-session dev-session]
31//	sso_start_url = https://my-sso-portal.awsapps.com/start
32//	sso_region = us-east-1
33//	sso_registration_scopes = sso:account:access
34//
35// Using the config module, you can load the AWS SDK shared configuration, and
36// specify that this profile be used to retrieve credentials. For example:
37//
38//	config, err := config.LoadDefaultConfig(context.TODO(), config.WithSharedConfigProfile("devsso"))
39//	if err != nil {
40//	    return err
41//	}
42//
43// # Programmatically loading AWS SSO credentials directly
44//
45// You can programmatically construct the AWS SSO Provider in your application,
46// and provide the necessary information to load and retrieve temporary
47// credentials using an access token from ~/.aws/sso/cache.
48//
49//	ssoClient := sso.NewFromConfig(cfg)
50//	ssoOidcClient := ssooidc.NewFromConfig(cfg)
51//	tokenPath, err := ssocreds.StandardCachedTokenFilepath("dev-session")
52//	if err != nil {
53//	    return err
54//	}
55//
56//	var provider aws.CredentialsProvider
57//	provider = ssocreds.New(ssoClient, "123456789012", "SSOReadOnlyRole", "https://my-sso-portal.awsapps.com/start", func(options *ssocreds.Options) {
58//	  options.SSOTokenProvider = ssocreds.NewSSOTokenProvider(ssoOidcClient, tokenPath)
59//	})
60//
61//	// Wrap the provider with aws.CredentialsCache to cache the credentials until their expire time
62//	provider = aws.NewCredentialsCache(provider)
63//
64//	credentials, err := provider.Retrieve(context.TODO())
65//	if err != nil {
66//	    return err
67//	}
68//
69// It is important that you wrap the Provider with aws.CredentialsCache if you
70// are programmatically constructing the provider directly. This prevents your
71// application from accessing the cached access token and requesting new
72// credentials each time the credentials are used.
73//
74// # Additional Resources
75//
76// Configuring the AWS CLI to use AWS Single Sign-On:
77// https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html
78//
79// AWS Single Sign-On User Guide:
80// https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html
81package ssocreds