README

A Laravel package that implements the complete Canvas LMS OAuth authorization flow.

CanvasOAuth handles the entire OAuth lifecycle, including:

Authorization URL generation
Access token storage
Automatic access token refresh
Invalid token cleanup
Multi-tenant support for multiple Canvas instances

Note

CanvasOAuth only manages OAuth tokens. It does not authenticate or manage your application's users.

Requirements

PHP >= 8.0
Laravel >= 8.0

Installation

1. Install the package

composer require xcesaralejandro/canvasoauth

2. Publish the package resources

php artisan vendor:publish --provider="xcesaralejandro\canvasoauth\Providers\CanvasOauthServiceProvider" --force

The package resolves its models from your application (for example, App\Models\CanvasClient) instead of using the package models directly. The published models extend the package's base models, allowing the package to work with your application's models while giving you the flexibility to customize, extend, or override their behavior without modifying the package source code.

3. Run the migrations

php artisan migrate

Configuration

Register a Canvas client

CanvasOAuth supports multiple Canvas instances simultaneously.

Each Canvas instance is stored in the database and identified by a unique internal client code.

When creating your Developer Key in Canvas, configure the following Redirect URI:

https://YOUR_DOMAIN/canvas-oauth/callback

Then register the client:

php artisan canvas:create-client

The command will ask for:

Field	Description
Internal Client Code	A unique identifier used by your application to reference this Canvas instance.
Canvas Base URL	The root URL of your Canvas instance (for example `https://institution.instructure.com`).
Client ID	The Developer Key ID generated by Canvas.
Client Secret	The Developer Key Secret generated by Canvas.

After registration, the command will:

Save the client configuration in the database.
Display a summary of the registered client.
Generate and display the Authorization URL.

Why use an internal client code?

Since the package supports multiple Canvas instances, your application must specify which Canvas client should be used whenever an OAuth flow is started.

Typical use cases include:

Multiple educational institutions
Multi-tenant SaaS applications
Development, staging, and production environments

Usage

Understanding user management

CanvasOAuth manages OAuth tokens only.

It does not authenticate users or provide user management for your application.

If your application already has its own user model, simply associate your local users with the Canvas user returned by the OAuth process.

A common approach is to add a canvas_user_id column to your users table and store:

$user->standard->id

Important

Do not use the Canvas numeric user ID (canvas_id) as a global identifier. Different Canvas instances may contain users with identical numeric IDs.

The package-generated identifier (standard->id) is globally unique across every registered Canvas instance.

Starting the authorization flow

Retrieve the desired Canvas client and generate its authorization URL:

use App\Models\CanvasClient;

$client = CanvasClient::where('code', 'YOUR_CLIENT_CODE')->firstOrFail();

$url = $client->getAuthorizationUrl();

Use this URL wherever it best fits your application:

A Connect with Canvas button
A hyperlink
An automatic redirect
Any custom authorization workflow

Once the user grants permission, CanvasOAuth stores the tokens and automatically refreshes them whenever necessary.

In most cases, users only need to authorize your application once.

OAuth callbacks

Publishing the package also publishes a controller that you can customize:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use xcesaralejandro\canvasoauth\DataStructures\AuthenticatedUser;
use xcesaralejandro\canvasoauth\Http\Controllers\CanvasOAuthController as BaseCanvasOAuthController;

class CanvasOAuthController extends BaseCanvasOAuthController
{
    public function onPermissionGranted(AuthenticatedUser $user, Request $request): mixed
    {
        // Called after the user successfully grants access.

        return parent::onPermissionGranted($user, $request);
    }

    public function onPermissionDenied(Request $request): mixed
    {
        // Called when the user denies or cancels the authorization request.

        return parent::onPermissionDenied($request);
    }

    public function onError(\Exception $exception): mixed
    {
        // Called whenever an unexpected error occurs during the OAuth flow.

        return parent::onError($exception);
    }
}

The default implementation only writes debug information to Laravel's log.

Override the methods you need. If you do not want the default logging behavior, simply remove the parent::...() calls.

The AuthenticatedUser object

When the OAuth authorization process completes successfully, the package provides an AuthenticatedUser instance.

class AuthenticatedUser
{
    public CanvasUser $standard;
    public ?CanvasUser $supplanted_by;
}

Property	Description
`standard`	The Canvas user who originally granted access to your application.
`supplanted_by`	The Canvas user currently acting on behalf of the standard user. This is `null` unless Canvas Masquerading is being used.

For most applications, the recommended identifier is:

$user->standard->id

This identifier is generated by the package and is guaranteed to be unique across every registered Canvas instance.

Retrieving an access token

Access tokens are managed automatically by the package.

Whenever you request a token, CanvasOAuth verifies whether the current access token is still valid. If it has expired, it is automatically refreshed before being returned.

public function onPermissionGranted(AuthenticatedUser $user, Request $request): mixed
{
    $accessToken = $user->standard->token->freshToken();

    dd($accessToken);
}

The freshToken() method always attempts to return a valid access token.

If the refresh operation fails—for example, because the refresh token has expired or the user revoked your application's authorization—the stored token is automatically removed.

In that case, simply redirect the user through the OAuth authorization flow again.

Summary

CanvasOAuth provides:

✅ Multi-tenant Canvas client management
✅ Authorization URL generation
✅ OAuth callback handling
✅ Secure token storage
✅ Automatic access token refresh
✅ Automatic cleanup of invalid tokens

Your application only needs to:

Register one or more Canvas clients.
Redirect users to the generated Authorization URL.
Associate your local users with standard->id.
Call freshToken() whenever you need to access the Canvas API.

xcesaralejandro / canvasoauth

Maintainers

Package info

Statistics

Security