Python D2L Authentication & Automation Scripts

This repository contains Python scripts for interacting with the Brightspace (D2L) API. It handles OAuth 2.0 authentication (with PKCE) and provides utilities for fetching user data, final grades, and other datasets.

Features

• OAuth 2.0 Authentication: Implements the full OAuth flow with PKCE, including a local HTTPS callback server.
• Token Management: Automatically saves and refreshes access tokens using a .env file.
• Data Export: Automates the creation and downloading of data exports (e.g., Final Grades).
• BDS Extracts: Fetches and downloads the latest Brightspace Data Sets (BDS) extracts.

Prerequisites

• Python 3.8+
• mkcert (for generating local SSL certificates)

Setup

1. Create a D2L OAuth 2.0 Client

In your Brightspace tenant, create an OAuth 2 client (App):

• Redirect URI: https://localhost:3001/callback
• Scopes: core:*:* users:userdata:read (Note: These are the minimum scopes for the Get_WhoAmI.py script. For other scripts, you will need additional scopes like datahub:*:*, datasets:*:*, etc. See the .env configuration section below for a full list.)
• Copy the Client ID (and Client Secret if the client is confidential).

Note: This app uses PKCE; a client secret is not required for public clients. If your client is confidential, set D2L_CLIENT_SECRET in your .env file, and the app will authenticate using HTTP Basic to the token endpoint.

2. Install Dependencies

pip install -r requirements.txt

3. Generate Local SSL Certificates

The OAuth callback requires a local HTTPS server. Use mkcert to generate trusted certificates for localhost.

# Install mkcert (if not already installed)
# Windows (using Scoop): scoop install mkcert
# macOS (using Homebrew): brew install mkcert nss

mkcert -install
mkcert -key-file localhost+2-key.pem -cert-file localhost+2.pem localhost 127.0.0.1 ::1

Ensure the generated .pem files are in the root of this directory.

4. Configure Environment Variables

Create a .env file in the root directory with your Brightspace credentials:

D2L_ROOT=https://your_school.brightspace.com
D2L_AUTH_BASE=https://auth.brightspace.com
D2L_CLIENT_ID=your_client_id
D2L_CLIENT_SECRET=your_client_secret
D2L_SCOPES="core:*:* datahub:*:* datasets:*:* grades:*:* jobs:*:* reporting:*:* users:*:*"  # Adjust scopes as needed
D2L_REDIRECT_URI=https://localhost:3001/callback
TLS_CERT_FILE=localhost+2.pem
TLS_KEY_FILE=localhost+2-key.pem

Usage

Authentication Test

Run Get_WhoAmI.py to test the connection. It will open a browser for login if needed and print your user details.

python Get_WhoAmI.py

Export Final Grades

Creates a data export job for the last 30 days, waits for completion, and downloads the zip file to the Outputs/ directory.

python GetFinalGrades.py

Download User Extracts

Fetches the latest "Full" and "Differential" user data extracts from BDS and saves them to Outputs/.

python GetUsers.py

Project Structure

• Get_WhoAmI.py: Basic connectivity and authentication test.
• GetFinalGrades.py: Automates the Data Export API for final grades.
• GetUsers.py: Retrieves and downloads BDS user extracts.
• GetOrgUnits.py: (Assumed) Fetches Organizational Unit data.
• GetSurveyAttempts.py: (Assumed) Fetches Survey Attempt data.
• .env: Stores configuration and tokens (do not commit this file).
• Outputs/: Directory where downloaded files are saved.