You may be able to log in to NetDocuments in connection with logging in to your workstation, depending on your firm's system settings. This is done with what is called federated identity – the linking of one identity with multiple other identities.
See our Federated Identity Implementation Guide for more information.
See also our Federated Identity Data Flow Diagram.
What is federated identity?
Federated identity refers to linking a person’s identity in one system with the same person’s identity in another system. NetDocuments implements this linkage via the SAML 2.0 protocol, which is a secure, open standard for linking identity providers with service providers. In SAML 2.0 terminology NetDocuments acts as a service provider. NetDocuments can be linked via SAML to an identity provider, which is a system with access to user accounts and user login information. In most cases the user data is stored in a directory service, such as Windows Active Directory, and the identity provider is a separate system that integrates with the directory service.
When using federated identity, a user logs into NetDocuments via a login page controlled by the user’s organization instead of using the standard NetDocuments login page. After logging in, the organization’s identity provider constructs a SAML token containing the user’s identity, a timestamp, and claims. Claims are statements about the user, such as his name, email address, phone number, and groups the user belongs to. The SAML token is cryptographically signed and sent to NetDocuments. NetDocuments validates the token’s signature to verify that it hasn’t been tampered with and that it was issued by the correct identity provider, checks the timestamp to make sure the token is current, and then logs the user into NetDocuments.
Why should I use federated identity?
Federated identity provides significant benefits to both end-users and IT administrators.
- Single sign on – When a user’s organization account (such as his Windows Active Directory account) is linked to his NetDocuments account, the user no longer has to remember a NetDocuments username and password; he accesses NetDocuments by logging into his organization account. This can be configured to happen automatically if the user is logging in from within the organization’s LAN. And this is done in a secure way; the user’s organization account password is never sent to NetDocuments. SAML-based single sign on doesn’t require an ActiveX control, and it works with all browsers supported by NetDocuments.
- Organizational control over the login process – Since users are logging into NetDocuments with their organization accounts, the organization has complete control over the login process and credentials. They can determine their own policies for minimum password length, password complexity, frequency of required password changes, two-factor authentication, etc.
- Automatic user account updates – When information about a user, such as his name, email address, or phone number, is updated in his organization account, his NetDocuments account can automatically be updated the next time the user logs into NetDocuments.
- Dynamic group membership – SAML tokens sent from an identity provider may optionally contain group membership claims. When group membership claims are present and they match existing groups in NetDocuments, the user is automatically added to the matching NetDocuments groups. The dynamic membership is temporary, and the user is automatically removed from the group the next time the user logs in unless the SAML token sent with the subsequent login contains a matching group membership claim. This means that when users’ roles change, administrators don’t have to update group memberships in two places; they only have to adjust group memberships in the organization’s directory service and the membership changes will automatically flow into NetDocuments.
- Just-in-time provisioning – When a new user account is created in the organization’s directory service, a corresponding user account can be created in NetDocuments automatically the first time the user goes to NetDocuments.
How does a NetDocuments account become linked to an organization's user account?
When a SAML token is presented to NetDocuments and the user identity contained in the token has not previously been linked to a NetDocuments user account, NetDocuments checks whether the SAML token contains an email address claim with an address that is in a domain registered to the repository associated with the identity provider that issued the SAML token. If it does, one of the following occurs:
1. If there is an existing NetDocuments account with the email address in the token, the user identity in the token is linked to that NetDocuments account.
2. If there is not an existing NetDocuments account with the email address in the token, a new NetDocuments user account is created and the user is added as an internal member of the repository associated with the identity provider.
When a new NetDocuments user account is created from the Repository Membership page in a repository where federated identity is active, if the email address for the new user is in a domain that is registered with the repository, you have the option of linking the new user with your federated identity provider.
If this option is selected, the link sent to the new user in the welcome message will direct the user to the identity provider’s login page and will then link the new user’s NetDocuments account to his organization user account.
Which identity providers can be used with NetDocuments?
Theoretically NetDocuments can communicate with any identity provider that implements the SAML 2.0 protocol. But there are minor differences in the way each identity provider implements the protocol. NetDocuments has been tested with and officially supports only the following four identity providers:
- Active Directory Federation Services (AD FS) – AD FS is an add-on to Windows Active Directory that typically runs on an organization’s servers. It is highly configurable, allowing an administrator to precisely control what information is sent from Active Directory to a service provider like NetDocuments.
- Windows Azure Active Directory (WAAD) – WAAD is a cloud-based partial replica of an organization’s Active Directory domain. It allows an organization to implement federated identity without deploying and managing additional servers. Organizations that have deployed Office 365 have already created a WAAD instance, and that existing WAAD instance can be configured to communicate with NetDocuments. WAAD does not send phone number or organization name claims, so these NetDocuments user attributes cannot be updated automatically from the directory service when using WAAD.
- Okta - Okta is a cloud-based identity provider that can integrate with Windows Active Directory and many other identity systems
- OneLogin - OneLogin is a cloud-based identity provider that can integrate with Windows Active Directory or other user directories or run independently with user accounts configured directly in OneLogin
More information is provided in the document linked above about how to configure each of these identity providers to communicate with NetDocuments.
NetDocuments may be tested with and officially support additional identity providers in the future, and any other SAML 2.0 identity provider might be able to be used, but NetDocuments only tests and supports the four providers listed above.
NOTE: We recommend one of the cloud-based options over ADFS because it does not provide the redundancy that the cloud-based options do. For example, if something happens to your ADFS server, then your NetDocuments connections will have to all be changed in order for users to login until the server is back up.
NOTE: Login logging is not available when attempting to authenticate to NetDocuments.
How does an organization start using federated identity with NetDocuments?
1. Set up your identity provider and make sure it is configured to talk to your directory service. For example, if using WAAD you need to use the Windows Azure management tools to configure your WAAD instance to sync with your Active Directory domain. If using AD FS you need to install AD FS on one or more servers and configure those servers to talk to your Active Directory domain. If you plan to allow users to access NetDocuments from outside your offices, you will also need to configure your firewall to allow users on the Internet to access your AD FS servers.
2. Log into NetDocuments, go to the Add/Remove Users and Groups page, and click on the “Configure advanced authentication options” link.
3. The Advanced Authentication Configuration page has a section titled Federated Identity. Choose the type of federated identity server you will use.
4. Configure the metadata document.
Option 1: Paste in your identity provider’s federation metadata document URL. Click OK to save the configuration.
There is also an option here to allow users to use their NetDocuments username and password as well as their identity provider credentials.
Option 2: A link to the NetDocuments federated identity metadata document is shown. Copy this URL and use it to configure your identity provider to communicate with NetDocuments. See details in the following sections.
As noted on the Advanced Authentication Configuration page, many features of federated identity rely on having your organization’s email domain (the part of your email addresses after the @ sign) registered with NetDocuments. If you have not already done so, contact NetDocuments Support and ask that your email domain be registered.
How do users log in to NetDocuments via federated identity?
When a user with a federated identity wants to log into NetDocuments, the user’s browser needs to be redirected to the identity provider’s login page. There are 3 ways this can be done:
1. The user can click the "Need login assistance" link on the NetDocuments login page and then click on “I want to use my organization’s login”. This displays a form where the user can enter their email address.
If the user enters an email address with a domain that has been registered to a repository where federated identity has been configured, the user’s browser will be redirected to the identity provider’s login page.
2. A repository ID can be passed to NetDocuments in the URL the user uses to get to NetDocuments. The repository ID is passed as a querystring parameter with the name “whr”. For example, if the repository ID is CA-AUW52T23, the URL https://vault.netvoyage.com/neWeb2/docCent.aspx?whr=CA-AUW52T23 could be used. This URL could be sent to users in an email, or an organization’s internal web site might include a page with a link using this URL. When a user accesses this URL his browser will be automatically redirected to the identity provider’s login page (if he isn’t currently logged into NetDocuments); the user will not even see the NetDocuments login page.
3. When either of the previous methods is used and the user then logs into NetDocuments via a SAML token sent from the identity provider, a cookie is stored by the user’s browser. This cookie will cause the user’s browser to automatically redirect to the identity provider’s login page whenever the user subsequently needs to log into NetDocuments. So users will generally only have to use one of the first two methods once per browser, and after that the login redirection will happen automatically. If the login redirect cookie needs to be cleared, go to https://vault.netvoyage.com/neWeb2/docCent.aspx?whr=clear while not logged into NetDocuments. This will erase the login redirect cookie, which can be helpful when testing various scenarios.
After logging into the identity provider, the user’s browser will be redirected back to NetDocuments with a SAML token. NetDocuments will verify the token’s source and integrity via the digital signature applied to the token. NetDocuments will also compare the current time to the valid time period specified in the token. It is essential that the identity server’s clock is set to the correct time or this comparison may fail, causing the token to be rejected as invalid. If the token is confirmed to be valid, NetDocuments logs in the user and updates the user’s attributes and group memberships based on the claims contained in the token.
When testing your identity provider configuration you may find it helpful to append the parameter “samlTest=Y” to a NetDocuments URL, for example https://vault.netvoyage.com/neWeb2/docCent.aspx?whr=CA-AUW52T23&samlTest=Y. With this parameter you will not be logged into NetDocuments, but the SAML token sent to NetDocuments from the identity provider will be displayed in the browser. In some browsers you may need to right click on the page and View Source to see the token. By examining the data in this token, especially the AttributeElement statement, you can determine whether your identity provider is sending the claims you expected it to send.
What doesn't work with federated identity?
Federated identity can’t be used with applications that prompt for a username and password and attempt to access NetDocuments with those credentials. As discussed in the previous section, the SAML protocol involves a browser-based user interface that can be redirected from NetDocuments to the organization’s identity provider. Depending on how it is configured, the identity provider might simply prompt for a username and password or it might ask for other information such as the value shown on a time-based token or a code sent to the user’s phone. An application that simply prompts for username and password can’t provide this information.
This means that applications that access NetDocuments via the NetDocuments SOAP API cannot be used by users with federated identities. These applications should be updated to use the NetDocuments REST API. Applications calling the NetDocuments REST API authenticate via the OAuth protocol, which is compatible with federated identity.
This also means that users with federated identities cannot access NetDocuments via applications that use the WebDAV protocol (WebFolders), because these applications authenticate with a username and password.
How does this affect External Users and ShareSpace Users?
Only users with an email address of the registered domain will be automatically logged in through federated identity.
Changing a user's NetDocuments username or password
With FI configured, a user's password needs to be reset only in ADFS. In practice, they do not have a password for their NetDocuments account.
Users will see the option to change their username, but it requires a password (which a federated identity user doesn’t have in most cases). So if a Federated identity user would like to change their username then they need to ensure the Administrator has this setting checked in their federated identity configuration with NetDocuments.