Create an O365 service account

ShareDo will typically interact with SharePoint online as the current user of ShareDo once that user has linked their O365 account with ShareDo. In some circumstances, however, it is not possible for the system to always rely on a user having a dedicated account.

• B2C or B2B users who have no user on your 365 tenant
• When workflows need to create SharePoint objects such as folders or sites as part of matter inception processes.

In those circumstances, ShareDo will fallback to using a linked service account instead.

As such, it is important to configure a service account on 365 with appropriate licenses. (The account will need an O365 license such as E3 or another SharePoint Online plan).

Setup site collections

Go to https://admin.microsoft.com/, sign in as a global or SharePoint administrator and then from the left pane, select Resources > Sites (you may need to select “Show all” to see the resources option).

To create a new site collection, click the “Add a site” button;

This will open the “Create site collection” form in a new window. Fill in the requested details, ensure the site name is set to the current year and click OK. For example:

Once the site collection is provisioned (it takes a little while), you can navigate to it (https://[yourTenant].SharePoint.com/sites/2019 in the example above). The site should already have a default document library named “Documents” created – this will be the one used and managed by ShareDo. (If you require different document libraries, or a different structure to your SharePoint sites, this can be addressed with your project team).

The last step is to give the service account provisioned above, for ShareDo, access to the site. Navigate to the site you’ve just created and then;

• Click the cog in the top right, then select site settings.
• Select people and groups
• Select the “[sitename] Owners” group
• Click New > Add Users
• Find / enter the name of the service account created above and then click “Share”.

The service account should now own this site and its contents.

Repeat the above process to create site collections for future years.

Planning your SharePoint online information architecture

ShareDo supports a variety of different documents in the DMS, including:

• Inbound post/emails that is not related to a specific case or matter
• Document Templates and enclosures
• Instruction or Enquiry Specific Repositories
• Matter or Case Specific Repositories

When considering your information architecture for matter related documents you have several different options

• A single site per Case/Matter with documents being held within a specific document library in that matter – this is the default option described above
• A single document library with multiple folders for each matter

Configure repositories in ShareDo to use SharePoint online

Your project team will create the document repository configurations necessary to have ShareDo use your SharePoint online instance. In order to do so, you will need to provide;

• A SharePoint Site and SharePoint document libraries for the document repositories that you require. There is guidance on document repositories and their configuration in this article - ShareDo Document Repositories

Create a ShareDo App Registration in Office 365

1. Open the azure portal at https://portal.azure.com
2. From the left-hand menu select the “Azure Active Directory” resource.
   
3. Select the “App registrations” option.
   
4. Click on the “New registration” toolbar button.
   
   Which will present this form:
   
5. Give the application a name (suggest “ShareDo”), set “Accounts in this organizational directory only”.

Setup integration secret

After setting up the app, you will be presented with the app registration portal for the new application. Select “Certificates and Secrets” from the left-hand menu:

Then, click the “New Client Secret” button. Provide a description and set the expiration ideally to “Never”, though you can specify an expiry of your choosing, but remember once expired, the integration will need to be set up again.

Copy the value of the new secret as you will need it later when setting up the integration in ShareDo.

Setup the redirect URI

Next, click the “Authentication” button from the left-hand menu:

In the Redirect URIs section, add a new redirect of type “Web” with a value of https://[your-ShareDo-instance]/externalServices/replyFrom, then press the Save button.

Setup API Permissions

To allow the App Registration to interact with ShareDo on a user’s behalf a set of delegated API permissions are required. In some organisations, these API permissions require Admin Consent to be granted. This allows users to agree to the API being used on their behalf.

The following delegated API Permissions should be added.

• offline_access
• Files.ReadWrite.All
• Sites.ReadWrite.All

Once added, the permissions need to be given explicit admin consent.

All the permissions should now show they have been granted

Gather information for configuring ShareDo

To configure the integration between O365 and ShareDo, you will need to gather the following information whilst in the azure portal’s app registration page:

• Tenant Id
• Client Id
• Client secret

You should have already copied the client secret when it was setup above. To get the tenant id and client id, click the “Overview” left-hand navigation option.

And this will show a summary as follows;

Copy the values for “Application (client) ID” and “Directory (tenant) ID”.

Set up the SharePoint online DMS linked service in ShareDo

Now that O365 is configured to know about ShareDo, we need to link ShareDo to O365. Go to your ShareDo installation and sign in as an administrator, then open the admin console and select Security > Manage Linked Services (/admin/oauth). A screen similar to that shown below will appear:

Click the “Configure” button on the “Office 365 – SharePoint” card. (It’s presently red as its configuration is invalid, making the service entirely unavailable). You will be presented with the configuration blade for this service.

Fill in the blanks under “Service Configuration” using the details from the app registration above.

• Tenant Id: Set this to the “Directory (tenant) ID” value.
• App Id: Set this to the “Application (client) ID” value.
• Client secret: Set this to the client secret configured in the earlier step.

Once those fields are configured, click “Save and close” from the ribbon to return to the card list, where the “Office 365 – SharePoint” card should update to show that it’s configuration is now valid;

Link the system account in ShareDo

Next, click the “Link” button on the “Office 365 – SharePoint” card and follow the instructions – this will take you through authenticating with office 365 (you will leave ShareDo and go to office 365), agreeing to allow ShareDo access content on their service, and sending back tokens. When prompted, you should login as the service account created for this purpose.

The final step of account linking will show a blade as follows:

Make SharePoint available (and mandatory) to users

When ShareDo talks to office 365, it can do so either using a user token, or a system token. User tokens offer a better experience in that interactions with O365 will be logged as the currently signed in ShareDo user, whereas relying only on the linked system token will show all user interactions as being performed by that service account user.

Not all users will have 365 accounts on your office 365 instance – B2B/B2C users for example – and so we can specify that certain users can link their own accounts, but the system will fall back to the linked system account when a user does not have (or cannot have) their own tokens.

We specify this through configuration. From the ShareDo admin tool “Security > Managed Linked Services”, select “Configure” on the “Office 365 – SharePoint” card. The same blade as detailed above will appear, but this time we are focussing on the “Team Availability” section;

To make this service available to a sub-set of users, start typing the name of a team in the search box, and select one to add it to the list;

The selected team will appear in the list. You can add multiple teams;

Users in any of these teams will be able to manage their link to the O365 service from their“My profile” menu using the “My Linked Services” option. If you want users to be forced to link their O365 account, check the “Required” checkbox.

Setting a team to “required” will result in users in that team, with no linked token, being pestered by ShareDo to link their accounts via toast messages similar to this;

Link user accounts

The process for linking user accounts is identical to linking service accounts above, but is done by the users themselves. On signing in to ShareDo, if users are missing mandatory tokens, they will be nagged as described above. Clicking the reminder toast, or selectin their “My Profile” menu and choosing “My Linked Accounts” will present a card view blade that shows the services they can link, and highlight those that are mandatory and must be configured;

Clicking “Link your account” then starts the authentication and token journey as described in the “Linking the system account in ShareDo”.

Final notes

Once configured, ShareDo will impersonate users when interfacing with O365 – any documents they see in ShareDo will be security trimmed based on permissions in O365, any interactions such as document generation and upload will all be marked as the correct user in O365, and so on, yet the system is still able to function for B2B/B2C users without an O365 account using the low privileged system account that is linked at the system level.