PHPackages                             xcesaralejandro/canvasoauth - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. xcesaralejandro/canvasoauth

ActiveLibrary[Authentication & Authorization](/categories/authentication)

xcesaralejandro/canvasoauth
===========================

This package provides a simple integration for oauth between canvas and laravel.

2.0.0(1mo ago)1243MITPHPPHP ^8.0

Since Jul 14Pushed 4w ago1 watchersCompare

[ Source](https://github.com/xcesaralejandro/canvasoauth)[ Packagist](https://packagist.org/packages/xcesaralejandro/canvasoauth)[ RSS](/packages/xcesaralejandro-canvasoauth/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (4)Versions (10)Used By (0)

CanvasOAuth
===========

[](#canvasoauth)

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
------------

[](#requirements)

- PHP >= 8.0
- Laravel >= 8.0

Installation
------------

[](#installation)

### 1. Install the package

[](#1-install-the-package)

```
composer require xcesaralejandro/canvasoauth
```

### 2. Publish the package resources

[](#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

[](#3-run-the-migrations)

```
php artisan migrate
```

Configuration
-------------

[](#configuration)

### Register a Canvas client

[](#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:

FieldDescriptionInternal Client CodeA unique identifier used by your application to reference this Canvas instance.Canvas Base URLThe root URL of your Canvas instance (for example `https://institution.instructure.com`).Client IDThe Developer Key ID generated by Canvas.Client SecretThe 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?

[](#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
-----

[](#usage)

### Understanding user management

[](#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

[](#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
---------------

[](#oauth-callbacks)

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

```