CognitoPass
Player accounts with Amazon Cognito

Overview

CognitoPass gives your game player accounts backed by an Amazon Cognito user pool. Players sign up, confirm their e-mail, sign in, add an authenticator app, reset forgotten passwords and stay signed in between game sessions. When you also configure a Cognito identity pool, the signed-in player's ID token is registered with it automatically, so Get AWS Credentials returns temporary AWS keys scoped to that player without any extra wiring.

• 18 latent nodes covering the complete account life cycle, each with On Success / On Failure pins and a clear error.
• Sign In and Respond To Challenge have an On Challenge pin for MFA codes, new passwords and MFA setup.
• Remembered sessions (refresh token in the SaveGame slot CognitoPassSession) and automatic token refresh.
• App clients with a client secret: the SECRET_HASH is computed for every request.
• Authenticator-app (TOTP) MFA with an otpauth:// URI ready for a QR code.
• CognitoPass Subsystem events (On Signed In, On Signed Out, On Session Refreshed) for UI and game code.
• All requests run on background worker threads; results arrive on the game thread. Tokens and passwords are never logged.

Requirements

Installation

1. Install CognitoPass from Fab into your engine, or copy the CognitoPass folder into your project's Plugins folder.
2. Open the project, enable CognitoPass in Edit > Plugins and restart the editor.
3. Open Project Settings > Plugins > CognitoPass and enter the User Pool Id and App Client Id (see Setting up Cognito).
4. C++ only: add PublicDependencyModuleNames.Add("CognitoPass"); to your Build.cs.

Setting up Cognito

1. Create the user pool

1. In the AWS console open Amazon Cognito > User pools > Create user pool.
2. Application type: Mobile app (or "Traditional web application"). Give the app client a name, for example game-client.
3. Sign-in identifiers: choose Username and/or Email. Required attributes: at least email if you want e-mail confirmation and password reset.
4. Create the pool. Copy the User pool ID (for example eu-west-1_AbCdEf123) into User Pool Id. The region is taken from it.

2. Configure the app client

1. Open the pool's App clients page and select the app client. Copy its Client ID into App Client Id.
2. Edit the authentication flows and enable ALLOW_USER_PASSWORD_AUTH and ALLOW_REFRESH_TOKEN_AUTH.
3. Recommended: create the app client without a client secret. If it has one, copy it into App Client Secret (Advanced) — but a secret inside a game build can be extracted.
4. Optional: set the token validity (ID/access token 60 minutes and refresh token 30 days are common) and the attribute read/write permissions used by Update User Attributes.
5. Keep refresh token rotation turned off: Restore Session and Refresh Session use the REFRESH_TOKEN_AUTH flow.

3. MFA (optional)

Under Sign-in > Multi-factor authentication choose Optional MFA or Require MFA and enable Authenticator apps (and SMS or e-mail if you configured them). With required MFA, a player without MFA gets the MFA_SETUP challenge at sign-in: handle it with Setup Authenticator App and Verify Authenticator App.

4. Identity pool for AWS credentials (optional)

1. Open Amazon Cognito > Identity pools > Create identity pool. Enable Authenticated access (and Guest access if guests need AWS access).
2. Identity source: Amazon Cognito user pool; choose your user pool and app client.
3. Create (or choose) the authenticated IAM role and give it only the permissions your game needs. The example below lets each player read and write their own folder of an S3 bucket.
4. Copy the Identity pool ID (for example eu-west-1:01234567-89ab-cdef-0123-456789abcdef) into Identity Pool Id.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PlayerOwnFolder",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::my-game-saves/${cognito-identity.amazonaws.com:sub}/*"
    },
    {
      "Sid": "ListOwnFolder",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::my-game-saves",
      "Condition": { "StringLike": { "s3:prefix": "${cognito-identity.amazonaws.com:sub}/*" } }
    }
  ]
}

The role's trust policy (created by the console) must allow sts:AssumeRoleWithWebIdentity for cognito-identity.amazonaws.com with your identity pool id in cognito-identity.amazonaws.com:aud and "cognito-identity.amazonaws.com:amr": "authenticated".

Quick start

1. On your login screen call Restore Session. On Success = the player is signed in already (skip the form).
2. Otherwise call Sign In with the user name and password from the form.
   • On Success: read Session.Sub (permanent player id) and go to the main menu.
   • On Challenge: show the right prompt for Challenge Name (see Challenges) and call Respond To Challenge.
   • On Failure: show Error.Message. UserNotConfirmedException means the player must confirm the sign-up code first.
3. New players: Sign Up → Confirm Sign Up with the code from the e-mail → Sign In.
4. Bind On Signed Out of the CognitoPass Subsystem (Get Game Instance Subsystem) to return to the login screen.

Account nodes

Sign-in & session

Challenges & MFA

Respond To Challenge takes the Cognito response keys. The key CODE is mapped to the right key for the challenge, so one text box works for every code challenge. USERNAME and SECRET_HASH are added for you.

Authenticator app

Passwords

AWS credentials

Get AWS Credentials returns Identity Id, Access Key Id, Secret Access Key, Session Token and Expiration. In Cognito Identity Pool mode the player is authenticated when signed in (the ID token is registered as the login cognito-idp.<region>.amazonaws.com/<user pool id>) and a guest otherwise (when the pool and Allow Guest Access permit it). Credentials are cached and renewed 5 minutes before they expire.

The Static Keys and Default Credential Chain modes return the keys from the settings or the standard AWS chain (environment, ~/.aws profile, instance role) — for development, dedicated servers and tools.

Helper nodes

Total Blueprint nodes: 18 latent + 6 helpers + 2 on the node object = 26.

Events

The CognitoPass Subsystem (a Game Instance Subsystem — use Get Game Instance Subsystem) broadcasts what the nodes do, so UI can react in one place:

Types

Settings

Project Settings > Plugins > CognitoPass (saved to DefaultGame.ini).

C++

#include "CognitoPassLibrary.h"
#include "CognitoPassSubsystem.h"

// Events
UCognitoPassSubsystem* Accounts = GetGameInstance()->GetSubsystem<UCognitoPassSubsystem>();
Accounts->OnSignedIn.AddDynamic(this, &AMyHUD::HandleSignedIn);

// Session and claims
if (UCognitoPassLibrary::IsSignedIn())
{
	const FCognitoPassSession Session = UCognitoPassLibrary::GetSession();
	TMap<FString, FString> Claims;
	FString Json;
	UCognitoPassLibrary::GetTokenClaims(Session.IdToken, Claims, Json);
}

// Latent nodes are UBlueprintAsyncActionBase classes, e.g.
UCognitoPassSignInAction* SignIn = UCognitoPassSignInAction::SignIn(this, Name, Password);
SignIn->OnSuccess.AddDynamic(this, &AMyHUD::HandleSession);
SignIn->OnFailure.AddDynamic(this, &AMyHUD::HandleSession);
SignIn->Activate();

Security notes

• Tokens, passwords and secrets are never written to the log.
• The remembered refresh token is stored in a local SaveGame file. Turn off Remember Session on shared machines, or offer a "keep me signed in" checkbox and call Sign Out when it is unticked.
• Get Token Claims does not verify signatures. Backends must verify Cognito JWTs against the pool's JWKS.
• Prefer app clients without a secret for game clients, and keep identity-pool roles minimal.
• Never ship long-term access keys in a game client: use the identity pool for players.

Troubleshooting

Credits

© 2026 Alpha XP — alphaxp.net · Support: support@alphaxp.net. Includes the AWS SDK for C++ 1.11.916 (Apache-2.0). Built for Unreal Engine 4.27 and 5.8.