Name: O365-EDU-Python-Samples
Owner: Office Developer
Description: null
Created: 2016-06-06 20:23:24.0
Updated: 2018-01-06 16:56:13.0
Pushed: 2018-05-24 00:48:15.0
Homepage: null
Size: 5796
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
In this sample, we show you how to integrate with school roles/roster data as well as O365 services available via the Graph API.
School data is kept in sync in O365 Education tenants by Microsoft School Data Sync.
Table of contents
The sample demonstrates:
Calling Graph APIs, including:
Linking locally-managed user accounts and Office 365 (Azure Active Directory) user accounts.
After linking accounts, users can use either local or Office 365 accounts to log into the sample website and use it.
Getting schools, sections, teachers, and students from Office 365 Education:
This sample is implemented with the Python language and Django web framework.
Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design. Built by experienced developers, it takes care of much of the hassle of Web development, so you can focus on writing your app without needing to reinvent the wheel. It?s free and open source.
Deploying and running this sample requires:
An Azure subscription with permissions to register a new application, and deploy the web app.
An O365 Education tenant with Microsoft School Data Sync enabled
One of the following browsers: Edge, Internet Explorer 9, Safari 5.0.6, Firefox 5, Chrome 13, or a later version of one of these browsers.
Additionally: Developing/running this sample locally requires the following:
Python 3.5.2 or above
Django 1.11 or above
Sign into the new Azure portal: https://portal.azure.com/.
Choose your Azure AD tenant by selecting your account in the top right corner of the page:
Click Azure Active Directory -> App registrations -> +Add.
Input a Name, and select Web app / API as Application Type.
Input Sign-on URL: http://127.0.0.1:8000/
Click Create.
Once completed, the app will show in the list.
Click it to view its details.
Click All settings, if the setting window did not show.
Click Properties, then set Multi-tenanted to Yes.
Copy aside Application ID, then Click Save.
Click Required permissions. Add the following permissions:
| API | Application Permissions | Delegated Permissions |
| —————————— | ———————– | —————————————- |
| Microsoft Graph | Read directory data | Read all users' full profiles
Read directory data
Read directory data
Access directory as the signed in user
Sign users in |
| Windows Azure Active Directory | | Sign in and read user profile
Read and write directory data |
Click Keys, then add a new key:
Click Save, then copy aside the VALUE of the key.
Close the Settings window.
The following softwares are required:
Run the app:
Configure the following environment variables:
clientId: use the Client Id of the app registration you created earlier.
clientSecret: use the Key value of the app registration you created earlier.
SourceCodeRepositoryURL: use the URL of this repository.
Open terminal and navigate to the source code folder. Execute the command below:
install -r requirements.txt
on manage.py runserver
Open http://127.0.0.1:8000/ in a browser.
GitHub Authorization
Generate Token
Open https://github.com/settings/tokens in your web browser.
Sign into your GitHub account where you forked this repository.
Click Generate Token
Enter a value in the Token description text box
Select the followings (your selections should match the screenshot below):
Click Generate token
Copy the token
Add the GitHub Token to Azure in the Azure Resource Explorer
Open https://resources.azure.com/providers/Microsoft.Web/sourcecontrols/GitHub in your web browser.
Log in with your Azure account.
Selected the correct Azure subscription.
Select Read/Write mode.
Click Edit.
Paste the token into the token parameter.
Click PUT
Deploy the Azure Components from GitHub
Check to ensure that the build is passing VSTS Build.
Fork this repository to your GitHub account.
Click the Deploy to Azure Button:
Fill in the values in the deployment page and select the I agree to the terms and conditions stated above checkbox.
Resource group: we suggest you create a new group.
Site Name: please input a name. Like EDUGraphAPICanviz or EDUGraphAPI993.
Note: If the name you input is taken, you will get some validation errors:
Click it you will get more details like storage account is already in other resource group/subscription.
In this case, please use another name.
Source Code Repository URL: replace
Source Code Manual Integration: choose false, since you are deploying from your own fork.
Client Id: use the Client Id of the app registration you created earlier.
Client Secret: use the Key value of the app registration you created earlier.
Check I agree to the terms and conditions stated above.
Click Purchase.
Add REPLY URL to the app registration
After the deployment, open the resource group:
Click the web app.
Copy the URL aside and change the schema to https. This is the replay URL and will be used in next step.
Navigate to the app registration in the new Azure portal, then open the setting windows.
Add the reply URL:
Note: to debug the sample locally, make sure that http://127.0.0.1:8000/ is in the reply URLs.
Click SAVE.
Solution Component Diagram
Authentication
Django comes with a user authentication system. It handles user accounts, groups, permissions and cookie-based user sessions. For more details, see Django authentication system.
Local users authentication is based on the built-in API:
O365 users authentication is implemented with Open ID Connect.
Data Access
In this sample, Django's built-in ORM is used to access data from the backend SQLite database.
Below are the tables:
| Table | Description |
| —————————— | —————————————- |
| auth_user | Django built-in user table which contains users' authentication information: username, email, password… |
| user_roles | Contains users' roles. Three roles are used in this sample: admin, teacher, and student. |
| profiles | Contains users' extra information: favoriteColor, organization_id, o365UserId, and o365Email. The later two are used to connect the local user with an O365 user. |
| organizations | A row in this table represents a tenant in AAD.
isAdminConsented column records if the tenant consented by an administrator. |
| token_cache | Contains the users' access/refresh tokens. |
| classroom_seating_arrangements | Contains the classroom seating arrangements data. |
Models are defined in /models/db.py.
Views
Below are the views:
| Path | Description | | ——————– | —————————————- | | /account/views.py | Contains views for users to register, login and logout. | | /admin/views.py | Contains administrative views like consent tenant, manage linked accounts. | | /link/views.py | Contains views used for link user accounts. | | /management/views.py | Contains views of the about me page. | | /schools/view.py | Contains education views, like schools, classes, and class details. |
Decorators
The below decorators were used in this app:
| Decorator | Description | | —————– | —————————————- | | login_required | Only allow logged in users to access the protected resources. | | admin_only | Only allow admins to access the protected resources. | | linked_users_only | Only allow linked users to access the protected resources. |
Services
The services used by the server side app:
| Service | Description | | —————- | —————————————- | | UserService | Contains method used to manipulate users in the database. | | LinkService | Contains method used to link user accounts. | | AuthService | Contains methods used for authorization and authentication. | | AADGraphService | Contains methods used to access AAD Graph APIs. | | MSGraphService | Contains methods used to access MS Graph APIs. | | EducationService | Contains two methods to access Education REST APIs. | | TokenService | Contains method used to get and update tokens from the database |
The services are in the /services folder.
Middleware
HandleRefreshTokenExceptionMiddleware catches RefreshTokenException thrown by TokenService when refresh token does not exist or expired. Then it redirects the user to a page to let the user re-login.
Multi-tenant app
This web application is a multi-tenant app. In the AAD, we enabled the option:
Users from any Azure Active Directory tenant can access this app. Some permissions used by this app require an administrator of the tenant to consent before users can use the app. Otherwise, users will see this error:
For more information, see Build a multi-tenant SaaS web application using Azure AD & OpenID Connect.
The Office 365 Education APIs return data from any Office 365 tenant which has been synced to the cloud by Microsoft School Data Sync. The APIs provide information about schools, sections, teachers, students, and rosters. The Schools REST API provides access to school entities in Office 365 for Education tenants.
In this sample, the Microsoft.Education Class Library project encapsulates the Office 365 Education API.
The EducationServiceClient is the core class of the library. It is used to easily get education data.
Get schools
get_schools(self):
url = self.api_base_uri + 'administrativeUnits'
return self.rest_api_service.get_object_list(url, self.access_token, model=School)
ypescript
get_school(self, object_id):
url = self.api_base_uri + 'administrativeUnits/%s' % object_id
return self.rest_api_service.get_object(url, self.access_token, model=School)
Get classes
get_sections(self, school_id, top=12, nextlink=''):
skiptoken = self._get_skip_token(nextlink)
url = self.api_base_uri + "groups?$filter=extension_fe2174665583431c953114ff7268b7b3_Education_ObjectType eq 'Section' and extension_fe2174665583431c953114ff7268b7b3_Education_SyncSource_SchoolId eq '%s'&$top=%s%s" % (school_id, top, skiptoken)
return self.rest_api_service.get_object_list(url, self.access_token, model=Section, next_key='odata.nextLink')
ypescript
get_section(self, object_id):
url = self.api_base_uri + 'groups/%s' % object_id
return self.rest_api_service.get_object(url, self.access_token, model=Section)
Get users
get_members(self, object_id, top=12, nextlink=''):
skiptoken = self._get_skip_token(nextlink)
url = self.api_base_uri + 'administrativeUnits/%s/members?$top=%s%s' % (object_id, top, skiptoken)
return self.rest_api_service.get_object_list(url, self.access_token, model=EduUser, next_key='odata.nextLink')
Below are some screenshots of the sample app that show the education data.
There are 4 authentication flows in this project.
The first 2 flows (Local Login/O365 Login) enable users to login in with either a local account or an Office 365 account, then link to the other type account. This procedure is implemented in the LinkController.
Local Login Authentication Flow
O365 Login Authentication Flow
Admin Login Authentication Flow
This flow shows how an administrator logs into the system and performs administrative operations.
After logging into the app with an Office 365 account,the administrator will be asked to link to a local account. This step is not required and can be skipped.
As mentioned earlier, the web app is a multi-tenant app which uses some application permissions, so tenant administrator must consent the app first.
This flow is implemented in the AdminController.
There are two distinct Graph APIs used in this sample:
| | Azure AD Graph API | Microsoft Graph API | | ———— | —————————————- | —————————————- | | Description | The Azure Active Directory Graph API provides programmatic access to Azure Active Directory through REST API endpoints. Apps can use the Azure AD Graph API to perform create, read, update, and delete (CRUD) operations on directory data and directory objects, such as users, groups, and organizational contacts | A unified API that also includes APIs from other Microsoft services like Outlook, OneDrive, OneNote, Planner, and Office Graph, all accessed through a single endpoint with a single access token. | | Client | Install-Package Microsoft.Azure.ActiveDirectory.GraphClient | Install-Package Microsoft.Graph | | End Point | https://graph.windows.net | https://graph.microsoft.com | | API Explorer | https://graphexplorer.cloudapp.net/ | https://graph.microsoft.io/graph-explorer |
IMPORTANT NOTE: Microsoft is investing heavily in the new Microsoft Graph API, and they are not investing in the Azure AD Graph API anymore (except fixing security issues).
Therefore, please use the new Microsoft Graph API as much as possible and minimize how much you use the Azure AD Graph API.
Below is a piece of code shows how to get group documents from the Microsoft Graph API.
get_documents(self, object_id):
url = self.api_base_uri + 'groups/%s/drive/root/children' % object_id
return self.rest_api_service.get_object_list(url, self.access_token, model=Document)
Note that in the AAD Application settings, permissions for each Graph API are configured separately:
We encourage you to contribute to our samples. For guidelines on how to proceed, see our contribution guide.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Copyright (c) 2017 Microsoft. All rights reserved.