Setting up Cognito

AWS Cognito signs external guests in: people outside your organisation who have no account in your directory. It runs alongside Entra rather than replacing it, and the two sign-in paths are entirely separate.

Who this is for: Whoever is standing the portal up. You need permission to create Cognito and IAM resources in AWS.

Skip this page if only internal staff are in scope.

Cognito does not replace Entra

Even with Cognito handling every person who signs in, an Entra registration is still required as the identity that reads Power BI reports and SharePoint workbooks. Cognito adds a sign-in path; it does not remove Entra from the picture. See Setting up Entra ID.

Create the user pool

1. Cognito → User pools → Create user pool.
2. Sign-in options: tick Email, and nothing else. ReportMesh treats the email address as the sign-in identity.
3. Password policy: your organisation's standard. Cognito enforces it when a guest exchanges their temporary password for a permanent one.
4. Multi-factor authentication: Required.
   • Authenticator apps (TOTP): enabled.
   • SMS: disabled. SMS codes are interceptable, and cost money per message.
5. Self-service account recovery: email.
6. Required attributes: email. Add name as well if you want display names to arrive from Cognito rather than being blank until first sign in.
7. Create the pool, then record the User pool ID from its Overview page, along with the region it sits in.

Turn self-registration off

This is the important one. External guests are invited by an administrator, and must never be able to sign themselves up.

Why this is not a preference

The bootstrap administrator rule exists because an open pool plus a portal with no administrator yet would let a stranger sign themselves up and become its administrator. Leaving self-registration enabled re-opens exactly that path.

External guests hold the ordinary user role and nothing else, enforced in the application itself. But where two independent guards are available, use both.

Create the app client

Create a confidential client, one with a client secret, and record both the Client ID and the Client secret.

There is no redirect URI and no hosted UI to configure. Unlike Entra, the Cognito flow runs on ReportMesh's own sign-in page: the portal sends the credentials to the API, which talks to Cognito directly, and the MFA step happens in that same exchange. Nothing here needs a callback URL.

Grant the application access to the pool

ReportMesh reads and invites users through AWS's own credential mechanism, using the role attached to the server it runs on. No additional secret goes into the application's configuration.

Attach a policy to that role allowing these three actions, scoped to the pool you created:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cognito-idp:ListUsers",
        "cognito-idp:AdminCreateUser",
        "cognito-idp:AdminGetUser"
      ],
      "Resource": "arn:aws:cognito-idp:<region>:<account-id>:userpool/<user-pool-id>"
    }
  ]
}

Scope it to the pool's ARN rather than leaving it open to every pool in the account.

A second site for guests

Guests sign in at their own hostname, separate from the staff portal, for example portal.example.com. It is a separate build of the same application, hosted separately, and it must sit under the same parent domain as the API for the same reason every other hostname does.

Both hostnames also need to be listed as permitted origins in the application's configuration. A missing one shows up as every request failing from that site.

Why the two sites are kept apart

Each site is issued a differently named session cookie, and each tells the API which one to read. That naming is the only thing separating the two sessions, because a single cookie domain wide enough to cover a site and the API also covers the other site.

Given one shared name instead, signing into one site silently takes over the session on the other, and someone appears already signed in to a site they never visited.

Inviting guests

Two records exist for every guest, created at different times. This is the most common misunderstanding here:

1. The Cognito record, created in advance when an administrator invites them. Cognito emails them a temporary password.
2. The ReportMesh record, created automatically the first time they successfully sign in.

So an administrator invites once, and the portal's own record appears by itself. An invited person does not appear in the user list until they have signed in at least once.

Their first sign in walks them through it: the temporary password, then setting a permanent one, then scanning a QR code with an authenticator app, then entering the first code it generates.

Once the portal is running, this is done from the admin screens — see Managing users.

Checklist

• Self-registration is disabled on the pool.
• MFA is Required, with TOTP on and SMS off.
• Email is the only sign-in option.
• The app client has a secret.
• The server's role carries the three cognito-idp: actions, scoped to the pool's ARN.
• The guest site is built separately, on its own hostname, under the same parent domain.
• Both hostnames are listed as permitted origins.
• Signing into one site does not show you as signed in on the other.

Common problems

What you see	What it usually means
The application will not start	A sign-in provider is switched on with its configuration incomplete. All four Cognito values must be present.
Someone appears already signed in on the other site	Both sites were built for the same provider, so they request the same cookie.
Signed in, but every request fails on one site only	That site was built for a provider it never signs in as.
An invited guest is missing from the user list	They have not signed in yet. Their record is created on first sign in.

Next

Sign in is now configured for both staff and guests. What remains is giving ReportMesh reach over the content itself: Granting Power BI workspace access and Granting SharePoint site access.