AWS solutions documentation change
Summary
Reorganized client setup sections, clarified capabilities of web portal, CLI, and desktop application. Added detailed steps for obtaining portal URL, installing CLI with integrity checks, and updated troubleshooting. Emphasized that file operations require CLI or desktop app and that desktop app depends on CLI.
Security assessment
Added SHA256 checksum verification for CLI installation files to prevent execution of tampered software. This enhances security by ensuring file integrity but doesn't address a specific vulnerability.
Diff
diff --git a/solutions/latest/spatial-data-management-on-aws/client-setup.md b/solutions/latest/spatial-data-management-on-aws/client-setup.md index ab402ac2b..ace3df69d 100644 --- a//solutions/latest/spatial-data-management-on-aws/client-setup.md +++ b//solutions/latest/spatial-data-management-on-aws/client-setup.md @@ -3 +3 @@ -PrerequisitesWeb portal setupDesktop Client setupCLI setupSystem requirements and browser compatibilityTroubleshootingGetting help +PrerequisitesWeb portal setupCLI setupDesktop application setupSystem requirements and browser compatibilityTroubleshootingGetting help @@ -7 +7 @@ PrerequisitesWeb portal setupDesktop Client setupCLI setupSystem requirements an -This section describes how to set up and configure the three client applications for accessing Spatial Data Management on AWS: +This section describes how to set up and configure the client applications for accessing Spatial Data Management on AWS: @@ -9 +9 @@ This section describes how to set up and configure the three client applications - * **Web portal** – Browser-based interface for resource management (libraries, projects, assets metadata) + * **Web portal** – Browser-based interface for resource management (libraries, projects). No file upload or download capabilities. @@ -11 +11 @@ This section describes how to set up and configure the three client applications - * **Command-Line Interface (CLI)** – Python-based CLI tool for automation and scripting + * **Command-Line Interface (CLI)** – Python-based CLI tool for automation, scripting, and file operations (upload/download) @@ -13 +13 @@ This section describes how to set up and configure the three client applications - * **Desktop application** – Native application for Windows, macOS, and Linux with full asset upload and download capabilities (requires CLI to be installed first) + * **Desktop application** – Native application for Windows, macOS, and Linux with graphical interface for file upload and download @@ -17,0 +18,4 @@ This section describes how to set up and configure the three client applications +###### Important + +To upload or download files, you must use either the CLI or desktop application. The web portal does not support file operations. The desktop application requires the CLI to be installed first. + @@ -22 +26 @@ Before setting up any client application, ensure you have: - * Deployed the Spatial Data Management on AWS solution in your AWS account + * The Spatial Data Management on AWS solution deployed in an AWS account @@ -24 +28 @@ Before setting up any client application, ensure you have: - * Amazon Cognito user credentials (username and password) from your IT Administrator + * Your IT Administrator may have already deployed this for you @@ -26 +30 @@ Before setting up any client application, ensure you have: - * API endpoint URL from your deployment + * User credentials for authentication: @@ -28 +32 @@ Before setting up any client application, ensure you have: - * Network access to your deployment (VPN if required) + * Amazon Cognito username and password from your registration email or IT Administrator, or @@ -29,0 +34 @@ Before setting up any client application, ensure you have: + * Single Sign-On credentials if SSO is configured @@ -30,0 +36 @@ Before setting up any client application, ensure you have: + * Network access to your deployment @@ -31,0 +38 @@ Before setting up any client application, ensure you have: + * Contact your IT Administrator if you need custom domain access or VPN connection @@ -33 +39,0 @@ Before setting up any client application, ensure you have: -### Client application capabilities @@ -35 +40,0 @@ Before setting up any client application, ensure you have: -**Web portal:** @@ -37 +41,0 @@ Before setting up any client application, ensure you have: - * Use for resource management (creating libraries, projects, managing metadata, searching assets) @@ -39 +43 @@ Before setting up any client application, ensure you have: - * No file upload or download capabilities +## Web portal setup @@ -40,0 +45 @@ Before setting up any client application, ensure you have: +The web portal requires no installation and can be accessed directly through a web browser. @@ -41,0 +47 @@ Before setting up any client application, ensure you have: +### Access the web portal @@ -42,0 +49 @@ Before setting up any client application, ensure you have: + 1. Obtain the portal URL from your IT Administrator or the person who deployed the solution. @@ -44 +51 @@ Before setting up any client application, ensure you have: -**CLI or desktop application:** + 2. Open the URL in a supported web browser (Google Chrome, Mozilla Firefox, Microsoft Edge, or Safari). @@ -46 +53 @@ Before setting up any client application, ensure you have: - * Required for uploading and downloading asset files + 3. Sign in with your Amazon Cognito credentials provided by your IT Administrator. @@ -48 +54,0 @@ Before setting up any client application, ensure you have: - * Full resource management capabilities @@ -50 +55,0 @@ Before setting up any client application, ensure you have: - * The desktop application requires the CLI to be installed first @@ -52,0 +58 @@ Before setting up any client application, ensure you have: +**If you do not have the portal URL:** @@ -53,0 +60 @@ Before setting up any client application, ensure you have: +You can retrieve it from the AWS CloudFormation console: @@ -55 +62 @@ Before setting up any client application, ensure you have: -## Web portal setup + 1. Sign in to the AWS Management Console and open the CloudFormation console @@ -57 +64 @@ Before setting up any client application, ensure you have: -The web portal requires no installation and can be accessed directly through a web browser. + 2. Locate the main stack for your Spatial Data Management deployment @@ -59 +66 @@ The web portal requires no installation and can be accessed directly through a w -### Access the web portal + 3. In the **Resources** tab, find the nested stack with a logical ID starting with `PortalStack` @@ -61 +68,8 @@ The web portal requires no installation and can be accessed directly through a w - 1. Request the portal URL from your IT Administrator or the person who deployed the {solution-name} solution in your organization. + 4. Choose the nested stack link + + 5. In the **Outputs** tab, copy the value for `PortalCloudFrontDistributionUrl` + + + + +Alternatively, if you have AWS CLI access: @@ -63 +76,0 @@ The web portal requires no installation and can be accessed directly through a w - 2. (Optional) If you have AWS CLI access, you can retrieve the portal URL from AWS CloudFormation outputs: @@ -66,4 +79,82 @@ The web portal requires no installation and can be accessed directly through a w - aws cloudformation describe-stacks \ - --stack-name <stack-name> \ - --query 'Stacks[0].Outputs[?OutputKey==`PortalUrl`].OutputValue' \ - --output text + aws cloudformation describe-stacks --stack-name $(aws cloudformation list-stack-resources --stack-name <stack-name> --query 'StackResourceSummaries[?starts_with(LogicalResourceId, `PortalStackNested`)].PhysicalResourceId' --output text) --query 'Stacks[0].Outputs[?OutputKey==`PortalCloudFrontDistributionUrl`].OutputValue' --output text + +## CLI setup + +The CLI is a Python-based command-line tool that provides full access to Spatial Data Management features, including file upload and download capabilities. + +###### Important + +If you plan to use the desktop application, you must install the CLI first. The desktop application depends on the CLI for file operations. + +### Prerequisites + + * Python 3.8 or later + + * pip (Python package installer) + + + + +### Verify Python installation + + + # Check Python version + python --version + # or + python3 --version + + # Check pip version + pip --version + # or + pip3 --version + +If Python is not installed, download from [python.org](https://www.python.org/downloads/). + +### Install CLI from wheel file + +#### Step 1: Obtain CLI wheel file + +Download the CLI wheel file (`.whl`) from your IT Administrator or from the Amazon S3 location: + +###### Note + +Always download the latest available version for the most recent features and bug fixes. + +**Version 0.1.1 (Latest):** + + * Download [CLI wheel 0.1.1](https://solutions-reference.s3.amazonaws.com/spatial-data-management/latest/artifacts/cli/amzn_spatial_data_mgmt-0.1.1-py3-none-any.whl) + + * Download [Checksum 0.1.1](https://solutions-reference.s3.amazonaws.com/spatial-data-management/latest/artifacts/cli/amzn_spatial_data_mgmt-0.1.1-py3-none-any.whl.sha256) + + + + +**Version 0.1.0:** + + * Download [CLI wheel 0.1.0](https://solutions-reference.s3.amazonaws.com/spatial-data-management/latest/artifacts/cli/amzn_spatial_data_mgmt-0.1.0-py3-none-any.whl) + + * Download [Checksum 0.1.0](https://solutions-reference.s3.amazonaws.com/spatial-data-management/latest/artifacts/cli/amzn_spatial_data_mgmt-0.1.0-py3-none-any.whl.sha256) + + + + +#### Step 2: Verify file integrity (recommended) + +Verify the downloaded file using the SHA256 checksum: + +**Windows (PowerShell):** + + + # Calculate SHA256 hash (replace <filename> with your downloaded file) + $hash = Get-FileHash -Algorithm SHA256 <filename>.whl + + # Compare with expected hash + $expectedHash = Get-Content <filename>.whl.sha256 + + if ($hash.Hash -eq $expectedHash.Split()[0]) { + Write-Host "Checksum verified successfully" -ForegroundColor Green + } else { + Write-Host "Checksum verification failed" -ForegroundColor Red + } + +**macOS and Linux:** @@ -71 +161,0 @@ The web portal requires no installation and can be accessed directly through a w - 3. Open the URL in a supported web browser: @@ -73 +163,4 @@ The web portal requires no installation and can be accessed directly through a w - * Google Chrome + # Verify checksum (replace <filename> with your downloaded file) + sha256sum -c <filename>.whl.sha256 + + # Expected output: <filename>.whl: OK @@ -75 +168 @@ The web portal requires no installation and can be accessed directly through a w - * Mozilla Firefox +**Important:** Do not proceed with installation if the checksum verification fails. Contact your IT Administrator for a valid file. @@ -77 +170 @@ The web portal requires no installation and can be accessed directly through a w - * Microsoft Edge +#### Step 3: Install CLI wheel file @@ -79 +172 @@ The web portal requires no installation and can be accessed directly through a w - * Safari +**Windows:** @@ -81 +173,0 @@ The web portal requires no installation and can be accessed directly through a w - 4. Sign in with your Amazon Cognito credentials provided by your IT Administrator. @@ -82,0 +175,2 @@ The web portal requires no installation and can be accessed directly through a w + # Install CLI (replace <filename> with your downloaded file)