FYB Explore OpenID Microsoft Guide
OVERVIEW
To use FYB Explore you are required to register the application on Azure Active Directory. The registration will be used to acquire an access token to make web API requests to access certain Microsoft resources for a tenant (organisation).
CREATE THE APP REGISTRATION
-
Sign in to Azure web portal using the link below https://azure.microsoft.com/en-gb/features/azure-portal/
-
Once signed in, click on the Azure Active Directory button

-
Click on the App Registrations option from the left menu

-
Click on the New registration button
-
Enter FYB Explore into the name input field

-
Under Supported account types section enabled Accounts in this organizational directory option

-
Select Single-page application (SPA) from the drop-down menu and type in the hostname configured for FYB Explore followed by /fybexplore/
NoteThe URI is case sensitive, the route must match exactly the pattern below where the only variable that needs to be replaced is the hostname. Please include the trailing slash in the URL and ensure all characters are in lowercase. Example: https://hostname/fybexplore/
-
Click on the Register button

ADDING SHAREPOINT PERMISSIONS
The application will require various API permissions, please follow the steps below to add the required permission for FYB Explore.
-
Click on the API permissions option from the left menu

-
Click on the Add Permissions button
-
When the right-hand permission panel appears, click on Microsoft Graph (This will be at the very top)

-
Click on Delegate permissions

-
Using the select permission window, add the following delegate permissions to the application
-
email
-
offline_access
-
openid
-
profile
-
Sites.Read.All
-
Files.ReadWrite.All
-
User.Read (If not already added)

-
Scroll down to the bottom of the panel and click the Add Permission button
-
An Azure administrator will need to grant permission for the application to access the resources by clicking on the Grant Permission button
-
Once granted the status will update to Green, indicating the permission has been successfully granted

-
Click on Grant Admin Consent
NoteDo not remove the default user.read delegated permission
NoteNote if users are still receiving the below message upon the first login then an Azure Administrator will need to complete the first login and grant consent from the Microsoft login pop-up instead.

API PERMISSION USAGE
| NAME | TYPE | DESCRIPTION | CONSENT REQUIRED | USAGE |
|---|---|---|---|---|
| Delegated | View users' email address | Yes | Required for OpenID authentication | |
| offline_access | Delegated | Maintain access to data you have given it access to | Yes | Required for OpenID authentication |
| openid | Delegated | Sign users in | Yes | Required for OpenID authentication |
| profile | Delegated | View users' basic profile | Yes | Required for OpenID authentication |
| User.Read | Delegate | Read basic information for logged in user | No | Default permission set by Azure, used to allow user to sign in |
| Sites.Read.All | Delegated | Read items in all site collections | Yes | Required for listing sites when uploading documents to SharePoint |
| Files.ReadWrite.All | Delegate | Read and write files in all site collections | Yes | This permission is required for users to view and edit documents. |
EXPOSE THE API
Applying a custom scope to the registration will prevent unauthorized access to the FYB Explore API endpoints.
-
In the Left Menu, click on Expose an API

-
Next to the Application ID URI click on Set

-
Click Save

-
Click Add a scope

-
Specify the values below in the Add a scope window, then click Add scope
NoteThe scope must be named Grant.Access
Field Value Scope Name Grant.Access Who can consent? Admins and users Admin Consent display name Grant Access to FYB Explore Admin consent description Grant Access to FYB Explore State Enabled 
-
Once the scope has been added, click on API permissions

-
Click on Add a permission

-
Click My APIs
-
Click on the previously created FYB Explore app registration
NoteIf your app registration is not listed, wait 5-10 minutes or search for the app registration using the within the APIs my organization uses tab

-
Click on the Grant.Access scope and then click Add permissions at the bottom of the screen
-
Click on Grant admin consent

GATHERING APP DETAILS
Please follow the steps below to retrieve the Application ID, Tenant ID and Redirect URL on the Azure portal. These values are required for the installation.
-
Once signed into the Azure portal click on Azure Active Directory

-
Click on App registrations
-
Click on the required application (FYB Explore created previously)
-
Click on Overview

-
Copy the Application (client) ID and Directory (tenant) ID and note them down.

-
Click on Redirect URIs from the overview page
-
And then copy and note down the Redirect URI value

-
Click on Expose an API

-
Copy the value of the Application ID URI

CERTIFICATE BASED AUTHENTICATION
The background scheduler component of the application utilizes certificate-based authentication to verify its identity to Microsoft Azure. As such you will need to register a certificate for your application on Azure AD. You can choose to use an existing certificate if you have one (the same certificate used for the FYB Explore site) otherwise you can create/purchase a new certificate for this purpose. Please follow the steps below on how to upload a certificate:
-
After obtaining a copy of your certificate (.pfx), install the certificate to the Certificate Manager tool under local machine on the server the application will be installed on

-
Ensure the certificate has been given a friendly name, this is required when installing the app to the server

-
Please ensure the account that will be running the application pool for the application has access to the certificate private key
-
Right-click the certificate > All Task > Manage Private Key

-
Grant the account running the app pool full control permission on the certificate
-
Export the public key from the certificate using this guide (https://docs.microsoft.com/en-us/azure/application-gateway/certificates-for-backend-authentication), you will only need to complete steps 1 to 7 in the Export authentication certificate (for v1 SKU) section
-
Upload your certificate public key (.CER) to Microsoft Azure for the 365|2CM application by going to the Certificates & secrets section

VALUES REQUIRED FOR INSTALLATION
The following values will be required for the installation of FYB Explore. Please ensure that the person responsible for the installation has these values.
- Redirect URI
- Application ID
- Tenant ID
- Certificate Friendly Name
- Content Manager Application Id
| Name | Description |
|---|---|
| Redirect URI | The URI where Azure will send the authentication payload upon successful authentication. |
| Application ID | Application's unique identifier on AzureAD. |
| Tenant ID | The organization tenant's unique identifier on AzureAD. |
| Application ID URI | Application ID URI of the registered Content Manager application. |
| Certificate Friendly Name | The friendly name of the nominated certificate (.pfx) installed on the machine. This certificate is used to prove the application's identity by encrypting the application's claims in the form of a JWT token. |
| Content Manager Application Id | The application Id of the Azure App used for the Content Manager Service API |
ENDPOINTS
All valid endpoints for the registered application can be seen via the Azure web portal.
-
Select the registered application on Azure
-
From the Overview page select Endpoints

