OneRoster Integrations and Open Authorization (OAuth)

Overview & availability

OneRoster is a set of standards that define the specifications for storing and presenting rostering and gradebook data between multiple web services. Through standardization, OneRoster allows developers to create software against a single specification, expediting the software development cadence when integrating with a provider.

OneRoster is governed by the IMS Global Learning Consortium, which also manages Learning Tools Interoperability (LTI) and other standards for integrated education environments. In OneRoster terms, Blackbaud Student Information System is the "provider" of roster data and the "recipient" of assignment grades. We support "consumer-driven events" through a “pull model”; the system that pulls roster data from our system and pushes assignment grades to our system is the initiator of the exchanges. For details about OneRoster, visit the IMS Global OneRoster homepage.

Platform managers can manage these integrations in Core.

Note: We recommend your school test this integration with a test roster and assignments with your LMS or another provider before you go live with the integration.

Learn about OAuth 1 and OAuth 2

We currently support OneRoster integrations through OAuth 1.0 using HMAC-SHA256 as the signature method, and OAuth 2.0 using the client credentials grant type. Both OAuth 1 and OAuth 2 are served over TLS 1.2.

Note: The OneRoster OAuth 2.0 API provides an implementation of the OneRoster v1.1 specification.

OAuth is a standard method to enable third-party websites, vendors, applications, APIs, etc., to access information from your school's site using tokens instead of assigning passwords. OAuth enables your school to use OneRoster integrations with your learning management system (such as Canvas Learning Management System).

Platform managers handle credentials for this authentication method in Core.

Create authentication credentials and determine data access permissions

Before providers access your data, create the key and secret they need to gain access and determine the information they can retrieve.

To get started, navigate to Core, hover over Settings in the navigation, and select Integration settings. On the Integration settings page, choose OneRoster Settings.

Select + Add.
Enter a Name for the authentication token. Consider using the name of the provider you are granting access.
Under Provider, select Canvas if integrating with Canvas. Otherwise, select Standard.
Optional: Mark Use legacy OAuth 1.0 authentication if required. The key and secret must be used with OAuth 2.0 authentications if left unmarked.
Select the Rostering options tab to determine what data the provider can access.
Select the Gradebook options tab. Specify a default Assignment type to give assignments that do not have an assignment type. Assignments that do not have a type are excluded from gradebook results.
Return to the Provider tab, and select Generate key and secret.

Note: The key and secret are both used by vendors to create an authentication token to permit access to the OneRoster endpoints.
Select Save.

Copy a key or secret for use with a provider

To enable a provider to access your school's data, provide them with secure tokens that they'll use to authenticate to your site.

To get started, navigate to Core, hover over Settings in the navigation, and select Integration settings. On the Integration settings page, choose OneRoster Settings.

On the row of the existing credentials for a provider, select the ellipsis [...] and then Edit.
Copy the key.

Give this information to the provider.
Copy the secret.

Give this information to the provider.
1. Provide one of the following URLs to the provider based on which OAuth configuration you created:
  - OAuth 1.0
    
    https://{schoolName}/ims/oneroster/v1p1/
  - OAuth 2.0
    
    https://developer.sky.blackbaud.com/docs/services/afe-rostr/operations/getAcademicSession
    
    Note: Providers need to generate a bearer token and include it in the headers of requests to our endpoints.
    
    Note: The OneRoster OAuth 2.0 API provides an implementation of the OneRoster v1.1 specification.

Edit authentication credentials

Although you cannot change the key and secret to correspond from OAuth 1.0 to OAuth 2.0, or vice versa, you can rename the credentials, select a different provider, or redetermine what data the provider can access.

To get started, navigate to Core, hover over Settings in the navigation, and select Integration settings. On the Integration settings page, choose OneRoster Settings.

On the row of the existing credentials for a provider, select the ellipsis [...] and then Edit.
Enter a Name and select a Provider.
Under Options, you can set the following output options:
- Specify the years you would like to include.
- Specify the format of the sections(classes):
  - Each section: Each section will appear as a separate row with one term.
  - Lead section only: One row for all sections with multiple terms on a single row.
- Specify the type of groups:
  - Academics only
  - Advisory only
  - Academics and Advisory
- Specify if all courses/groups should be included or a select subset of courses/groups
  - Return all: returns all Academic classes and/or Advisory groups.
  - Return selected: allows you to select specific classes or groups.
Save the change.

The key and secret remain unchanged.

View Blackbaud endpoints for OneRoster

Blackbaud Education Management has implemented multiple API endpoints for OneRoster integrations and will add more in the future.

There are a separate set of endpoints for both OAuth1.0 and OAuth 2.0.

OneRoster Endpoint reference:

The OAuth 2.0 endpoints require providers to follow the User credentials authentication flow to generate the bearer token used to authenticate with the endpoints.

Requests to generate the OAuth 2.0 bearer token must be made to: https://oauth2.sky.blackbaud.com/token

Note: The OneRoster OAuth 2.0 API provides an implementation of the OneRoster v1.1 specification.

Delete credentials

When you delete credentials, all authentication data for the provider will be removed from your school (including the Key and Secret). Any data your school previously sent to the provider or received from the provider will remain unchanged, but new data will not be sent or received.

To get started, navigate to Core, hover over Settings in the navigation, and select Integration settings. On the Integration settings page, choose OneRoster Settings.

On the row of the existing credentials for a provider, select the ellipsis [...].
Select Delete.
Confirm the change.

Note: To resume using sending data to the provider, you must create new credentials.

Automate OneRoster file exports using SSH File Transfer Protocol (SFTP)

Integration managers can set up an automated job that exports the OneRoster files to a self-maintained SFTP server using a provided SFTP location and the corresponding authentication credentials.

To get started and set up the automated job, as an Integration manager, navigate to Core, select Settings in the navigation, and then select Integration settings.

Additionally, gather your SFTP location, SFTP username, and SFTP password credentials.

Add a new or Edit an existing OneRoster setting.
Select the File Export options tab.
Select Automatically export files.
Define the SFTP location, the SFTP port if it is not 22, the Internal directory, and the connection authentication details.

For the SFTP location, enter the server hostname.

For the Internal directory, include the folder or folder structure for the export to be placed in within (e.g., folderName for a single directory or folderName1/folderName2/folderName3 for a nested directory).
Select Test connection to ensure a connection can be established with the provided SFTP details.
Complete the other settings tabs, as necessary, and select Save.

After setting up, the automated job will deposit the exported file to the SFTP location every morning at 2 am EST. You can find references to each export under the OneRoster export page, with each automated entry showing 'Blackbaud System' as the 'Submitted by' entry.

Export data for OneRoster as zipped CSV

Platform managers and data managers can export data as a zipped (.zip) comma-separated value (.csv) file for use with OneRoster integrations that don't use Rest APIs.

Select Core.
Select System tools.
Select OneRoster export.
Select Create export a new export file or download your previously created export file
Under Provider name, select the provider you would like to perform an export for then select Run to generate your export.

Tip: The exported file will have the provider name in the file name so you can easily see which provider you have run the export for.
Provide the export file to the OneRoster partner, who imports the file to update their data.