@ivannxbt/ai-config 0.1.0

package/.agents/skills/entra-app-registration/references/console-app-example.md

@@ -0,0 +1,392 @@
+# Console Application Examples
+
+This document provides complete working examples of console applications that authenticate with Microsoft Entra ID using MSAL (Microsoft Authentication Library).
+
+## Table of Contents
+
+- [C# (.NET) Example](#c-net-example)
+- [Python Example](#python-example)
+- [JavaScript (Node.js) Example](#javascript-nodejs-example)
+
+## C# (.NET) Example
+
+### Prerequisites
+
+```bash
+dotnet new console -n EntraAuthConsole
+cd EntraAuthConsole
+dotnet add package Microsoft.Identity.Client
+```
+
+### Complete Code
+
+```csharp
+using Microsoft.Identity.Client;
+using System;
+using System.Linq;
+using System.Threading.Tasks;
+
+namespace EntraAuthConsole
+{
+    class Program
+    {
+        // Configuration - replace with your values
+        private const string ClientId = "YOUR_APPLICATION_CLIENT_ID";
+        private const string TenantId = "YOUR_TENANT_ID";
+        private static readonly string[] Scopes = new[] { "User.Read" };
+
+        static async Task Main(string[] args)
+        {
+            try
+            {
+                // Build the MSAL client
+                var app = PublicClientApplicationBuilder
+                    .Create(ClientId)
+                    .WithAuthority(AzureCloudInstance.AzurePublic, TenantId)
+                    .WithRedirectUri("http://localhost")
+                    .Build();
+
+                // Try to get token silently from cache first
+                var accounts = await app.GetAccountsAsync();
+                AuthenticationResult result;
+
+                try
+                {
+                    result = await app.AcquireTokenSilent(Scopes, accounts.FirstOrDefault())
+                        .ExecuteAsync();
+                    Console.WriteLine("Token acquired from cache");
+                }
+                catch (MsalUiRequiredException)
+                {
+                    // Interactive authentication required
+                    result = await app.AcquireTokenInteractive(Scopes)
+                        .WithPrompt(Prompt.SelectAccount)
+                        .ExecuteAsync();
+                    Console.WriteLine("Token acquired interactively");
+                }
+
+                // Display user information
+                Console.WriteLine($"\nWelcome, {result.Account.Username}!");
+                Console.WriteLine($"Token expires: {result.ExpiresOn}");
+
+                // Call Microsoft Graph API
+                await CallGraphApiAsync(result.AccessToken);
+            }
+            catch (MsalException ex)
+            {
+                Console.WriteLine($"Error acquiring token: {ex.Message}");
+            }
+        }
+
+        private static async Task CallGraphApiAsync(string accessToken)
+        {
+            using var httpClient = new System.Net.Http.HttpClient();
+            httpClient.DefaultRequestHeaders.Authorization = 
+                new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
+
+            var response = await httpClient.GetAsync("https://graph.microsoft.com/v1.0/me");
+            
+            if (response.IsSuccessStatusCode)
+            {
+                var content = await response.Content.ReadAsStringAsync();
+                Console.WriteLine("\nUser profile from Microsoft Graph:");
+                Console.WriteLine(content);
+            }
+            else
+            {
+                Console.WriteLine($"API call failed: {response.StatusCode}");
+            }
+        }
+    }
+}
+```
+
+### Run the Application
+
+```bash
+dotnet run
+```
+
+### Device Code Flow (for headless scenarios)
+
+```csharp
+// Use this for servers or devices without a browser
+result = await app.AcquireTokenWithDeviceCode(Scopes, deviceCodeResult =>
+{
+    Console.WriteLine(deviceCodeResult.Message);
+    return Task.CompletedTask;
+}).ExecuteAsync();
+```
+
+---
+
+## Python Example
+
+### Prerequisites
+
+```bash
+pip install msal requests
+```
+
+### Complete Code
+
+```python
+import msal
+import requests
+import json
+
+# Configuration - replace with your values
+CLIENT_ID = "YOUR_APPLICATION_CLIENT_ID"
+TENANT_ID = "YOUR_TENANT_ID"
+AUTHORITY = f"https://login.microsoftonline.com/{TENANT_ID}"
+SCOPES = ["User.Read"]
+
+def acquire_token_interactive():
+    """Acquire token using interactive flow (opens browser)"""
+    app = msal.PublicClientApplication(
+        CLIENT_ID,
+        authority=AUTHORITY
+    )
+    
+    # Try to get token from cache first
+    accounts = app.get_accounts()
+    result = None
+    
+    if accounts:
+        # Try silent acquisition
+        result = app.acquire_token_silent(SCOPES, account=accounts[0])
+        if result:
+            print("Token acquired from cache")
+    
+    if not result:
+        # Interactive authentication
+        result = app.acquire_token_interactive(
+            scopes=SCOPES,
+            prompt="select_account"
+        )
+        print("Token acquired interactively")
+    
+    return result
+
+def acquire_token_device_code():
+    """Acquire token using device code flow (for headless scenarios)"""
+    app = msal.PublicClientApplication(
+        CLIENT_ID,
+        authority=AUTHORITY
+    )
+    
+    flow = app.initiate_device_flow(scopes=SCOPES)
+    
+    if "user_code" not in flow:
+        raise Exception(f"Failed to create device flow: {flow.get('error_description')}")
+    
+    # Display instructions to user
+    print(flow["message"])
+    
+    # Wait for user to complete authentication
+    result = app.acquire_token_by_device_flow(flow)
+    return result
+
+def call_graph_api(access_token):
+    """Call Microsoft Graph API with access token"""
+    headers = {
+        'Authorization': f'Bearer {access_token}',
+        'Content-Type': 'application/json'
+    }
+    
+    response = requests.get(
+        'https://graph.microsoft.com/v1.0/me',
+        headers=headers
+    )
+    
+    if response.status_code == 200:
+        user_data = response.json()
+        print("\nUser profile from Microsoft Graph:")
+        print(json.dumps(user_data, indent=2))
+    else:
+        print(f"API call failed: {response.status_code}")
+        print(response.text)
+
+def main():
+    # Choose authentication method
+    print("Select authentication method:")
+    print("1. Interactive (opens browser)")
+    print("2. Device code (for headless scenarios)")
+    choice = input("Enter choice (1 or 2): ")
+    
+    try:
+        if choice == "1":
+            result = acquire_token_interactive()
+        elif choice == "2":
+            result = acquire_token_device_code()
+        else:
+            print("Invalid choice")
+            return
+        
+        if "access_token" in result:
+            print(f"\nWelcome, {result.get('id_token_claims', {}).get('preferred_username', 'User')}!")
+            print(f"Token expires in: {result.get('expires_in')} seconds")
+            
+            # Call Microsoft Graph API
+            call_graph_api(result["access_token"])
+        else:
+            print(f"Error acquiring token: {result.get('error')}")
+            print(f"Description: {result.get('error_description')}")
+    
+    except Exception as e:
+        print(f"Error: {e}")
+
+if __name__ == "__main__":
+    main()
+```
+
+### Run the Application
+
+```bash
+python console_app.py
+```
+
+---
+
+## JavaScript (Node.js) Example
+
+### Prerequisites
+
+```bash
+npm init -y
+npm install @azure/msal-node axios
+```
+
+### Complete Code
+
+```javascript
+const msal = require('@azure/msal-node');
+const axios = require('axios');
+
+// Configuration - replace with your values
+const config = {
+    auth: {
+        clientId: "YOUR_APPLICATION_CLIENT_ID",
+        authority: "https://login.microsoftonline.com/YOUR_TENANT_ID",
+    }
+};
+
+const scopes = ["User.Read"];
+
+// Interactive authentication (opens browser)
+async function acquireTokenInteractive() {
+    const pca = new msal.PublicClientApplication(config);
+    
+    const authCodeUrlParameters = {
+        scopes: scopes,
+        redirectUri: "http://localhost:3000",
+    };
+
+    // This opens the browser for authentication
+    const response = await pca.acquireTokenInteractive(authCodeUrlParameters);
+    return response;
+}
+
+// Device code flow (for headless scenarios)
+async function acquireTokenDeviceCode() {
+    const pca = new msal.PublicClientApplication(config);
+    
+    const deviceCodeRequest = {
+        deviceCodeCallback: (response) => {
+            console.log("\n" + response.message);
+        },
+        scopes: scopes,
+    };
+
+    const response = await pca.acquireTokenByDeviceCode(deviceCodeRequest);
+    return response;
+}
+
+// Client credentials flow (service-to-service, no user)
+async function acquireTokenClientCredentials() {
+    const confidentialConfig = {
+        auth: {
+            clientId: "YOUR_APPLICATION_CLIENT_ID",
+            authority: "https://login.microsoftonline.com/YOUR_TENANT_ID",
+            clientSecret: "YOUR_CLIENT_SECRET", // From app registration
+        }
+    };
+    
+    const cca = new msal.ConfidentialClientApplication(confidentialConfig);
+    
+    const clientCredentialRequest = {
+        scopes: ["https://graph.microsoft.com/.default"],
+    };
+
+    const response = await cca.acquireTokenByClientCredential(clientCredentialRequest);
+    return response;
+}
+
+// Call Microsoft Graph API
+async function callGraphApi(accessToken) {
+    const options = {
+        headers: {
+            Authorization: `Bearer ${accessToken}`
+        }
+    };
+
+    try {
+        const response = await axios.get('https://graph.microsoft.com/v1.0/me', options);
+        console.log('\nUser profile from Microsoft Graph:');
+        console.log(JSON.stringify(response.data, null, 2));
+    } catch (error) {
+        console.error('API call failed:', error.response?.status, error.message);
+    }
+}
+
+// Main function
+async function main() {
+    console.log("Select authentication method:");
+    console.log("1. Device code flow (recommended for CLI)");
+    console.log("2. Client credentials (service-to-service)");
+    
+    // For demonstration, using device code flow
+    // In production, get user input with readline or similar
+    const choice = "1";
+    
+    try {
+        let result;
+        
+        if (choice === "1") {
+            result = await acquireTokenDeviceCode();
+        } else if (choice === "2") {
+            result = await acquireTokenClientCredentials();
+        }
+        
+        if (result.accessToken) {
+            console.log('\nAuthentication successful!');
+            console.log(`Token expires: ${new Date(result.expiresOn)}`);
+            
+            // Call Microsoft Graph API
+            await callGraphApi(result.accessToken);
+        } else {
+            console.error('Failed to acquire token');
+        }
+    } catch (error) {
+        console.error('Error:', error.message);
+    }
+}
+
+main();
+```
+
+### Run the Application
+
+```bash
+node console_app.js
+```
+
+## Next Steps
+
+- Review [oauth-flows.md](oauth-flows.md) for flow details
+- See [api-permissions.md](api-permissions.md) for permission setup
+- Check [troubleshooting.md](troubleshooting.md) for common issues
+
+## Additional Resources
+
+- [MSAL Libraries](https://learn.microsoft.com/entra/msal/)

package/.agents/skills/entra-app-registration/references/first-app-registration.md

@@ -0,0 +1,243 @@
+# First App Registration - Step-by-Step Guide
+
+This guide walks you through creating your first Microsoft Entra app registration from scratch.
+
+## Overview
+
+You'll learn how to:
+1. Create an app registration in Azure Portal
+2. Configure authentication settings
+3. Add API permissions
+4. Create client credentials
+5. Test the authentication flow
+
+## Prerequisites
+
+- Azure subscription (free tier works)
+- Azure Portal access: https://portal.azure.com
+- Basic understanding of your application type (web, mobile, service)
+
+## Step 1: Navigate to App Registrations
+
+1. Open [Azure Portal](https://portal.azure.com)
+2. Search for **"Microsoft Entra ID"**
+3. In the left menu, click **"App registrations"**
+4. Click **"+ New registration"** at the top
+
+## Step 2: Register Your Application
+
+You'll see a form with several fields:
+
+### Application Name
+- **What to enter:** A descriptive name for your app
+- **Example:** "My First Console App" or "Product Inventory API"
+- **Tip:** Use a name that clearly identifies the purpose
+
+### Supported Account Types
+
+Choose who can use your application:
+
+| Option | When to Use |
+|--------|-------------|
+| **Accounts in this organizational directory only (Single tenant)** | Only users from the same tenant of this app registration need access |
+| **Accounts in any organizational directory (Multi-tenant)** | Users from multiple organization tenants need access |
+| **Accounts in any organizational directory + Personal Microsoft accounts** | Users from multiple organization tenants and MSA users need access |
+| **Personal Microsoft accounts only** | Only MSA users need access |
+
+**Note:** Once selected, users whose account type is not allowed will get errors when trying to get access token for the app registration.
+
+### Redirect URI (optional)
+
+The redirect URI is where authentication responses are sent.
+
+**Platform:** Select the type:
+- **Web** - Server-side web apps
+- **Single-page application (SPA)** - React, Angular, Vue apps
+- **Public client/native** - Mobile, desktop, console apps
+
+**URI examples:**
+- Web app: `https://localhost:5001/signin-oidc`
+- SPA: `http://localhost:3000`
+- Console/Desktop: `http://localhost`
+
+**For your first app:** Select **"Public client/native"** and enter `http://localhost`
+
+### Click "Register"
+
+After clicking, you'll be redirected to your app's overview page.
+
+## Step 3: Save Important Information
+
+On the **Overview** page, you'll see critical information. **Copy and save these values:**
+
+### Application (client) ID
+- **What it is:** Unique identifier for your app
+- **Format:** `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` (GUID)
+- **When you need it:** Every time your app authenticates
+- **Where to save:** Environment variables, configuration file
+
+### Directory (tenant) ID
+- **What it is:** Unique identifier for your Azure AD tenant
+- **Format:** `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` (GUID)
+- **When you need it:** Constructing authentication URLs
+
+### Example values to save:
+```bash
+# Save these in a secure location
+APPLICATION_CLIENT_ID="12345678-1234-1234-1234-123456789012"
+TENANT_ID="87654321-4321-4321-4321-210987654321"
+```
+
+## Step 4: Configure Authentication (Optional)
+
+Click **"Authentication"** in the left menu.
+
+### Advanced Settings
+
+**Allow public client flows:**
+- **What it is:** Enables device code flow, resource owner password flow
+- **For console apps:** Turn this **ON**
+- **For web apps:** Keep **OFF**
+
+### Supported account types
+
+You can change this later if needed.
+
+### Logout URL (optional)
+
+Where to redirect users after logout.
+
+**Click "Save"** at the top if you made changes.
+
+## Step 5: Add API Permissions
+
+Click **"API permissions"** in the left menu.
+
+### Default Permission
+
+You'll see one default permission:
+- **Microsoft Graph → User.Read (Delegated)**
+
+This allows your app to read the signed-in user's profile.
+
+### Add More Permissions
+
+1. Click **"+ Add a permission"**
+2. Select **"Microsoft Graph"**
+3. Choose **"Delegated permissions"** (for user context)
+4. Search for and select permissions you need:
+   - **User.Read** - Read user profile (already added)
+   - **Mail.Read** - Read user's mail
+   - **Calendars.Read** - Read user's calendar
+
+5. Click **"Add permissions"**
+
+### Admin Consent
+
+Some permissions require admin consent:
+- If you're an admin: Click **"Grant admin consent for [Your Org]"**
+- If you're not: Ask your admin to grant consent
+
+**Status indicator:**
+- ✅ Green checkmark = Granted
+- ⚠️ Yellow warning = Not granted (may still work for user consent)
+
+## Step 6: Create Client Secret (If Needed)
+
+**Skip this if:** You're building a desktop/mobile/console app (public client)
+
+**Do this if:** You're building a web app, API, or service (confidential client)
+
+1. Click **"Certificates & secrets"** in the left menu
+2. Click **"+ New client secret"**
+3. Enter a description: "Development Secret"
+4. Choose expiration:
+   - **Recommended for development:** 6 months
+   - **For production:** 12-24 months (set up rotation)
+5. Click **"Add"**
+
+**⚠️ CRITICAL:** Copy the secret **Value** immediately!
+- It's only shown once
+- You cannot retrieve it later
+- If you lose it, create a new one
+
+```bash
+# Save this securely (example)
+CLIENT_SECRET="abc123~defGHI456jklMNO789pqrSTU"
+```
+
+**Security tips:**
+- Never commit secrets to source control
+- Use Azure Key Vault for production
+- Use environment variables for development
+
+## Step 7: Test Your App Registration
+
+### Option A: Quick Test with Azure CLI
+
+```bash
+# Set your values
+CLIENT_ID="your-client-id-here"
+TENANT_ID="your-tenant-id-here"
+
+# Interactive login
+az login --scope "https://graph.microsoft.com/.default"
+
+# Get an access token
+az account get-access-token --resource "https://graph.microsoft.com"
+```
+
+### Option B: Test with MSAL Library
+
+See the complete code example in [console-app-example.md](console-app-example.md)
+
+### Expected Results
+
+**Success:**
+- Browser opens for authentication (or device code shown)
+- You authenticate with your Azure AD account
+- Access token is returned
+- You can call Microsoft Graph API
+
+**Common first-time issues:**
+- Redirect URI mismatch → Double-check URI in Authentication settings
+- Insufficient permissions → Add required API permissions
+- User consent required → Grant admin consent or user must consent
+
+**Tip:** Once you get the access token, you can use [jwt.ms](https://jwt.ms) to decode it and inspect its claims.
+
+## Step 8: Review Configuration
+
+### Checklist
+
+- ✅ App registered with clear name
+- ✅ Application ID and Tenant ID saved securely
+- ✅ Redirect URI configured correctly
+- ✅ API permissions added
+- ✅ Admin consent granted (if required)
+- ✅ Client secret created and saved (if needed)
+- ✅ Authentication tested successfully
+
+## Next Steps
+
+- In your client app, implement the OAuth flow to acquire access tokens for your app registration.
+- In your server app, implement token validation to protect your resources.
+
+## Troubleshooting
+
+### Redirect URI mismatch"
+
+**Solution:**
+- Check Authentication → Redirect URIs
+- Ensure exact match (case-sensitive, trailing slash matters)
+- Ensure correct platform (Web vs SPA vs Public client)
+
+### User consent required
+
+**Solution:**
+- Grant admin consent in API permissions
+- Or have user consent during first login
+
+## Additional Resources
+
+- [Microsoft Entra ID Documentation](https://learn.microsoft.com/en-us/entra/identity-platform/)