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
81 package ssocreds
82