Edmund AI Dokumentace
/NÁVODY

Část A — Prvotní nastavení

Registrace aplikace v Microsoft Entra ID, udělení přístupu pro čtení k jedné site a zadání čtyř hodnot v Edmundovi.

Část A se provádí jednou, administrátory zákazníka. Výsledkem jsou čtyři hodnoty, které pak uživatel s rolí Administrator zadá v aplikaci; od té chvíle je všechno samoobslužné.

Potřebné role: Global Administrator nebo Privileged Role Administrator pro udělení souhlasu s oprávněními v kroku 3 a SharePoint Administrator pro vytvoření grantu na site v kroku 4.

1. Registrace aplikace v Entra ID

  1. Otevřete App registrations

    Přejděte na entra.microsoft.com, pak Applications → App registrations → New registration.

  2. Zaregistrujte aplikaci

    Pojmenujte ji edmund-sharepoint-readonly. Supported account types nastavte na Single tenant. Redirect URI nechte prázdné — aplikace se přihlašuje sama za sebe, ne za uživatele.

    Klikněte na Register.

  3. Zkopírujte identifikátory

    Na stránce Overview zkopírujte Application (client) ID a Directory (tenant) ID, u každého pole kopírovacím tlačítkem. Object ID na téže stránce není záměnný ani s jedním z nich.

2. Vytvoření client secretu

Přejděte na Certificates & secrets → New client secret. Zadejte popis a expiraci; 12 měsíců je rozumný kompromis mezi náročností rotace a rizikem.

Warning

Hodnotu secretu (value) zkopírujte okamžitě. Azure ji zobrazí jednou. Secret ID vedle ní není secret a k autentizaci nepostačí.

Datum expirace si zaznamenejte. Expirovaný secret zastaví synchronizaci bez jakékoli chyby v Edmundovi — dokumenty prostě přestanou přicházet. Výměna je popsaná v kapitole 13.

3. Oprávnění Microsoft Graph

Přejděte na API permissions → Add a permission → Microsoft Graph → Application permissions. Ne Delegated — není žádný přihlášený uživatel.

Vyberte jedno:

OprávněníRozsah
Sites.SelectedDoporučeno. Bez explicitního grantu nedává přístup nikam, povoluje se site po site
Sites.Read.AllČtení všech SharePointových sites v tenantu
Warning

Vedle nich se nabízí Files.SelectedOperations.Selected a jeho popis vypadá jako užší varianta téhož. Je to jiný model — přístup k jednotlivým souborům nasdíleným aplikaci — a konektor přes něj fungovat nemůže.

Klikněte na Grant admin consent. Bez souhlasu nemá aplikace přístup, ať je v seznamu cokoli. Oprávnění je nastavené, když je Sites.Selected v seznamu uvedené jako Granted for <organizace>.

4. Udělení přístupu k jedné site

Note

Tento krok se týká jen Sites.Selected. U Sites.Read.All je oprávnění účinné hned po udělení souhlasu a pokrývá všechny sites.

Grant je na jednu site a pokrývá celý její obsah. Site vytvořená pro Edmunda ho proto drží užší než grant na root site tenantu, který by odhalil i knihovnu intranetu.

Sites.Selected sám o sobě nedává nic. Musí platit tři podmínky: oprávnění je odsouhlasené, na site existuje grant a token nese daný scope.

Oba dotazy se provádějí v Graph Exploreru, přihlášeném jako administrátor tenantu, který musí mít odsouhlasená delegovaná oprávnění Sites.Read.All a Sites.FullControl.All.

  1. Zjistěte identifikátor site
    GET https://graph.microsoft.com/v1.0/sites/{hostname}:/sites/{site-name}

    id v odpovědi je site ID — hostname a dva GUIDy oddělené čárkami, které se v dalším dotazu použijí celé.

  2. Udělte aplikaci přístup pro čtení
    POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
    Content-Type: application/json
    
    {
      "roles": ["read"],
      "grantedToIdentities": [{
        "application": {
          "id": "{application-client-id}",
          "displayName": "edmund-sharepoint-readonly"
        }
      }]
    }

    Grant potvrzuje odpověď 201 Created. Odpověď vrací i display name aplikace, což je nejrychlejší kontrola, že se identifikátor přeložil na zamýšlenou aplikaci.

Odebrání grantu později:

GET https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
DELETE https://graph.microsoft.com/v1.0/sites/{site-id}/permissions/{permission-id}

Smazání potvrzuje 204 No Content. Smazání grantu odebere přístup k té jedné site; odebrání souhlasu v Entra ID odebere přístup ke všem sites naráz.

5. Zjištění drive ID

Edmund potřebuje identifikátor knihovny dokumentů, ve které dokumenty leží.

GET https://graph.microsoft.com/v1.0/sites/{site-id}/drives

Knihovna se v odpovědi jmenuje Documents; její id je drive ID. Pokud má site knihoven více, pošlete tu, ve které jsou sledované složky.

Aplikace si ho může přečíst i sama pod svými přihlašovacími údaji, čímž se zároveň ověří secret i grant:

import msal
import requests

TENANT_ID = "YOUR_TENANT_ID"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
SHAREPOINT_HOST = "contoso.sharepoint.com"
SITE_NAME = "sites/edmund-documents"

GRAPH_BASE = "https://graph.microsoft.com/v1.0"


def acquire_token(tenant_id: str, client_id: str, client_secret: str) -> str:
    app = msal.ConfidentialClientApplication(
        client_id,
        authority=f"https://login.microsoftonline.com/{tenant_id}",
        client_credential=client_secret,
    )
    result = app.acquire_token_for_client(
        scopes=["https://graph.microsoft.com/.default"])
    if "access_token" not in result:
        raise RuntimeError(f"Failed to acquire token: {result.get('error_description')}")
    return result["access_token"]


def get_site_id(token: str, host: str, site_name: str) -> str:
    url = f"{GRAPH_BASE}/sites/{host}:/{site_name}"
    resp = requests.get(url, headers={"Authorization": f"Bearer {token}"}, timeout=30)
    resp.raise_for_status()
    return resp.json()["id"]


def get_drive_id(token: str, site_id: str) -> str:
    url = f"{GRAPH_BASE}/sites/{site_id}/drive"
    resp = requests.get(url, headers={"Authorization": f"Bearer {token}"}, timeout=30)
    resp.raise_for_status()
    return resp.json()["id"]


if __name__ == "__main__":
    token = acquire_token(TENANT_ID, CLIENT_ID, CLIENT_SECRET)
    site_id = get_site_id(token, SHAREPOINT_HOST, SITE_NAME)
    print("Site ID: ", site_id)
    print("Drive ID:", get_drive_id(token, site_id))

Skript potřebuje msal a requests:

pip install msal requests

Pokud je skript nepohodlný, drive ID se dá přečíst i v Graph Exploreru voláním výše.

6. Zadání připojení v Edmundovi

Success

Čtyři hodnoty a datum expirace secretu ve vlastní evidenci.

Uživatel s rolí Administrator otevře v Edmundovi Nastavení → Připojení → SharePoint a zadá:

PoleZdroj
Tenant IDDirectory (tenant) ID, krok 1
Client IDApplication (client) ID, krok 1
Client secretKrok 2
Drive IDKrok 5

Edmund hodnoty před uložením ověří proti knihovně. Chybná hodnota se rovnou odmítne a nic se nezapíše; uložené připojení je tedy takové, u kterého je prokázané, že funguje. Secret se potom nikdy nezobrazuje zpět — stránka jen ukazuje, že nějaký je uložený.

Note

Client secret neopouští vaši organizaci. Zadává ho přímo v Edmundovi váš vlastní administrátor, neposílá se nám. Nemusí tedy cestovat e-mailem ani jiným kanálem.

Poznamenejte si datum expirace secretu, aby se dala naplánovat jeho výměna; ta je popsaná v části B, kapitola 13.

Které složky který projekt sleduje, se nastavuje na témže místě, nebo na kartě Integrace v nastavení projektu — část B, kapitola 11. Ani to nevyžaduje účast Edmunda.