Forem: James Miller

Multiplayer WebXR Readyplayer.me Avatars — Part 1

James Miller — Thu, 10 Aug 2023 17:03:32 +0000

Multiplayer WebXR Readyplayer.me Avatars — Part 1

Overview of technical concepts for multiplayer WebXR readyplayer.me avatars

Intro

Real-time multiplayer WebXR experiences is an area I am very excited about.

I don’t think its an area that has been fully utilised or explored to its potential.

In my previous series of posts about this topic, I talked through the concepts, practicalities of real time user interactions and steps to enabling 3d object interactions.

In this series of blog posts, I’m going to expand on the enhancement of user interactions through the use of free-to-use readyplayer.me avatars.

This first blog post will focus on the concepts, the following blog posts will explain more about the practical steps.

GIF of avatar enhanced interactions

Overview

In this section, I’ll explain the core principles of how to build a real-time multiplayer WebXR experience that uses readyplayer.me avatars!

The Concept

This example works by creating a web application that renders on different devices (e.g an Oculus Quest Pro or a Macbook Pro), then getting those users to log into the website from those devices.

When those users log in they then have the option to create an avatar using Ready Player Me, which will return a 3D model that is stored in the cloud — along with the positional data which is all shared between users.

As a very broad overview:

A user visits the website on their device and logs in using their credentials, the site will render as appropriate for their device (thanks to the WebXR API)
Users can choose to select a model using Ready Player Me, which is then stored in the cloud.
This 3d model is then visualised on their screen, as well as other users avatars — which is enabled by the cloud connecting these devices together.

The Tech Stack

As this was originally written for Wrapper.js, it adheres to the use of Terraform, Serverless Framework and Next.js.

The below diagram details this further.

I use Terraform to create all cloud resources except for Lambda functions, which are created and managed by Serverless Framework.

All environment variables required to interact with Amazon Cognito are passed to the React.js Front End created using Next.js.

The Front End also requests the 3D model from Ready Player Me, which is then rendered along with the rest of the 3D environment with React Three Fiber and Three.js.

The App Flow

If you were to map out when these technologies get used within this example, it would look something like the below diagram.

If you start at the bottom of the diagram, you can see that all the Front End files are exported statically and hosted on the S3 Bucket.

These files are then distributed with the Cloudfront CDN , assigned with an SSL certificate by AWS Certificate Manager and are provided with a custom domain name with Amazon Route 53.

At this point, Step 1 begins:

The user opens the website on their device (e.g the Oculus Quest Pro) by visiting the domain name
At this point React-Three-XR renders the website based on the device’s capability (in this case a mixed reality headset)

Next up is Step 2:

The user logs into their AWS Cognito account, with the use of the AWS Amplify library on the Front End
Having logged in, the website now has a unique identifier for the person that is using that device

Once the user has successfully logged in and uniquely identified themselves, this sets them up nicely for Step 3:

The user has the option to open a model, that allows them to configure and create a 3D model
If the user then selects this model at the end of the configuration process, a URL is returned back to the Front End that contains the .GLB files to render the avatar

Its at this point that Step 4 begins:

If an Avatar was selected, this is saved to DynamoDB, other users can then pull this avatar into their environments to be rendered.
The user then emits their x/y/z co-ordinates in real-time to the websocket API gateway which then stores these in DynamoDB, other users can then see these positions and update their Front Ends in real time

Conclusion

This has been a long blog post, I hope it has been helpful in showing you how real-time multiplayer WebXR experiences that use readyplayer.me avatars work!

In the next post, I will details the practical sides of the actual code that enables all of this.

In the meantime, hope you enjoyed this post and have fun :D

Multiplayer Metaverse Creation on Ethereum

James Miller — Sun, 02 Jul 2023 12:13:59 +0000

How to create a serverless Metaverse with Solidity, Lambda, API Gateway, React Three Fiber, DynamoDB and Metamask.

Intro

The word Metaverse has been thrown around a lot and it can be quite confusing to actually understand what it means.

I’ve previously created a post that explains what the term ‘metaverse’ means, in this blog post I want to talk through the steps on how to build a Metaverse — like this one

This demo is a combination of the WebXR and Web3 log-in codebases I’ve previously created.

If you want to follow along with this, it is my strong recommendation that you read through the WebXR and Web3 log-in blog posts I’ve created, as a lot of the content in this post is built on top of them.

If you want to skip all this and try out getting started with building a metaverse using a template I’ve created, you can have a play with that here!

LETS JUMP IN :D

The theory behind building a Metaverse

In this section I’ll explain the theory behind how building a Metaverse can work, by talking through the concept, tech stack and app flow!

Concept

The demo I’ve created essentially works as follows:

The users who want to use the Metaverse log in to the web page using their Metamask wallets (see this blog post for details on how that works)
Once logged in, those users can interact with other users through the use of websockets (see this blog post for further details)
Those users can then interact with smart contracts on the Ethereum blockchain via the use of their Metamask wallets

The Tech Stack

I’ve summarised the technologies used to create the Metaverse demo as:

Infrastructure

I use Terraform to create all cloud resources on AWS excluding Lambda functions that run business logic.

Back End

Serverless Framework is used to create Node.JS lambda functions, which interact with the Ethereum network via Web3.js and with the AWS resources that generate credentials for authenticated users. The Back End also implements Websockets using API Gateway.

Blockchain

I’ve used Ethereum related technologies such as Solidity and Hardhat for the smart contract creation / deployment, Web3.js is a core technology in the stack that lets the Back End and Front End interact with Smart Contracts.

Front End

Next.js a React.js framework that contains the logic for the Three.js library that generates the 3D environment in WebGL.

The App Flow

This app flow is a mix between the Web3 Auth and the WebXR multiplayer blog posts that I’ve previously created.

As a summary for the Web3 Auth flow:

A user signs a signature with their metamask wallet and submits this to AWS via the API Gateway
A lambda function then processes the signature to verify if this has been signed by a valid user, if so it will then generate AWS STS credentials for the user to log in with
Once logged in, the user can then interact with smart contracts and other users on the DApp

As a summary for what happens in the DApp:

A user opens a websocket connection using the AWS credentials that they’ve been provided with from the Auth process
This websocket broadcasts the users position in 3d space, as well as receives other users positions in that 3d space and visualises them on the users screen
The users can then move around the environment and interact with smart contracts together in real time

Conclusion

I hope this post has been useful in summarising how to go about developing a Metaverse.

As this post is a cross between Web3 Auth and WebXR multiplayer experiences (both of which I have created long tutorials posts about previously), I’ve deliberately kept this one shorter.

For the full code base and instructions on how to set up, please see this template I’ve made for Wrapper.js!

Have fun :D

How to set up Auth with Metamask using Amazon Cognito (part 2)

James Miller — Fri, 23 Jun 2023 13:58:27 +0000

Code samples that demonstrate how to set up Amazon Cognito Auth with Metamask in a DApp.

Intro

In my previous blog post, I talked through the theory of how to implement web3 log in to a DApp using MetaMask and AWS, the below gif demonstrates the end result.

In this post I’ll talk through some code samples that enable this Auth process, step-by-step!

Important note

The below code samples are experiments I make in my spare time and are not recommendations of how to implement a production web app. If you choose to use these examples in your code base, be sure to test thoroughly and audit as appropriate.

Code samples that enable Web3 Auth with MetaMask and AWS

I’ll be referring to this diagram that I created in my previous blog post, in order to understand the below code samples its important you read it before continuing with the rest of this blog post.

In this section I’ll show the code behind each of the numbered items in the above diagram.

Here is the full repo, use this url if you want to get a version of it running.

Generating Credentials with the Metamask Wallet

1. Get account address

The first step is to retrieve the users public address for their account.

A wallet has a number of addresses returned in an array, the active account is the first item in the array, so we return this as the address to log in with.

const accounts = await window.ethereum.request({
    method: "eth_requestAccounts",
});

const address = accounts[0];

2. Get / create nonce

Once the users account address has been retrieved, we then need to get a nonce (random string of characters) that we can then use for the user to sign and prove they are the owner of the account that created the signature.

To do this, we pass the address into a function on the Front End, that then passes POST’s this address to the Back End.

Once the Back End receives this address, check if a nonce already exists (if it doesn’t it will generate one), then return that nonce back to the Front End.

Front End

const { nonce } = await getUserNonce(address);

const getUserNonce = async (address) =>
  await axios({
    method: "post",
    url: `${httpApiURL}/signup/nonce`,
    data: {
      address: address,
    },
    headers: {
      "Content-Type": "application/json",
    },
  }).then(
    (res) => {
      const data = JSON.parse(res.data.body);
      return data;
    },
    (error) => {
      console.log(error);
    }
);

Back End

"use strict";
const AWS = require("aws-sdk");
const dynamoDb = new AWS.DynamoDB.DocumentClient();
const crypto = require("crypto");

const { nonce_table_id } = process.env;

module.exports.handler = async (event, context, callback) => {
  const response = {
    statusCode: 200,
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Credentials": true,
    },
    body: JSON.stringify(await data(event.body.address)),
  };
  callback(null, response);
};

const data = async (address) => {
  const nonce = crypto.randomBytes(16).toString("hex");
  const putParams = {
    Item: {
      address: address,
      nonce: nonce,
    },
    TableName: nonce_table_id,
  };

  if (!await getData(address)) {
    await dynamoDb.put(putParams).promise();
  }
  return await getData(address);
};

const getData = async (address) => {
  const getParams = {
    TableName: nonce_table_id,
  };
  const users = await dynamoDb.scan(getParams).promise();
  let chosenUser;
  for (let x = 0; x < users.Items.length; x++) {
    if (users.Items[x].address == address) {
      chosenUser = users.Items[x];
    }
  }
  return chosenUser;
};

3. Sign message with nonce & private key

Back on the Front End, we call a function called web3.eth.person.sign() — and pass the nonce and the users address into it, this will trigger a Metamask pop up to appear with these parameters encrypted.

const signature = await web3.eth.personal.sign(
    web3.utils.sha3(`Welcome message, nonce: ${nonce}`),
    address
);

This Metamask pop up (see below) will have a ‘Sign’ button, which when clicked will cryptographically generate a signature using your private key and the props that you passed into the web3.eth.personal.sign function.

Please note, the private key itself is not actually seen at any point during this process and is not visible in the codebase. In clicking the ‘Sign’ button, you are allowing Metamask to confirm that you own the private key that is associated with the public address you’re signing, this enables the creation of a cryptographically valid signature.

4. Log in with signature & public address

Now you have a valid signature, you pass this to the Back End, along with the nonce and your public address via a POST method.

const {
    AccessKeyId, SecretKey, SessionToken, Expiration
} = await login(nonce, signature, address);

const login = (nonce, signature, address) =>
  axios({
    method: "post",
    url: `${httpApiURL}/signup/login`,
    data: {
      nonce: nonce,
      signature: signature,
      address: address,
    },
    headers: {
      "Content-Type": "application/json",
    },
  }).then(
    (res) => {
      const data = JSON.parse(res.data.body);
      return data;
    },
    (error) => {
      console.log(error);
    }
  );

5. Validate signature

Once the Back End receives your signature, nonce and address — it can then start the process of validating the signature.

You do this by manually generating a cryptographic hash that contains your nonce, then passing that into the web3.eth.accounts.recover function along with the signature you generated in the previous step, all going well this will then return the public address of the account that signed the transaction.

If this returned address matches the address that you sent from the Front End to the Back End, then we can consider the public address of the account that was received by the Back End to be sent with a valid signature and it can now have AWS credentials generated for it.

const sigValidated = await validateSig(nonce, signature, address);

const validateSig = async (nonce, signature, address) => {
    const message = `Welcome message, nonce: ${nonce}`;
    const hash = web3.utils.sha3(message);
    const signing_address = await web3.eth.accounts.recover(hash, signature);
    return signing_address.toLowerCase() === address.toLowerCase();
};

Before we go any further, since we have validated a user with this nonce — it has served its purpose and we will now generate a new nonce in the database for that user.

await updateNonce(address, nonce);

const updateNonce = async (address, oldNonce) => {
    const nonce = crypto.randomBytes(16).toString("hex");

    const putParams = {
      Item: {
        address: address,
        nonce: nonce,
      },
      TableName: process.env.nonce_table_id,
    };

    const setData = () => dynamoDb.put(putParams).promise();
    await module.exports.deleteData(address, oldNonce);
    return await setData();
};

6. Generate / retrieve Cognito Identity

Since we have validated a genuine user, we now want to generate access credentials for that user.

We do this by retrieving that public address’s Amazon Cognito Identity, if one does not exist then we will generate one for them.

const { IdentityId: identityId, Token: token } = await getIdToken(address);

const getIdToken = (address) => {
    const param = {
      IdentityPoolId: process.env.cognito_identity_pool_id,
      Logins: {},
    };
    param.Logins[process.env.domain_name] = address;
    return cognitoidentity.getOpenIdTokenForDeveloperIdentity(param).promise();
};

7. Generate Cognito Identity credentials

Using that Amazon Cognito Identity, we will now using AWS Security Token Service (STS) to generate a temporary set of Identity Access Management (IAM) credentials and then return these to the Front End.

Important to note, is you must ensure that the permissions of these temporarily generated credentials are limited in scope to your usecase.

const { Credentials: credentials } = await getCredentials(
      identityId,
      token
);

const getCredentials = (identityId, cognitoOpenIdToken) => {
    const params = {
      IdentityId: identityId,
      Logins: {},
    };
    params.Logins["cognito-identity.amazonaws.com"] = cognitoOpenIdToken;
    return cognitoidentity.getCredentialsForIdentity(params).promise();
}

Using those credentials for Front End and Back End Auth

Now that we’ve generated credentials for a valid user and returned them to the Front End — we can now grant that user access to our DApp and to our Back End.

Front End

Once the Front End receives the credentials from the login process, it will then store these credentials in local storage and generate an AWS Client.

This AWS Client is then used to make a request to the Back End, with a signed url that is generated with the temporary AWS IAM credentials.

All going well, the result of this API call is logged in the browsers’ console.

const {
    AccessKeyId, SecretKey, SessionToken, Expiration
} = await login(nonce, signature, address);

if (AccessKeyId && SecretKey && SessionToken && Expiration) {
    const authenticatedUser = authenticateUser(
      address,
      AccessKeyId,
      SecretKey,
      SessionToken,
      Expiration
    );
    const request = await authenticatedUser.sign(`${httpApiURL}/signup/testData`, {
        method: "GET",
    });
    const response = await fetch(request);
    console.log(await response.json());
}

const authenticateUser = (
  address,
  accessKeyId,
  secretAccessKey,
  sessionToken,
  expiration
) => {
  localStorage.setItem("address", JSON.stringify(address));
  localStorage.setItem("sessionToken", JSON.stringify(sessionToken));
  localStorage.setItem("accessKeyId", JSON.stringify(accessKeyId));
  localStorage.setItem("secretAccessKey", JSON.stringify(secretAccessKey));
  localStorage.setItem("expiration", JSON.stringify(expiration));

  return new AwsClient({
    accessKeyId,
    secretAccessKey,
    sessionToken,
    region: process.env.region,
    service: "execute-api",
  });
};

Back End

From a Back End perspective, I will demonstrate how this works with Lambda functions in Serverless Framework.

The yaml file that is used to configure the lambda function is set to be an http endpoint, expecting IAM credentials as an authorizer.

The lambda function itself just returns a simple string (assuming the credentials used in generating the signed url are correct).

// lambda.yml

testData:
  handler: testData/index.handler
events:
  - http:
      path: signup/testData
      method: get
      authorizer: aws_iam
      cors: true

// index.js

"use strict";

const headers = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Credentials": true,
};
module.exports.handler = async (event) => {
  return {
    headers,
    statusCode: 200,
    body: JSON.stringify(
      "Hello!! This is test data that you are pulling from the Back End, based on your authenticated wallet!"
    ),
  };
};

Conclusion

SO!! Those are the practical steps to enabling Web3 Auth using Metamask and AWS!

There was a lot in there, I hope it all made sense and was helpful!!

If you want to have a play with a template that has all of this working ‘out-of-the-box’, here is a link for you to explore.

In the meantime, have fun :D

How to set up Auth with Metamask using Amazon Cognito (part 1)

James Miller — Tue, 20 Jun 2023 20:11:34 +0000

Implement Auth in your DApp using Web3.js, Metamask, Amazon Cognito and serverless technologies!!

In this series of posts, I’ll explain how to set up Amazon Cognito with the rest of your Serverless infrastructure to Auth users using their Metamask wallet from within your Decentralised Application (DApp)!

This first post will be more about the concepts of how everything works, as always I’ll do my best to simplify and make everything easy to understand :)

The following posts in the series will then show code samples to demonstrate practically how to build these concepts.

This post builds on my previous series on what Auth with Amazon Cognito is and how to implement it, I won’t be re-explaining those points in this post so feel free to read that before jumping into this ( trust me it will help!! ) :D

What is Metamask?

Metamask is a crypto wallet that is used to interact with DApps and send or receive money, through the use of a browser extension / mobile app.

I may do a further explanation of what a crypto wallet is in a future post, for now the core details you need to understand in order to follow along with the concepts in this post — are that once you’ve set up a Metamask wallet (e.g in your desktop web browser) you will then be able to create accounts.

When an account is created, ‘keys’ are also generated:

A public key is an address that identifies you and allows

people to send you money and allows them to also identify payments sent from you
your transactions to be searchable on public blockchains like Ethereum via their block explorer
you to be identified on dApps & interact with their smart contracts

A private key is kind of like a password for that account which must be kept secret, this can be used to

restore (or import) that account into a wallet
approve transactions / interactions with DApps through the process of ‘signing’

Demo

In practice, the process of logging into and interacting with Smart Contracts on a DApp from a user’s perspective is:

User enters the password in order to open the Metamask Browser Extension
User signs a cryptographically generated message, which interacts with the Ethereum Blockchain and Amazon Cognito to authenticate and authorise your access to the dApp
Once access is granted, you can then interact with the Smart Contracts on the DApp by signing further transactions!

If you want to try this out, feel free to check out this Wrapper.js template!

Oversimplified explanation

Oversimplifying the Auth process:

You login to Metamask and sign a transaction that generates a cryptographic message that could only be generated if you have access to the account, this is visualised as the green key on the left.
This cryptographic message is sent to an API, which goes through a bunch of Auth processes — if successful then Amazon Cognito will generate a special token that grants access to the rest of the infrastructure — this token is visualised as the orange key.

The theory of Amazon Cognito Auth with Ethereum

Implementing Auth with Ethereum and Amazon Cognito within a DApp can be done in different ways, here is how I personally tend to go about it.

Tech stack to implement Auth with Cognito and Ethereum

I use Terraform to create all cloud resources except for Lambda functions, which are created and managed by Serverless Framework.

I use Solidity for smart contract development, Hardhat for helper functions that speed up localhost development + deployment, Web3.js for interacting with the Ethereum Network and with Metamask.

All environment variables required to interact with Amazon Cognito and Metamask / Ethereum are passed to the React.js Front End created using Next.js.

App flow for Cognito Auth with Ethereum

Here is how it looks in an app flow format:

The user starts by visiting the DApp (a website) and clicking on the log in button to allow the DApp to request the users’s account address as a public key from Meta Mask.
The DApp will then send this public key to the API and check if a nonce (randomly generated cryptographic string) exists for this key, it will generate a nonce if not — then return this nonce back to the DApp.
The user signs a message that contains the nonce and a signature is created
The Dapp sends this signature and public address to the API
The API runs logic to validate that the nonce that is provided in the signature is the same that is in the database, it also checks that the provided address is the same as the address that created the signature
Assuming this validation is successful, this will retrieve that public address’s Cognito Identity — if one does not exist then one will be created
Temporary AWS credentials will then be generated for that Cognito Identity and returned to the DApp
Using these Credentials, the user can then access the Front End and retrieve data from the Back End (using the AWS Credentials for Auth in retrieving appropriate data), the user can also interact with the Smart Contracts!

Conclusion

There was a lot of information squeezed into this post, I hope it helped to show how Auth can be done with Amazon Cognito and Ethereum!

There were a few sites that I found online that helped me understand these concepts, the most useful one I’d like to to note these here Yi Ai’s post on Hackernoon

If you want an ‘out-of-the-box’ implementation of Cognito Ethereum Auth, I have created a template in wrapperjs that you can download and use :D

Hope this is all helpful, have fun!

How to add Amazon Cognito Auth to a Web App (part 4)

James Miller — Sun, 23 Apr 2023 10:24:49 +0000

Looking at the NodeJS logic that is run in lambda functions to power the Back End of Amazon Cognito Authentication.

Intro

In my last post, I explained how Amazon Cognito is integrated into the Front End, to allow content to become visible to users that have gone through the Auth process as shown in the below demo 👇

In this post, I’ll explain how this same process can be implemented in the Back End.

If you look at the right side of the above gif, you will see an open console log. Please note the ‘Hello World!! :D‘ message that appears in the logs once the user has successfully signed in.

This message is returned to users, that have logged into the Front End and then gone through the Auth process on the Back End.

Implementing Cognito Auth on the Back End

I have a Wrapper.js template that you can use to spin up an implementation of Cognito, here are some highlight files from that template:

serverless/serverless.common.yml

service: ${file(./../../../serverless.env.json):service_name}-${file(./../../../serverless.env.json):stage}

provider:
  environment: ${file(./../../../serverless.env.json)}
  name: aws
  region: ${file(./../../../serverless.env.json):region}
  runtime: nodejs12.x
  stage: ${file(./../../../serverless.env.json):stage}
  apiGateway: # Optional API Gateway global config
    restApiId: ${file(./../../../serverless.env.json):api_gateway_rest_api_id} # REST API resource ID. Default is generated by the framework
    restApiRootResourceId: ${file(./../../../serverless.env.json):api_gateway_root_resource_id} # Root resource ID, represent as / path
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - dynamodb:Query
            - dynamodb:Scan
            - dynamodb:GetItem
            - dynamodb:PutItem
            - dynamodb:UpdateItem
            - dynamodb:DeleteItem
          Resource: "*"
        - Effect: Allow
          Action:
            - "execute-api:ManageConnections"
          Resource:
            - "arn:aws:execute-api:*:*:**/@connections/*"

custom:
  apiAuthorizer:
    id : ${file(./../../../serverless.env.json):cognito_authorizer}
  serverless-offline:
    host: '0.0.0.0'

Serverless Framework in WrapperJS is organised into HTTP and Websocket services, each service has its own yaml configuration.

Variables that are exported from Terraform (the cognito details) are passed to the above file, which the individual services can then reference.

These variables are:

restApiId : the ID of the API Gateway that Serverless Framework should deploy lambda end points to
restApiIdRootResourceId : the root path of that API Gateway, that all lambda endpoints will be added to
apiAuthorizer : an API Authorizer that was created by Terraform from the ARN of the Cognito User Pool

serverless/services/http/users/serverless.yml

service: ${file(./../../../serverless.common.yml):service}-${self:custom.service}
useDotenv: true

provider: ${self:custom.common.provider}

functions:
  - ${file(userData/lambda.yml)}

plugins:
  - serverless-offline

custom:
  service: users-service
  common: ${file(./../../../serverless.common.yml)}
  apiAuthorizer: ${self:custom.common.custom.apiAuthorizer.id}
  serverless-offline: ${self:custom.common.custom.serverless-offline}

In lines 4 and 15 of the Users service’s yaml (our demo service), you can see the configurations declared in the previous file being set in this service.

serverless/services/http/users/userData/lambda.yml

getUserData:
handler: userData/index.handler
events:
  - http:
      path: users/data
      method: get
      integration: lambda
      authorizer:
        type: COGNITO_USER_POOLS
        authorizerId: ${self:custom.apiAuthorizer}
      cors:
        origin: '*'
        headers: # <-- Specify allowed headers
          - Content-Type
          - Authorization

The configuration for the users/data endpoint (our test endpoint) is configured to return data if the Front End provides the authorizer that has been defined in lines 8–10.

serverless/services/http/users/userData/index.js

'use strict';

module.exports.handler = async(event, context, callback) => {
  const response = {
    statusCode: 200,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Credentials': true
    },
    body: 'Hello World!! :D'
  };
  callback(null, response);
};

Finally, this is the lambda that is executed when the end point has been called and the appropriate authorisation is provided.

The function returns a body of ‘Hello World!! :D‘.

Conclusion

So that is it, the end of the 4 part tutorial series!!!!

I hope this has been helpful for you in understanding how to use Amazon Cognito on the Back End for Lambda functions in Serverless Framework.

Feel free to use the template I created for Wrapper.js to spin this up and give it a go!!

In the meantime, go build cool stuff and have fun :D

How to add Amazon Cognito Auth to a Web App (part 3)

James Miller — Sat, 25 Mar 2023 17:13:30 +0000

Understanding the Next.JS code samples that creates the User Interface for an Amazon Cognito Authenticated Web App.

Intro

In my last post, I explained how Terraform was being used to create the cloud infrastructure that enables Amazon Cognito to be implemented in the below demo 👇

In this post, I will explain how to integrate Amazon Cognito into the Front End of a Web App, so you can see it as visualised above.

Implementing Cognito Auth on the Front End

I have a Wrapper.js template that you can use to spin up an implementation of Cognito, here are some highlight files from that template:

In this example, I’ll show you a Next.js React App, that uses the Amazon Amplify library to authenticate the Front End with Amazon Cognito.

I recommend reading the first post in this series before continuing, so you understand the concept of what is being implemented!

components/Cognito/utils.js

Let’s start by showing how the variables that were exported from Terraform integrate into the Front End.

import Amplify, { Auth } from 'aws-amplify';

export function setupAmplify() {
    Amplify.configure({
        Auth: {
            // REQUIRED only for Federated Authentication - Amazon Cognito Identity Pool ID
            identityPoolId: process.env.cognito_identity_pool_id,
            // REQUIRED - Amazon Cognito Region
            region: process.env.region,
            // OPTIONAL - Amazon Cognito User Pool ID
            userPoolId: process.env.cognito_user_pool_id,
            userPoolWebClientId: process.env.cognito_user_pool_client_id
        }
    });
}

You can see the following variables being set up in the AWS Amplify library:

identityPoolId : the ID for the identity pool that is used to authorise access to other AWS services
region : the region for the Amazon Cognito resource
userPoolId : the ID for the user pool where that allows users to create credentials that can be authenticated
userPoolWebClientId : the ID that is assigned from Cognito to our app, to allow it to access the User Pool

pages/_app.js

At the core of the application is _app.js, which executes logic each time a page is loaded.

import { createGlobalStyle } from 'styled-components'
import Cognito from '../components/Cognito'
import { Authenticator } from '@aws-amplify/ui-react';

const GlobalStyle = createGlobalStyle`
    html {
        overflow: hidden;
    }
    *, *:before, *:after {
        box-sizing: inherit;
    }
    body{
        margin: 0;
    }
    :root {
        --amplify-primary-color:lightblue;
        --amplify-primary-tint: #0A3369;
        --amplify-primary-shade:#0A3369;
        --amplify-secondary-color:#0A3369;
        --amplify-secondary-tint:#D00C1B;
        --amplify-secondary-shade:#1F2A37;
        --amplify-tertiary-color:#5d8aff;
        --amplify-tertiary-tint:#7da1ff;
        --amplify-tertiary-shade:#537BE5;
        --amplify-grey:#828282;
        --amplify-light-grey:#c4c4c4;
        --amplify-white:#ffffff;
        --amplify-red:#dd3f5b;
        --amplify-primary-contrast: var(--amplify-white);
        --amplify-secondary-contrast:var(--amplify-white);
        --amplify-tertiary-contrast:var(--amplify-red);
        --amplify-font-family:'Helvetica Neue Light', 'Helvetica Neue', 'Helvetica', 'Arial', 'sans-serif';
        --amplify-text-xxs:0.75rem;
        --amplify-text-xs:0.81rem;
        --amplify-text-sm:0.875rem;
        --amplify-text-md:1rem;
        --amplify-text-lg:1.5rem;
        --amplify-text-xl:2rem;
        --amplify-text-xxl:2.5rem;
      }

    amplify-authenticator {
        justify-content:center;
        align-items: center;
        display: inline-block;
        height: auto;
        --width:400px;
        border: 0px solid;
        color: #0A3369;
        font-size:var(--amplify-text-md);
        --box-shadow:none;
        --container-height:400px;
        --padding:20px;
      }
`

export default function App({ Component, pageProps }) {
    return (
        <Authenticator.Provider>
            <Cognito>
                <GlobalStyle />
                <Component {...pageProps} />
            </Cognito>
        </Authenticator.Provider>
    )
  }

In this case, our app checks if a user is authenticated with Cognito (the App function) and renders content based on that users level of authorisation.

components/Cognito/index.js

This component contains the core Amazon Cognito logic.

import { Auth } from 'aws-amplify';
import { Authenticator, useAuthenticator } from '@aws-amplify/ui-react';
import '@aws-amplify/ui-react/styles.css';
import React, { useEffect } from 'react';
import cognitoStore from './../../stores/cognito';
import userStore from './../../stores/user';
import styled from 'styled-components';
import { setupAmplify } from './utils.js';
import { httpApiURL } from '../../utils';
import axios from 'axios';

setupAmplify();

const getUserData = (cognito) => axios({
    method: 'post',
    url: `${httpApiURL}/users/data`,
    data: {
      cognito: cognito
    },
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${cognito.jwt}`
    }
}).then((res) => {
    const data = JSON.parse(res.data.body);
    return data;
}, (error) => {
    throw new Error(error);
})

const Cognito = (props) => {
    const { children } = props;
    const { cognito, setCognito, signInState, setSignInState } = cognitoStore();
    const { setUser } = userStore();
    const { user } = useAuthenticator((context) => [context.user]);

    useEffect(() => {
        const fetchData = async() => {
            // Update the document title using the browser API
            if(cognito != '' && cognito != undefined) {
                try{
                    setUser(await getUserData(cognito));
                } catch (e) {
                    console.log(e);
                }
            }

            if(user != undefined && cognito == '' && user.signInUserSession) {
                const {accessToken, idToken} = user.signInUserSession;
                const role = accessToken.payload['cognito:groups'];
                const token = {
                    jwt: idToken.jwtToken,
                    role: (role) ? role[0] : '',
                    username: accessToken.payload.username
                }
                setCognito(token);
            }
        }

        try {
            fetchData();
        }
        catch (e) {
            console.error(e);
        }
        // eslint-disable-next-line react-hooks/exhaustive-deps
    }, [user])

    useEffect(() => {
        const checkState = async() => {
            if(signInState == 'signOut') {
                await Auth.signOut();
                setCognito('');
                setSignInState('signedOut');
            }
        }
        checkState();
        // eslint-disable-next-line react-hooks/exhaustive-deps
    }, [signInState]);
    return (
        <>
            {cognito == '' ?
                <AmplifyWrapper>
                    <Authenticator
                        headerText="Enter your details below"
                        submitButtonText="Sign in"
                        usernameAlias="email"
                        hideSignUp
                    >
                    </Authenticator>
                </AmplifyWrapper>

            :
                <ContentWrapper>
                    {children}
                </ContentWrapper>
            }
        </>
    )
}

const AmplifyWrapper = styled('div')`
    position: absolute;
    top: 50%;
    left: 50%;
    -ms-transform: translate(-50%, -50%);
    transform: translate(-50%, -50%);
`
const ContentWrapper = styled('div')`
    position: relative;
    z-index: 1;
    width: 100vw;
    height: 100vh;
`

export default Cogn

Diving into the logic of how this Cognito component works:

The first useEffect life cycle method demonstrates the logic that attempts to make a request to authenticate with Cognito and get the JWT as a response.
The returned elements demonstrates the logic that renders a log in page if the user is not authenticated and renders the children content if the user is authenticated

The idea being, if a user is not authenticated, they enter their details into the log in form, this will trigger the an attempt to authenticate with Cognito and then to show content upon success.

pages/index.js

Finally, we have a component that renders the web page (assuming that the user has passed Cognito Auth).

import Head from 'next/head'
import React, { useEffect } from 'react'
import styled from 'styled-components'
import axios from 'axios'

import { httpApiURL } from './../utils'
import Header from '../components/Header'
import cognitoStore from '../stores/cognito'

export default function Home() {
  const { cognito } = cognitoStore();

  useEffect(() => {
    const getData = async(cognito) => await axios({
      method: 'get',
      url: `${httpApiURL}/users/data`,
      data: {
        cognito: cognito
      },
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${cognito.jwt}`
      }
    }).then((res) => {
      console.log(res.data.body)
    }, (error) => {
      console.log(error);
    })

    getData(cognito);

    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);

  return (
    <>
      <Head>
        <title>Wrapper.js Authentication Example</title>
      </Head>
      <Header />

      <Img src='/wrapperjs.png' />
      <P>Authentication template</P>
    </>
  )
}

const Img = styled('img')`
  display: block;
  height: 60vh;
  width: auto;
  margin-left:auto;
  margin-right:auto;
  position: relative;
  // min-width: 500px;
`

const P = styled('p')`
  text-align: center;
  font-weight: bold;
`

Talking through this example of how the content that could be shown on the Front End works:

The useEffect method shows data being loaded from the Back End based on an API request that uses JWT authentication.
The returned elements show what the Front End should render if authentication has been successful.

Conclusion

I hope the above is helpful in showing you how to implement Amazon Cognito on the Front End using the Amplify library, to only show content to users that have gone through the Auth process!

In the next (and last) post in this series, I’ll talk through how to implement Amazon Cognito on the Back End to secure API data.

In the meantime, have fun 😀

How to add Amazon Cognito Auth to a Web App (part 2)

James Miller — Sun, 05 Feb 2023 12:58:24 +0000

Terraform code samples that demonstrate how to set up Amazon Cognito Auth in a Web App.

Intro

In the last blog post, I talked through the concepts of how Amazon Cognito works in a Web App.

In this post, I will explain how Amazon Cognito can be programmatically set up using Terraform — so you can build cool stuff like this 👇

Creating Amazon Cognito with Terraform

I have a Wrapper.js template that you can use to spin up an implementation of Cognito, here are some highlight files from that template:

I use Terraform as the tool to create the majority of the cloud infrastructure.

main.tf

This is the core file that creates all the terraform resources, I’ll go deeper into lines 7–12 and 42–52, which are used to create Cognito and the Secrets Manager that is used to pass the Cognito details to both the Back End and Front End.

module "nextjs_app_s3" {
    source = "./modules/s3"
    bucket = var.domain_name
    acl = "public-read"
}

module "acm" {
    source = "./modules/acm"
    root_domain_name = var.root_domain_name
    domain_name = var.domain_name
    region = "us-east-1"
}

module "nextjs_app_cloudfront" {
    source = "./modules/cloudfront"
    hosted_zone_name = var.root_domain_name
    domain_name = var.domain_name
    # lambda_edge_qualified_arn = module.uri_redirect_edge_lambda.qualified_arn
    acm_cert_arn = module.acm.cert_arn
    acm_cert_id = module.acm.cert_id
    s3_website_endpoint = module.nextjs_app_s3.website_endpoint
    default_root_object = "index.html"
}

module "rest_api_gateway" {
    source = "./modules/restApiGateway"
    certificate_arn = module.acm.cert_arn
    root_domain_name = var.root_domain_name
    domain_name = "api.${var.domain_name}"
    certificate_id = module.acm.cert_id
    stage_name = var.stage
    cognito_arn = module.cognito.user_pool_client_arn
}

module "cognito" {
    source = "./modules/cognito"
    domain_name = var.domain_name
    stage_name = var.stage
    service_name = var.service_name
}

module "secrets_manager" {
    source = "./modules/secretsManager"
    service_name = var.service_name
    cognito_identity_pool_id = module.cognito.identity_pool_id
    cognito_user_pool_id = module.cognito.user_pool_id
    cognito_user_pool_client_id = module.cognito.user_pool_client_id
    cognito_user_pool_client_arn = module.cognito.user_pool_client_arn
    cognito_authorizer = module.rest_api_gateway.cognito_authorizer
    api_gateway_rest_api_id = module.rest_api_gateway.rest_api_id
    api_gateway_root_resource_id = module.rest_api_gateway.root_resource_id
}

modules/cognito/main.tf

This is the file that creates the Amazon Cognito configuration.

Here you can see how the User Pool (lines 1–3) and Identity Pool (lines 11–20) are configured to allow authenticated users access to aws resources.

resource "aws_cognito_user_pool" "this" {
  name = "${var.service_name}-${var.stage_name}-pool"
}

resource "aws_cognito_user_pool_client" "this" {
  name = "${var.service_name}-${var.stage_name}-client"

  user_pool_id = aws_cognito_user_pool.this.id
}

resource "aws_cognito_identity_pool" "this" {
  identity_pool_name = "${var.service_name}_${var.stage_name}_identity_pool"
  allow_unauthenticated_identities = false

  cognito_identity_providers {
    client_id = aws_cognito_user_pool_client.this.id
    provider_name = "cognito-idp.eu-west-2.amazonaws.com/${aws_cognito_user_pool.this.id}"
    server_side_token_check = false
  }
}

resource "aws_iam_role" "authenticated" {
  name = "${var.service_name}-${var.stage_name}-cognito_authenticated"

  assume_role_policy = <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "cognito-identity.amazonaws.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "cognito-identity.amazonaws.com:aud": "${aws_cognito_identity_pool.this.id}"
        },
        "ForAnyValue:StringLike": {
          "cognito-identity.amazonaws.com:amr": "authenticated"
        }
      }
    }
  ]
}
EOF
}

resource "aws_iam_role_policy" "authenticated" {
  name = "${var.service_name}-${var.stage_name}-authenticated_policy"
  role = aws_iam_role.authenticated.id

  policy = <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "mobileanalytics:PutEvents",
        "cognito-sync:*",
        "cognito-identity:*"
      ],
      "Resource": [
        "*"
      ]
    }
  ]
}
EOF
}

resource "aws_cognito_identity_pool_roles_attachment" "this" {
  identity_pool_id = aws_cognito_identity_pool.this.id

  roles = {
    authenticated = aws_iam_role.authenticated.arn
  }
}

modules/cognito/outputs.tf

After creating your Amazon Cognito configuration, the outputs file allows you to export variables to be used in other parts of the Terraform configuration.

This outputs file generates 4 variables that will enable the Front End and Back End to interact with Amazon Cognito to generate and use JSON Web Tokens (JWT’s).

output "identity_pool_id" {
  value = aws_cognito_identity_pool.this.id
}

output "user_pool_id" {
  value = aws_cognito_user_pool.this.id
}

output "user_pool_client_id" {
  value = aws_cognito_user_pool_client.this.id
}

output "user_pool_client_arn" {
  value = aws_cognito_user_pool.this.arn
}

modules/restApiGateway/authorizer.tf

One of the important resources that will allow the Back End to leverage Cognito Auth is an API Gateway Authorizer.

Here you can see one the 4 variables, the user pool arn — that is used to create an authorizer for the REST API Gateway, that is configured to interact with the Cognito User Pool we just generated.

resource "aws_api_gateway_authorizer" "this" {
  name = var.domain_name
  rest_api_id = aws_api_gateway_rest_api.this.id
  type = "COGNITO_USER_POOLS"
  provider_arns = [var.cognito_arn]
}

modules/restApiGateway/outputs.tf

Once this API Gateway Authorizer is created, we then need to output some configuration variables so that it can be saved into an AWS Secret (next step) and retrieved by Serverless Framework for the Back End Auth.

output "root_resource_id" {
  value = aws_api_gateway_rest_api.this.root_resource_id
}

output "rest_api_id" {
  value = aws_api_gateway_rest_api.this.id
}

output "cognito_authorizer" {
  value = aws_api_gateway_authorizer.this.id
}

modules/secretsManager/main.tf

Lastly, we create an AWS Secret with all the exported outputs, so that the Front End and Back End have the configurations they need in order to interact with Amazon Cognito.

resource "aws_secretsmanager_secret" "this" {
  # Fill in the name you gave to your secret
  name = "${var.service_name}-tf"
  description = "Generated by Terraform for ${var.service_name}"

  recovery_window_in_days = 0
}

resource "aws_secretsmanager_secret_version" "this" {
  secret_id = aws_secretsmanager_secret.this.id
  secret_string = jsonencode(local.secrets)
}

locals {
  secrets = merge(
    var.secrets,
    {
      next_cognito_identity_pool_id = "${var.cognito_identity_pool_id}"
      next_sls_cognito_user_pool_id = "${var.cognito_user_pool_id}"
      next_sls_cognito_user_pool_client_id = "${var.cognito_user_pool_client_id}"
      sls_cognito_authorizer = "${var.cognito_authorizer}"
      sls_cognito_user_pool_client_arn = "${var.cognito_user_pool_client_arn}"
      sls_api_gateway_root_resource_id = "${var.api_gateway_root_resource_id}"
      sls_api_gateway_rest_api_id = "${var.api_gateway_rest_api_id}"
    },
  )
}

Conclusion

So this is how you use Terraform to create the Amazon Cognito resource and export its variables into a secret that can be used on the Front End and the Back End.

For the full codebase, check out this link and see this documentation for further details on the wrapper.js template!

In the next post, I’ll talk through how to use these secrets on the Front End!

Until then, I hope this has been helpful and have fun :D

How to add Amazon Cognito Auth to a Web App (part 1)

James Miller — Mon, 02 Jan 2023 22:03:44 +0000

Using Terraform, Serverless Framework and Next.JS to implement Auth in a Web App.

In this series of posts, I’ll explain how to set up Amazon Cognito in your app.

This first post will explain the conceptual aspects of what Amazon Cognito is, why it is useful and how it works.

I’ll try my best to simplify the concepts, to help make it quicker to digest :)

The next posts will in this series will be more practical, focussing on code samples etc.

What is Amazon Cognito?

Amazon Cognito is an AWS service that provides web apps with the ability to provide authentication and authorisation of users to content.

Authentication is the process of proving the users identity by assessing their credentials (e.g look at someones passport/id card photo, then looking at that persons face to see if they match)
Authorisation is the mechanism to understand what level of access that person should have (e.g the id card may permit that person into the ‘lobby’ but not into the ‘top secret vault’)

It also comes with a bunch of other useful features such as user management, out of the box sign-up / sign-in options and various third party integrations such as Facebook / Google etc.

Demo

In practice, this process looks something like the above GIF

User provides this email address, along with a password to the login to the web app ( authentication of their credentials)
User can see content based on what permissions are assigned to them ( authorisation of that user)

If you want to try this out, feel free to have a look at this Wrapper.js template!

Oversimplified explanation

In very oversimplified terms:

A user enters their log in credentials into the sign in form on the Front End, which is then assessed by Amazon Cognito (the green key shown above).
If the provided credentials correct, Amazon Cognito with authenticate that users identity and provide a JWT token as a response, allowing them access to view the Front End content based on the level of authorisation that is assigned to that user.
This same JWT token can then be used to authorise what data is allowed to be provided from the Back End to a user visiting the website on the Front End (the orange key shown above).

If a user provides invalid credentials when attempting to log in, then authentication fails and they are not authorised to view any content (the red key above).

The theory of Amazon Cognito Auth

Implementing Amazon Cognito within a web app can be done in different ways, here is how I tend to go about it.

Tech stack to implement Authentication with Cognito

I use Terraform to create all cloud resources except for Lambda functions, which are created and managed by Serverless Framework.

All environment variables required to interact with Amazon Cognito are passed to the React.js Front End created using Next.js.

From an app flow perspective, it works something as follows:

User opens the web app on their device (e.g macbook pro), the statically hosted S3 website is delivered through Cloudfront CDN.
When the user attempts to log in to their device, a Front End library called AWS Amplify is used to help make the authentication process quicker. If successful, Cognito will return a JWT token to the Front End.
This JWT token provides access to the Front End and is then used to make requests to the API Gateway which runs lambda functions that execute the Back End logic.

Conclusion

So that sums up the concept for how Amazon Cognito works and how I tend to go about implementing it.

If you want an ‘out-of-the-box’ implementation of it, I have a template created in wrapper.js that you can download and use :)

Hope this is all helpful, have fun!!

How to configure Github Actions

James Miller — Sun, 11 Dec 2022 14:03:07 +0000

A post about what Github Actions is, why it is useful, how to get it working on your project!

Intro

I’ve recently been playing with Github Actions and have been able to now integrate it with Wrapper.js.

This is super cool and opens up a load of exciting possibilities for speeding up deployment of apps by automating the wrapper script functions!

In this post, I’ll explain what Github Actions is and how it works, so you can then understand how it is implemented in Wrapper.js (so you can take what you like and implement it in your own projects) :D

What is Github Actions

Github Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your tests, build and deployment pipeline.

In simple terms, it allows developers to automate testing and deployment of their apps, by simply pushing updates to their code repositories :)

Why is Github Actions useful

I’ve now integrated Github Actions with Wrapper.js, it’s useful because if you want to deploy an app (e.g a WebXR template) like this 👇

You can automate this deployment and better yet, spin up multiple environments (dev / stage / prod etc), all by just pushing code to your git repository — like this 👇

From the developers perspective, they develop a feature and commit their work to a branch in their code base — the pipeline takes are of deploying it into an environment that can then be viewed on its own url!

How it works

In the below steps, I’ll show how it is all pieced together.

I’ll demonstrate this using a Wrapper.js template as an example, you can extract what you’d like from this into your own set up.

Set up the project and pipeline

The first step, is to set up the Wrapper.js template and the Github repo for accessing your AWS account.

Adding AWS and Secret details to Github

Create a Github repository for your project and then add your AWS credentials to the Repository Secrets.

You find this under ‘Settings’ > ‘Secrets’ > ‘Actions’, then click on the green ‘New repository secret’ button to add your AWS_REGION, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY details.

Please note, you get these details from your AWS IAM credentials — never share these with anyone or post them online.

Lastly, add the name of your wrapper.js secret in as a Repository Secret called WRAPPERJS_SECRET_NAME.

Set up Wrapper.js Project

Set up your project, by following the steps outlined on this instruction page, until you get to the end of step 3.

Doing this will mean you have chosen a wrapper.js template and have used the unwrap CLI command configured your own project settings (domain name etc) that you’d like your app to be deployed with.

Run the pipeline automations

Now you have the basic project and github repository set up, the next step is to trigger the deployment and watch the automations do their work!

Raise a PR and trigger the automations

In this example, I’ll explain this as if you raised a Pull Request (PR) to the github repository. Please note, this process also works with pushing to master and creating a ‘release’.

When a PR is raised, the pipeline is activated and several automations happen:

Github spins up a temporary virtual machine (VM) to run automations
All necessary libraries (e.g Wrapper.js) are installed onto that VM
During the setup processs, the AWS Credentials are configured
Wrapper.js uses this AWS access, to retrieve the secret you configured for your project
Wrapper.js then attempts to create a duplicate of this secret (if it doesn’t already exist), modifying the values for a PR environment

With all the above steps complete, the deployment process is ready to deploy your environment, using the newly duplicated Wrapper.js secret!

Retrieve secrets

Next, Github Actions runs the gobble secrets command to retrieve the duplicated secret and create a temporary .env file

Dynamically create Terraform resources

With this .env file (saved as terraform.tfvars.json), it then runs:

gobble tf init
gobble tf plan
gobble tf apply

This command essentially is initiating Terraform with the .env values, planning out what resources it is going to generate and then applies its plan to manage the selected cloud resources.

Retrieve secrets from Terraform resources

Once Terraform has finished running, the Github Actions pipeline then runs the gobble secrets command to retrieve the newly generated secrets file that Terraform has created.

This updates the locally generated .env file with new details from cloud resources like API Gateway and S3 etc, so the Front End and Back End can use them as part of their set up processes (coming up next).

Deploy Back End endpoints to the API

With the new details updated in the local .env file, the Github Actions pipeline then runs gobble sls deploy, which then deploys the lambda endpoints to the API Gateway.

Like with the previous terraform commands, these gobble commands inject the .env details (API Gateway variables) into the Serverless Framework config files, so that the lambda functions can be deployed to the correct API Gateway endpoints.

Deploy the statically hosted Front End

Lastly, Github Actions then runs gobble next export — which then creates a new static build of a Next.JS app and exports this to the S3 bucket whose details were originally generated from Terraform.

That is it, the pipeline has finished automating and the app is deployed! :D

Example pipeline config

I hope the above diagrams were useful from a visual perspective to understand what was going on.

Here is the yaml file, that turns those diagrams into actual useable Github Actions configuration :)

https://medium.com/media/351834c2ab277831e662f59c8975cb48/href

Conclusion

This has been a long blog post!

With any luck, you now understand what Github Actions is, why it is useful and how exciting it is that it can automate deployment of your app deployment!!

If you want to have a play, feel free to take a look at these Wrapper.js templates and have go :D

In the meantime, have fun making stuff!!

Easy win WIFI set up on Ubuntu

James Miller — Sat, 05 Nov 2022 16:10:07 +0000

Fast method to connect a hard wired device to a wireless network when WIFI adapters aren’t working.

I’ve owned a Linux computer for the past 2 years and have LOVED it!

There are however aspects of Ubuntu that are surprisingly difficult to get working.. like setting up a WIFI connection 🤯

In this post, I’ll explain how I managed to get my Ubuntu computer set up on a WIFI network.

Intro

Having tried various different WIFI adapters and installing multiple drivers, I haven’t been able to get any of them to actually work and have instead just relied on a wired Ethernet connection for internet access!!

If you’re reading this post, you’re probably the same as me — just wanting an ‘easy win’ way to get your computer connected to a wireless network!

I have found a super easy fix to help get my Linux computer access to WIFI that I wanted to share, so others struggling with this can make use of what I’ve found.

Quick Caveat: this is NOT my ideal solution and as with most technical problems there are multiple ways to fix it, but this method works — FAST .

Enough talk, lets get into it!!

WIFI to Ethernet Adaptor

I used the BrosTrend WiFi Bridge, that essentially converts the wireless connection into a wired one.

This means that you can use an Ethernet cable to connect your computer to the WiFi Bridge in order to receive the internet connection.

This is how it works:

You plug the Wireless Bridge into a wall socket and it creates a temporary wireless hot spot
Use your mobile device to connect to the wireless hot spot and follow the instructions to set it to the network you’re looking to connect a wired device to
The Wifi Bridge will now act as an extension of your chosen network, you can now use an Ethernet cable to connect your device to the wireless bridge to get an internet connection!!

Diagram showing how the Wireless Bridge can be used to connect a hard wired device to a wireless network (you can also connect the WiFi Bridge to a network switch if you have multiple hard wired devices to connect)

Conclusion

In this blog post, I’ve shown you an alternative and easy-win method for enabling your hard wired devices to get connected to a wireless network via the use of a WiFi Bridge.

I need to make an admission in my last closing comments of this post…

After making the effort to write a blog post about a work around for setting up WIFI on ubuntu, I embarrassingly was able to actually get it working.

Buy this BrosTrend wifi adapter, then follow the steps mentioned in their manual. It might require a bit of fiddling (a few restarts and updates etc), but it should work for you in the end.

If you go through all those steps and still are not able to get it working, then at least the content in this blog post will be useful for you 😉

In the meantime, hope this was helpful and have fun 😄

Wrapper.js: A New Devops Library

James Miller — Sun, 16 Oct 2022 16:49:16 +0000

Unwrapping the details on Wrapper.js: what it is, why I made it, how it works and where to find out more!

I’ve recently created documentation for my first open source project called Wrapper.js.

In this blog post, I’ll briefly explain what it is, why I made it, how it works and where you can learn more about how to use it.

What is Wrapper.js

Wrapper.js is an open source configurable wrapper script, that aims to speed up development and deployment of web experiences.

To start off with, it is released with a couple of ready made templates that let you spin up an out-of-the-box and fully configurable experience (see the WebXR template as an example).

In the future the hope is that, you can choose to configure your app with other libraries and easily spin up projects that use emerging technologies.

Why I made it

Over the years of working on Creative Technology projects, I’ve slowly grown to use certain technologies as part of a mono-repo setup, that are flexible enough to be adapted to most projects:

Next.js : an opinionated React.js frame work for Front End development, that comes with a variety of helper functions to help speed up development and build of your web app.
Serverless Framework : an Infrastructure as Code (IaC) framework that comes with CLI commands that help you develop lambda functions locally and then deploy them to an API Gateway
Terraform : an Infrastructure as Code (IaC) framework that uses Hashicorp Configuration Language (HCL) config files to create, manage and deploy cloud resources.

Over time I ended up informally creating a wrapper script to help orchestrate these technologies, so I could re-use this base template from a ‘full stack’ perspective and spend time focusing on project specific functionality.

I’ve found this wrapper script very useful in helping me deliver projects — so I thought I’d formalise it into an Open Source project — in case someone else other than me finds it helpful :)

How does it work

Full instructions can be found on this page, but here is an oversimplified summary in 3 steps.

1. Select a template

Once you’ve installed necessary libraries, choose a template you want to use, for example the WebXR template.

2. Configure the app

Use CLI commands to create an AWS Secret and S3 bucket for your template configuration.

Then use gobble CLI commands to use those secrets to deploy your customised template.

3. Dev and deploy

Continue using gobble CLI commands to develop your full stack app on your local machine — or integrate wrapper.js into your continous deployment pipeline to automate dynamic deployments for the different environments of your app!

Where to learn more

To find out more details about Wrapper.js, you can see the below links:

How to make real-time multiplayer WebXR experiences — part 3

James Miller — Wed, 07 Sep 2022 21:11:29 +0000

Intro

This is the third blog post detailing how to make real-time multiplayer WebXR experiences.

Having covered the conceptual sides of how it works and the practical sides of how to implement user position data, this blog post will clarify how to implement interactions with 3D models so users can interact with their environment in real time.

If you havent already, read the other two posts referenced above and have fun reading the below :D

Code Examples

In the previous blog post, I talk about the XRScene Higher Order Component (HOC) which is declared in the index directory.

Well start from there and expand on:

how to declare a 3D models
how to make those 3D models interactive
how to integrate the Websockets with the 3D models

Lets go :D

How to declare 3D models

In order to emit and retrieve a 3D models position data with Websockets, you need to first instantiate the Websockets (as explained in part 2 of this tutorial series) and then declare a 3D model component that is set up to leverage those Websockets.

Lets take a look at how Ive set them up, by first looking at the index.js file.

The index.js file

See lines 8 and 2024, which show where the 3D model is loaded.

You can see that we are passing a name, position and rotation property into this componentlets take a closer look at the Shiba.js component to understand how those are being used.

import Head from 'next/head'
import dynamic from 'next/dynamic';
import React, { useRef, useState, Suspense, lazy, useEffect } from 'react'

import Header from '../components/Header'

const XRScene = dynamic(() => import("../components/XRScene"), { ssr: false });
const Shiba = lazy(() => import("../components/3dAssets/Shiba.js"), {ssr: false});
const Slide = lazy(() => import("../components/3dAssets/Slide.js"), {ssr: false});
const Dome = lazy(() => import("../components/3dAssets/Dome.js"), {ssr: false});

export default function Home() {
  return (
    <>
      <Head>
        <title>Wrapper.js Web XR Example</title>
      </Head>
      <Header />
      <XRScene>
        <Shiba
          name={'shiba'}
          position={[1, -1.1, -3]}
          rotation={[0,1,0]}
        />
        <Dome
          name={'breakdown'}
          image={'space.jpg'}
          admin={true}
        />
        <Slide
          name={'smile'}
          image={'smile.jpeg'}
          position={[-2, 1, 0]}
          rotation={[0,-.5,0]}
          width={10}
          height={10}
        />
        <ambientLight intensity={10} />
        <spotLight position={[10, 10, 10]} angle={0.15} penumbra={1} />
        <pointLight position={[-10, -10, -10]} />
        <spotLight position={[10, 10, 10]} angle={15} penumbra={1} />
      </XRScene>
    </>
  )
}

The 3D model component (Shiba.js)

This component is responsible for rendering the GLTF 3D model, allowing it to be interactive with XR controllers and connecting it to Websockets.

To break this down further:

Rendering the GLTF model : between lines 1632 is the logic that is auto-generated by an opensource repository that converts GLTFs into React-Three-Fiber components
Enabling the use of XR interactivity for the model : on line 12 and 39 the Higher Order Component (HOC) withXrInteractivity.js is used to provide Shiba.js with XR interactivity.
Enabling the use of Websockets for the model: on lines 11 and 40 the HOC withCollaboration.js is used to provide Shiba.js with

/*
Auto-generated by: https://github.com/pmndrs/gltfjsx
author: zixisun02 (https://sketchfab.com/zixisun51)
license: CC-BY-4.0 (http://creativecommons.org/licenses/by/4.0/)
source: https://sketchfab.com/3d-models/shiba-faef9fe5ace445e7b2989d1c1ece361c
title: Shiba
*/

import React, { useRef, forwardRef, useEffect } from 'react'
import { useGLTF, useAnimations } from '@react-three/drei'
import withCollaboration from './withCollaboration';
import withXrInteractivity from './withXrInteractivity';

const Model = forwardRef((props, group) => {
  const {name } = props;
  const { nodes, materials } = useGLTF('/shiba/scene.gltf')
  return (
    <group ref={group} {...props} dispose={null} name={name}>
      <group rotation={[-Math.PI / 2, 0, 0]}>
        <group rotation={[Math.PI / 2, 0, 0]}>
          <group rotation={[-Math.PI / 2, 0, 0]}>
            <mesh geometry={nodes.Group18985_default_0.geometry} material={nodes.Group18985_default_0.material} />
          </group>
          <group rotation={[-Math.PI / 2, 0, 0]}>
            <mesh geometry={nodes.Box002_default_0.geometry} material={nodes.Box002_default_0.material} />
          </group>
          <group rotation={[-Math.PI / 2, 0, 0]}>
            <mesh geometry={nodes.Object001_default_0.geometry} material={nodes.Object001_default_0.material} />
          </group>
        </group>
      </group>
    </group>
  )
});

useGLTF.preload('/shiba/scene.gltf')

const InteractiveModel = withXrInteractivity(Model);
const Shiba = withCollaboration(InteractiveModel);

export default Shiba;

How to make those models interactive

In order to enable the use of your XR controllers (e.g Oculus Quest 2 controllers or HoloLens 2 hand tracked controllers etc), you need to implement a library called react-three/xr.

In this example, Ive implemented this in a HOC called withXrInteractivity.js, lets take a deeper look at it!

Higher Order ComponentwithXrInteractivity.js

This HOC is responsible for:

Enabling the object to become grabbable by the XR controller: lines 4046 we are using the RayGrab HOC that is provided by react-three/xr, for devices that are capable of XR interactions
Tracking the position values of the model that has been moved: lines 1826 we are using the useXREvent function from react-three/xr to track the position of where an object has moved to and from
Updating the global app state with the name and positions of the object that has been moved: finally, between lines 2836 we are figuring out which of the objects with this HOC attached to it have been moved and then update the apps global state with that objects name and position values

import React, { useRef, useEffect, useState } from 'react'
import { useThree } from '@react-three/fiber';
import { RayGrab, useXREvent } from '@react-three/xr';
import deviceStore from '../../stores/device';

import selectedObjectStore from '../../stores/selectedObject';
import { Matrix4, Vector3, } from 'three';

const withXrInteractivity = (BaseComponent) => (props) => {
  const { device } = deviceStore();
  const { setSelectedObject } = selectedObjectStore();
  const group = useRef();
  const { scene } = useThree();
  const [oldPosition, setOldPosition] = useState();
  const [newPosition, setNewPosition] = useState()

  if(device != '' && device != 'web') {
    useXREvent('selectstart', (e) => {
      updatePosition(props.name, scene, setOldPosition);
    });

    useXREvent('selectend', (e) => {
      updatePosition(props.name, scene, setNewPosition);
    })
  }

  useEffect(()=> {
    if(oldPosition && newPosition) {
      // if the old positions are not equal to the new positions
      if(oldPosition.x != newPosition.x || oldPosition.y != newPosition.y || oldPosition.z != newPosition.z) {
        // then you know this object has just been updated, execute logic to update websockets and analytics
        selectedObject(props.name, scene.getObjectByName(props.name), setSelectedObject, group);
      }
    }
  },[oldPosition, newPosition])

  return (
    <>
        {device != '' && device != 'web' &&
          <RayGrab>
              <BaseComponent
                ref={group}
                {...props}
              />
          </RayGrab>
        }
        {device != '' && device == 'web' &&
          <BaseComponent
          ref={group}
          {...props}
          />
        }
    </>
  )
};

const updatePosition = (name, scene, setPosition) => {
  let pos = new Vector3();
  let tempMatrix = new Matrix4;
  tempMatrix = scene.getObjectByName(name).matrixWorld;

  // set the oldPosition based on the matrix world positions
  pos.setFromMatrixPosition(tempMatrix);
  setPosition(pos)
};

const selectedObject = (objectname, object, setSelectedObject, group) => {
  let { x, y, z } = object.position
  setSelectedObject({
    objectname: objectname,
    position: {
      x:x,
      y:y,
      z:z
    },
    group: group
  });
}

export default withXrInteractivity;

How to integrate the Websockets with the 3D models

Once weve made the model interactive with the XR controllers, we then need to integrate the use of Websockets to allow other users to see the new position of the model youve moved.

There are two sides of this to understand, the first is the withCollaboration.js HOC that is responsible for the actual Websocket integration on the Front End and the second is what the data actually looks like in DynamoDB.

Higher Order ComponentwithCollaboration.js

Starting with the Front End, withCollaboration.js does the following:

Submits the positions of the object youve just moved with your XR controllers to the Websocket : lines 1925 check if youre device is capable of XR interactivity, if so then it will update the Websocket with the name of the model being moved, as well as the position of that moved model and the name of the user which moved it
Listens to the Websocket for any updates and updates the positions of the moved models : lines 2832 listen for updates on the Websocket and then check if the submission was made from a different user from the one that submitted it, if so then the new position of the model is applied to the scene.

Building on that last bullet point, the reason it needs to check if the user that submitted the movement is different from the user receiving the positional data on the web app, is to prevent bouncing of position values for the user that originally submitted the new position of the model.

For example, if you submit position values to the Websocket, the Websocket would immediately detect that you had moved the model and would would try to update the position of the model youve just movedthis can cause confusion at the Three.JS layer and cause the position of the model to move erratically and become buggy.

import React, { useRef, useEffect, useState } from 'react'
import { useThree } from '@react-three/fiber';
import { RayGrab, useXREvent } from '@react-three/xr';
import deviceStore from '../../stores/device';
import socketStore from '../../stores/socket';
import cognitoStore from '../../stores/cognito';
import selectedObjectStore from '../../stores/selectedObject';
import { Matrix4 } from 'three';

const withCollaboration = (BaseComponent) => (props) => {
  const { device } = deviceStore();
  const { selectedObject } = selectedObjectStore();
  const { sendJsonMessage, lastJsonMessage } = socketStore();
  const { cognito } = cognitoStore();
  const { scene } = useThree();
  const [socketMode, setSocketMode] = useState('initialLoad');

  useEffect(()=> {
    if(device != '' && device != 'web') {
      if(selectedObject.objectname) {
        submitPositionsToCloud(selectedObject.objectname, cognito.username, scene.getObjectByName(selectedObject.objectname), sendJsonMessage);
      }
    }
  },[selectedObject])

  useEffect(()=> {
    if(device != '') {
      updateModelFromWebSockets(lastJsonMessage, props.name, cognito, scene.getObjectByName(props.name), socketMode, setSocketMode);
    }
  }, [lastJsonMessage])

      return (
        <BaseComponent
          {...props}
        />
      )
};

const submitPositionsToCloud = (objectname, username, object, sendJsonMessage) => {
  let newData = {
    type: 'objects',
    uid: objectname,
    data: {
      submittedBy: username,
      matrixWorld: object.matrixWorld
    }
  };
  sendJsonMessage({
    action: 'positions',
    data: newData
  });
}

const updateModelFromWebSockets = (lastJsonMessage, name, cognito, group, socketMode, setSocketMode) => {
  let data;
  if(lastJsonMessage != null){
    for(let x=0; x<lastJsonMessage.length; x++) {
      if(lastJsonMessage[x].uid == name) {
        if(lastJsonMessage[x].data.matrixWorld.length != 0) {
          data = lastJsonMessage[x].data;
        }
      }
    }
  }
  if(data) {
    if(socketMode == 'stream' && data.submittedBy != cognito.username || socketMode == 'initialLoad') {
      let tempMatrix = new Matrix4();
      tempMatrix.copy(data.matrixWorld);
      tempMatrix.decompose(group.position, group.quaternion, group.scale)
      if(socketMode == 'initialLoad') {
        setSocketMode('stream');
      }
    }
  }
}

export default withCollaboration;

Database for Websocket positional data

Having submitted the new position values of the model to the Websocket, this is then passed onto DynamoDB through the same process outlined in part 2 of this tutorial series.

Ive attached a screenshot below of the DynamoDB table, which shows two types of entries: objects and users.

Users refers to people who have logged in and have moved around, their position values are stored there (see part 2 of this tutorial series).

Objects refers to the models that users have moved using their XR controllers as described in this blog post, lets take a deeper look at this.

Screenshot of the positional data in the DynamoDB Table

Looking at an example of the model entry that is stored, you can see that the models name is stored (in this case shiba) as well as the position of the model (called matrixWorld) and the name of the user that submitted the new position.

The reason that we stored the position as a matrixWorld instead of x/y/z value, is down to the complexities of how a models position is changed when you move it using an XR controller.

When you grab a model using an XR controller, that model becomes a child of the controller, until the moment that you release that model.

In order to provide other users with the accurate position of where youve moved the model to, we are storing that models matrixWorld position, which is essentially its global positionnot its position in relation to the XR controller (aka not its position as a child of the XR controller).

{
  "type": {
    "S": "objects"
  },
  "uid": {
    "S": "shiba"
  },
  "data": {
    "M": {
      "matrixWorld": {
        "M": {
          "elements": {
            "L": [
              {
                "N": "-0.8743998152939527"
              },
              {
                "N": "-0.23723998239253116"
              },
              {
                "N": "-0.4231857431325429"
              },
              {
                "N": "0"
              },
              {
                "N": "-0.23408684389239517"
              },
              {
                "N": "0.9703077655463146"
              },
              {
                "N": "-0.0602815775361555"
              },
              {
                "N": "0"
              },
              {
                "N": "0.4249385470147294"
              },
              {
                "N": "0.046353861928324164"
              },
              {
                "N": "-0.9040077143825459"
              },
              {
                "N": "0"
              },
              {
                "N": "0.6380046282561553"
              },
              {
                "N": "1.0890667315312834"
              },
              {
                "N": "-4.233745217744318"
              },
              {
                "N": "1"
              }
            ]
          }
        }
      },
      "submittedBy": {
        "S": "hi@jamesmiller.blog"
      }
    }
  }
}

Conclusion

Now THAT is a lot of information!!!

I really hope this has been helpful in enabling you to make real-time multiplayer WebXR experiences using React-Three-Fiber and Websockets :D

With any luck, you will be able to adapt this code for your appor even better use Wrapper.js to build your WebXR experiences!

I hope this is helpful and in the meantimehave fun :D

Forem: James Miller

Multiplayer WebXR Readyplayer.me Avatars — Part 1

Multiplayer WebXR Readyplayer.me Avatars — Part 1

Overview of technical concepts for multiplayer WebXR readyplayer.me avatars

Intro

Overview

The Concept

The Tech Stack

The App Flow

Conclusion

Multiplayer Metaverse Creation on Ethereum

How to create a serverless Metaverse with Solidity, Lambda, API Gateway, React Three Fiber, DynamoDB and Metamask.

Intro​

The theory behind building a Metaverse​

Concept​

The Tech Stack​

The App Flow​

Conclusion​

How to set up Auth with Metamask using Amazon Cognito (part 2)

Code samples that demonstrate how to set up Amazon Cognito Auth with Metamask in a DApp.

Intro

Code samples that enable Web3 Auth with MetaMask and AWS

Generating Credentials with the Metamask Wallet

1. Get account address

2. Get / create nonce

3. Sign message with nonce & private key

4. Log in with signature & public address

5. Validate signature

6. Generate / retrieve Cognito Identity

7. Generate Cognito Identity credentials

Using those credentials for Front End and Back End Auth

Conclusion

How to set up Auth with Metamask using Amazon Cognito (part 1)

Implement Auth in your DApp using Web3.js, Metamask, Amazon Cognito and serverless technologies!!

What is Metamask?

Demo

Oversimplified explanation

The theory of Amazon Cognito Auth with Ethereum

Tech stack to implement Auth with Cognito and Ethereum

App flow for Cognito Auth with Ethereum

Conclusion

How to add Amazon Cognito Auth to a Web App (part 4)

Looking at the NodeJS logic that is run in lambda functions to power the Back End of Amazon Cognito Authentication.

Intro

Implementing Cognito Auth on the Back End

serverless/serverless.common.yml

serverless/services/http/users/serverless.yml

serverless/services/http/users/userData/lambda.yml

serverless/services/http/users/userData/index.js

Conclusion

How to add Amazon Cognito Auth to a Web App (part 3)

Intro

Implementing Cognito Auth on the Front End

components/Cognito/utils.js

pages/_app.js

components/Cognito/index.js

pages/index.js

Conclusion

How to add Amazon Cognito Auth to a Web App (part 2)

Intro

Creating Amazon Cognito with Terraform​

main.tf​

modules/cognito/main.tf​

modules/cognito/outputs.tf

modules/restApiGateway/authorizer.tf

modules/restApiGateway/outputs.tf

modules/secretsManager/main.tf

Conclusion

How to add Amazon Cognito Auth to a Web App (part 1)

What is Amazon Cognito?

Demo

Oversimplified explanation

The theory of Amazon Cognito Auth

Tech stack to implement Authentication with Cognito

Conclusion

How to configure Github Actions

Intro

What is Github Actions

Why is Github Actions useful

How it works

Intro

The theory behind building a Metaverse

Concept

The Tech Stack

The App Flow

Conclusion

Creating Amazon Cognito with Terraform

main.tf

modules/cognito/main.tf