☁️Amazon Cognito

A guide to get you started with using Picket as a Federated Identity Provider for Amazon Cognito

Overview

Picket is OAuth 2.0 and OIDC compatible, which makes it easy to integrate with web2 identity providers like AWS Cognito. Picket is added to Amazon Cognito as a federated identity provider, allowing users to log in to your existing Amazon Cognito app (a.k.a User Pool) via Picket. This makes it easy to add Picket to existing Amazon Cognito apps or support multiple login methods like Picket for Web3 and Google for Web2.

This guide will walk you through how to add Picket to an existing Amazon Congito user pool. It's a Picket-specific version of the adding OIDC identity provider to a user pool AWS docs.

Getting Started

Requirements

Setup Picket

1. Go to your Picket Dashboard

2. Create a new Project

You'll see the Create New Project button at the top of the Projects section of your Picket dashboard. Alternatively, you can re-use an existing project. Feel free to edit the project to give it a memorable name.

We're done for now! We'll revisit this project when we are setting up Picket as an identity provider in Amazon Cognito in the next section.

Setup Amazon Cognito

Old vs New AWS UI

If your Amazon Cognito looks different than the screenshots below, it is because the instruction use the latest Amazon Cognito UI. The old UI is visually different but information is the same.

1. Create or Choose a User Pool

Create a new or choose an existing user pool for us to add Picket as a federated identity provider. For more information on user pools, see the AWS documentation.

2. Add a New Federated Identity Provider

For instructions on how to add a new federated identity provider to a user pool, there are step by step instructions in the AWS docs. Below is all the information you need to setup Picket as a federated OIDC identity provider as well as screenshots in case you get lost.

  • Name = Picket

  • Client ID = Picket project's publishable key. Copy it from your Picket dashboard

  • Client secret = Picket project's secret key. Copy it from your Picket dashboard

  • Authorized scopes = openid email profile

  • Attribute request method = POST

  • Setup Method = Auto fill through issuer URL

  • Issuer URL = https://picketapi.com/api/v1

3. User Attribute Mapping

List of Mappable Picket User Attributes

Reference the Anatomy of an Access Token page for a complete list of mappable OpenID Connect Attributes and their names.

The mapping between Picket user attributes and your user pool is up to you. Do whatever makes sense for your application and needs. For a list of mappable user properties and their attribute names, checkout the Anatomy of an Access Token concept page.

Below is an example mapping, but again how you map Picket attributes to your application is up to you.

4. Review

Test the Picket OIDC IdP Integration

Almost done! It's time to test the integration end to end.

If your app already authenticates users with AWS Cognito, you can now use Picket as an additional login method. If not, an easy way to test your integration is to use the default user pool domain.

Default User Pool Host UI Test URL

To construct a test URL, insert the following values in the URL below

  • <your_user_pool_domain> = You can find your domain on the user pool Domain name console page

  • <your_client_id> = Client ID from your Amazon Cognito user pool client app. This is not the same as the client ID for the the Picket OIDC provider.

  • <your_redirect_uri> = Replace with the URI you want your user to land on after a successful or unsuccessful login. Typically this is the URI of your app. For example, if I want users to log in to Picket, I would set this to https://picketapi.com

https://<your_user_pool_domain>/oauth2/authorize?response_type=code&client_id=<your_client_id>&redirect_uri=<your_redirect_uri>

Add Redirect URI to your Picket Project

Last but not least we need to whitelist the redirect URI for your Picket project. Whitelisting redirect URIs are a critical part of the security of the OAuth 2.0 authorization flow.

For federated identity providers, like Picket, the redirect URI you want to whitelist is typically the domain that is initiated the login request.

For example, if my login domain is https://picket-preview.auth.us-west-2.amazoncognito.com, then I would add the following to my Picket project in my Picket dashboard

Done!

You and your users should now be able to log into your app with their wallet of choice!

Additional Information

OIDC - OpenID Connect

OIDC, or OpenID Connect, is an extension of the OAuth 2.0 standard. It defines APIs for accessing information about the currently logged in user.

Web3 Emails

OIDC is centered around web2 social profile information, like emails. At the time of writing this, there isn't a ubiquitous web3-native email provider or email equivalent for wallets. To maintain compatibility with OIDC and make the integration with web2 identity providers as simple as possible for our developers, we generate a web3 email address for users when they login.

Currently we default to Skiff as the web3 email provider. The emails generated are in the format WALLET_ADDRESS@skiff.com. You can use these emails to contact users but they will only see the emails if they log into Skiff with their wallet address.

This is subject to change in the future. Web3-native communication is still unsolved and we are actively monitoring for better solutions.

Questions?

Reach out! We're here to help. Email us at team@picketapi.com

PreviousSupabaseNextPicket Shopify App - Merchant Documentation

Last updated