AWS Cognito

In this guide, you will learn how to configure AWS Cognito and integrate the Arcana Auth SDK with a Web3 app that uses AWS Cognito for onboarding users. After integrating with the Auth SDK, the developers can enable the authenticated users to access the embedded, non-custodial Arcana wallet.

Prerequisites

Make sure you can access the Arcana Developer Dashboard: https://dashboard.arcana.network
Install the @arcana/auth package. For details, see Arcana Auth Quick Start Guide.

Note that some steps are performed using AWS Management Console, others using Arcana Dashboard. Once the users are authenticated using AWS Cognito, the developer can call Auth SDK functions to access Web3 wallet operations offered by the embedded Arcana wallet from within the app context.

Web3 applications that use AWS Cognito for user authentication can enable the Arcana wallet for the authenticated users. The developers must configure AWS Cognito and then integrate the app with the Arcana Auth SDK.

Step 1: Use Arcana Dashboard

Go to the Arcana Dashboard: https://dashboard.arcana.network

Register your dApp by creating a new dApp entry and specifying a name using the 'Create New App' wizard.

Registering the Application

If you have already registered your dApp using Arcana Dashboard and obtained an Client ID, you may skip this step.

Use defaults for other settings or change them as per your use case. Refer to the how to configure dApp guide for details.

Go to the Configure->Social Auth configuration section and copy the redirect URI value displayed there. This will be used in the next step to generate Cognito OAuth credentials.

Do not close the dashboard browser tab. Open another tab and set up AWS Cognito OAuth. Then come back to the Dashboard tab and complete the dApp configuration settings.

Step 2: Use AWS Management Console

Go to the AWS Management Console and register your dApp as a new Cognito client application. Log in to the console, search for 'Cognito' and you will see the Cognito setup dashboard. Using this dashboard, you need to add your app as a Cognito client in the context of a Cognito 'User Pool'. If you do not already have a Cognito 'User Pool' setup, create a new User Pool first as highlighted in the figure below.

Cognito Sign-in Options

Email ID must be selected as one of the Cognito sign-in options.

If you already have a user pool set up, select it from the list and double-click on it to see the details. Refer to the App Integration tab settings and click Create App Client on the bottom right of the page.

You will see the Create Client dashboard screen. You need to specify the following settings for your app and update the requisite fields in the console:

App Type: Public Client
App Client Name: Enter the app name
Client Secret: Select the 'Do not generate client secret' option
Authentication Flows: Select ALLOW_REFRESH_TOKEN_AUTH

Then scroll down to the Hosted UI section and refer to the Allowed Callback URLs field. In this field, add the Redirect URI copied from Arcana Dashboard in the previous step.

Make sure you add Cognito User Pool in the Identity Provider section of the settings as shown in the figure above.

For the OAuth 2.0 Grant Type setting, make sure you specify Authorization Code Grant and Implicit Grant values as shown in the figure below:

In the Custom Scope section, ensure that the attribute EmailID has read access. This is used by Arcana Auth SDK to enable the aggregate login feature.

Save the new client app settings. You will see the new client app entry in the user pool page under the App Client List section.

Copy the ClientID that is automatically generated by Cognito for the newly registered Client App. It will be required in the next step while completing the Arcana dashboard dApp configuration.

Step 3: Update Arcana Dashboard

Revisit the Arcana Developer Dashboard portal. Click on your app entry and visit the application dashboard. Click Configure->Social Auth in the LHS navigation bar. Refer to the "Cognito" field and paste the Client ID assigned by AWS Management Console after the Cognito OAuth setup in the previous step, in the input text field.

Save the settings. Arcana Network assigns a Client ID to every registered and configured dApp. You need to save this Client ID and use it while integrating the dApp with the Auth SDK.

You are all set with the Cognito configuration. Integrate the Web3 application with the Arcana Auth SDK. After authentication, users can access Arcana wallet functionality.

Tip

The Client ID is displayed on the top right of your dashboard.

You can revisit the Arcana Dashboard later to view and modify configuration settings.

Step 4: Integrate with Arcana Auth SDK

Use the instructions here to integrate with the Arcana Auth SDK

After integration, use the following code to trigger Cognito login to onboard users:

await auth.loginWithSocial('aws')

Check if a user is logged in:

const connected = await auth.isLoggedIn()

Use other Auth SDK functions in your dApp. See Auth SDK Usage Guide for details.

Add code in the application to log out an authenticated user:

await auth.logout()

That is all!

Your app is all set for authenticating users via AWS Cognito. Authenticated users can instantly access the Arcana wallet to sign blockchain transactions.

Apps using Federated Identity Providers

Apps integrating with the Arcana Auth SDK can choose multiple social providers for onboarding users. For example, to allow user onboarding via Google and Twitter, developers must set up both these providers in the Arcana Developer Dashboard. Some apps may choose to not use the Auth SDK for onboarding users via social providers but integrate with federated identity providers, such as AWS Cognito, for user authentication. But such apps may want to integrate with the Auth SDK to access the embedded Arcana wallet and allow authenticated users to sign blockchain transactions.

The federated identity providers such as AWS Cognito typically aggregate and directly support various authentication verifiers such as Google, Facebook, etc. Developers must use the respective provider's developer console, e.g., Cognito Developer Console to set up the user authentication verifiers, such as Google, directly and not through the Arcana Developer Dashboard.

To integrate with Web3 apps that use federated identity providers to onboard users instead of the Arcana Auth SDK, the developers need to only configure the federated identity provider via the Arcana Developer Dashboard before integrating with the Auth SDK. It is not required to configure the authentication verifiers used by the federated identity providers (e.g., Google) in the Arcana Developer Dashboard.

What's Next?

To know more about how to use Web3 wallet operations programmatically in your app, see Arcana Wallet Developer's Guide. Refer to the Arcana Wallet User's Guide for more information on how authenticated app users can access the wallet UI.