# Kanject.Identity

A typed .NET surface over AWS Cognito — user and group management, authentication flows, MFA, and federation, plus a permission model your services enforce — running against a Cognito user pool in *your* AWS account.

> **Note:** This is the developer guide. For the feature tour and pricing, see the [Identity product page](https://www.kanject.com/baas/identity/). Identity pairs with [Identity.Server](https://www.kanject.com/docs/baas-identity-server/) for a Cognito-backed authorization server.

**You'll learn**

- Provision the Identity module — a Cognito user pool — into your AWS account
- Register it with `AddCognitoIdentityProvider<…>` over your user, group, and context types
- Register users and run authentication flows through `IUserIdentityService<…>`
- Protect endpoints with `[RequiresPermission]` and the authorization server

## Provision

Identity is a CloudFormation stack in *your* account — a Cognito user pool plus its app clients. Deploy it once per stage; the template is idempotent, so re-runs are safe.

```bash
# One CloudFormation deploy per AWS account, per stage. Idempotent.
kanject baas deploy identity --env dev
```

## Register it in your service

Registration is generic over three types you own — the data context, your application user, and your user group — and takes a typed `AwsCognitoConfiguration` delegate. The NuGet package is provider-versioned (`Kanject.Identity.Provider.AwsCognitoV4`).

```csharp
using Kanject.Identity.Provider.AwsCognitoV4.Extensions;

// Your own user, group, and data-context types (the three generics).
public sealed class AppUser : IApplicationUser { /* your profile fields */ }
public sealed class AppUserGroup : IApplicationUserGroup { }
public partial class IdentityDbContext; // your Kanject data context

builder.Services.AddCognitoIdentityProvider<IdentityDbContext, AppUser, AppUserGroup>(
    options =>
    {
        options.Region     = appSettings.AwsRegion;
        options.UserPoolId = appSettings.CognitoUserPoolId;
        options.ClientId   = appSettings.CognitoClientId;
    });

// Add the authorization server to enable [RequiresPermission] enforcement.
builder.Services.AddAuthorizationServer();
```

## Register users, run auth flows

Inject `IUserIdentityService<TApplicationUser, TApplicationUserGroup>`. Its methods take request objects (not loose strings): `RegisterUserAsync<T>` creates a Cognito user and places them in a group; `UserAuthenticationAsync<T>` runs the sign-in flow and returns a typed token response.

```csharp
// Inject the typed identity service (generic over your user + group types).
public class AccountService(IUserIdentityService<AppUser, AppUserGroup> identity)
{
    public Task<AppUser> RegisterAsync(RegisterAppUserRequest request)
        // request implements IRegisterUserRequest, IAddUserToGroupRequest
        => identity.RegisterUserAsync(request);

    public Task<TokenWithUserAuthenticationFlowResponse> SignInAsync(SignInRequest request)
        => identity.UserAuthenticationAsync(request);
}
```

## Protect endpoints

Cognito-issued JWTs validate through standard ASP.NET Core authentication. For authorization, the SDK ships a `[RequiresPermission]` action filter backed by `AddAuthorizationServer()` — a permission/group model synced to DynamoDB — rather than only role strings.

```csharp
// Protect endpoints with the permission filter (backed by the authorization
// server + a permission/group model synced to DynamoDB).
[RequiresPermission("reports.read")]
[HttpGet("/admin/reports")]
public IActionResult Reports() => Ok();
```

## What you get

- **Cognito user pool** — sign-up, sign-in, and token flows against a pool in your account
- **Typed service** — `IUserIdentityService<TUser, TGroup>` with request-object methods for users and groups
- **Groups & permissions** — a permission/group model enforced via `[RequiresPermission]` + the authorization server
- **MFA & federation** — Cognito-native second factors and social / SAML / OIDC identity providers
- **Sessions** — optional session management via `Kanject.Identity.Extensions.Sessions`
- **Provider versions** — Cognito providers V1–V4; register the version your service targets

> **Pitfall:** A Cognito user pool's **sign-in aliases and required attributes are fixed at creation**. Decide whether users log in by email, phone, or username — and which attributes are mandatory — *before* your first production users, because changing them later means migrating the pool.

**Recap**

- Identity provisions a Cognito user pool into your account via `kanject baas deploy identity`.
- Register with `AddCognitoIdentityProvider<TCtx, TUser, TGroup>(options => …)`; the package is provider-versioned.
- The runtime surface is `IUserIdentityService<TUser, TGroup>` with request-object methods.
- Authorize with `[RequiresPermission]` + `AddAuthorizationServer()`, and plan the pool's aliases/attributes up front.

## Related modules

- **[Identity.Server](https://www.kanject.com/docs/baas-identity-server/)** — Cognito-backed authorization server — permissions and roles.
- **[NotificationHub](https://www.kanject.com/docs/baas-notifications/)** — Login alerts, verification, and password-reset flows.
- **[Insights](https://www.kanject.com/docs/baas-insights/)** — Auth metrics — sign-up funnels and login cohorts.

> **Next step:** Wiring auth into a service? Pair Identity with [NotificationHub](https://www.kanject.com/docs/baas-notifications/) for verification and login-alert flows, or read the [BaaS deployment guide](https://www.kanject.com/docs/baas/) for the full module-composition workflow.

---
_Source: https://www.kanject.com/docs/baas-identity/ · Kanject Docs_