OAuth 2 Configuration

Introduction

This section describes how to configure and use iObeya as an OAuth 2 client for SharePoint API.

Registering iObeya in Your Office 365 Tenant

First of all, you have to register an iObeya application on Office 365 from Azure AD menu. This will allow you to get a client ID, you can then generate a key for this application in order to get a client secret.

  1. Open https://portal.azure.com/ in a new tab.

  2. Login with your Office 365 administration account.

  3. Select Azure Active Directory ‣ App registrations.

  4. Select New application registration, fill the form, then save.

    Your client ID is displayed in the Application ID column.

  5. Click Certificates and secrets.

  6. Click New client secret.

  7. Copy the generated value for future use.

Warning

Copy the key value right now. You won’t be able to retrieve it after you leave this blade.

Defining the Scope

For SharePoint:

From the API permissions of your registered app:

  1. Click Add a permission.
  2. Select SharePoint from Request API permission.
  3. Click Delegated permission.
  4. In the section Select permission, select:
    • AllSites ‣ AllSites.Read,
    • MyFiles ‣ MyFiles.Read.
    • User ‣ User.Read.All.
  5. Click Add permissions.
For Microsoft Graph:

From the API permissions of your registered app:

  1. Click Add a permission.
  2. Select Microsoft Graph from Request API permission.
  3. Click Delegated permission.
  4. In the section Select permission, select User.read
  5. Click Add permissions.

Configuring External Applications in iObeya

To configure iObeya to access to SharePoint API as an OAuth client, you have to configure an external application in the administration web interface of iObeya.

  1. Configure an application type.

    From the administration web interface, you have to create an application type. This makes it easier to group application instances.

    1. Click SETTINGS ‣ Accessible applications in iObeya.

    2. Click Add application type.

    3. Fill the Application type with office365.

      _images/new_application_type.png

      Warning

      You have to use exactly office365 as the application type name, this name is used by the SharePoint add-on to find the list of Office 365 application instances.

  2. Configure an application instance.

    You can add a SharePoint application instance from an application type. This instance matches with a SharePoint instance that should return OAuth tokens.

    iObeya domains

    You must select All domains to be able to retrieve your application instance during the configuration of a new external source.

    Name

    Name of SharePoint application instance, example: sharepoint.

    OAuth version

    OAuth version used by SharePoint API, SharePoint needs OAuth 2.

    URL

    SharePoint API base URL, this URL is not yet used by the iObeya SharePoint add-on, you can set your SharePoint base URL with this type of URL https://{tenant_name}.sharepoint.com.

    Authorize URL

    Office 365 OAuth authorize URL, its value is https://login.microsoftonline.com/{tenant ID}/oauth2/authorize.

    Note

    You cannot use Version 2.0 URLs.

    Token URL

    Office 365 OAuth token URL, its value is https://login.microsoftonline.com/{tenant ID}/oauth2/token.

    Note

    You cannot use Version 2.0 URLs.

    Client ID

    Client ID of the application you created on Office 365. The Client ID corresponds to the application ID in Azure.

    Client secret

    Client secret of the application you created on Office 365. The Client secret corresponds to the Value in Azure.

    Note

    The Value is only displayed once just after the client secret creation. To retrieve it see see Microsoft documentation.

    Allow offline API call by IObeya

    This parameter allows the SharePoint add-on to refresh OAuth token automatically if needed.

    Resources

    SharePoint resource to specify has the following value: https://{tenant name}.sharepoint.com

    Warning

    The Resources is required for sharepoint configuration, please specify its value (or clean old oauth token) before launching a new oauth dance.

    Note

    You can find OAuth endpoints from https://portal.azure.com/. Select Azure Active Directory ‣ App registrations, then select the endpoints menu on the top of the page.

    Example of a SharePoint instance configuration:

    _images/new_application_instance.png

A callback URL (Redirect URL field) is generated while creating a new application instance. You will need to use this URL in Office 365 in order to configure iObeya’s access. Following screenshot shows an application instance’s details with the generated callback URL.

_images/application_instance_details.png

Configuring the SharePoint Application from Azure AD

To finalize iObeya application configuration on Office 365, set the callback URL got from the preview step.

  1. From https://portal.azure.com/, select Azure Active Directory ‣ App registrations.
  2. Select your application.
  3. Click Authentication.
  4. Click Add a platform.
  5. Select Web in the :guilabel:`Configure platform`pannel on the right.
  6. Click Add URI.
  7. Add the callback URL you got from iObeya administration.

Configuring the SharePoint Add-On to Use OAuth 2

You can now configure your SharePoint add-on to connect to SharePoint API with OAuth tokens.

  1. From iObeya administration, access the external resource menu, then add a new SharePoint external resource:

    _images/sharepoint_add_on_config.png

  2. Start an OAuth dance to get OAuth access, then refresh tokens by selecting Start OAuth Dance.

    A new OAuth dance starts, you will have to connect to azure AD with an account which has access to iObeya application configured in Azure AD.

  3. Come back to the SharePoint configuration popup, then select check access token to check if the token has been generated successfully;

  4. Save your configuration.

Your SharePoint add-on is started successfully. It can from now refresh automatically the OAuth access token if needed.