Skip to content

Stage 3 — Create a User Pool and Initialise Users and Groups

How to complete this stage

Create a Cognito Local user pool, configure an app client, and initialise the users and groups required for authentication and ABAC testing.

Approach and rationale

Cognito Local does not automatically create a user pool. All users, groups, and login tokens used by the IA node must belong to an explicitly created pool. This stage establishes the identity structure that later stages rely on for:

  • Authentication
  • Attribute resolution
  • Attribute-based access control (ABAC) Without a correctly configured user pool and app client, authentication and token verification will fail.

3.1 Create the user pool

This creates a container for user and authentication settings within the local identity provider. All users, groups, and login tokens used by the IA node belong to this user pool.

aws cognito-idp create-user-pool \
  --pool-name local_ianode \
  --endpoint-url http://localhost:9229

3.2 Discover the user pool ID (do not hard-code)

When you create a user pool, Cognito Local assigns it an internal identifier. This identifier:

  • Is not deterministic.
  • May change if the identity service is restarted or reset.
  • Must not be copied from examples or hard-coded.

List the available user pools:

aws cognito-idp list-user-pools \
  --max-results 10 \
  --endpoint-url http://localhost:9229

Locate the entry with the name local_ianode and copy its Id value. Export that value so it can be reused by later commands:

export USER_POOL_ID="local_XXXXXXXX"

Replace local_XXXXXXXX with your value.

3.3 Create an app client (required)

An app client represents an application that is allowed to request login tokens from the identity provider. The access service uses this app client when authenticating users and issuing tokens for the IA node. Cognito Local does not create an app client automatically, so you must create one explicitly.

Create the app client:

aws cognito-idp create-user-pool-client \
  --user-pool-id "$USER_POOL_ID" \
  --client-name local_ianode_client \
  --explicit-auth-flows USER_PASSWORD_AUTH \
  --generate-secret \
  --endpoint-url http://localhost:9229

The command returns a ClientId. Capture the ClientId value and export it so it can be used by later services:

export CLIENT_ID="YOUR_CLIENT_ID"

Replace YOUR_CLIENT_ID with the value returned by the command.

3.4 Run the user and group initialisation scripts

These scripts populate the local identity provider with a set of test users and groups that will be used later to demonstrate access control. Specifically, they:

  • Reset any existing Cognito Local state
  • Create users with known email addresses
  • Create groups
  • Assign users to groups required for ABAC testing

From the ianode-access/cognito-local directory, run:

export COGNITO_ADMIN_PASSWORD="<choose a password>"
sudo sh reset_cognito.sh
sh config_cognito.sh

If you are prompted to configure AWS credentials, run:

aws configure

When prompted, you may enter dummy values, as no real AWS services are used:

  • AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
  • AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
  • Default region name [None]: us-east-1
  • Default output format [None]: json

When the scripts complete successfully, the output should indicate that:

  • Users have been added to groups.
  • Groups have been created.
  • You can now authenticate using an AWS CLI command.
  • Make a note of the authentication command shown in the output.
Operational notes

These scripts assume a clean Cognito Local state. They may print success messages even if underlying AWS CLI calls fail. If users or groups do not appear later, reset Cognito Local and rerun this step.

3.5 Validate users and groups

Before continuing, confirm that users and groups were created correctly. Do not rely solely on the script output, as the scripts may report success even if underlying commands failed.

List users

List the users in the user pool:

aws cognito-idp list-users  --user-pool-id "$USER_POOL_ID"  --endpoint-url http://localhost:9229

You should see entries for the test users created by the initialisation scripts.

List groups

List the groups in the user pool:

aws cognito-idp list-groups --user-pool-id "$USER_POOL_ID" --endpoint-url http://localhost:9229

You should see the expected groups used for ABAC testing.

Operational notes
  • Cognito assigns a UUID as the Username; the email address is stored as an attribute.
  • When adding users to groups, Cognito requires the UUID Username, not the email address.
  • The initialisation scripts assume a clean Cognito Local state.
  • The scripts may print success messages even if underlying AWS CLI calls fail.

If group creation returns HTTP 500 errors or messages referring to missing .cognito/db/...json files, the local Cognito state may be corrupted.

Recovery procedure

Stop and remove local Cognito state:

docker compose down -v

Restart Cognito Local:

docker compose up -d

Then:

  • Recreate the user pool.
  • Recreate the app client.
  • Rerun the user and group initialisation scripts.

3.6 Checkpoint

At the end of this stage:

  • A Cognito Local user pool exists.
  • The USER_POOL_ID environment variable has been exported.
  • An app client has been created.
  • The CLIENT_ID environment variable has been exported.
  • Test users exist in the user pool.
  • Groups exist and users are assigned to them.

You should be able to confirm this by successfully running:

aws cognito-idp list-users
--user-pool-id "$USER_POOL_ID"
--endpoint-url http://localhost:9229

and

aws cognito-idp list-groups
--user-pool-id "$USER_POOL_ID"
--endpoint-url http://localhost:9229

If users or groups are missing:

  • Reset Cognito Local.
  • Recreate the user pool and app client.
  • Rerun the user and group initialisation scripts.

Do not proceed until this checkpoint passes.

Next Steps

Start Access Service