Skip to content

Latest commit

 

History

History
288 lines (211 loc) · 11.5 KB

README.md

File metadata and controls

288 lines (211 loc) · 11.5 KB

Auth Setup - Compatible with Connected Mobility Solution on AWS modules

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

Solution Overview

The Auth Setup module supports the following features within CMS:

  • Create IdP configuration for CMS Auth module's Token Validation and Authorization Code Exchange lambda functions
  • Create IdP configuration for Users to login to the Backstage module
  • Create IdP configuration for CMS modules to perform service-to-service auth via the Client Credentials flow
  • Provide an optional deployment of Cognito infrastructure compatible with Backstage, and populate the IdP configurations appropriately

These features are accomplished primarily via three AWS Secrets Manager secrets, which provide configuration structure for any OAuth 2.0 identity provider. The secrets are as follows:

  • IdP Config
    • IdP configurations needed to facilitate authentication and authorization via OAuth 2.0 identity providers.
  • Service Client Config
    • Service client configuration needed for OAuth 2.0 operations.
  • User Client Config
    • User client configuration needed for OAuth 2.0 operations.

This module also provides an optional deployment of Cognito infrastructure which is configured for basic usage within CMS. If deploying the Cognito infrastructure, the configuration secrets will be populated with the appropriate values. Otherwise, it is necessary for the user to either manually provide the configuration values for your identity provider of choice after the initial deployment, or specify existing secret arns to use as the configuration secrets. For more details, see the Usage section.

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

Architecture Diagram

Architecture Diagram

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

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://raw.githubusercontent.com/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/auth_setup/

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

Deployment Options

The Auth Setup module has three primary deployment paths depending on your existing identity provider setup. These paths are detailed below.

1. Cognito Deploy

If using the optional Cognito infrastructure deployment which is provided by this module, deploy the module with the CloudFormation parameter ShouldCreateCognitoResources set to "True". This will deploy a basic Cognito infrastructure including a user pool, service app client, and user app client, to your account. It will also populate the three configuration secrets and one SSM Parameter with values specific to the Cognito deployment.

2. Empty Config Deploy

If using your own identity provider, and you do not have existing configuration secrets from a previous deployment, the Auth Setup module will deploy the three configuration secrets in the expected JSON format as well as one SSM Parameter with empty values. These values can be populated after the deployment with values specific to your identity provider. To execute this deployment, deploy the module with the CloudFormation parameter ShouldCreateCognitoResources set to "False", and do not provide values for the existing secret arn parameters.

3. Existing Config Deploy

If using your own identity provider, and you have existing configuration secrets from a previous deployment with appropriate values that you would like to reuse, the Auth Setup module will connect the existing secrets to SSM parameters expected by other CMS module's. This can be done for any or all of the three configuration secrets. To execute this deployment, deploy the module with the CloudFormation parameter ShouldCreateCognitoResources set to "False", and provide an existing secret arn for any of the three existing secret arn CloudFormation parameters.

Integration with ACDP / Backstage

Callback URIs

If you would like to use the Auth Setup module for authenticating logins to the Backstage portal deployed by ACDP, it is necessary to include the appropriate Backstage Callback URI in your identity provider's user client. This Callback Uri is defined as 'https://your-backstage-domain/api/auth/provider-id/handler/frame'. See the backstage docs for more info: https://backstage.io/docs/auth/oidc#the-configuration.

This value is added by default to the Cognito user app client when deploying Cognito infrastructure, and when deploying via the Makefile make deploy target, by using the FULLY_QUALIFIED_DOMAIN_NAME environment variable (this is the same variable used to set the Backstage domain during an ACDP / Backstage deploy). Otherwise, you must configure the Callback URIs for your identity provider client manually to facilitate the Backstage login redirect.

Scopes

To allow login to Backstage, the IdP must be configured to allow the following three scopes: openid, email, profile. Without these scopes, Backstage will fail to authenticate users on login. This can be adjusted from the Backstage source code if desired.

Secret Structure

IdP Config

  • issuer
    • Issuer URL for the IdP that will be included in the iss claim of access tokens
  • token_endpoint
    • /oauth2/token endpoint for the IdP
  • authorization_endpoint
    • /oauth2/authorize endpoint for the IdP
  • alternate_aud_key
    • Claim key to use for validating access tokens instead of aud, if aud is not including in the access tokens provided by your IdP
  • auds
    • Array of allowed audience values for the aud claim of access tokens
  • scopes
    • Array of scopes used to validate the scopes claim of access tokens

User Client Config

  • client_id
    • Client ID of User client
  • client_secret
    • Client Secret of User client

Service Client Config

  • client_id
    • Client ID of Service client
  • client_secret
    • Client Secret of Service client

SSM Parameter

  • Cognito user pool Id

Cost Scaling

Cost will scale depending on usage of optional Cognito deployments. Without the Cognito deployment, cost is minimal.

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.