Audience: ClassLink Administrator
Before you can effectively export to a destination, you will need to authorize access to that destination. Based on the destination type, you will have to follow different steps based on authorization type. Authorization for Active Directory occurs at the beginning of the destination creation process, while authorization for GSuite and Azure occurs after the destination has been created.
Note: When adding GSuite and Microsoft Azure accounts as destinations, you must have pop-ups unblocked in order to allow a pop-up that will prompt you for account credentials and authorize a connection. GSuite and Azure destinations also require additional setup to register the OneSync API. See below for details.
- Active Directory (Authorization)
- GSuite (Obtaining a Client ID & Secret)
- Google Sheets
- Azure (Obtaining a Client ID & Secret)
Active Directory (Authorization)
1. When creating an Active Directory destination, you will be prompted for your authorization credentials at the beginning of the destination creation process. You will need your username, password, domain, base path, and port. OneSync currently only supports LDAP protocols.
2. Press the Test Connection button to check your credentials. If you entered them correctly, this button will show Connected.
Note: OneSync can connect to your Active Directory and the Test Connection button will show Connected if you use an IP address in place of your domain. However, not all destination functions will work with an IP address, mainly Groups. We thus advise that you enter your domain name and not an IP address.
GSuite (Obtaining a Client ID & Secret)
To export to a GSuite destination, you must first register the OneSync API to allow it access to your Google Account using an API Client ID & Secret.
1. Create a new Project:
a. Go to https://console.developers.google.com/ and sign in.
b. Click on the drop down.
c. Click on NEW PROJECT.
d. Enter ClassLink for the Project name.
e. Click on Create button.
2. Enable necessary APIs and credentials:
a. From Dashboard, click on + ENABLE APIS and SERVICES.
b. In Search bar for the API Library enter Admin SDK. When found select it.
c. Click on the ENABLE button.
d. Select Credentials from menu on left.
e. Click on CONFIGURE CONSENT SCREEN button on right of screen.
f. Choose your preference of User Type and click CREATE.
NOTE: Either option (Internal or External) for user type is available for use with OneSync.
g. Fill out the OAuth consent screen.
- Application type Public.
- Application name onesync.
h. Midway down the screen click on the Add Scope button.
- Click on the manually paste link toward the bottom of the screen.
i. In the box that opens up at the bottom enter the following on separate lines or separated by commas:
j. Click on the ADD button (bottom-right of Add Scope window).
k. Click on the Save button (bottom-left of the OAuth consent screen window).
l. Click back to Credentials on the left-hand navigation menu. At the top of the screen click Create Credentials>OAuth Client ID.
m. Select Web Application as the Application Type.
n. Enter the Name (ex. Web client onesync).
o. Enter the Authorized redirect URIs as http://localhost/oauth2 (Case Sensitive) and click Create.
Note: if you do not access your onesync server via localhost, replace "http://localhost" with your url. For example: https://onesync.mydistrict.edu/oauth2
3. Use your client ID and client secret for GSuite authorization in OneSync.
Similar to GSuite, Google Sheets will need its own API key and secret. To create a new API key and secret for Google Sheets navigate to https://console.developers.google.com and click Select a project in the top left corner which should prompt this popup:
From here you will need to add a new project by clicking on the New Project button in the top right corner of the popup. Once clicked you will be prompted with a new page to create your project which looks like the page below:
For the project name you can either enter OneSync or ClassLink, which ever you would like to choose, and for the Location you will want to select the Parent Organization that you will be using for OneSync.
Note: "An Organization resource is automatically created the first time a user associated with a G Suite or Cloud Identity domain creates a project or billing account. The Organization will be linked to your account with the project or billing account set as a child resource. All projects and billing accounts created under your G Suite or Cloud Identity domain will be children of this Organization." (from Google documentation)
After creating your project you will be redirected to the APIs & Services page and from there you will need to enable APIs and services, if you already have this enabled you may skip this step. To enable APIs and Services click the + ENABLE APIS AND SERVICES
Once you've enabled APIs and Services for your google account you will be redirected to the Google API Library and from here you will need to select Google Sheets:
Before you enable the Google Sheets API make sure that the project that you just created is selected in the top left corner. From here you will need to click Enable:
After you enable your Google Sheets API you now have an API key and secret that you can use. Before using these credentials you will first want to alter the scope of credentials by navigating back to the Dashboard by clicking on the Google APIs logo in the top left corner next to the sandwich menu drop down:
Once you're at the dashboard you will want to then navigate to the OAuth consent screen by clicking on the the button shown above. If you get prompted to choose between a User Type, select Internal which will only allow users within your organization to use the OAuth 2 credentials. Within the OAuth consent screen you will need to fill out the application name and then add scopes to your API by clicking on the Add scope button.
Below are the scopes you will want to select to allow OneSync to read from your desired sheets correctly:
After adding the scopes above by clicking the ADD button and clicking save at the bottom of the OAuth consent screen, you will need to get credentials for the API you just setup on your account. First you will want to navigate back to the dashboard by clicking on the Google APIs logo in the top left corner (this will always bring you back to the dashboard), then you will want to click on Credentials located on the left navigation bar which is highlighted below.
If you do not have any credentials setup you will be prompted with a blue Create credentials button in the center of the screen. Click -> Create credentials -> then click -> OAuth client ID.
After you have selected the OAuth client ID option you will be redirected to the Create OAuth client ID page. You will need to fill out the following credentials:
- Application Type: Web Application (from the radio button selection)
- Name: OneSync
- Authorized redirect URIs: http://localhost/oauth2
After you click Create (you may have to click Create twice to save the full form) you will be redirected to the Credentials screen where your OAuth client will appear with a Client ID and a Client Secret. Remember to not share your key or secret for security purposes.
For security purposes OneSync will only accept Google Sheets that are not publicly accessible, this means that the Google user that is authorizing must have full access to the Google Sheet. For security reasons it is best to only import Google Sheets that you have created or a Sheet that has been created and managed by somebody within your organization.
Azure (Obtaining a Client ID & Secret via v2.0 endpoint)
To export to an Azure destination, you must first register the OneSync API to allow it access to your Azure Active Directory Account using an API Client ID & Secret.
1. Register a New App: Navigate and sign into the Azure Portal.
2. In the main menu to the left, navigate to Azure Active Directory -> App registrations (Preview).
3. Click the blue +New registration button at the top. This will bring you to a new page called Register an Application.
4. Name the app "OneSyncAPI."
5. Under "Supported account types," select "Accounts in any organizational directory".
6. Under "Redirect URI (optional)", enter the URL for your OneSync account with "Web" for the type. In most cases, this URL will be "http://localhost/oauth2". If you are using a custom URL, simply append "/oauth2" to it.
7. Click the blue Register button.
8. Manage Authentication: Once you register the app, you will be redirected to the app's Preview page.
9. In the second toolbar from the left, underneath the Manage section, click Authentication -> Scroll down to the Implicit grant section.
10. Select Access tokens and ID tokens.
11. Click Save at the top.
12. Assign Permissions: While you are still in the app's Preview page, navigate to API Permissions in the second toolbar.
13. Click the +Add a permission button. This will open a slide over with different APIs and permissions.
14. At the top of the slide over, under Commonly used Microsoft APIs -> click Microsoft Graph.
15. Click Delegated permissions. This will display a list of applicable permissions.
16. Search for and apply the following permissions:
17. Click the blue Add permissions button at the bottom left of the slide over.
18. To obtain the client ID, simply navigate to the app's Overview of the Preview page. The client ID will be list as at the top of the page.
19. To obtain a secret, navigate to Certificates Application (client) ID& secrets.
20. Underneath Client secrets -> click +New client secret.
21. You will give the secret a description and select the expiration date for it.
22. Click the blue Add button.
23. Copy the new client secret value. You won't be able to retrieve it after you leave this page.
Once you have the client ID and secret, you can authorize an Azure destination in OneSync.
For destinations and sources that have an API key and secret (Azure, Google Sheets, and G Suite) we have an Authorization Module to keep authorization credentials together in a single place. Within OS Settings navigate to the Auth Credentials tab and from there, you can add new credentials by clicking the blue Add Auth Credential button in the top right corner of the page which is shown below:
You can also edit previously made credentials by clicking the edit button which is a pencil and paper icon. When creating or editing a credential you can either Save or Save + Authorize, Save doesn't prompt an authorization pop-up whereas Save + Authorize prompts for the appropriate credentials for the account being authorized. For Azure authorization, please make sure to click the check-box on the authorization screen that says "Consent on behalf of your organization" in order to authorize the OneSync API properly.
Updated: Oct 2019