auth-and-identity

Auth & Identity in Cratis Arc

This skill covers the full auth and identity stack in a Cratis Arc application. Read the relevant reference files below for detailed API usage.

Read the relevant instruction files first. This skill references concepts from the core copilot instructions in .github/copilot-instructions.md. If you need details on vertical slices, commands, queries, or proxy generation, consult those instructions.

Architecture Overview

Identity and auth in Arc follow a cookie-first, convention-based pattern:

Frontend (React)                          Backend (ASP.NET Core)
─────────────────                         ──────────────────────
<IdentityProvider>                        app.MapIdentityProvider()
  └── useIdentity() hook                    └── GET /.cratis/me
        │                                        │
        ├─ 1. Read .cratis-identity cookie        │
        └─ 2. If no cookie → fetch /.cratis/me    │
                                                  ▼
                                    AuthenticationMiddleware
                                      └── IAuthenticationHandler[]
                                            │ sets HttpContext.User
                                            ▼
                                    IIdentityProvider.Get()
                                      └── IProvideIdentityDetails.Provide()
                                            │
                                            ▼
                                    IdentityProviderResult
                                      → JSON response
                                      → .cratis-identity cookie (base64)

Authorization:
  [Authorize] / [Roles("Admin")] / [AllowAnonymous]
    └── AuthorizationEvaluator checks per command/query

Key design decisions:

• The .cratis-identity cookie is HttpOnly=false so the frontend JavaScript can read it directly — no extra HTTP call needed on page load.
• Identity details are base64-encoded JSON in the cookie, automatically decoded by the frontend IdentityProvider.
• Only one IProvideIdentityDetails implementation is allowed per application (auto-discovered). If none exists, a default provider grants access to everyone.
• Cratis has its own [Authorize], [AllowAnonymous], and [Roles] attributes in Cratis.Arc.Authorization — these are distinct from ASP.NET Core's and are evaluated by AuthorizationEvaluator in the command and query pipeline.