SharePoint — część A: konfiguracja początkowa
Rejestracja aplikacji Entra ID, przyznanie odczytu jednej witryny i wprowadzenie czterech parametrów połączenia.
Konfigurację początkową wykonują jednorazowo administratorzy klienta. Uzyskane cztery wartości wprowadza w Edmundzie osoba z rolą Administrator. Dalsza obsługa jest samodzielna.
Do zgody na uprawnienia w kroku 3 potrzebny jest Global Administrator lub Privileged Role Administrator. Do nadania dostępu do witryny w kroku 4 potrzebny jest SharePoint Administrator.
1. Rejestracja aplikacji w Entra ID
- W portalu Entra otwórz Applications → App registrations → New registration.
- Wpisz nazwę
edmund-sharepoint-readonly. Dla Supported account types wybierz Single tenant. Pozostaw pusty adres przekierowania: aplikacja uwierzytelnia siebie, a nie użytkownika. Kliknij Register. - Ze strony Overview skopiuj przyciskami kopiowania Application (client) ID oraz Directory (tenant) ID. Object ID nie zastępuje żadnej z tych wartości.
2. Utworzenie sekretu klienta
Otwórz Certificates & secrets → New client secret. Ustaw opis i termin wygaśnięcia. Okres 12 miesięcy równoważy częstotliwość rotacji i ryzyko.
Natychmiast skopiuj wartość sekretu. Azure pokazuje ją tylko raz. Widoczny obok Secret ID nie jest sekretem i nie pozwala się uwierzytelnić.
Zapisz datę wygaśnięcia. Wygaśnięty sekret zatrzymuje synchronizację: nowe dokumenty przestają docierać, a źródło nie gwarantuje osobnego komunikatu błędu w Edmundzie. Wymianę opisuje część B, rozdział 13.
3. Uprawnienia Microsoft Graph
Otwórz API permissions → Add a permission → Microsoft Graph → Application permissions. Nie wybieraj uprawnień Delegated, ponieważ nie ma zalogowanego użytkownika.
Wybierz jeden wariant:
| Uprawnienie | Zakres |
|---|---|
Sites.Selected | Zalecane. Brak dostępu, dopóki nie zostanie nadany oddzielnie dla witryny |
Sites.Read.All | Odczyt wszystkich witryn SharePoint w dzierżawie |
Files.SelectedOperations.Selected jest innym modelem dostępu do pojedynczych plików udostępnionych aplikacji. Mimo podobnego opisu nie jest obsługiwane przez ten konektor.
Kliknij Grant admin consent. Bez zgody aplikacja nie ma dostępu niezależnie od wpisu na liście. Potwierdzeniem jest stan Granted for <organisation> przy Sites.Selected.
4. Dostęp do jednej witryny
Ten krok dotyczy wyłącznie Sites.Selected. Przy Sites.Read.All zgoda administratora obejmuje wszystkie witryny.
Nadanie dostępu obejmuje całą zawartość danej witryny. Oddzielna witryna dla Edmunda ogranicza zakres w porównaniu z witryną główną dzierżawy, która może zawierać również bibliotekę intranetu.
Samo Sites.Selected niczego nie udostępnia. Muszą być spełnione trzy warunki: zgoda na uprawnienie, nadanie dostępu do witryny oraz odpowiedni zakres w tokenie.
Poniższe wywołania wykonuje administrator dzierżawy w Graph Explorer. Sam Graph Explorer musi mieć zgodę na własny delegowany dostęp Sites.Read.All i Sites.FullControl.All.
Odczyt identyfikatora witryny
GET https://graph.microsoft.com/v1.0/sites/{hostname}:/sites/{site-name}
Pole id w odpowiedzi zawiera nazwę hosta i dwa GUID rozdzielone przecinkami. W następnym wywołaniu użyj całej wartości.
Nadanie odczytu
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"
}
}]
}
Odpowiedź 201 Created potwierdza nadanie dostępu. Zwrócona nazwa aplikacji pozwala sprawdzić, czy wskazano właściwy identyfikator.
Późniejsze odebranie dostępu
GET https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
DELETE https://graph.microsoft.com/v1.0/sites/{site-id}/permissions/{permission-id}
204 No Content potwierdza usunięcie. Usunięcie tego uprawnienia odbiera dostęp do jednej witryny. Wycofanie zgody w Entra ID odbiera dostęp do wszystkich witryn naraz.
5. Identyfikator biblioteki — Drive ID
Edmund potrzebuje identyfikatora biblioteki przechowującej dokumenty:
GET https://graph.microsoft.com/v1.0/sites/{site-id}/drives
Biblioteka jest widoczna jako Documents; jej id to Drive ID. Jeśli witryna ma kilka bibliotek, wybierz tę z monitorowanymi folderami.
Aplikacja może odczytać identyfikator własnymi danymi uwierzytelniającymi. Jednocześnie sprawdza to sekret i dostęp do witryny:
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))
Skrypt wymaga pakietów msal i requests:
pip install msal requests
Zamiast skryptu można użyć wskazanego wywołania w Graph Explorer.
6. Połączenie w Edmundzie
Administrator otwiera Settings → Connections → SharePoint i wprowadza:
| Pole | Źródło |
|---|---|
| Tenant ID | Directory (tenant) ID z kroku 1 |
| Client ID | Application (client) ID z kroku 1 |
| Client secret | Wartość z kroku 2 |
| Drive ID | Identyfikator z kroku 5 |
Przed zapisaniem Edmund weryfikuje dane na wskazanej bibliotece. Nieprawidłowe wartości są odrzucane bez zmiany konfiguracji. Zapisane połączenie przeszło więc test dostępu. Sekret nie jest ponownie wyświetlany; widoczna jest tylko informacja, że został zapisany.
Sekret klienta wpisuje bezpośrednio w aplikacji własny administrator. Nie należy wysyłać go zespołowi Edmunda e-mailem ani innym kanałem.
Zapisz termin wygaśnięcia sekretu, aby wymienić go odpowiednio wcześnie zgodnie z częścią B, rozdziałem 13.
Przypisanie folderów do projektów wykonuje się w tym samym miejscu albo na karcie Integrations w ustawieniach projektu. Opisuje je część B, rozdział 11. Nie wymaga to udziału zespołu Edmunda.