Tutorial for SSO using the Amazon 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 Amazon CLI to generate a temporary SSO token instead of generating it programmatically.
This tutorial shows you a small portion of SSO functionality in the Amazon SDK for .NET. For full details about using IAM Identity Center with the Amazon 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 Amazon CLI and .NET application.
Note
Several of the steps in this tutorial help you configure services like Amazon 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 Amazon Web Services account that you can use to test SSO. For the purposes of this tutorial, this is called the test Amazon Web Services 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 Amazon 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 Amazon
This section shows you how to set up various Amazon services for this tutorial.
To perform this setup, first sign in to the test Amazon Web Services account as an administrator. Then, do the following:
Amazon S3
Go to the Amazon S3 console
Amazon IAM
Go to the IAM console
Amazon Organizations
Go to the Amazon Organizations console
This action adds the test Amazon Web Services 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 Amazon Web Services Management Console, look for the Amazon Web Services Region that was set when you enabled SSO. This is the dropdown menu to the left of the Amazon Web Services 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 Amazon accounts page and choose the Amazon 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 Amazon
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 Amazon
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 Amazon 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 Amazon resources or resources in your development environment such as files and folders.