Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(credential-provider-sso): readme fixes, clarification #2488

Merged
merged 1 commit into from
Jun 17, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 18 additions & 15 deletions packages/credential-provider-sso/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,15 @@

## AWS Credential Provider for Node.js - AWS Single Sign-On (SSO)

This module provides a function, `fromSSO` that will create `CredentialProvider`
functions that read from [AWS SDKs and Tools shared configuration and credentials files](https://docs.aws.amazon.com/credref/latest/refdocs/creds-config-files.html)(Profile appears
in the credentials file will be given precedence over the profile found in the
config file). This provider will load the _resolved_ access token on local disk,
and then request temporary AWS credentials. For the guidance over AWS Single
Sign-On service, please refer to [the service document](https://aws.amazon.com/single-sign-on/).
This module provides a function, `fromSSO`, that creates
`CredentialProvider` functions that read from [AWS SDKs and Tools
shared configuration and credentials
files](https://docs.aws.amazon.com/credref/latest/refdocs/creds-config-files.html).
Profiles in the `credentials` file are given precedence over
profiles in the `config` file. This provider loads the
_resolved_ access token from local disk then requests temporary AWS
credentials. For guidance on the AWS Single Sign-On service, please
refer to [AWS's Single Sign-On documentation](https://aws.amazon.com/single-sign-on/).

## Supported configuration

Expand All @@ -26,16 +29,16 @@ the `fromSSO` factory function. The following options are supported:
- `configFilepath` - The path to the shared config file. If not specified, the
provider will use the value in the `AWS_CONFIG_FILE` environment variable or
`~/.aws/config` by default.
- `ssoClient` - The SSO Client that used to request AWS credentials with the SSO
- `ssoClient` - The SSO Client used to request AWS credentials with the SSO
access token. If not specified, a default SSO client will be created with the
region specified in the profile `sso_region` entry.

## SSO Login with AWS CLI
## SSO Login with the AWS CLI

This credential provider relies on [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html#sso-configure-profile)
to login to an AWS SSO session. Here's a brief walk-through:
This credential provider relies on the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html#sso-configure-profile)
to log into an AWS SSO session. Here's a brief walk-through:

1. Create a new AWS SSO enabled profile using AWS CLI. It will ask you to login
1. Create a new AWS SSO enabled profile using the AWS CLI. It will ask you to login
to your AWS SSO account and prompt for the name of the profile:

```console
Expand All @@ -45,7 +48,7 @@ $ aws configure sso
CLI profile name [123456789011_ReadOnly]: my-sso-profile<ENTER>
```

2. Configure you SDK client with the SSO credential provider:
2. Configure your SDK client with the SSO credential provider:

```javascript
import { fromSSO } from "@aws-sdk/credential-provider-sso"; // ES6 example
Expand All @@ -54,8 +57,8 @@ import { fromSSO } from "@aws-sdk/credential-provider-sso"; // ES6 example
const client = new FooClient({ credentials: fromSSO({ profile: "my-sso-profile" });
```

Alternatively, the SSO credential provider is supported in default Node.js credential
provider:
Alternatively, the SSO credential provider is supported as a default
Node.js credential provider:

```javascript
import { defaultProvider } from "@aws-sdk/credential-provider-node"; // ES6 example
Expand All @@ -64,7 +67,7 @@ import { defaultProvider } from "@aws-sdk/credential-provider-node"; // ES6 exam
const client = new FooClient({ credentials: defaultProvider({ profile: "my-sso-profile" });
```

3. To log out from the current SSO session, use AWS CLI:
3. To log out from the current SSO session, use the AWS CLI:

```console
$ aws sso logout
Expand Down