ivy-interactive/ivy-framework/ivy-create-auth-connection

ivy-create-auth-connection

Add an authentication provider to an existing Ivy project. This skill guides you through selecting a provider, collecting the required credentials, and configuring the project.

Pre-flight: Read Learnings

If the file .ivy/learnings/ivy-create-auth-connection.md exists in the project directory, read it first and apply any lessons learned from previous runs of this skill.

Reference Files

Read before implementing:

• references/AGENTS.md -- Ivy framework API reference (widgets, hooks, layouts, inputs, colors)

Step 1: Validate the Project

1. Verify this is a valid Ivy project. Check for a .csproj file and Program.cs in the working directory. If this is not an Ivy project, tell the user and stop.

Step 2: Choose an Auth Provider

1. If the user has not already specified a provider, ask them to choose one from the supported list:

Step 3: Collect Provider-Specific Credentials

1. Based on the chosen provider, collect the required credentials from the user. Each provider requires different configuration values:

Basic Auth (JWT)

• Ask the user for initial user credentials (username:password pairs, comma-separated)
• Ask for a JWT issuer name (default: the project name)
• Ask for a JWT audience name (default: the project name)
• A hash secret and JWT secret are auto-generated

Auth0

• Ask for the Auth0 Domain (e.g. your-tenant.auth0.com)
• Ask for the Client ID from the Auth0 application
• Ask for the Client Secret from the Auth0 application
• Ask for the API Audience (e.g. https://your-api.example.com)
• Optionally, Auth0 supports additional options like role-based access control and custom claims

Supabase

• Ask for the Supabase project URL (e.g. https://your-project.supabase.co)
• Ask for the Supabase anon/public API key
• Optionally, ask for the legacy JWT secret (for direct JWT verification)
• Supabase supports additional options like WorkOS SSO integration

Clerk

• Ask for the Clerk Publishable Key (starts with pk_)
• Ask for the Clerk Secret Key (starts with sk_)
• Clerk supports additional options like organization-based access

GitHub OAuth

• Ask for the GitHub OAuth App Client ID
• Ask for the GitHub OAuth App Client Secret
• Ask for the Redirect URI (e.g. https://localhost:5001/callback)

Authelia

• Ask for the Authelia instance URL (e.g. https://auth.example.com)

Microsoft Entra ID

• Ask for the Tenant ID
• Ask for the Application (Client) ID
• Ask for the Client Secret

Step 4: Generate the Auth Configuration

1. The auth provider setup involves:

• Adding the required NuGet package for the provider
• Storing secrets in dotnet user secrets (with the provider-specific prefix)
• Updating Program.cs with server.UseAuth<[ProviderClassName]>()

1. Initialize user secrets for the project:

dotnet user-secrets init

1. Set each required secret using dotnet user-secrets set. For example:

dotnet user-secrets set "Auth0:Domain" "your-tenant.auth0.com"
dotnet user-secrets set "Auth0:ClientId" "your-client-id"

1. Consult the specific auth provider documentation (via https://docs.ivy.app/sitemap.xml or documentation markdown endpoints) if you need details about the NuGet package name, the provider class name, or the Program.cs registration pattern for the chosen provider.

Step 5: Verify

1. Run dotnet build to verify everything compiles. Fix any errors.

1. If the project is in a git repository, create a commit with a descriptive message, for example: "Added [ProviderDisplayName] authentication."

1. Tell the user the auth provider is ready and summarize what was configured:

• Auth provider package added
• Secrets stored with the provider prefix
• Program.cs updated with the auth registration

Recovery

If the setup fails:

1. Diagnose the root cause (invalid credentials, auth provider not configured, network issues):

• For invalid credentials: verify API keys, tokens, or OAuth client credentials are correct
• For provider config issues: check that the auth provider is registered in the app's configuration
• For network issues: verify the auth provider endpoint is accessible

1. After fixing the underlying issue, either retry using the /ivy-create-auth-connection skill from scratch, or manually create the auth provider class and register it in Program.cs.

1. Consult the provider documentation endpoints for provider-specific guidance.

Post-run: Evaluate and Improve

After completing the task:

1. Evaluate: Did the build succeed? Were there compilation errors, unexpected behavior, or manual corrections needed during this run?
2. Update learnings: If anything required correction or was surprising, append a concise entry to .ivy/learnings/ivy-create-auth-connection.md (create the file and .ivy/learnings/ directory if they don't exist). Each entry should note: the date, what went wrong, why, and what to do differently next time.
3. Skip if clean: If everything succeeded without issues, do not update the learnings file.