User Guide – SP2013 – Authentication

ATTENTION: Starting with version 2.4.1, we have introduced a new service-based authentication system which enables users to skip the following section. You may still use the system outlined below, however, we recommend using our new system in most cases. Please see the section labeled “NEW: Service-Based Authentication” for more information

Prior to the installation of any other WebParts, the netDocShare Auth WebPart must be installed first. This WebPart is required for security reasons, as your NetDocuments account is secured by login and authentication processes. If the Auth WebPart is not added, the other WebParts will be unable to login to NetDocuments. Alternatively, you can add each webpart URL as a redirect URI to your NetDocuments developer account, this is not recommended as best practice, but it is possible if you are only using a few instances of the webpart.

Step-by-step installation instructions:

Create a new page to place the Auth webpart in. It is recommended to name the page “Auth” or “Authorization”.

Note: This page does not have to be the same page as where you wish to install the Document Viewer, RecentDocs, TreeView WebParts. The netDocShareAuthWebPart only needs to exist on a page within the scope of your Root Site Collection in order to facilitate the NetDocuments authentication procedure for all the included WebParts.

To add a webpart, Click Page in the upper left-hand corner. Next, click Edit Page on<br /> the ribbon’s far left.

Once you’ve begun editing the current page, in the upper Left-hand corner, click “INSERT”,<br /> and then click “Web Part”

Under the Categories gallery, find and the folder named “NetDocuments Webparts” from the menu and select the Auth WebPart. Note: Your category list may look different depending on what you have installed on your SharePoint tenant.

1. Once the webpart is added, you will see that the newly added Web Part says, “Please input your NetDocuments Configuration Object.” Click the Web Part menu (small arrow in the upper right-hand corner) and then select Edit Web Part.

2. Classic SharePoint:

Select Extended Settings at the bottom and enter the App Configuration Auth JSON Object (Example provided in following step) inside the Config Settings field, then click Apply.

Classic SharePoint (Team Site):

At the Configure web part, click “Configure”. Enter the App Configuration Auth JSON Object (Example provided in following step) inside the Enter your Webpart Config here field, then click “x” at top-right and click Apply.

3. An example and explanation of this Auth JSON Object is as follows:

{

“viewType”: “Auth”,

“netDocsClientId”: “AP-P0V35CC”,

“netDocsClientSecret”: “22neL4s4DF5WU18RMaUX2pikMzg460urwyr2xMCsf”,

“netDocsBaseUrl”: “https://api.vault.netvoyage.com/v2“,

“CDNBaseUrl”: ” https://klstsp13d-sp:5807/ “,

“authPage”: “redirect”

“AuthSuffix”: “Pages/auth.aspx ”

}

For explanations of each property, what they do and what values should be used to change them, please see our Config Builder Properties Appendix at the end of the document.

If you are intending to use the ‘redirect’ option for Auth, please include “authPage”: “redirect” in ALL webparts, not just the Auth webpart. If you are intending to use iFrame, you may omit this property<br /> in all webparts.

Additionally, if you wish to auth page with redirect enabled, once the page has been created you will not be able to<br /> edit the page, due to the default behavior of the page, that redirects you to the netdocuments auth pages.

In order to edit an existing<br /> auth page, you will have to delete the currently implemented one, and create a new one.

AuthSuffix should be the relative path of the<br /> page where the netDocShare Auth WebPart exists. In the example above, the full webpage URL for the Auth WebPart would be:

4. Once the configs are applied, the WebPart will open a popup containing a NetDocuments authorization page. You may close the popup by pressing the ESC button if you are in the process of saving and publishing your page. The authorization does NOT need to happen now. This page exists so that other webparts can use its URL to authenticate with NetDocuments.

5. Note: The page to which you add the Auth WebPart must be registered with your NetDocuments Developer account (https://NetDocuments.force.com) as a redirect URI. With this method, no matter where your other netDocShare WebParts are, the NetDocuments REST API will always authenticate to the URL where your Auth WebPart exists.
This allows multiple WebParts on the site collection to be authenticated from just 1 location. Without this process, every WebPart page will need to authenticate on its own, requiring you to add every URL to the Dev account.

6. Now that you have a netDocShare Auth WebPart, you may create or navigate to any other page within the scope of your Root Site Collection and install any of the other netDocShare WebParts using the same process as above. For every following webpart, you will need the CDNBaseUrl and AuthSuffix to point towards the Auth webpart page that you just created.

7. Once the Auth process activates, a popup will be opened with a NetDocuments login screen similar to this:

Enter your NetDocuments credentials. It should recognize that the login is coming from a custom app instead of a general browser login. It will then ask for permissions for this specific app on a screen that looks like this:

Note the name of the app, which should match the name of the App created in your netdocuments.force.com account

You must click ‘Allow’ for the app to work but you do NOT have to do it during the process of setting up Auth for the first time. When in initial setup, all you need to do is make sure that the app name, redirect URL and login details on the top right are correct. You may press escape to cancel the popup and save the webpart page to continue.

Note: When making the Auth page for the first time, once you have determined that the configs are correct, simply save the page. You may notice that if you press “Allow” in this initial state, it may redirect you to an empty or blank page. This is because the Auth webpart is designed to be used as a part of the authorization process, in which it will re-direct users back to the original requesting page after authorizing. This will not work if you do not have other webparts created yet.

Invalid URL error

Users must make sure that the URL they submit to https://netdocuments.force.com is EXACTLY the same as their auth page URL. This must match case and spelling exactly or else it will throw invalid URL error. This includes http and https.

Duplicate Webparts

In some older SharePoint versions, webparts linger on the page even after they have been deleted. The number of webparts can be seen here:

If there is more than one webpart on a page, it will impact how our software will function, e.g. the page might have multiple auth popups among other things, as the hidden webparts will still be loading code. To remove the unnecessary webparts officially, open the page in Web Part Page Maintenance and remove hidden webparts.

Auth failing to refresh or redirect

If Authentication is failing to redirect or failing to reload the page after logging in or clicking the “Allow / Deny” prompt, this may be due to existing errors on the page which may block attempts to navigate to another page. In order to avoid this, or to test whether this is the issue, please insert our webpart on a blank Sharepoint page that loads no other content such as ScriptEditor webparts or scripts embedded into the Master Page. If the webpart can work on the blank page but not on the original page, there is some content that is blocking the functionality of our app. In this case, we recommend fixing the existing errors on the page or using a page which does not load the problematic content.

The process of authenticating with NetDocuments requires some steps in your NetDocuments administration account. This can be reached through https://netdocuments.force.com/.

In order to obtain the netDocsClientId and netDocsClientSecret (required for each webpart), you must create an “app” on https://netdocuments.force.com/. You should be lead to the following screen:

Fill in the required fields and make sure to keep track of 2 important things:

Once you save, your Client Id and Client Secret will be generated. Please keep track of them as they will be required in every webpart’s config.

Redirect URI and Additional Redirect URIs will be very important once you have begun to create webparts. Every environment requires a distinct Redirect URI which is used to redirect you back to your source after executing standard Oauth authentication procedures. Each distinct environment must have its own authentication page

You must include every redirect URI that you are planning to use into this list or else the authentication will return Invalid Redirect URI errors. Note that the RedirectURIs are very case sensitive.

Once the Auth webpart is created, you can create another webpart which will retrieve data, on a page such as:

https://klstsp13d-sp:5807/Pages/documentView.aspx

Now, the full authentication cycle should be complete. Let’s see an example of how it works using our example pages:

User visits the documentView.aspx page in order to see their documents

A request to the NetDocuments<br /> API will require an access token, if there is no token, the app will bring up the auth.aspx page as a popup**.

The Auth page will use<br /> existing info OR ask the user to login and an authorization request is sent to NetDocuments with the auth.aspx page as a redirect

NetDocuments<br /> sends an authorization code which brings up the “Allow / Deny” dialog.

Once “Allow” is pressed, NetDocuments will send a refresh token<br /> and an access token. Congratulations! Authentication is complete and the user will be taken back to documentView.aspx where they can view any number of documents until the token expires

** Users have the option to choose between 2 Authentication styles that we offer: iFrame or redirect. We recommend iFrame as it is a smoother user experience, in that it is a 2-step process instead of a 3-step process. However, we offer the second option as some client environments may block iFrame windows for security reasons.

With ‘iFrame’, the webpart will open a modal iFrame window popup which will contain the Login or Allow / Deny pages served by NetDocuments. Then, it will refresh the original page with the new credentials active.

With ‘redirect’, the webpart will change the current page’s url to manually navigate to the Login or Allow / Deny pages served by NetDocuments. Then, it will redirect back to the user’s set up Auth page and from there, they will be redirected a 3rd time back to the original page which requested the permissions.

Access Tokens

Access tokens have a limited lifespan. They expire after 60 minutes of no activity or between 24 and 48 hours of when they are issued. If an API is made with an expired token, a 401 Unauthorized status is returned. netDocShare automatically processes expired tokens and attempts to retrieve a new token when required. For this, we use refresh tokens which last much longer.

With the new OAuth implementation, the refresh token with full access will expire in 40 days rather than 1 year. A refresh token with the least access will expire after 90 days. Once the refresh token has been depleted, users will be expected to enter their login credentials again in order to obtain a new refresh token.

This is different from a login lifetime when using NetDocuments itself. NetDocuments for security reasons will log out users automatically after 90 minutes of inactivity. As a NetDocuments user, you can enable an automated login option if your organization has Microsoft Active Directory Services.