The Risky Pipeline

Managing Configurations for Prometheus and Grafana Helm Charts

Fri, 21 Jul 2023 12:00:00 +0000

Diagram

Managing Prometheus and Grafana via Helm (draw.io viewer)

The Prometheus Operator manages the CRDs. The Values.yaml and CRDs impacts each object’s configuration

This blog post is in specific reference to the Kube Prometheus Stack as part of the Prometheus Community, prometheus-community/kube-prometheus-stack

When using the Helm Charts managed by the Prometheus Monitoring Community repo, certain considerations should be made when managing the Prometheus configuration options such as Alerting Rules and Scrape Configs. This post will attempt to break-down best practices using the Kubernetes Custom Resource Definitions (CRDs) created by the helm chart deployment.

Service Discovery Versus Static Configs

When using the Prometheus Monitoring Community’s Kube Prometheus Stack, Service Discovery for Kubernetes is configured. Discovery is dynamic upon the creation and destruction of objects within the cluster. Objects in Kubernetes are therefore ready for monitoring in Prometheus during their lifecycle which is accomplished using the Kubernetes API server. Service Discovery configs are used in lieu of Static Configs for dynamic metrics gathering. Refer to the Kubernetes Service Discovery configuration for more details.

When creating Scrape Configs, along with other Prometheus configuration options, using CRDs is the best approach when applying the Kube Prometheus Stack helm chart. The chart includes the Prometheus Controller Manager and its CRDs.

Using the Service Monitor CRD automatically configures the relabel_config based on spec.selector within the manifest. The relabel config enables service discovery of targets for the specified job being created.

Example:

apiVersion: v1
items:
- apiVersion: monitoring.coreos.com/v1
  kind: ServiceMonitor
  metadata:
    labels:
      app: ibkr-dash
      release: prometheus
    name: ibkr-dash
  spec:
    endpoints:
    - interval: 30s
      port: metrics
    namespaceSelector:
      matchNames:
      - default
    selector:
      matchLabels:
        app.kubernetes.io/managed-by: Helm

Will resolve to the following Configuration:

- job_name: serviceMonitor/default/ibkr-dash/0
  honor_timestamps: true
  track_timestamps_staleness: false
  scrape_interval: 30s
  scrape_timeout: 10s
  scrape_protocols:
  - OpenMetricsText1.0.0
  - OpenMetricsText0.0.1
  - PrometheusText0.0.4
  metrics_path: /metrics
  scheme: http
  enable_compression: true
  follow_redirects: true
  enable_http2: true
  http_headers: null
  relabel_configs:
  - source_labels: [job]
    separator: ;
    regex: (.*)
    target_label: __tmp_prometheus_job_name
    replacement: $1
    action: replace
  - source_labels: [__meta_kubernetes_service_label_app_kubernetes_io_managed_by,
      __meta_kubernetes_service_labelpresent_app_kubernetes_io_managed_by]
    separator: ;
    regex: (Helm);true
    replacement: $1
    action: keep
...
kubernetes_sd_configs:
  - role: endpoints
    kubeconfig_file: ""
    follow_redirects: true
    enable_http2: true
    http_headers: null
    namespaces:
      own_namespace: false
      names:
      - default

The above YAML has been condensed as indicated by the ellipses (...)

Notice that the resolved scrape config includes the kubernetes_sd_configs for automated service discovery of endpoints created for IBKR-Dash app within the default namespace. You may review the resolved configuration with the Prometheus UI by selecting Status -> Configuration. The application will also be populated within the Status -> Service Discovery view.

More details about Service Monitor CRDs and why CRDs in general should be used when configuring Prometheus will be discussed further in this bog post.

Why CRDs?

Making changes the the CRDs objects or creating new CRDs as defined by the helm chart enables a more clean and consistent approach to managing the configuration options for Prometheus and Grafana. Changes or additions to the CRD will perform an automated config reload against the Prometheus or Grafana objects in Kubernetes. In addition, future updates the the helm charts will prevent your custom values from being overwritten.

This is in contrast to making changes by first pulling in the Values.yaml, editing then updating the helm charts using the -f flag. Using this method requires a manual reload by calling the service endpoints for the Prometheus deployment using CURL. These CRDs are defined and managed by the Prometheus Operator built into the aforementioned helm chart.

You may determine the reload endpoint by executing the following command against your Kubernetes cluster:

kubectl get sts <helm release>-prometheus-kube-prometheus-prometheus -n <namespace> -o yaml | grep reload-url

Available Prometheus CRDs

To check for available CRD object which may be editing or created, execute the following command:

kubectl get crds -n <namespace>

Each of the listed CRDs may then be called against the Kubernetes API like any other Kubernetes Object, such as a Deployments or StatefulSets. For example, for the alertmanagers.monitoring.coreos.com CRD, you may list its existing objects by executing

kubectl get alertmanagerconfigs -n <namespace>

New resources created as defined by each of the CRDs must contain the configured key/value CRD label selector when populating the metadata.labels object. This enables Prometheus Service Discovery to discover the endpoints as referenced by these new resources. For example, when creating a new ServiceMonitor object for scraping a custom metrics endpoint, the endpoints referenced by the new object are not discoverable by prometheus unless the metadata.labels also matches the underlying CRD config.

I will now delve into the key CRDs to create/update when managing the Helm Chart Configs for Prometheus and Grafana.

Alerting Rules

The alerting rules are managed by the prometheusrules.monitoring.coreos.com CRD which define alert conditions for Prometheus. Learn more at the official Prometheus Documentation - Alerting Rules

Create a yaml manifest as follows to add a new alert rule:

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  labels:
    release: prometheus
  name: prometheus-example-rules
spec:
  groups:
  - name: ./example.rules
    rules:
    - alert: down
      expr: up==0
      for: 0m
      labels:
        severity: critical
      annotations:
        summary: prometheus

The metadata.labels section must contain the key/value for what is configured for the underlying CRD. Check the existing CRD by running kubectl get prometheuses <helm release>-kube-prometheus-prometheus -n <namespace> -o yaml | grep -i matchlabels -A5

The output will show the matchLabels: selector.

Scrape Configs

Managed by the servicemonitor.monitoring.coreos.com CRD which specifies a set of targets and parameters describing how to scrape them. One scrape config specified a single job in prometheus. Learn more at the official Prometheus Documentation - Configuration/Scrape Config.

Note: When creating a scrape config, ensure a Kubernetes Service object exists exposing the service against the Pod/ReplicaSet/StatefulSet/daemonSet/Deployment.

Create a yaml manifest as follows to add a new scrape config:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: servicemonitor-app
  labels:
    app: servicemonitor-app
    release: prometheus
spec:
  endpoints:
  - port: http-metrics
    path: /url/paths
    interval: 30s
  namespaceSelector:
    matchNames:
      - service-monitor-namespace
  selector:
    matchLabels:
      instance: service

Note the spec.namespaceSelector and spec.selector work together to ensure the ServiceMonitor selects the Kubernetes objects containing the custom metrics URL path such as Deployments, Pods, or StatefulSets.

The spec.endpoints section must reference a port’s name inside of a Service which exposes its underlying objects such as NodePort or ClusterIP.

The metadata.labels section must contain the key/value for what is configured for the underlying CRD. Check the existing CRD by running kubectl get servicemonitors <helm release>-kube-prometheus-prometheus -n monitoring -o yaml | grep -i matchLabels -A

The output will show the matchLabels: selector.

Exporters

Scrape Configs are also required when adding or writing a Prometheus Exporter such as for Redis.These exporters act as a translation layer between the application and Prometheus, exposing an additional /metrics endpoint, sometimes using a sidecar container. These exporters also exist as Docker Images in Docker Hub.

It is recommended to add an Exporter, if not already built into the Helm chart maintained for the application in question, by first searching for an existing Exporter within Artifact Hub.

Redis Helm Chart for example contains a sidecar container for exposing Redis application metrics.

When installing an add-on Exporter via Helm, its Values.yaml should be updated to match the key/value label as specified in the metadata.labels above, in addition to the correct Service Name and Port as determined by the Service created to expose the application.

You may use the helm show values <repo/helm-chart> > values.yaml and helm install (or upgrade) <release> -f values.yaml method to accomplish this. See the chart’s documentation for more details.

The serviceMonitor section is what instructs the helm chart to spin-up a new ServiceMonitor CRD with the correct metadata.labels directive in lieu of the manual steps defined above. If a comparable serviceMonitor directive does not exist, manual steps must be taken to create each of the ServiceMonitor as defined above. In addition, if a Service is not created which exposes the Exporter pod, create one manually.

Example Exporter Match Label Config Snippet:

mongodb:
  uri: "mongodb://mongodb-service:27017" # points to the existing Service for MongoDB

serviceMonitor:
  additionalLabels:
    release: prometheus # must match what is configured for the ServiceMonitor CRD. 

Check the Service created by the Exporter’s helm chart via port forwarding or creating an additional NodePort, then attempt to browse to the exposed scrape URL path, usually /metrics. You should also see the new ServiceMonitor listed as a Target in the Prometheus UI with its detected endpoints.

Alert Manager Rules

Managed by the alertmanager.monitoring.coreos.com CRD which handles alerts sent by the client application. It takes care of grouping and routing alerts to the correct receiver. Learn more at the official Prometheus Documentation - AlertManger.

Create a yaml as follows to add a new alert manager rule:

apiVersion: monitoring.coreos.com/v1
kind: AlertManager
metadata:
  name: servicemonitor-app
  labels:
    app: servicemonitor-app
    release: prometheus
spec:
  route:
    groupBy: ["alertname"]
    groupWait: 30s
    groupInterval: 5m
    repeatInterval: 12h
    receiver: "webhook"
    routes:
    - matchers:
      - name: job
        value: kubernetes
      receiver: "infra"
      groupBy: ["severity"]

The metadata.labels section must contain the key/value for what is configured for the underlying CRD. Check the existing CRD by running kubectl get alertmanagers <helm release>-kube-prometheus-alertmanager -n <namespace> -o yaml | grep -i selector

If the alertmanagerConfigSelector value is empty, it must first be specified by the following steps:

Execute helm show values prometheus-community/kube-prometheus-stack > values.yaml
Edit the values.yaml by searching alertmanagerConfigSelector. Remove the value {} and replace with:
```
 alertmanagerConfigSelector:
  matchLabels:
    resource: prometheus
```
Execute helm upgrade <helm release> prometheus-community/kube-prometheus-stack -f values.yaml

Using Helm Values

You may also edit the aforementioned config values by editing the values.yaml. This is not recommended as further updates to the helm-chart may override these values.

Execute helm show values prometheus-community/kube-prometheus-stack > values.yaml
Edit the values.yaml for the following configuration options (examples to uncomment are provided):
- Scrape Config - additionalScrapeConfigs (example)
- Alerting Rules - additionalPrometheusRulesMap (example)
- Alert Manager Config - alertManagerConfiguration (example)
Execute helm upgrade <helm release> prometheus-community/kube-prometheus-stack -f values.yaml

AWS CDK - Breaking Down AWS Cognito OAuth & OIDC Workflows

Sun, 05 Mar 2023 12:00:00 +0000

Diagram

Amazon Cognito OAuth & OIDC Workflow (draw.io viewer)

In my previous blog post, “AWS CDK - Using Amazon Cognito Authentication and Authorization”, I go-over implementing Cognito Authentication & Authorization workflow into your application via the AWS CDK. I attempt here, to dive deeper into the workflow components as they relate to AWS Cognito in alignment with OAuth standards. For more context, reading the previous post or series of posts within the subject matter will shed more light into this deep-dive.

AWS Cognito with CDK Post Series

Breaking It Down

Components (from left to right)

Web Application - from the previous example was a React App hosted within an S3 bucket
Resource Server - Each Resource Server may contain a list of defined Custom Scopes. Authorization with an Access Code must be returned to the Token Endpoint when using Authorization Code Grant to receive the Custom Scopes. Custom Scopes get injected into the Access Token based on the associated App Client. Multiple Resource Servers may defined.
Authorization Server - Cognito User Pool, where users, User Groups, User Groups default roles, App Clients, and Resource Servers are defined. Federated Identity may also be configured here.
- App Client - Custom Scopes are attached from the Resource Server to each App Client. Multiple App Clients may be defined each with their own set of Resource Server created Custom Scopes.
- Federated Identity Providers (IdP) may be OAuth, OIDC, SAML, and other popular social and cloud integrations such as ‘Sign-in with Amazon’, ‘Sign-in with Google’ and Facebook.
AWS Credentials - Cognito Identity Pool which gets associated with an App Client. The Identity Pool associated with the App Client gets used. Role mappings are defined based on either the Rules or Token method. Refer to the previous post for more details. Default IAM Roles are configured for Authenticated and Unauthenticated (Guest) access, providing a baseline set of roles the Web App may use. Role mapping may either be used with or overwrite the default IAM role base on the Role Mapping Rule utilized.
API Gateway - A Cognito Authorizer may be defined for the API, which then gets utilized be each API method. The API methods may specify Custom Scopes to ensure more fined-grained permissions. The API method can check for these custom scopes before access to the API is granted. Custom Scopes are defined in the Resource Server and attached to the App Client within an Identity Pool before they get injected into the the Access Token for authorization. The Base64 encoded JWT token must be specified.

The Flow

Authenticate - Based on how the associated Identity Pool is configured, upon successful Authentication to the Hosted UI, the following gets generated:
1. Access Token (JWT format), ID Token (JWT format according to Open ID Connect), and AWS Credentials.
OAuth flow - Based on how the Authentication flow is configured within the App Client, upon successful authentication in step 1, the following flow occurs:
1. Implicit Grant - Requests and Returns an Access Token to the Web App via the browser (or user agent which is not depicted in the diagram)
2. Authorization Grant - Requests an Authorization Code to the App Clients token endpoint and returns an Access Code. Use the Access Code to request an Access Token. Custom Scopes are injected into the Access Token via the Resource Server. This exchange occurs outside of the browser on the server side whereby the server side performs the subsequent requests to the Resource Server.
  1. This flow will not work with single page applications such as those written in React where no server side channel exist.
The multiple grants returned to the client as follows:
1. Access Token in JWT format - Used for accessing API resources defined within the API Gateway.
2. ID Token in JWT format - Open ID Connect JWT containing the Cognito Roles and Groups, which enable IAM assumed roles to the listed role ARNs, and standard claims such as ‘sub’ and ‘name’. The details provided enable personalized user experience within the web application. More details about ID TOkens from a prior blog post
3. AWS Credentials - Contains an AWS Access Key, Secret Access Key, and Session Token, for use by the Web Application for access to various AWS resources. For example, permissions to an S3 bucket for uploading an image which can than be returned as a profile photo. The assumed role as contingent upon the Identity Pool’s default assigned role and/or Role Mappings which then dictate the cognito:preferred_role value within the token. Refer to Assigning precedence values to groups for more details.

Breaking Down OAuth Scopes A Bit Further

I wanted to add some additional context that may have been lacking in previous blog posts regarding scopes. Here is how I break down with references to additional reading:

A great example of custom scopes may be explored via Google’s OAuth 2.0 Playground. Using these third party defined scopes is what enables access permissions to those APIs, such as the aforementioned Google APIs.
Standard scopes will also get injected. Cognito based User Pools inject the aws.cognito.signin.user.admin scope, which enables Cognito Users access read and write their attributes. Other standard scopes include:
- openid - The minimum scope for OpenID Connect queries which authorizes the ID token the unique-identifier sub, and the ability to request other scopes
- profile - Authorizes all user attributes that the app client can read
- email - Authorizes the user attributes email and email_verified with email_verified sent back from Cognito if the value is explicitly set.
- phone - Authorizes the user attributes phone_number and phone_number_verified.
- Refer to the Developer Guide for Amazon Cognito Scopes for more details.

Example OAuth Access Token

{
   "sub":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "device_key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "cognito:groups":[
      "testgroup"
   ],
   "iss":"https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example",
   "version":2,
   "client_id":"xxxxxxxxxxxxexample",
   "origin_jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "event_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "token_use":"access",
   "scope":"phone openid profile resourceserver.1/appclient2 email",
   "auth_time":1676313851,
   "exp":1676317451,
   "iat":1676313851,
   "jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "username":"my-test-user"
}

Breaking Down OpenID Connect A Bit Further

I also wanted to add a bit more clarification regarding OpenID Connect (OIDC) ID Tokens. OpenID Connect will use the same Authorization Server as OAuth, however, for OpenID Connect, the Authorization Server will return information regarding the authenticating user. In case if you have not figured out the difference between OpenID Connect and OAuth, OpenID Connect is an Authentication protocol as opposed to OAuth being an Authorization protocol. OpenID Connect is more interested in solving Authentication and the mechanism by which we acquire details specific to the end-user, such as profile related email, name, phone number, etc.

OpenID Connect makes use of UserInfo endpoint. When you specify the profile and openid scopes in OAuth, you are granting the bearer permissions to use the profile and other related OpenID connect information against this endpoint.
Typically, the app makes a call from the back channel and not the browser. For single page application written in client side code such as React, this will however occur between the client and Authorization server.
- For Cognito, the UserInfo endpoint is /oauth2/userInfo.
- Amazon Cognito returns the email_verified and phone_number_verified claims within the ID Token.
- Recall, the standard claims that are issued by OpenID Connect are presented within the official spec.
  - Some of these claims are: sub, name, given_name, and family_name.
- Also recall, we were scoped by the OAuth Access token which granted the application access to these claims. Cognito User Pool users only require the aws.cognito.signin.user.admin scope.
- The user attributed are presented by the userInfo endpoint when presented with an OAuth Access Token. The Open ID Connect Token responds with user attributed based on the scopes of the OAuth token.
- The OAuth third-party identity provider (IdP) also hosts a userInfo endpoint. When the user authenticated with that IdP, Cognito will exchange an authorization code with the IdP token endpoint. The user pool then passes the IdP access token to the userInfo endpoint for authorized retrieval of the user attributes from that IdP.
- Read more details about the UserInfo endpoint from the Developer Guide for Cognito.

Example OIDC ID Token

{
    "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "cognito:groups": [
        "test-group-a",
        "test-group-b",
        "test-group-c"
    ],
    "email_verified": true,
    "cognito:preferred_role": "arn:aws:iam::111122223333:role/my-test-role",
    "iss": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example",
    "cognito:username": "my-test-user",
    "middle_name": "Jane",
    "nonce": "abcdefg",
    "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "cognito:roles": [
        "arn:aws:iam::111122223333:role/my-test-role"
    ],
    "aud": "xxxxxxxxxxxxexample",
    "identities": [
        {
            "userId": "amzn1.account.EXAMPLE",
            "providerName": "LoginWithAmazon",
            "providerType": "LoginWithAmazon",
            "issuer": null,
            "primary": "true",
            "dateCreated": "1642699117273"
        }
    ],
    "event_id": "64f513be-32db-42b0-b78e-b02127b4f463",
    "token_use": "id",
    "auth_time": 1676312777,
    "exp": 1676316377,
    "iat": 1676312777,
    "jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "email": "my-test-user@example.com"
}

AWS CDK - Using Amazon Cognito Authentication and Authorization

Wed, 22 Feb 2023 12:00:00 +0000

Diagram

Amazon Cognito Client Workflow (draw.io viewer)

In my previous blog post, “AWS CDK - Testing Amazon Cognito Authentication and Authorization”, I go-over testing the Auth Service stack, ensuring we receive back proper JWT tokens. I will now illustrate how to make use of the Auth Service stack within a hypothetical React application.

Components

Component	File Name	Description
Authentication Service	AuthService.ts	Perform user challenge and authentication and authorization, returning JWT Tokens and AWS Credentials.
Login Component	LoginComponent.tsx	A very simple react component, which will perform the authentication, using the AuthService.ts service file.
Frontend Router	App.tsx	A very simple React frontend web application which will present a router, with ‘/login’ making a call to LoginComponent.tsx.

Overview

The components are stored and bundled into an S3 Bucket and served as static content. Hypothetically, in addition to the Authentication Service, APIs called via API Gateway can be used to trigger Lambda functions, which can make use of the custom scopes as injected by a Cognito Identity Pool client and/or, the ID Token used as an Authorization header to the API, whereby API Gateway can desingate Cognito as an Authorizer to check for access. We may also parse group memberships within the token to determine whether certain API methods are allowed or not.

Breaking It Down

Authentication Service

Full Code -> GitHub Gist

The authentication service code has been discussed at length, from the previous two blog posts, we perform a deep dive into creating a testing the auth service stack. The code here is identical to what we previously covered.

Some additional changes made to the AuthService file are as follows:

private async generateTemporaryCredentials() {
    const cognitoIdentityPool = `cognito-idp.${awsRegion}.amazonaws.com/${AuthStack.SpaceUserPoolId}`;
    const cognitoIdentity = new CognitoIdentityClient({
        credentials: fromCognitoIdentityPool({
            clientConfig: {
                region: awsRegion
            },
            identityPoolId: AuthStack.SpaceIdentityPoolId,
            logins: {
                [cognitoIdentityPool]: this.jwtToken!
            }
        })
    });
    const credentials = await cognitoIdentity.config.credentials();
    return credentials;
}

The function above will use Cognito for access to the temporary AWS Credentials by supplying the JWT Auth Token. When the Web Application wants to perform a task on behalf of the user, such as uploading a photo to an S3 bucket, these credentials may be used.
- The Assumed IAM Role for the Credentials will be the Authenticated default for Cognito. Any additional Cognito groups with designated IAM roles will also provide those permissions as well.
  - This is useful for delineating group permissions according to membership type, such as premium vs non-premium members.

Full Code -> GitHub Gist

Here we break down the code used for performing the login and ensuring the user authenticated. We make extensive use of State Hooks, which provide a clean way to initialize and update states across our web app.

type LoginProps = {
  authService: AuthService;
  setUserNameCb: (userName: string) => void;
};

export default function LoginComponent({ authService, setUserNameCb }: LoginProps) {
  const [userName, setUserName] = useState<string>("");
  const [password, setPassword] = useState<string>("");
  const [errorMessage, setErrorMessage] = useState<string>("");
  const [loginSuccess, setLoginSuccess] = useState<boolean>(false);

A function labeled,LoginComponent is created with one argument of type LoginProps. We defined the ‘type’ above, via the type LoginProps line.
- Hence, this one argument will require a type which contains two components, ‘authService’ of type ‘AuthService’, and ‘setUserNameCb’ which is a callback function that takes a string without a return.
We then initialize four State Hooks, each empty (and boolean as false) accessible via userName, password, errorMessage, and loginSuccess.
- We can now set and use these variables by calling their ‘setIndex’ for setting the state, and referencing each variable where they each apply.

const handleSubmit = async (event: SyntheticEvent) => {
    event.preventDefault();
    if (userName && password) {
      const loginResponse = await authService.login(userName, password);
      const userName2 = authService.getUserName();
      if (userName2) {
        setUserNameCb(userName2);
      }

      if (loginResponse) {
        setLoginSuccess(true);
      } else {
        setErrorMessage("invalid credentials");
      }
    } else {
      setErrorMessage("UserName and password required!");
    }
  };

The handleSubmit will take in one ‘event’ argument, a SyntheticEvent type which will be explained further below. This will grab the end-user action and perform the following:
- If the user provided a username and password within the login form, the loginResponse variable will perform a call to the authService.login method, which was supplied by the ‘LoginProps’ type argument.
- The method is supplied with the username and password, now being handed off to the Authentication Service component, will use Cognito to authenticate the user, then store the JWT tokens and make available the AWS Credentials.
- The ‘username2’ variable will contain the username if the authService.getUserName() succeeds. If set, set as the argument to the setUserNameCb callback supplied to the ‘LoginProps’ type argument.
- If LoginResponse was populated from the Auth Service login function, the State Hook for loginSuccess variable gets called, setLoginSuccess, setting it to ‘true’.

return (
    <div role="main">
      {loginSuccess && <Navigate to="/profile" replace={true} />}
      <h2>Please login</h2>
      <form onSubmit={(e) => handleSubmit(e)}>
        <label>User name</label>
        <input
          value={userName}
          onChange={(e) => setUserName(e.target.value)}
        />
        <br/>
        <label>Password</label>
        <input
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          type="password"
        />
        <br/>
        <input type="submit" value="Login" />
      </form>
      <br/>
      {renderLoginResult()}
    </div>
  );

The Login Component returns the React frontend component for logging in, the form for supplying the username and password, and a Submit button to set the variables for username and password via the Set Hooks, setUsername and setPassword.
- Notice the event being supplied to the ‘handleSubmit’ function ‘event’ parameter as e, which carries over each of their respective value vars supplied by the form to an anonymous function, which is supplied as e.target.value to each of the State Hooks’ ‘setIndexes’, such as setUserName(e.target.value).
- CLicking ‘Submit’ triggers the ‘setIndex’ calls to the handleSubmit function.

Application Router

Full Code -> GitHub Gist

Finally, the Application Router presents the code required for rendering a component based on the URL path.

const authService = new AuthService();
const dataService = new DataService(authService);

function App() {
  const [userName, setUserName] = useState<string | undefined>(undefined);

  const router = createBrowserRouter([
    {
      element: (
        <>
          <NavBar userName={userName}/>
          <Outlet />
        </>
      ),
      children:[
        {
          path: "/",
          element: <div>Hello world!</div>,
        },
        {
          path: "/login",
          element: <LoginComponent authService={authService} setUserNameCb={setUserName}/>,
        },
        {
          path: "/profile",
          element: <div>Profile page</div>,
        },
        {
          path: "/createSpace",
          element: <CreateSpace dataService={dataService}/>,
        },
        {
          path: "/spaces",
          element: <Spaces dataService={dataService}/>,
        },
      ]
    },
  ]);

Here, we have a router which will perform a component depending on where the user is redirected. Their would be a navbar at the entry point, which then routes to each of the provided path values. Based on the ‘path’, the element is dynamically rendered.
For path: "/login", the LoginComponent service is called as follows: LoginComponent authService={authService} setUserNameCb={setUserName}
- Notice the argument adheres to the LoginProps type declared in the LoginComponents above, with the authService being the imported AuthService() function assigned to the variable at the top of the code, along with,
- setUserNameCb, which is a callback function, called back by the LoginComponent when its username form field is set. The callback triggers the ‘setIndex’ for the userName State Hook: const [userName, setUserName] = useState<string | undefined>(undefined).
- Recall the LoginComponent’s function decleration, which declared the paramters as function LoginComponent({ authService, setUserNameCb }: LoginProps).
  - setUserNameCb in LoginComponent is the triggers the setUserName ‘setIndex’ in App.tsx, as it’s called back.
  - LoginProps type declared ‘setUserNameCb’ as an anonymous function, returning void as: setUserNameCb: (userName: string) => void

_{Original code snippets by Alex Dan via Udemy}

AWS CDK - Testing Amazon Cognito Authentication and Authorization

Tue, 21 Feb 2023 12:00:00 +0000

Diagram

Amazon Cognito Client Workflow (draw.io viewer)

In my previous blog post, “AWS CDK - Understanding Amazon Cognito Authentication and Authorization”, I go-over creating an Auth Stack, whereby a web service may provide protected access to APIs and AWS resources, depending on client authentication and access scopes. This article will delve into testing the Auth Stack, using TypeScript calls to the built-in CDK modules and constructs.

Creating an AuthService Test

AuthService.ts exported functions

Amplify.configure({
    Auth:{
        Cognito: {
            userPoolId: 'us-east-1_8j6R6jKCY',
            userPoolClientId: '66h766je9tqbba2fbip9j60hqb',
            identityPoolId: 'us-east-1:3ae853a4-e0a7-4b8f-a6d2-263b1e2da9f2'
        }
    }
})

Using AWS Amplify module, configure Cognito User Pool, User Pool Client, and User Pool ID.

export class AuthService {
    public async login(username: string, password: string){
        const result = (await signIn( {username, password, options: {authFlowType: 'USER_PASSWORD_AUTH'}})) 
          as SignInOutput
        return result
    }
}

Create the login method against the exported AuthService, taking in two argument, Cognito Username and Password. The return result will be the username and password applied to the signIn of the Amplify module, with {authFlowType: 'USER_PASSWORD_AUTH'} set as the sign-in options.

export declare function signIn(input: SignInInput): Promise<SignInOutput>;

export type SignInInput = AuthSignInInput<SignInOptions>;

export type AuthSignInInput<ServiceOptions extends AuthServiceOptions = AuthServiceOptions> = {
    username: string;
    password?: string;
    options?: ServiceOptions;
};

export type SignInOptions = AuthServiceOptions & {
    authFlowType?: AuthFlowType;
    clientMetadata?: ClientMetadata;
};

export type AuthFlowType = 'USER_SRP_AUTH' | 'CUSTOM_WITH_SRP' | 'CUSTOM_WITHOUT_SRP' | 'USER_PASSWORD_AUTH';

The method takes a AuthSignInInput type, with options? value taking a ServiceOption type. The ServiceOption type extends AuthServiceOptions.
AuthServiceOptions Type presents the following valid options for ‘signIn’ when used with the signInOptions type: 'USER_SRP_AUTH' | 'CUSTOM_WITH_SRP' | 'CUSTOM_WITHOUT_SRP' | 'USER_PASSWORD_AUTH'.
For this test, we are using a ‘USER_PASSWORD_AUTH’.

auth.test.ts call to the exported AuthService.ts functions.

async function testAuth() {
    const service = new AuthService();
    await service.login('user-bob', 'bobs-password');

    const {idToken} = (await fetchAuthSession()).tokens ?? {}
    const {accessToken} = (await fetchAuthSession()).tokens ?? {}
    const creds = (await fetchAuthSession()).credentials

    console.log(idToken);
    console.log("--------SEPARATOR--------")
    console.log(accessToken)

    await listBuckets(creds)

}

The previously created AuthService() object is instantiated and assigned to the service variable. The login function assigned to ‘AuthService’ is supplied with the Cognito Username and Password arguments, prepended with await, since ‘login’ returns a Promise via SignInOutPut.
- Recall this from the ‘signIn’ function, export declare function signIn(input: SignInInput): Promise<SignInOutput>. When we created the ‘AuthService’ class, we assigned it to ‘async’, meaning, we are leveraging the use of Async/Await in TypeScript for the Promise returned.
We then parse out the idToken, accessToken, and creds, printing all three to the console. These values are taken from the returned fetchAuthSession Promise, which is also apart of the Amplify module.

Analyzing ‘fetchAuthSession’ a bit further

export declare const fetchAuthSession: (options?: FetchAuthSessionOptions) => Promise<AuthSession>;

export type AuthSession = {
    tokens?: AuthTokens;
    credentials?: AWSCredentials;
    identityId?: string;
    userSub?: string;
};

export type AuthTokens = {
    idToken?: JWT;
    accessToken: JWT;
};

export type AWSCredentials = {
    accessKeyId: string;
    secretAccessKey: string;
    sessionToken?: string;
    expiration?: Date;
};

export type JWT = {
    payload: JwtPayload;
    toString: () => string;
};

interface JwtPayloadStandardFields {
    exp?: number;
    iss?: string;
    aud?: string | string[];
    nbf?: number;
    iat?: number;
    scope?: string;
    jti?: string;
    sub?: string;
}

We can see, AuthSession is a Promise, hence, also called with Async/Await. The returned type supplies us with tokens?, credentials?, etc., each with their own declared type. Hence, we are able to return tokens and credentials from ‘fecthAuthSession’.
Diving a bit deeper, the return types of ‘tokens’ is AuthTokens, which contain both idToken and accessToken, each of which are returned as JWT types, since both types are formatted as JWT (JSON Web Tokens).
‘credentials’ returns AWSCredentials type, which contains accessKeyId, secretAccessKey, sessionToken, and expiration strings.
Also, the JWT type is provided for analysis here as well, which returns the ‘payload’ as JwtPayload, also shown. ‘JwtPayload may be returns as a string using toString()’.
Going yet a bit deeper, ‘JwtPayload’ returns JwtPayloadStandardFields fields, adhering to the JWT standard.

Bringing It All Together

Executing the test via the CDK CLI should print to console the ID Token, Access Token, and AWS Credentials. ts-node auth.test.ts

Example Output

--------ID Token--------
{
  toString: [Function: toString],
  payload: {
    sub: 'd488e438-b0d1-7011-bc2c-604a199fcdd5',
    'cognito:groups': [ 'admins' ],
    email_verified: true,
    iss: 'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_8j6R6jKCY',
    'cognito:username': 'user',
    origin_jti: '79d0f26f-bd39-4dfd6-9f97-0b68c10d5b73',
    'cognito:roles': [
      'arn:aws:iam::820127509812:role/AuthStack-CognitoAdminRole4C10FBA4-EiDTHoEf1anR'
    ],
    aud: '66h766je9tqbba2fbip9j60hqb',
    event_id: '8626e824-ddbb-410a-af39-56ec4c820657',
    token_use: 'id',
    auth_time: 1708633895,
    exp: 1708637495,
    iat: 1708633895,
    jti: 'c9ddfe55-ec2b-4e27-a291-564e52de9aef',
    email: 'user@user.com'
  }
}
--------Access Token--------
{
  toString: [Function: toString],
  payload: {
    sub: 'd488e438-b0d1-7011-bc2c-604a199fcdd5',
    'cognito:groups': [ 'admins' ],
    iss: 'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_8j6R6jKCY',
    client_id: '66h766je9tqbba2fbipdfdfddf0hqb',
    origin_jti: '79d0f26f-bd39-4dfd6-9f97-0b68c10d5b73',
    event_id: '8626e824-ddbb-410a-af39-56ec4c820657',
    token_use: 'access',
    scope: 'aws.cognito.signin.user.admin',
    auth_time: 1708633895,
    exp: 1708637495,
    iat: 1708633895,
    jti: 'c4a365e7-21d9-463d-bfcc-3534866be4c2',
    username: 'user'
  }
}
--------AWS Credentials--------
{
  accessKeyId: 'ASDFRWSDVFU2AZSFREWDS',
  secretAccessKey: 'examplesecretaccesskey',
  sessionToken: 'examplesessiontoken-examplesessiontoken'
}

Notice the ID Token, which indicates the assumed roles for the session as

  'cognito:roles': [
  'arn:aws:iam::820127509812:role/AuthStack-CognitoAdminRole4C10FBA4-EiDTHoEf1anR'
],

This is the default mapped Authenticated Role. If you were a member of multiple Cogito User Pool Group, each of the group IAM roles would be listed here in addition to the group names, also indicated within the ID Token as:
```
 'cognito:groups': [ 'admins' ],
```

Testing The OAuth Token Endpoint for Custom Scopes

When using resource servers for creating auth flows with different scopes, the API Gateway can use these scopes within the Access Token to determine the access granted to the authenticated user.

Custom scopes added via Resource Servers are then defined within each respective Cognito User Pool Client, each mapping to a Resource Server based on its assigned Custom Scopes.
Each client provides a separate hosted UI, presented to the end-user for authenticating to the application. Depending on how the auth flow is configured, either an Access and ID token are returned or an Authorization Code which is then exchanged for Access and ID tokens.
- The former is an Implicit grant, which exposes the tokens within the URL, while the latter uses Authorization code grant flow, which is more secure.
- Authorization code flow requires a back-channel or server side which will not work with a single page app such as those written in React.

Breaking It Down

Within the AWS Console, click on the appropriate Hosted UI, by first going to the Cognito User Pool, App Integration Tab, then click on the App Client to test under ‘App Client and Analytics’.
This is where the Auth flows, scopes, callback URLs, and timeout options are assigned.
Click View Hosted UI, and authenticate. If only a code= response is generated within the URL, then an Authorization code grant is being used. Test the returned Authorization Code as follows:

Example Screenshot

The following is an example CURL request/response to/from the token endpoint

Request

curl --location --request POST 'https://example-est.auth.us-east-1.amazoncognito.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=5j9701eo7qmhf91oth5eks6kii' \
--data-urlencode 'code=79927d32-ba18-4cff-8254-b7d43d1347a2' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=https://example.com'

Response

{"id_token":"eyJraWQiOiI3SFRmUHF3OTdVRHQwdTQ0cFoyVVZQMFVCVUV5d0toWlNmYVNsc0pTdWl3PSIsImFsZyI6IlJTMjU2In0.eyJhdF9oYXNoIjoibzBNVDBnWVEwbVdua3EwdnA2dHk4ZyIsInN1YiI6ImQ0ODhlNDM4LWIwZDEtNzAxMS1iYzJjLTYwNGExOTlmY2RkNSIsImNvZ25pdG86Z3JvdXBzIjpbImFkbWlucyJdLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfOGo2UjZqS0NZIiwiY29nbml0bzp1c2VybmFtZSI6ImFsZWNobm9zIiwib3JpZ2luX2p0aSI6IjYyMGEwMTY2LTRhNGItNDA0Ny1iNGQzLWFmN2U5MWE1NTQ0NyIsImNvZ25pdG86cm9sZXMiOlsiYXJuOmF3czppYW06OjgyMDEyNzUwOTgxMjpyb2xlXC9BdXRoU3RhY2stQ29nbml0b0FkbWluUm9sZTRDMTBGQkE0LUVpRFRIb0VmMWFuUiJdLCJhdWQiOiI1ajk3MDFlbzdxbWhmOTFvdGg1ZWtzNmtpaSIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNzA4NjMxOTg0LCJleHAiOjE3MDg2MzU1ODQsImlhdCI6MTcwODYzMTk4NSwianRpIjoiYzJmMzMwZWQtYmE0Zi00YzNmLWJhY2ItMDQyNDA3ZGE2NTZmIiwiZW1haWwiOiJhZGFtLmxlY2hub3NAZ21haWwuY29tIn0.veWBGSGEUL8Gz9zHLHa0oWm6L_w3Y76-GtXG_oYnDrmgVAHU7e2RYCE7YEYRN2Mh1sZVLEXZdbQIgO-BNjQqbfLQwIeyDz4o0hAakUMYwuBvk1f9WfntTuszCS8jCZvK2ERZ8r9utcpKndjqVWt2RzGmYaSgJXa5xdCZXfSS77y3KhRvLKY-4AI-pnuthheRHFUzxZHkDhM0YXjL3lKSpjI3697bDBa5K-qRMTVNO37uVAno_AUJ1bb0C7iqwWAC0DN9D6QyGetY0coh4ex9IxmoHiti7D9pZKAyriufa5P6VAk-QNJpPWJ1b0rkT4dIZ_4vG2Ydh63hvUPN99NO_g","access_token":"eyJraWQiOiIyRDRPSlk2ZTY4OGt0aU94eXBSNWRvWEtEc3lHYmFCR01WWmJmYm1oN0dvPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJkNDg4ZTQzOC1iMGQxLTcwMTEtYmMyYy02MDRhMTk5ZmNkZDUiLCJjb2duaXRvOmdyb3VwcyI6WyJhZG1pbnMiXSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfOGo2UjZqS0NZIiwidmVyc2lvbiI6MiwiY2xpZW50X2lkIjoiNWo5NzAxZW83cW1oZjkxb3RoNWVrczZraWkiLCJvcmlnaW5fanRpIjoiNjIwYTAxNjYtNGE0Yi00MDQ3LWI0ZDMtYWY3ZTkxYTU1NDQ3IiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJhd3MuY29nbml0by5zaWduaW4udXNlci5hZG1pbiBvcGVuaWQgdXNlcnNcL3JlYWQiLCJhdXRoX3RpbWUiOjE3MDg2MzE5ODQsImV4cCI6MTcwODYzNTU4NCwiaWF0IjoxNzA4NjMxOTg1LCJqdGkiOiI1YjI1YTRhYS0zZGZjLTRiZWUtOGIyMS0zMjA4NTRlY2QyOGUiLCJ1c2VybmFtZSI6ImFsZWNobm9zIn0.EWCEwDk46i8fOU4IVnlwgM7XNz_i-jtYcpyOYE8q4YGFC7giK5lWgzgIcD9_zHzUF6bVc6iv1uqtQDEXZlOU7pofMhUWBykqnDUC0Q57X4bP3giDigIYmfj77zJLxlWhwRvim28hZfJg9Sz_RIBcf13lo4D8bZvTE5HVEEI-tztuA4B-1dDY65po2zMHqwBEWF9FYaQC2edm5lyQEtTFleHVawBVbQWIU3Ud16TznAy9WEp2q_QgsNSFKuF-2LnQuO27MfyFWFGza8gDMrBwxVJ1l9bjrJuLH300QqQWLdaX7FTupOZHtvUxeND3K4Hc0-ZTu-nvpGUYOAxemfyyIQ","refresh_token":"eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.RMAy1jPNXxpGdPIr1TUukG685KbV5JgokWkBtnWDFOOlcFSRGWS-uNkglPdJJv4g1r4nk7jxYY8J8HnYmomzlt7OD0FdSnvrCEr61SbDZz5FZ9jhzdl-p2_fEoi_fUydpwG_JUliFucvutwDcBd1W2Ul900b24m1nHSrq_NL8r9uFJcVrkFDWLKQ9fxipSYZyU37LePN-qrxX78pQS2vIIe8tVvrG6CuK4GjdRDUvz10tpDFHdTFH75Bn0GHr5xoXXCuTg7CkuyipVYapYeI_AwJIEYBfLzlUjl99hrfkxDUVqlpyqgj9Jq_NOsXwt-sd73ZbPoBGAurAIw2Yw6mxg.WUaX_U7nlacSnml-.CctUJfNf4hngQr4QktmuTWTT5myYN03GzwVWgktiQpGHccW5jgK9QSQmKIG5v33qHoG5KOpm7xyKU9YsehJjpZHj8yq_NMMEamk7DCv4UR7ooXBJS2Hf6KL7Y-2sFxD6Eec7P37t1HtP5QOB1P5CNZgxW069hQpKj6uyOmOqvrso88Jtk18HjRw0SZY1r2jzdey-PRsoinukv2_JWaH2A35QFuApVwurov3DWl7kNKXkQldOROkYC1xrOidXxVTfirschCxSTcNWf481Jh9BF-W_eYcnyAJU0RAFQjZdLEdEUBTl2uH3jTVfGl9qdq32oXmd_EoeugBCW2zUbgekJbRlfmMWt42bZ67qz6ZAZ-cgijp16g1f01pXKV-vKdXIvjOm6IZin9whMwoK4i6zFjfAZLlYPRP2N-lZCRW8d7YeOz7S00OISy5qHF6DpDhm6sWFe0VBmyaYjZKzZob99DXyXBVLJukn1_R2MD5nJNRzCUvJCni3RZ4vEOW8lUK2RwcGjPiLgMH9EalVcALsIq0zV_SsSHUzgXeuvFz6sP-ygIkogrfLKGnGg5ssMpsL6rAlmSskz39veMmWDRxzx20daQXr_vpRHVmk5_Lg6alX7l3uMNGUOpvLEJssRsDWf99kuyXYWA0aqNr80RiJS67TXX0DrmhKtipvnd_cb3G5xcvVsu5xc37g9UnA57Bzvi1ulB9XlcgfrpKZxgPUTV0OtWvVvUDIoi06aOCOMeQgcMBRKoS6T8Qrplg8OzCGmg5cNPgap8foPfD9qgY5DWDlMgtmtohmH_Sg8dFTAdE0fmWhFXmWw5ErVlg4Ea0FtOl5ix8DqOQx0hT_ClhGW-aiXUHoVy7uZHK2Fa385aBoxrk-DtxO5r0ROUjnVwGTVUdUPBFWAb905nTs1K5cvWgkwdRp-wq4NFhwcDy8T1h5Dss3kouIx53JiZv5E4gsroynF7fOL_4vxlt0dM-ykWBB1sN988cTvqUNunWM3vofNWnaEg-_YP7xbOFas78HKqqm4-2UNlM0bYY8E8D6TDf9KtPbZb0Pt2HuJYv6z9JiAmS24Og7Bce1DiEOlGafLrSMgkHp84TumRXWOLurJtVIW2MajM06k3xvAQYdP4rcb4zgss_Pegtq-6AWgNpJ7TvT14NLjm2GXahu2x6gr4EG8Tr3LRDJwOAkxxNwogv2RfBqI8YrjQzDZ_-jzwhhdOvvik3FswYoeLv-UGy333K4gYYEu9SuPsvV5ag.Uy9EJjNpUCosi7jYTiIdew","expires_in":3600,"token_type":"Bearer"}

JWT.io deencoded Access Token

{
  "sub": "d488e438-b0d1-7011-bc2c-604a199fcdd5",
  "cognito:groups": [
    "admins"
  ],
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_8j6R6jKCY",
  "version": 2,
  "client_id": "5j9701eo7qmhf91oth5eks6kii",
  "origin_jti": "620a0166-4a4b-4047-b4d3-af7e91a55447",
  "token_use": "access",
  "scope": "aws.cognito.signin.user.admin openid users/read",
  "auth_time": 1708631984,
  "exp": 1708635584,
  "iat": 1708631985,
  "jti": "5b25a4aa-3dfc-4bee-8b21-320854ecd28e",
  "username": "username"
}

The de-encoded Base64 Access Token indicates the scope values which were also attached to the resource server, "scope": "aws.cognito.signin.user.admin openid users/read".
For Implicit grants, the ID and Access Tokens are returned directly within the URL.

_{Original code snippets by Alex Dan via Udemy}

AWS CDK - Understanding Amazon Cognito Authentication and Authorization

Mon, 20 Feb 2023 12:00:00 +0000

Diagram

Amazon Cognito Client Workflow (draw.io viewer)

The Moving Pieces

Components of Amazon Cognito which are part of the authentication and authorization flow:

Cognito User Pools - Authentication, Authorization, and Resource Servers

Refer to my blog post, AWS CDK - Breaking Down AWS Cognito OAuth & OIDC Workflow for more details about what Authentication, Authorization, and Resource Servers are.
Contains a directory of users & groups or, may be delegated to a Federated Identity Provider for sign-in experience, such as Google, Facebook, Amazon, Apple, SAML, or OIDC (OpenID Connect).
Groups created within the User Pool are associated with IAM (AWS Identity and Access Management) roles, assumed by the user for performing tasks within AWS, such as reading S3 Buckets.
- Each group may have a separate IAM Role configured, for allowing delineated permissions amongst disparate managed group members.
App integration settings, where app clients are defined and its token expiration, authentication flows, OAUTH 2.0 grant types, and OpenID Connect Scopes and Identity Providers are defined.
- Authentication flow options: ALLOW_ADMIN_USER_PASSWORD_AUTH, ALLOW_USER_PASSWORD_AUTH, ALLOW_REFRESH_TOKEN_AUTH, ALLOW_USER_PASSWORD_AUTH, and ALLOW_USER_SRP_AUTH.
- OAuth 2.0 grant type options:
  - Authorization code grant - provides an authorization code as the response to be exchanges on a back-channel or server side for a Access Token. The exchange would include a client ID and Client Secret.
  - Implicit grant - specifies that the client should get the access token (and optionally, ID token, based on scopes) directly. (exposes the OAuth (Access) token within the URL)
- OpenID Connect Scopes - at least one scope is required to specify the attributes the app client can retrieve for access. Scopes include:
  - aws.cognito.sigin.user.admin, openid, email, phone, and profile (the last three options also require OpenID to be selected)
  - These scopes authorize the access token for retrieval of user attributes from the userInfo endpoint for OpenID Connect.
- Identity providers - which are made available to the client. Some or all of your user pool external Identity Providers may be selected to authenticate your users.
  - Selecting at least Cognito user pool enables authentication via the Cognito User Pool, which enables access to its Federated Identity Providers, or, its own internal set of users.
- Adding at least a Configured User Pool Domain within the App Integration tab provides a Hosted UI for the user sign-in experience.
- The client is where the Authentication flow session duration, refresh token expiration, access token expiration, ID token expiration, and other advanced authentication settings are specified.

Cognito Identity Pools - AWS Resource Access via IAM Assumed Roles

Grants users access to AWS resources, and are associated with Identity Pools as the Identity Provider. External Identity Providers may be selected here as well, bypassing the use of Amazon Cognito User Pools.
Default Authenticated and Unauthenticated (Guest Access) roles may be specified, whereby the ID pool is the trusted resource assuming the role on behalf of the user.
Custom roles may be added then mapped via the user pool and its assigned groups (Admin group members will be assigned the Admin IAM role for example).
- This mapping would be used either in conjunction or in lieu of the IAM roles associated with groups created within the Cognito User Pools, depending on how the role mappings are configured.
  - Rule based role mappings will match claim values, whereas Token based role mappings will perform a lookup of the IAM Role associated with cognito:role and cognito:preferred_role claims injected into the ID Token from the Cognito Identity Pool.
- Using a Federated Identity Provider within the User Pool would require mapping the custom roles via the claim values to IAM Roles. Rule based role mappings are required. (more on this below)
The ARN of the assigned user’s role get injected into the ID Token as "cognito:role": [<list of role ARNs>].
In addition, "cognito:preferred_role":"<role ARN>" gets injected in the ID Token, based on the role with the best (lowest) precedence value. If there is only one role, this will be the value.
- i.e., if authenticated, but no group is assigned within the user pool, use the default role associated with the Authenticated settings.

AWS Amplify - Authentication Mechanism

Configure Cognito as the authentication provider
Present authentication frontend
Fetch ID Token upon authentication and pass it around where required
May use its own Federated Provider such as Google, Apple, etc.

Technical Terms

In Cognito, both ID Tokens and Access Tokens include a cognito:groups claims that contains user group memberships in the Cognito User Pool. Cognito returns both ID Tokens and Access Tokens.

Identity Provider (IdP)

Provides a database of user identities and their details, such as name, email, etc., and may be provided via a federated external provider, such as Google, Facebook, Amazon, Apple, or any OpenID Connect or SAML provider.
Refer to AWS’ developer guide for more info on Cognito User Pool Identity Providers.

JSON Web Token (JWT)

A formatted JSON nested object structure, used by both OAuth and OpenID Connect (more on these terms below) for passing data between web components, ensuring data integrity of the contained payload.
JWT does not encrypt the data (and will generally depend on TLS for data confidentiality).
JWTs are Signed by the issuer’s private key and verified using the issuer’s corresponding public key, for the data integrity component.
Refer to the official JWT website for more details.

ID Tokens

According to OpenID Connect (OIDC), in JWT format, provides proof of the user’s successful authentication.
Payloads contain claims about the user properties for the target/receiving application.
- Claims may be the following keys: aud, name, email, expiration, and others
- For Amazon Cognito, claims will also contains:
  - cogntio:groups, an array of the names of user pool groups that have your user as a member. Groups can generate a request for a preferred IAM role from and Identity pool.
  - cognito:preferred_role, the ARN of IAM role associated with the user’s highest priority user pool group.
  - cognito:username, the user name of the user within the user pool group
  - cognito:roles, an array of the names of the IAM roles associated with the user’s groups. Each user pool group can have an IAM role associated with it.
- Also refer to AWS’ developer guide around ID Tokens for more info.
Claims are used by the application to help with the user experience, in lieu of using cookies.

Example ID Token Payload

<header>.{
    "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "cognito:groups": [
        "test-group-a",
        "test-group-b",
        "test-group-c"
    ],
    "email_verified": true,
    "cognito:preferred_role": "arn:aws:iam::111122223333:role/my-test-role",
    "iss": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example",
    "cognito:username": "my-test-user",
    "middle_name": "Jane",
    "nonce": "abcdefg",
    "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "cognito:roles": [
        "arn:aws:iam::111122223333:role/my-test-role"
    ],
    "aud": "xxxxxxxxxxxxexample",
    "identities": [
        {
            "userId": "amzn1.account.EXAMPLE",
            "providerName": "LoginWithAmazon",
            "providerType": "LoginWithAmazon",
            "issuer": null,
            "primary": "true",
            "dateCreated": "1642699117273"
        }
    ],
    "event_id": "64f513be-32db-42b0-b78e-b02127b4f463",
    "token_use": "id",
    "auth_time": 1676312777,
    "exp": 1676316377,
    "iat": 1676312777,
    "jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "email": "my-test-user@example.com"
}
.<token signature>

Access Tokens

Contains claims about the authenticated user, a list of the user’s groups, and a list of scopes, via the OAuth 2.0 Scope specification, in JWT format.
Access token provider authorization, granting a client application access specific resources and allow specific actions on behalf of the user, as granted by the access token.
- For example, authorizing LinkedIn to access X’s (Twitter’s) APIs for cross posting.
- Refer to AWS’s developer guide for more info regarding Access Tokens
Access Tokens will contain the scope key, a list of OAuth 2.0 scopes that define what access the token provides. For Amazon Cognito API sign-in, only aws.cognito.signin.user.admin is contained within the scope.
Amazon Cognito Access Tokens will also contain cognito:groups, an array of the names of user pool groups that have you as a member, similar to the OIDC Access Token mentioned above.

Example Access Token

<header>.
{
   "sub":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "device_key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "cognito:groups":[
      "testgroup"
   ],
   "iss":"https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example",
   "version":2,
   "client_id":"xxxxxxxxxxxxexample",
   "origin_jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "event_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "token_use":"access",
   "scope":"phone openid profile resourceserver.1/appclient2 email",
   "auth_time":1676313851,
   "exp":1676317451,
   "iat":1676313851,
   "jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "username":"my-test-user"
}
.<token signature>

Sample CDK Code

Imagine if we were creating resources using CDK, and wanted to then create an Authentication Stack in order to provide authentication and authorization mechanisms for accessing these resources in AWS. Perhaps we would like to employ a token header for API access, and based on the token, claims about the user will be used in order to determine appropriate permissions. Suppose we would only grant PUT access to Admin users, but GET is always available to all users. Suppose also

Breaking Down The CDK Constructs

Refer to the GitHub Gist, containing the complete CDK for the hypothetical Authentication Stack, written in TypeScript. Here is the breakdown:

Create User Pool

private createUserPool(){
    this.userPool = new UserPool(this, 'UserPool', {
        selfSignUpEnabled: true,
        signInAliases: {
            username: true,
            email: true
        }
    });

    new CfnOutput(this, 'UserPoolId', {
        value: this.userPool.userPoolId
    })
}

Creates a new User Pool named UserPool, with user sign-up enabled with only username and email address.
CfnOutput provides output to console during CDK Deploy, whereby the UserPoolID is displayed.

Create User Pool Client

private createUserPoolClient(){
    this.userPoolClient = this.userPool.addClient('UserPoolClient', {
        authFlows: {
            adminUserPassword: true,
            custom: true,
            userPassword: true,
            userSrp: true
        }
    })

    new CfnOutput(this, 'UserPoolClientId', {
        value: this.userPoolClient.userPoolClientId
    })
}

Creates a new User Pool Client, which are specified under the App Integration tab of the User Pool, providing the app client name, authentication flow, session duration, and hosted UI settings.
Here we name the client UserPoolClient and attach it to the User Pool.
CfnOutput will output to console, the User Pool Client ID, during CDK Deploy.

Create User Pool Groups

private createUserGroup(){
    const cfnUserPoolGroup = new cognito.CfnUserPoolGroup(this, 'UserPoolGroup', {
        userPoolId: this.userPool.userPoolId
    })
}

private createAdminGroup(){
    new CfnUserPoolGroup(this, 'Admins', {
        userPoolId: this.userPool.userPoolId,
        groupName: 'admins',
        roleArn: this.adminRole.roleArn
    })
}

Creates two user pool groups, attached to the User Pool, UserPoolGroup and Admins. The createAdminGroup function also contains added property values for groupName, which will provide a cleaner group name, ‘admins’, and roleArn, which maps the group to the ‘adminRole’, created below.

Create Identity Pool

private createIdentityPool(){
    this.identityPool = new CfnIdentityPool(this, 'IdentityPool', {
        allowUnauthenticatedIdentities: true,
        cognitoIdentityProviders: [{
            clientId: this.userPoolClient.userPoolClientId,
            providerName: this.userPool.userPoolProviderName
        }]
    })

    new CfnOutput(this, 'IdentityPoolId', {
        value: this.identityPool.ref
    })

    this.identityPool.identityPoolName
}

Created an Identity Pool named IdentityPool, allowing Unauthenticated Users, and specifying Cognito User Pool as the Identity Provider referencing the User Pool Client via clientId and User Pool Identity Provider as providerName.
Here, the User Pool Client options and User Pool Identity Provider come together for integration with the Identity Pool.
CfnOutput print to console the Identity Pool ARN.

Create IAM Roles

private createRoles(){
    this.authenticatedRole = new Role(this, 'CognitoDefaultAuthenticatedRole', {
        assumedBy: new FederatedPrincipal('cognito-identity.amazonaws.com', {
            StringEquals: {
                'cognito-identity.amazonaws.com:aud': this.identityPool.ref
            },
            'ForAnyValue:StringLike': {
                'cognito-identity.amazonaws.com:amr': 'authenticated'
            }
        },
        'sts:AssumeRoleWithWebIdentity'       
        )
    })

    this.unauthenticatedRole = new Role(this, 'CognitoDefaultUnauthenticatedRole', {
        assumedBy: new FederatedPrincipal('cognito-identity.amazonaws.com', {
            StringEquals: {
                'cognito-identity.amazonaws.com:aud': this.identityPool.ref
            },
            'ForAnyValue:StringLike': {
                'cognito-identity.amazonaws.com:amr': 'unauthenticated'
            }
        },
        'sts:AssumeRoleWithWebIdentity'       
        )
    })

    this.adminRole = new Role(this, 'CognitoAdminRole', {
        assumedBy: new FederatedPrincipal('cognito-identity.amazonaws.com', {
            StringEquals: {
                'cognito-identity.amazonaws.com:aud': this.identityPool.ref
            },
            'ForAnyValue:StringLike': {
                'cognito-identity.amazonaws.com:amr': 'authenticated'
            }
        },
        'sts:AssumeRoleWithWebIdentity'       
        )
    })

    this.adminRole.addToPolicy(new PolicyStatement({
        effect: Effect.ALLOW,
        actions: ["s3:ListAllMyBuckets"],
        resources: ['*']
    }))

    new CfnOutput(this, 'AdminRoleArn', {
        value: this.adminRole.roleArn
    })
}

Creates three IAM Roles, CognitoDefaultAuthenticatedRole, CognitoDefaultUnauthenticatedRole, and CognitoAdminRole, with the last containing a PolicyStatement via the addToPolicy method, to allow the listing of all S3 Buckets within the AWS Account.
All three roles make user of the assumedBy property, by creating a new FederatedPrincipal object, each role contains a JSON object of ‘Trusted entities’, allowing each role to be assumed by the Identity Pool created above.
- CognitoDefaultAuthenticatedRole performs a StringEquals for Cognito Authenticated Users, allowing only users Authenticated by Cognito to assume this role, with the following line under ForAnyValue:StringLike: 'cognito-identity.amazonaws.com:amr': 'authenticated'.
  - Authenticated User will inherit the policy associated with this role. Currently, no policy statement has been set.
- CognitoDefaultUnauthenticatedRole is the same as the role above, however, ForAnyValue:StringLike: 'cognito-identity.amazonaws.com:amr': 'unauthenticated' for assumption of the role by unauthenticated users.
- CognitoAdminRole contains the same JSON as CognitoDefaultAuthenticatedRole, for use by Admin users. This role will only work for Authenticated Users, but contain the permissions as listed within the addToPolicy method.
  - In addition to the AWS permissions provided by the policy statement, API Gateway will receive the Access Token supplid by the Authorization header. Downstream, a Lambda function may parse the event claims’ 'cognito:groups:' key, and based on it value, allow the coded permissions.
    - For example, a hasAdminGroup function may be created, whereby the event body is supplied, and if any values in the list match ‘admin’, will allow certain API methods. Perhaps only the Delete method would contain the following code:
    - if (!hasAdminGroup(event)){ return { statusCode: 401, body: JSON.stringify('Not authorized!') } }

Identity Pool Role Attachments & Mappings

private attachRoles(){
    new CfnIdentityPoolRoleAttachment(this, 'RolesAttachment', {
        identityPoolId: this.identityPool.ref,
        roles: {
            'authenticated': this.authenticatedRole.roleArn,
            'unauthenticated': this.unauthenticatedRole.roleArn
        },
        roleMappings: {
            adminsMapping: {
                type: 'Token',
                ambiguousRoleResolution: 'AuthenticatedRole',
                identityProvider: `${this.userPool.userPoolProviderName}:${this.userPoolClient.userPoolClientId}`
            }
        }
    })
    }

The IAM Roles will be attached to the Identity Pool, whereby the Identity Pool is specified using this.identityPool.ref, and the default authenticated and unauthenticated roles via 'authenticated': this.authenticatedRole.roleArn and 'unauthenticated': this.unauthenticatedRole.roleArn lines.
Role mapping are specified within the nested JSON roleMappings: object. In the above example, the name is specified as adminsMapping, which is of type Token, with ambiguousRoleResolution set to AuthenticatedRole. The identityProvider contains the User Pool Provider name from the userPool object, concatenated with a : and the User Pool Client ID.
- Setting Type to ‘Token’ will use the cognito:roles and cognito:preferred_role from the ID Token claims supplied by the Cognito Identity Provider. The IAM roles are mapped via the user group memberships within the Cognito Identity Provider, as listed within the 'cognito:groups:' claim.
- Setting Type to ‘Rules’ will attempt to match claims from the ID Token to map a role. In this case the roleMappings JSON would be as follows:
```
  roleMappings: {
      adminsMapping: {
          type: 'Rules',
          ambiguousRoleResolution: 'AuthenticatedRole',
          identityProvider: `${this.userPool.userPoolProviderName}:${this.userPoolClient.userPoolClientId}`,
          rulesConfiguration: {
            rules: [{
              claim: 'claim',
              matchType: 'matchType',
              roleArn: 'roleArn',
              value: 'value',
            }]
          }
      }
  }
```
- In addition, the IAM policy attached to the Authenticated role will also be applied but not listed within any of the claims, granted permissions as provided across all mapped roles and the authenticated roles.
- Unauthenticated users will receive permissions against the Unauthenticated Role. APIs may still choose to allow access to certain to methods omitting a check against the Access Token.

Disparate App Client API Method Access

Authorization Scopes are used to determine the granted permissions for an app. Authorization Scopes are supplied to each API Method, by providing the Authorization value as the Cognito User Pool. A domain for the user pool must be configured, at which point, Amazon Cognito automatically provisions an OAuth 2.0 authorization server and hosted web UI with sign-up and sign-in pages that the web app can present to users. Authentication to the sign-in pages creates and ID Token and Access Token, which then may be used to access the API resource.

A Resource Server is an OAuth 2.0 API server, such as the API Gateway and its methods pointing to a Lambda function handler. It validates that access tokens from the user pool contain the scopes that authorize the requested method and path in the API that protects it.
Access tokens are the OAuth 2.0 JWT tokens which contain claims, including custom claims, recall from the Breaking Down The CDK Constructs section above. You also learned that ‘aws.cognito.signin.user.admin’ was added by default to the claims within the Access token. It authorizes the bearer of an access token to query and update all information about a user pool user with, for example, the GetUser and UpdateUserAttributes API operations.
- GetUser: Gets the user attributes and metadata for a user. More details within the API Reference for Amazon Cognito User Pools.
- UpdateUserAttributes: Allows users to update one or more of their attributes with their own credentials. More details within the API Reference for Amazon Cognito User Pools.
Additional Custom Scope are required in order to parse them from the API Authorizer to grant each method’s API access.
- For example, ‘read’ would be parsed by the GET resource to allow access to this API method.
- Custom scopes are added to the Cognito User Pool, App Integration, Resource servers, within the AWS Management Console.
- The created custom scopes are then added within the Identity Pool associated with the User Pool.
Read more about Cognito Custom Scopes for API Gateway
Read more details about OAuth 2.0 scopes and API Authorization with resource server

Adding a Resource Server

private createResourceServers(){
    const readOnlyScope = new cognito.ResourceServerScope({ scopeName: 'read', scopeDescription: 'Read-only access' });
    const fullAccessScope = new cognito.ResourceServerScope({ scopeName: '*', scopeDescription: 'Full access' });

    const userServer = this.userPool.addResourceServer('ResourceServer', {
        identifier: 'users',
        scopes: [ readOnlyScope, fullAccessScope ],
      });
      
      const readOnlyClient = this.userPool.addClient('read-only-client', {
        // ...
        oAuth: {
          // ...
          scopes: [ cognito.OAuthScope.resourceServer(userServer, readOnlyScope) ],
        },
      });
      
      const fullAccessClient = this.userPool.addClient('full-access-client', {
        // ...
        oAuth: {
          // ...
          scopes: [ cognito.OAuthScope.resourceServer(userServer, fullAccessScope) ],
        },
      });
}

Created two different resource servers named ‘read-only-client’ and ‘full-access-client’. The resource servers create two different access scopes, scopeName: 'read', scopeDescription: 'Read-only access' and scopeName: '*', scopeDescription: 'Full access', added to their respective resource servers. Each resource servers is accessed by its client ID, generated upon creation. The resource servers are then accessed by the hosted UI and client ID. In response will be either an ID and Access Token or Authorization Code, depending on the Authorization Flow. Authorization Codes are then redeemed for ID & Access Tokens, using the Token Endpoint.

The following is an example CURL request/response to/from the token endpoint for the Authorization Code flow using an Access Code. This is for illustrative purposes and would not work for a single page app written in React.

Request

curl --location --request POST 'https://example-est.auth.us-east-1.amazoncognito.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=5j9701eo7qmhf91oth5eks6kii' \
--data-urlencode 'code=79927d32-ba18-4cff-8254-b7d43d1347a2' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=https://example.com'

Response

{"id_token":"eyJraWQiOiI3SFRmUHF3OTdVRHQwdTQ0cFoyVVZQMFVCVUV5d0toWlNmYVNsc0pTdWl3PSIsImFsZyI6IlJTMjU2In0.eyJhdF9oYXNoIjoibzBNVDBnWVEwbVdua3EwdnA2dHk4ZyIsInN1YiI6ImQ0ODhlNDM4LWIwZDEtNzAxMS1iYzJjLTYwNGExOTlmY2RkNSIsImNvZ25pdG86Z3JvdXBzIjpbImFkbWlucyJdLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfOGo2UjZqS0NZIiwiY29nbml0bzp1c2VybmFtZSI6ImFsZWNobm9zIiwib3JpZ2luX2p0aSI6IjYyMGEwMTY2LTRhNGItNDA0Ny1iNGQzLWFmN2U5MWE1NTQ0NyIsImNvZ25pdG86cm9sZXMiOlsiYXJuOmF3czppYW06OjgyMDEyNzUwOTgxMjpyb2xlXC9BdXRoU3RhY2stQ29nbml0b0FkbWluUm9sZTRDMTBGQkE0LUVpRFRIb0VmMWFuUiJdLCJhdWQiOiI1ajk3MDFlbzdxbWhmOTFvdGg1ZWtzNmtpaSIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNzA4NjMxOTg0LCJleHAiOjE3MDg2MzU1ODQsImlhdCI6MTcwODYzMTk4NSwianRpIjoiYzJmMzMwZWQtYmE0Zi00YzNmLWJhY2ItMDQyNDA3ZGE2NTZmIiwiZW1haWwiOiJhZGFtLmxlY2hub3NAZ21haWwuY29tIn0.veWBGSGEUL8Gz9zHLHa0oWm6L_w3Y76-GtXG_oYnDrmgVAHU7e2RYCE7YEYRN2Mh1sZVLEXZdbQIgO-BNjQqbfLQwIeyDz4o0hAakUMYwuBvk1f9WfntTuszCS8jCZvK2ERZ8r9utcpKndjqVWt2RzGmYaSgJXa5xdCZXfSS77y3KhRvLKY-4AI-pnuthheRHFUzxZHkDhM0YXjL3lKSpjI3697bDBa5K-qRMTVNO37uVAno_AUJ1bb0C7iqwWAC0DN9D6QyGetY0coh4ex9IxmoHiti7D9pZKAyriufa5P6VAk-QNJpPWJ1b0rkT4dIZ_4vG2Ydh63hvUPN99NO_g","access_token":"eyJraWQiOiIyRDRPSlk2ZTY4OGt0aU94eXBSNWRvWEtEc3lHYmFCR01WWmJmYm1oN0dvPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJkNDg4ZTQzOC1iMGQxLTcwMTEtYmMyYy02MDRhMTk5ZmNkZDUiLCJjb2duaXRvOmdyb3VwcyI6WyJhZG1pbnMiXSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfOGo2UjZqS0NZIiwidmVyc2lvbiI6MiwiY2xpZW50X2lkIjoiNWo5NzAxZW83cW1oZjkxb3RoNWVrczZraWkiLCJvcmlnaW5fanRpIjoiNjIwYTAxNjYtNGE0Yi00MDQ3LWI0ZDMtYWY3ZTkxYTU1NDQ3IiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJhd3MuY29nbml0by5zaWduaW4udXNlci5hZG1pbiBvcGVuaWQgdXNlcnNcL3JlYWQiLCJhdXRoX3RpbWUiOjE3MDg2MzE5ODQsImV4cCI6MTcwODYzNTU4NCwiaWF0IjoxNzA4NjMxOTg1LCJqdGkiOiI1YjI1YTRhYS0zZGZjLTRiZWUtOGIyMS0zMjA4NTRlY2QyOGUiLCJ1c2VybmFtZSI6ImFsZWNobm9zIn0.EWCEwDk46i8fOU4IVnlwgM7XNz_i-jtYcpyOYE8q4YGFC7giK5lWgzgIcD9_zHzUF6bVc6iv1uqtQDEXZlOU7pofMhUWBykqnDUC0Q57X4bP3giDigIYmfj77zJLxlWhwRvim28hZfJg9Sz_RIBcf13lo4D8bZvTE5HVEEI-tztuA4B-1dDY65po2zMHqwBEWF9FYaQC2edm5lyQEtTFleHVawBVbQWIU3Ud16TznAy9WEp2q_QgsNSFKuF-2LnQuO27MfyFWFGza8gDMrBwxVJ1l9bjrJuLH300QqQWLdaX7FTupOZHtvUxeND3K4Hc0-ZTu-nvpGUYOAxemfyyIQ","refresh_token":"eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.RMAy1jPNXxpGdPIr1TUukG685KbV5JgokWkBtnWDFOOlcFSRGWS-uNkglPdJJv4g1r4nk7jxYY8J8HnYmomzlt7OD0FdSnvrCEr61SbDZz5FZ9jhzdl-p2_fEoi_fUydpwG_JUliFucvutwDcBd1W2Ul900b24m1nHSrq_NL8r9uFJcVrkFDWLKQ9fxipSYZyU37LePN-qrxX78pQS2vIIe8tVvrG6CuK4GjdRDUvz10tpDFHdTFH75Bn0GHr5xoXXCuTg7CkuyipVYapYeI_AwJIEYBfLzlUjl99hrfkxDUVqlpyqgj9Jq_NOsXwt-sd73ZbPoBGAurAIw2Yw6mxg.WUaX_U7nlacSnml-.CctUJfNf4hngQr4QktmuTWTT5myYN03GzwVWgktiQpGHccW5jgK9QSQmKIG5v33qHoG5KOpm7xyKU9YsehJjpZHj8yq_NMMEamk7DCv4UR7ooXBJS2Hf6KL7Y-2sFxD6Eec7P37t1HtP5QOB1P5CNZgxW069hQpKj6uyOmOqvrso88Jtk18HjRw0SZY1r2jzdey-PRsoinukv2_JWaH2A35QFuApVwurov3DWl7kNKXkQldOROkYC1xrOidXxVTfirschCxSTcNWf481Jh9BF-W_eYcnyAJU0RAFQjZdLEdEUBTl2uH3jTVfGl9qdq32oXmd_EoeugBCW2zUbgekJbRlfmMWt42bZ67qz6ZAZ-cgijp16g1f01pXKV-vKdXIvjOm6IZin9whMwoK4i6zFjfAZLlYPRP2N-lZCRW8d7YeOz7S00OISy5qHF6DpDhm6sWFe0VBmyaYjZKzZob99DXyXBVLJukn1_R2MD5nJNRzCUvJCni3RZ4vEOW8lUK2RwcGjPiLgMH9EalVcALsIq0zV_SsSHUzgXeuvFz6sP-ygIkogrfLKGnGg5ssMpsL6rAlmSskz39veMmWDRxzx20daQXr_vpRHVmk5_Lg6alX7l3uMNGUOpvLEJssRsDWf99kuyXYWA0aqNr80RiJS67TXX0DrmhKtipvnd_cb3G5xcvVsu5xc37g9UnA57Bzvi1ulB9XlcgfrpKZxgPUTV0OtWvVvUDIoi06aOCOMeQgcMBRKoS6T8Qrplg8OzCGmg5cNPgap8foPfD9qgY5DWDlMgtmtohmH_Sg8dFTAdE0fmWhFXmWw5ErVlg4Ea0FtOl5ix8DqOQx0hT_ClhGW-aiXUHoVy7uZHK2Fa385aBoxrk-DtxO5r0ROUjnVwGTVUdUPBFWAb905nTs1K5cvWgkwdRp-wq4NFhwcDy8T1h5Dss3kouIx53JiZv5E4gsroynF7fOL_4vxlt0dM-ykWBB1sN988cTvqUNunWM3vofNWnaEg-_YP7xbOFas78HKqqm4-2UNlM0bYY8E8D6TDf9KtPbZb0Pt2HuJYv6z9JiAmS24Og7Bce1DiEOlGafLrSMgkHp84TumRXWOLurJtVIW2MajM06k3xvAQYdP4rcb4zgss_Pegtq-6AWgNpJ7TvT14NLjm2GXahu2x6gr4EG8Tr3LRDJwOAkxxNwogv2RfBqI8YrjQzDZ_-jzwhhdOvvik3FswYoeLv-UGy333K4gYYEu9SuPsvV5ag.Uy9EJjNpUCosi7jYTiIdew","expires_in":3600,"token_type":"Bearer"}

JWT.io deencoded Access Token

{
  "sub": "d488e438-b0d1-7011-bc2c-604a199fcdd5",
  "cognito:groups": [
    "admins"
  ],
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_8j6R6jKCY",
  "version": 2,
  "client_id": "5j9701eo7qmhf91oth5eks6kii",
  "origin_jti": "620a0166-4a4b-4047-b4d3-af7e91a55447",
  "token_use": "access",
  "scope": "aws.cognito.signin.user.admin openid users/read",
  "auth_time": 1708631984,
  "exp": 1708635584,
  "iat": 1708631985,
  "jti": "5b25a4aa-3dfc-4bee-8b21-320854ecd28e",
  "username": "username"
}

The de-encoded Base64 Access Token indicates the scope values which were also attached to the resource server, "scope": "aws.cognito.signin.user.admin openid users/read".

The next post will go-over testing the CDK’s Authorization Stack, by writing some test code in TypeScript.

_{Original code snippets by Alex Dan via Udemy}

AWS Cloud Development Kit (CDK) - Understanding the Node/Tree Relationship

Fri, 17 Feb 2023 12:00:00 +0000

Diagram

AWS Cloud Development Kit Tree/Node Diagram (draw.io viewer)

Details

The AWS CDK is a tree/node relationship structure, requiring the initializing of the root node via the app = new.cdk.App() object, imported from the aws-cdk-lib CDK library. The object inherits the Stage object which in turn inherits the Construct object.
Subsequent AWS resources are instantiated Stack objects, such as the bucketStack = new BucketStack(app, 'BucketStack') instance created, which in turn inherits the Construct object.
Hence, each new instantiation of an AWS resource, is a child of the Construct, which is then added to the root Construct, app per the first scope argument for each instantiated resource’s constructor.
- i.e., handlerStack = new HandlerStack(app, ‘HandlerStack’, extendedProps..)
Resouces created inside resources, such as the new LambdaFunction(this, 'LambdaFunction', FunctionProps) Lambda functions, contains the first argument this, for the scope parameter since this is the parent object, handlerStack, which inherits a Construct object.

To button up the tree node relationship, each object is inherited from Construst, which in turn is nested within each other via the scope parameter, either as this when scoping in as a child of a resource, such as handlerStack, or as app for each new instantiated resource. Each nested resource is scoped within it’s parent, and each resource is scoped within its root node, app.

PCI Compliance in AWS - Simplified (featured in ISC2 Blog)

Sun, 01 Sep 2019 12:00:00 +0000

PCI Compliance in AWS - Simplified

This blog post also featured in the (ISC)² Blog

Payment Card Industry Data Security Standards or PCI DSS, are a set of 12 requirements with over 300 controls which apply to any organization which stores, processes or transmits credit card data. Today, I will attempt to add some clarity around PCI compliance within AWS.

Concepts and practices were sourced from the referenced document below and here I will break it down further. I do suggest you first read the Architecting for PCI DSS Scoping and Segmentation on AWS and come back to enhance your understanding of the methods being applied and its rationale.

For a quick primer on PCI-DSS, please refer to the council’s overview PDF. Referenced from: https://d1.awsstatic.com/whitepapers/pci-dss-scoping-on-aws.pdf

Infrastructure Services

Infrastructure services such as EC2 require the most amount of effort from a PCI compliance perspective based on the AWS Shared Responsibility Model. Other services are categorized as ‘Abstracted’ or ‘Containerized’(not to be confused with containers such as Docker or such services as Fargate thoughencompassed by this category). Examples are EC2 instances which require host based firewalls, configuration and patch management, OS level logging, and an assurance of non-vendor defaults such as the usage CIS bench-marking (using AWS AMIs should be sufficient).

Kubernetes on EC2

Like EC2, ECS and EKS are all deemed ‘Infrastructure’ based services. These services expose administrative access and control at the OS layer and hence their designation. Today, since we manually manage Kubernetes in a cluster of EC2 instances, we therefore must apply PCI practices at all layers of the shared responsibility model except for physical controls such as in the examples mentioned above.

AWS Fargate Considerations

Using AWS Fargate in lieu of EC2 hosting Kubernetes would reduce the PCI compliance footprint as Fargate is considered a ‘Containerized’ service and hence, the degree of PCI compliance requirements is greatly reduced as per the AWS Shared Responsibility Model. The instantiation of Fargate within-in it’s own AWS Account and the endpoints it connects would be in scope. Fargate would not require network, OS level, and like EC2, nor physical level controls.

Abstracted Services

URL Load Balancers, API Gateways, and other ‘Abstracted’ services are services in which the degree of control is limited to the movement of data using AWS APIs. AWS handles network, OS, and physical controls therefore, minimizing PCI scope of work.

The instantiation of an Abstracted service within its own AWS Account and the endpoints it connects would be in scope. Fargate would not require network or OS level controls and like EC2 nor physical level controls, like Containerized services.

Network and Encryption Level Abstracted Services

Application Load Balancers, Web Application Firewalls, and KMS must be configured to terminate TLS version 1.1 or greater between itself and all endpoints.

Connected-to and Security-Impacting Gotchas

Any service that supports, directly impacts, or provide security to the CDE fall with-in scope of PCI compliance. i.e, Vault provides configuration parameters for Docker Containers in Kubernetes within the CDE and hence, the EC2 instance in which Vault sits atop of, would fall with-in scope of PCI compliance.

Abstracted Service Caveats

Normally, if Abstracted services such as AWS S3 or Application Load Balancer transmits or stores CHD, these services fall with-in scope of PCI compliance. Since these services are considered ‘Abstracted’, network and OS level controls do not apply. If these services do not handle CHD, segmentation is assumed and therefore out of scope for PCI compliance even if located within the same CDE environment.

Examples

S3 Bucket without CHD An S3 bucket with-in the same VPC as the CDE in which no CHD is stored or passes, is not considered part of the CDE.

S3 Bucket with CHD An S3 bucket containing CHD would fall with-in scope of PCI compliance however, only pertinent PC requirements would apply such as role-based access controls and not OS layer controls such as anti-virus, etc, essentially controls around data access via the S3 APIs.

SQS without CHD If we were to replace Kafka with AWS SQS, we eliminate the use of Infrastructure services in favor of Abstracted Services, as Kafka currently sits atop EC2, therefore, SQS would be out of scope for PCI compliance unless it processes CHD either though it’s connected to the CDE.

SQS with CHD If we were to replace Kafka with AWS SQS in which CHD would be stored and transmitted, only those endpoints in which SQS connects would fall with-in scope of PCI even if with-in the same CDE.

Conclusion

Within the newly created AWS PCI Zone, replacing Kubernetes on EC2 with Fargate and possibly Kafka with SQS, would eliminate many of the PCI requirements in that zone as a result of using only. Abstracted and Containerized services as mentioned in the preceding examples above.

The Risky Pipeline

Managing Configurations for Prometheus and Grafana Helm Charts

Diagram

Managing Prometheus and Grafana via Helm (draw.io viewer)

Service Discovery Versus Static Configs

Why CRDs?

Available Prometheus CRDs

Alerting Rules

Scrape Configs

Exporters

Alert Manager Rules

Using Helm Values

AWS CDK - Breaking Down AWS Cognito OAuth & OIDC Workflows

Diagram

Amazon Cognito OAuth & OIDC Workflow (draw.io viewer)

AWS Cognito with CDK Post Series

Breaking It Down

Components (from left to right)

The Flow

Breaking Down OAuth Scopes A Bit Further

Example OAuth Access Token

Breaking Down OpenID Connect A Bit Further

Example OIDC ID Token

AWS CDK - Using Amazon Cognito Authentication and Authorization

Diagram

Amazon Cognito Client Workflow (draw.io viewer)

Components

Overview

Breaking It Down

Authentication Service

Login Component

Application Router

AWS CDK - Testing Amazon Cognito Authentication and Authorization

Diagram

Amazon Cognito Client Workflow (draw.io viewer)

Creating an AuthService Test

AuthService.ts exported functions

Analyzing the ‘signIn’ TypeScript type is as follows:

auth.test.ts call to the exported AuthService.ts functions.

Analyzing ‘fetchAuthSession’ a bit further

Bringing It All Together

Example Output

Testing The OAuth Token Endpoint for Custom Scopes

Breaking It Down

AWS CDK - Understanding Amazon Cognito Authentication and Authorization

Diagram

Amazon Cognito Client Workflow (draw.io viewer)

The Moving Pieces

Cognito User Pools - Authentication, Authorization, and Resource Servers

Cognito Identity Pools - AWS Resource Access via IAM Assumed Roles

AWS Amplify - Authentication Mechanism

Technical Terms

Identity Provider (IdP)

JSON Web Token (JWT)

ID Tokens

Example ID Token Payload

Access Tokens

Example Access Token

Sample CDK Code

Breaking Down The CDK Constructs

Create User Pool

Create User Pool Client

Create User Pool Groups

Create Identity Pool

Create IAM Roles

Identity Pool Role Attachments & Mappings

Disparate App Client API Method Access

Adding a Resource Server

AWS Cloud Development Kit (CDK) - Understanding the Node/Tree Relationship

Diagram

AWS Cloud Development Kit Tree/Node Diagram (draw.io viewer)

Details

PCI Compliance in AWS - Simplified (featured in ISC2 Blog)

PCI Compliance in AWS - Simplified

Infrastructure Services

Kubernetes on EC2

AWS Fargate Considerations

Abstracted Services

Network and Encryption Level Abstracted Services

Connected-to and Security-Impacting Gotchas