> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure & Microsoft 365

> Connect to Microsoft services with OAuth or Service Principal authentication

Noxus supports two authentication methods for Microsoft 365 integrations:

1. **OAuth (User-Delegated)** - Authenticate as a specific user
2. **Service Principal (Application)** - Authenticate as an application with organization-wide access

Both methods connect to Microsoft's identity platform to access Microsoft Graph API and other Microsoft services.

## Supported Microsoft 365 Services

| Service                           | OAuth | Service Principal |
| :-------------------------------- | :---- | :---------------- |
| **Outlook**                       | ✅ Yes | ✅ Yes             |
| **Microsoft Teams**               | ✅ Yes | ✅ Yes             |
| **OneDrive**                      | ✅ Yes | ✅ Yes             |
| **SharePoint**                    | ✅ Yes | ✅ Yes             |
| **Dynamics 365 CRM**              | ❌ No  | ✅ Yes             |
| **Dynamics 365 Field Service**    | ❌ No  | ✅ Yes             |
| **Dynamics 365 Business Central** | ❌ No  | ✅ Yes             |

***

## Authentication Method 1: OAuth (User-Delegated)

### Description

OAuth authentication allows Noxus to perform actions on behalf of a specific user. The user grants permission through an interactive consent screen, and Noxus can then access resources that user has access to.

### When to Use

<CardGroup cols={2}>
  <Card title="Use OAuth When" icon="user-check">
    * Actions should appear as coming from a specific user
    * Access should be limited to what the user can see
    * User accountability is required for audit trails
    * You only need access to one user's data
  </Card>

  <Card title="Characteristics" icon="info">
    * **Permission Type**: Delegated (user context)
    * **User Interaction**: Required during setup
    * **Access Scope**: Limited to user's accessible resources
    * **Token Management**: Automatic refresh
    * **Best For**: User-specific workflows, personal automation
  </Card>
</CardGroup>

### Authentication Flow

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant NF as Noxus Frontend
    participant ME as Microsoft Entra ID
    participant NB as Noxus Backend
    participant MG as Microsoft Graph API

    Note over U,MG: Initial Setup
    U->>NF: Click "Connect Service"
    NF->>ME: Redirect to consent screen
    ME->>U: Display permission request
    U->>ME: Approve permissions
    ME->>NF: Return authorization code
    NF->>NB: Complete connection
    NB->>NB: Store connection securely

    Note over U,MG: When running a workflow...
    NB->>ME: Request access token
    ME->>NB: Return valid token
    NB->>MG: API request with token
    MG->>NB: Return data
```

### Setup Process

<Steps>
  <Step title="Navigate to Integrations">
    Go to Integrations in your Noxus workspace
  </Step>

  <Step title="Find Microsoft Service">
    Select the Microsoft service you want to connect (Outlook, Teams, OneDrive, or SharePoint)
  </Step>

  <Step title="Click Connect">
    Click the Connect button for OAuth authentication
  </Step>

  <Step title="Sign In">
    Sign in with your Microsoft account when prompted
  </Step>

  <Step title="Approve Permissions">
    Review and approve the requested permissions
  </Step>

  <Step title="Complete">
    Connection is now active and ready to use
  </Step>
</Steps>

***

## Authentication Method 2: Service Principal (Application)

### Description

Service Principal authentication uses an Azure application identity with administrator-approved permissions. This enables organization-wide access without requiring individual user consent for each operation.

### When to Use

<CardGroup cols={2}>
  <Card title="Use Service Principal When" icon="server">
    * Running background automation without user involvement
    * Need fine-grained control of which permissions/entities can be accessed
    * Access to resources across multiple users
    * Organization-wide operations
    * Scheduled tasks and system integrations
  </Card>

  <Card title="Characteristics" icon="info">
    * **Permission Type**: Application (organization context)
    * **User Interaction**: None required after setup
    * **Access Scope**: Organization-wide (based on granted permissions)
    * **Token Management**: Automatic
    * **Best For**: Background automation, cross-user operations
  </Card>
</CardGroup>

### Authentication Flow

```mermaid theme={null}
sequenceDiagram
    participant AA as Azure Administrator
    participant AP as Azure Portal
    participant NP as Noxus Platform
    participant ME as Microsoft Entra ID
    participant MG as Microsoft Graph API

    Note over AA,MG: One-Time Setup
    AA->>AP: Register application
    AA->>AP: Configure API permissions
    AA->>AP: Grant admin consent
    AA->>AP: Generate client secret
    AA->>NP: Enter credentials

    Note over AA,MG: Automated Execution
    NP->>ME: Request token (client credentials)
    ME->>NP: Return access token
    NP->>MG: API request with token
    MG->>NP: Return data
```

***

## Azure Setup Requirements

### Step 1: Register an Application

<Steps>
  <Step title="Open Azure Portal">
    Go to [Azure Portal](https://portal.azure.com)
  </Step>

  <Step title="Navigate to App Registrations">
    Go to Microsoft Entra ID → App registrations
  </Step>

  <Step title="Create New Registration">
    Click **New registration**
  </Step>

  <Step title="Configure Application">
    * Enter a name for the application
    * Select "Accounts in this organizational directory only"
    * Click **Register**
  </Step>
</Steps>

### Step 2: Configure API Permissions

Add the following permissions based on the services you need:

<Tabs>
  <Tab title="Microsoft Graph">
    **For Outlook, Teams, OneDrive, SharePoint:**

    | Service        | Required Permissions                                                          |
    | :------------- | :---------------------------------------------------------------------------- |
    | **Outlook**    | Mail.Read, Mail.Send, Mail.ReadWrite                                          |
    | **Teams**      | Team.ReadBasic.All, Channel.ReadBasic.All, ChannelMessage.Send                |
    | **OneDrive**   | Files.Read.All, Files.ReadWrite.All                                           |
    | **SharePoint** | Sites.Read.All, Sites.ReadWrite.All (or Sites.Selected for restricted access) |
  </Tab>

  <Tab title="Dynamics 365">
    **For Dynamics 365 services:**

    | Service              | Required Permissions                                     |
    | :------------------- | :------------------------------------------------------- |
    | **Dynamics 365 CRM** | user\_impersonation or appropriate Dataverse permissions |
    | **Field Service**    | user\_impersonation or appropriate Dataverse permissions |
    | **Business Central** | Financials.ReadWrite.All                                 |
  </Tab>
</Tabs>

### Step 3: Grant Admin Consent

<Steps>
  <Step title="Open API Permissions">
    In your app registration, go to **API permissions**
  </Step>

  <Step title="Grant Consent">
    Click **Grant admin consent for \[Your Organization]**
  </Step>

  <Step title="Confirm">
    Confirm the action
  </Step>
</Steps>

<Warning>
  Admin consent is required for Service Principal authentication. Only Azure administrators can grant this consent.
</Warning>

### Step 4: Create Client Secret

<Steps>
  <Step title="Navigate to Secrets">
    Go to **Certificates & secrets**
  </Step>

  <Step title="Create New Secret">
    Click **New client secret**
  </Step>

  <Step title="Set Expiration">
    Set an expiration period (6 months, 12 months, or 24 months)
  </Step>

  <Step title="Copy Secret">
    Copy the secret value immediately (it won't be shown again)
  </Step>
</Steps>

<Warning>
  Store the client secret securely. You won't be able to retrieve it after leaving the page.
</Warning>

### Step 5: Gather Required Information

You will need:

| Credential        | Location                                |
| :---------------- | :-------------------------------------- |
| **Tenant ID**     | Found in Microsoft Entra ID overview    |
| **Client ID**     | Found in your app registration overview |
| **Client Secret** | The value you copied in Step 4          |

***

## Noxus Configuration

<Steps>
  <Step title="Navigate to Integrations">
    Go to Integrations in your Noxus workspace
  </Step>

  <Step title="Select Service Principal">
    Select the Service Principal version of your desired service
  </Step>

  <Step title="Enter Credentials">
    Enter your credentials:

    * Tenant ID
    * Client ID
    * Client Secret
  </Step>

  <Step title="Additional Configuration">
    For each integration there may be additional configurations, such as granular permissions used, or resource limitations
  </Step>

  <Step title="Save">
    Click Save to complete the connection
  </Step>
</Steps>

***

## Comparison: OAuth vs Service Principal

```mermaid theme={null}
graph TB
    subgraph OAuth["OAuth (User-Delegated)"]
        O1[User Identity]
        O2[Interactive Setup]
        O3[User-Scoped Access]
        O4[Personal Resources]
    end
    
    subgraph SP["Service Principal (Application)"]
        S1[Application Identity]
        S2[Admin Configuration]
        S3[Organization-Wide Access]
        S4[All Accessible Resources]
    end
    
    OAuth -.->|Best for| U1[User-initiated workflows]
    SP -.->|Best for| U2[Automated processes]
```

### Feature Comparison

| Feature              | OAuth                  | Service Principal                    |
| :------------------- | :--------------------- | :----------------------------------- |
| **Identity**         | Individual user        | Application                          |
| **Setup**            | User clicks to connect | Admin configures in Azure            |
| **Consent**          | User approves          | Admin pre-approves                   |
| **Access Level**     | User's resources only  | Organization-wide                    |
| **User Interaction** | Required at setup      | Not required                         |
| **Typical Use Case** | Personal automation    | Background jobs, org-wide operations |
| **Maintenance**      | Minimal                | Secret rotation required             |

### Decision Tree

```mermaid theme={null}
graph TD
    A[Which authentication method?] --> B{Who performs the action?}
    B -->|Specific user| C{Need user context?}
    B -->|System/Automation| D{Organization-wide access needed?}
    C -->|Yes| E[OAuth]
    C -->|No| D
    D -->|Yes| F[Service Principal]
    D -->|No| E
```

***

## Advanced: SharePoint Sites.Selected Permission

For use-cases requiring restricted access to specific SharePoint sites, Noxus supports the `Sites.Selected` permission model.

<Tabs>
  <Tab title="Sites.Read.All / Sites.ReadWrite.All">
    **Full Access Model**

    * Access to all SharePoint sites in the organization
    * Simpler configuration
    * Broader permissions
    * No site-specific configuration needed
  </Tab>

  <Tab title="Sites.Selected">
    **Restricted Access Model**

    * Access only to specified sites
    * Better security posture
    * Granular control
    * Requires configuration of allowed site URLs
  </Tab>
</Tabs>

### Configuration Options

| Setting                           | Description                                             |
| :-------------------------------- | :------------------------------------------------------ |
| **Allowed Site URLs**             | List of SharePoint site URLs the integration can access |
| **Use Sites.Selected Permission** | When enabled, only fetches the specified sites          |

<Tip>
  Use `Sites.Selected` for better security when you don't need access to all SharePoint sites.
</Tip>

***

## Dynamics 365 Integrations

<Warning>
  Dynamics 365 services only support Service Principal authentication.
</Warning>

### Dynamics 365 CRM and Field Service

```mermaid theme={null}
graph LR
    N[Noxus] -->|Client Credentials| ME[Microsoft Entra ID]
    ME -->|Access Token| N
    N -->|Authenticated Request| D[Dataverse API]
    D -->|CRM Data| N
    D -->|Field Service Data| N
```

**Supported Operations:**

* Accounts, Contacts, Leads, Opportunities (CRM)
* Work Orders, Bookings, Resources (Field Service)
* Custom entities via Dataverse

### Dynamics 365 Business Central

```mermaid theme={null}
graph LR
    N[Noxus] -->|Client Credentials| ME[Microsoft Entra ID]
    ME -->|Access Token| N
    N -->|Authenticated Request| BC[Business Central API]
    BC -->|Customers| N
    BC -->|Invoices| N
    BC -->|Sales Orders| N
    BC -->|Items| N
```

**Supported Operations:**

* Customer management
* Sales invoice creation and posting
* Sales order management
* Item and inventory queries
* Payment tracking

***

## Security Best Practices

<Tabs>
  <Tab title="For OAuth">
    **Protecting User-Delegated Access:**

    <Steps>
      <Step title="Regular Reviews">
        Regularly review connected applications in your Microsoft account
      </Step>

      <Step title="Remove Unused">
        Disconnect services you no longer use
      </Step>

      <Step title="Permission Awareness">
        Be cautious about the permissions you approve
      </Step>

      <Step title="Monitor Activity">
        Review activity logs for unexpected access
      </Step>
    </Steps>
  </Tab>

  <Tab title="For Service Principal">
    **Securing Application Access:**

    <Steps>
      <Step title="Minimum Permissions">
        Use the minimum permissions necessary for your use case
      </Step>

      <Step title="Rotate Secrets">
        Rotate client secrets before they expire
      </Step>

      <Step title="Monitor Usage">
        Monitor API usage through Azure logs
      </Step>

      <Step title="Restricted Access">
        Consider using Sites.Selected for SharePoint when full access is not needed
      </Step>

      <Step title="Documentation">
        Document which applications have admin consent
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Failed" icon="circle-x">
    **Possible Causes:**

    * Invalid credentials (Tenant ID, Client ID, or Client Secret)
    * Client secret expired
    * Missing API permissions
    * Admin consent not granted

    **Solutions:**

    * Verify credentials are correct
    * Generate a new client secret if expired
    * Check API permissions in Azure Portal
    * Ensure admin consent has been granted
  </Accordion>

  <Accordion title="Permission Denied Errors" icon="shield-x">
    **Possible Causes:**

    * Missing required API permissions
    * Admin consent revoked
    * Resource access restrictions
    * User doesn't have access (OAuth)

    **Solutions:**

    * Review and add missing permissions in Azure
    * Re-grant admin consent
    * Check resource-level permissions
    * Verify user has access to the resource
  </Accordion>

  <Accordion title="Token Refresh Failed" icon="refresh-cw">
    **Possible Causes:**

    * Client secret expired
    * App registration deleted
    * Permissions changed
    * User revoked consent (OAuth)

    **Solutions:**

    * Generate and update client secret
    * Verify app registration still exists
    * Review permission changes
    * Re-authenticate with OAuth
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Google Workspace" icon="mail" href="/integrations/providers/google">
    Connect Gmail, Drive, Sheets, and more
  </Card>

  <Card title="Atlassian" icon="trello" href="/integrations/providers/atlassian">
    Integrate Jira and Confluence
  </Card>

  <Card title="All Integrations" icon="blocks" href="/integrations/catalog">
    Browse the complete catalog
  </Card>
</CardGroup>