Tutorial for SSO using the AWS CLI and .NET applications
This tutorial shows you how to enable SSO for a basic .NET application and a test SSO user. It uses the AWS CLI to generate a temporary SSO token instead of generating it programmatically.
This tutorial shows you a small portion of SSO functionality in the AWS SDK for .NET. For full details about using IAM Identity Center with the AWS SDK for .NET, see the topic with background information. In that topic, see especially the high-level description for this scenario in the subsection called AWS CLI and .NET application.
Note
Several of the steps in this tutorial help you configure services like AWS Organizations and IAM Identity Center. If you've already performed those configurations, or if you're only interested in the code, you can skip to the section with the example code.
Prerequisites
-
Configure your development environment if you haven't already done so. This is described in sections like Install and configure your toolchain and Get started.
-
Identify or create at least one AWS account that you can use to test SSO. For the purposes of this tutorial, this is called the test AWS account or simply test account.
-
Identify an SSO user who can test SSO for you. This is a person who will be using SSO and the basic applications that you create. For this tutorial, that person might be you (the developer), or someone else. We also recommend a setup in which the SSO user is working on a computer that is not in your development environment. However, this isn't strictly necessary.
-
The SSO user's computer must have a .NET framework installed that's compatible with the one you used to set up your development environment.
-
Be sure that the AWS CLI version 2 is installed on the SSO user's computer. You can check this by running
aws --version
in a command prompt or terminal.
Set up AWS
This section shows you how to set up various AWS services for this tutorial.
To perform this setup, first sign in to the test AWS account as an administrator. Then, do the following:
Amazon S3
Go to the Amazon S3 console
AWS IAM
Go to the IAM console
AWS Organizations
Go to the AWS Organizations console
This action adds the test AWS account to the organization as the management account. If you have additional test accounts, you can invite them to join the organization, but doing so isn't necessary for this tutorial.
IAM Identity Center
Go to the IAM Identity Center console
Then, perform the following configuration.
-
Go to the Settings page. Look for the "access portal URL" and record the value for later use in the
sso_start_url
setting. -
In the banner of the AWS Management Console, look for the AWS Region that was set when you enabled SSO. This is the dropdown menu to the left of the AWS account ID. Record the Region code for later use in the
sso_region
setting. This code will be similar tous-east-1
. -
Create an SSO user as follows:
-
Go to the Users page.
-
Choose Add user and enter the user's Username, Email address, First name, and Last name. Then, choose Next.
-
Choose Next on the page for groups, then review the information and choose Add user.
-
-
Create a group as follows:
-
Go to the Groups page.
-
Choose Create group and enter the group's Group name and Description.
-
In the Add users to group section, select the test SSO user that you created earlier. Then, select Create group.
-
-
Create a permission set as follows:
-
Go to the Permission sets page and choose Create permission set.
-
Under Permission set type, select Custom permission set and choose Next.
-
Open Inline policy and enter the following policy:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "s3:ListAllMyBuckets", "iam:ListUsers" ], "Resource": "*" } ] }
-
For this tutorial, enter
SSOReadOnlyRole
as the Permission set name. Add a Description if you want and then choose Next. -
Review the information and then choose Create.
-
Record the name of the permission set for later use in the
sso_role_name
setting.
-
-
Go to the AWS accounts page and choose the AWS account that you added to the organization earlier.
-
In the Overview section of that page, find the Account ID and record it for later use in the
sso_account_id
setting. -
Choose the Users and groups tab and then choose Assign users or groups.
-
On the Assign users and groups page, choose the Groups tab, select the group that you created earlier, and choose Next.
-
Select the permission set that you created earlier and choose Next, then choose Submit. The configuration takes a few moments.
Create example applications
Create the following applications. They will be run on the SSO user's computer.
Include NuGet packages AWSSDK.SSO
and AWSSDK.SSOOIDC
in addition to
AWSSDK.S3
and AWSSDK.SecurityToken
.
using System; using System.Threading.Tasks; // NuGet packages: AWSSDK.S3, AWSSDK.SecurityToken, AWSSDK.SSO, AWSSDK.SSOOIDC using Amazon.Runtime; using Amazon.Runtime.CredentialManagement; using Amazon.S3; using Amazon.S3.Model; using Amazon.SecurityToken; using Amazon.SecurityToken.Model; namespace SSOExample.S3.CLI_login { class Program { // Requirements: // - An SSO profile in the SSO user's shared config file. // - An active SSO Token. // If an active SSO token isn't available, the SSO user should do the following: // In a terminal, the SSO user must call "aws sso login --profile my-sso-profile". // Class members. private static string profile = "my-sso-profile"; static async Task Main(string[] args) { // Get SSO credentials from the information in the shared config file. var ssoCreds = LoadSsoCredentials(profile); // Display the caller's identity. var ssoProfileClient = new AmazonSecurityTokenServiceClient(ssoCreds); Console.WriteLine($"\nSSO Profile:\n {await ssoProfileClient.GetCallerIdentityArn()}"); // Display a list of the account's S3 buckets. // The S3 client is created using the SSO credentials obtained earlier. var s3Client = new AmazonS3Client(ssoCreds); Console.WriteLine("\nGetting a list of your buckets..."); var listResponse = await s3Client.ListBucketsAsync(); Console.WriteLine($"Number of buckets: {listResponse.Buckets.Count}"); foreach (S3Bucket b in listResponse.Buckets) { Console.WriteLine(b.BucketName); } Console.WriteLine(); } // Method to get SSO credentials from the information in the shared config file. static AWSCredentials LoadSsoCredentials(string profile) { var chain = new CredentialProfileStoreChain(); if (!chain.TryGetAWSCredentials(profile, out var credentials)) throw new Exception($"Failed to find the {profile} profile"); return credentials; } } // Class to read the caller's identity. public static class Extensions { public static async Task<string> GetCallerIdentityArn(this IAmazonSecurityTokenService stsClient) { var response = await stsClient.GetCallerIdentityAsync(new GetCallerIdentityRequest()); return response.Arn; } } }
Include NuGet packages AWSSDK.SSO
and AWSSDK.SSOOIDC
in addition to
AWSSDK.IdentityManagement
and AWSSDK.SecurityToken
.
using System; using System.Threading.Tasks; // NuGet packages: AWSSDK.IdentityManagement, AWSSDK.SecurityToken, AWSSDK.SSO, AWSSDK.SSOOIDC using Amazon.Runtime; using Amazon.Runtime.CredentialManagement; using Amazon.IdentityManagement; using Amazon.IdentityManagement.Model; using Amazon.SecurityToken; using Amazon.SecurityToken.Model; namespace SSOExample.IAM.CLI_login { class Program { // Requirements: // - An SSO profile in the SSO user's shared config file. // - An active SSO Token. // If an active SSO token isn't available, the SSO user should do the following: // In a terminal, the SSO user must call "aws sso login --profile my-sso-profile". // Class members. private static string profile = "my-sso-profile"; static async Task Main(string[] args) { // Get SSO credentials from the information in the shared config file. var ssoCreds = LoadSsoCredentials(profile); // Display the caller's identity. var ssoProfileClient = new AmazonSecurityTokenServiceClient(ssoCreds); Console.WriteLine($"\nSSO Profile:\n {await ssoProfileClient.GetCallerIdentityArn()}"); // Display a list of the account's IAM users. // The IAM client is created using the SSO credentials obtained earlier. var iamClient = new AmazonIdentityManagementServiceClient(ssoCreds); Console.WriteLine("\nGetting a list of IAM users..."); var listResponse = await iamClient.ListUsersAsync(); Console.WriteLine($"Number of IAM users: {listResponse.Users.Count}"); foreach (User u in listResponse.Users) { Console.WriteLine(u.UserName); } Console.WriteLine(); } // Method to get SSO credentials from the information in the shared config file. static AWSCredentials LoadSsoCredentials(string profile) { var chain = new CredentialProfileStoreChain(); if (!chain.TryGetAWSCredentials(profile, out var credentials)) throw new Exception($"Failed to find the {profile} profile"); return credentials; } } // Class to read the caller's identity. public static class Extensions { public static async Task<string> GetCallerIdentityArn(this IAmazonSecurityTokenService stsClient) { var response = await stsClient.GetCallerIdentityAsync(new GetCallerIdentityRequest()); return response.Arn; } } }
In addition to displaying lists of Amazon S3 buckets and IAM users, these applications display the user
identity ARN for the SSO-enabled profile, which is my-sso-profile
in this tutorial.
Instruct SSO user
Ask the SSO user to check their email and accept the SSO invitation. They are prompted to set a password. The message might take a few minutes to arrive in the SSO user's inbox.
Give the SSO user the applications that you created earlier.
Then, have the SSO user do the following:
-
If the folder that contains the shared AWS
config
file doesn't exist, create it. If the folder does exist and has a subfolder called.sso
, delete that subfolder.The location of this folder is typically
%USERPROFILE%\.aws
in Windows and~/.aws
in Linux and macOS. -
Create a shared AWS
config
file in that folder, if necessary, and add a profile to it as follows:[default] region =
<default Region>
[profile my-sso-profile] sso_start_url =<user portal URL recorded earlier>
sso_region =<Region code recorded earlier>
sso_account_id =<account ID recorded earlier>
sso_role_name = SSOReadOnlyRole -
Run the Amazon S3 application. A runtime exception appears.
-
Run the following AWS CLI command:
aws sso login --profile my-sso-profile
-
In the resulting web sign-in page, sign in. Use the user name from the invitation message and the password that was created in response to the message.
-
Run the Amazon S3 application again. The application now displays the list of S3 buckets.
-
Run the IAM application. The application displays the list of IAM users. This is true even though a second sign-in wasn't performed. The IAM application uses the temporary token that was created earlier.
Cleanup
If you don't want to keep the resources that you created during this tutorial, clean them up. These might be AWS resources or resources in your development environment such as files and folders.