AWS Cognito

Integration Guide

Step 1: Installing the Package

Install the PrimusSaaS.Identity.Validator package via NuGet:

dotnet add package PrimusSaaS.Identity.Validator

Step 2: Configuring Program.cs

Register the Primus Identity services and middleware in your Program.cs:

using PrimusSaaS.Identity.Validator;

var builder = WebApplication.CreateBuilder(args);

// Add Primus Identity Validator
builder.Services.AddPrimusIdentity(opts => 
    builder.Configuration.GetSection("PrimusIdentity").Bind(opts));

builder.Services.AddControllers();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

app.Run();

Step 3: Configuring App Settings

Configure the Cognito provider in your appsettings.json:

{
  "PrimusIdentity": {
    "RequireHttpsMetadata": true,
    "ValidateLifetime": true,
    "ClockSkew": "00:05:00",
    "Issuers": [
      {
        "Name": "Cognito",
        "Type": "Cognito",
        "Issuer": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123xyz",
        "Audiences": [ "1abc2def3ghi4jkl5mno6pqr" ]
      }
    ]
  }
}

How to create Cognito User Pool and get configuration values

1. Create a Cognito User Pool

1. Go to AWS Console and sign in
2. Navigate to Cognito service
3. Click Create user pool
4. Configure sign-in options:
   • Select Email as sign-in option
   • Click Next
5. Configure security requirements (keep defaults for testing)
6. Configure sign-up experience (keep defaults)
7. Configure message delivery:
   • Select Send email with Cognito for testing
8. Integrate your app:
   • Enter a User pool name (e.g., my-app-pool)
   • Check Use the Cognito Hosted UI if needed
   • Enter an App client name (e.g., my-api-client)
9. Review and click Create user pool

2. Get Configuration Values

After creating the pool:

Value	Where to Find
Region	Top right of AWS console (e.g., us-east-1)
User Pool ID	User pool Overview User pool ID (e.g., us-east-1_ABC123xyz)
App Client ID	User pool App integration App clients Client ID

3. Build the Issuer URL

The issuer URL format is:

https://cognito-idp.{REGION}.amazonaws.com/{USER_POOL_ID}

Example:

https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123xyz

4. Create a Test User

1. Go to your User Pool
2. Click Users tab
3. Click Create user
4. Enter email and temporary password
5. The user will receive an email to set their password

5. Generate Access Token (for testing)

Using AWS CLI:

aws cognito-idp initiate-auth \
    --auth-flow USER_PASSWORD_AUTH \
    --client-id YOUR_APP_CLIENT_ID \
    --auth-parameters USERNAME=user@example.com,PASSWORD=YourPassword123!

Or use the Cognito Hosted UI to sign in and get a token.

Step 4: Configuring Endpoint

Create a protected endpoint to test the authentication.

[HttpGet("cognito")]
[Authorize]
public IActionResult Get()
{
    return Ok(new { 
        validated = true,
        issuer = User.FindFirst("iss")?.Value,
        subject = User.FindFirst("sub")?.Value,
        email = User.FindFirst("email")?.Value
    });
}

Step 5: Testing the Endpoint

Get a token from Cognito and test the endpoint:

curl -k -X GET "https://localhost:5001/cognito" \
     -H "Authorization: Bearer <ACCESS_TOKEN>"

Alternative: Fluent API Configuration

You can also configure Cognito using the fluent API:

builder.Services.AddPrimusIdentity(opts =>
{
    opts.UseCognito(
        region: "us-east-1",
        userPoolId: "us-east-1_ABC123xyz",
        audience: "1abc2def3ghi4jkl5mno6pqr"
    );
});

Cognito-Specific Notes

Feature	Support
User Pool tokens	Fully supported
Identity Pool	Not directly supported (use custom JWT)
Hosted UI tokens	Fully supported
Machine-to-machine	Requires Cognito Resource Server setup