Tutorial for SSO using the Amazon CLI and .NET applications - Amazon SDK for .NET
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

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.

Before you start this tutorial, see the background information for using IAM Identity Center with the Amazon SDK for .NET. Also see 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 Setting up your project.

  • 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 and add some innocuous buckets. Later in this tutorial, the SSO user will retrieve a list of these buckets.

Amazon IAM

Go to the IAM console and add a few IAM users. If you give the IAM users permissions, limit the permissions to a few innocuous read-only permissions. Later in this tutorial, the SSO user will retrieve a list of these IAM users.

Amazon Organizations

Go to the Amazon Organizations console and enable Organizations. For more information, see Creating an organization in the Amazon Organizations User Guide.

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 and enable SSO. Perform email verification if necessary. For more information, see Enable IAM Identity Center in the IAM Identity Center User Guide.

Then, perform the following configuration.

  1. Go to the Settings page. Look for the "User portal URL" and record the value for later use in the sso_start_url setting.

  2. 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 to us-east-1.

  3. Create an SSO user as follows:

    1. Go to the Users page.

    2. Choose Add user and enter the user's Username, Email address, First name, and Last name. Then, choose Next.

    3. Choose Next on the page for groups, then review the information and choose Add user.

  4. Create a group as follows:

    1. Go to the Groups page.

    2. Choose Create group and enter the group's Group name and Description.

    3. In the Add users to group section, select the test SSO user that you created earlier. Then, select Create group.

  5. Create a permission set as follows:

    1. Go to the Permission sets page and choose Create permission set.

    2. Select Create a custom permission set and choose Next: Details.

    3. For this tutorial, enter SSOReadOnlyRole for the Name and enter a Description.

    4. Select Create a custom permissions policy and enter the following policy:

      { "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "s3:ListAllMyBuckets", "iam:ListUsers" ], "Resource": "*" } ] }
    5. Choose Next: Tags, Next: Review, and Create.

    6. Record the name of the permission set for later use in the sso_role_name setting.

  6. Go to the Amazon accounts page and choose the Amazon account that you added to the organization earlier.

  7. In the Overview section of that page, find the Account ID and record it for later use in the sso_account_id setting.

  8. Choose the Users and groups tab and then choose Assign users or groups.

  9. On the Assign users and groups page, choose the Groups tab, select the group that you created earlier, and choose Next.

  10. 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:

  1. 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.

  2. 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
  3. Run the Amazon S3 application. A runtime exception appears.

  4. Run the following Amazon CLI command:

    aws sso login --profile my-sso-profile
  5. 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.

  6. Run the Amazon S3 application again. The application now displays the list of S3 buckets.

  7. 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.