Integrating External Authentication Providers With Sharepoint Online Using Javascript

Overview of External Authentication in SharePoint Online

SharePoint Online supports federated authentication workflows to enable users from external identity providers like Azure AD, ADFS, and third-party authentication providers to securely access SharePoint resources. The key capabilities offered are:

• Ability to configure SharePoint Online tenant to federate with external providers using standard protocols like WS-Federation, SAML 2.0, and OpenID Connect.
• Create federated trust relationships between SharePoint Online tenant and other identity providers for enabling single sign-on.
• Use external authentication providers like Google, Facebook, Microsoft Account etc. for login into SharePoint Online using OAuth 2.0 and OpenID Connect.
• Develop custom Web/JavaScript apps for initiating and managing federated authentication flows.

By integrating external identity providers, SharePoint administrators can enable centralized identity and access management while providing users flexibility to use their existing credentials for logging into SharePoint.

Key Components for External Authentication

The key components involved in configuring external authentication providers with SharePoint Online are:

1. SharePoint Online Tenant: This represents the SharePoint environment hosted on Microsoft’s cloud which needs access management using external identity providers.
2. Azure Active Directory Tenant: The Azure AD tenant associated with the SharePoint Online subscription which facilitates federated authentication capabilities.
3. External Identity Providers: Third-party identity management systems like ADFS, PingFederate, Okta etc. which hold user identities and credentials.
4. Custom Web Apps: Custom developed JavaScript/REST apps which can initiate and manage authentication flows with external providers.

Prerequisites for Setting Up External Authentication

Before configuring SharePoint Online tenant for external authentication, ensure that the following prerequisites are met:

Compatible Authentication Protocols

The external identity provider service must support standard federated authentication protocols like WS-Federation, SAML 2.0 or OpenID Connect which can integrate with Azure AD system used by SharePoint Online.

CNAME Domain Records

Appropriate Domain Name System (DNS) CNAME records must be created to link custom domains names used by external providers with SharePoint Online URLs.

TLS/SSL Certificates

The identity provider and any custom web apps involved should use valid TLS/SSL certificates issued from trusted Certificate Authorities for enabling secure authentication flows.

Admin Privileges

The user configuring the federated authentication environment must have Global Administrator privileges in both SharePoint Online tenant and Azure Active Directory tenant for that subscription.

Configuring Azure AD Application for External Authentication

A key prerequisite for enabling external authentication is to register a custom Azure AD application in the Azure portal which will facilitate authentication requests and responses between SharePoint Online and the identity providers. The key configuration steps are:

Register New Azure AD App

1. Login to Azure Portal using Global Admin credentials and navigate to Azure Active Directory section.
2. Under Manage section, click on App Registrations to list existing applications.
3. Click on +New registration and create an application providing an appropriate name and supported account types as Single Tenant.
4. Under Redirect URI section, update any valid redirect URLs which will receive authentication responses.
5. Once app is registered, note down the Application (Client) ID, Directory (Tenant) ID values from the Overview section.

Enable OAuth 2.0 Implicit Grant Flow

In the Azure app’s Authentication section, click on implicit grant option and enable both Access Tokens and ID Tokens options to support OAuth 2.0 authentication flows.

Define App Roles for Access Control

Under App Roles section in the Azure app, create custom app roles which map to SharePoint user profiles which need access. These roles will be included in access tokens to authorize users.

Provide Delegated API Access

In API Permissions section, enable Windows Azure Active Directory and SharePoint Online delegated permissions which are required for user validation and profile data access by external providers.

Developing Custom JavaScript for Initiating Authentication Flow

For initiating authentication flows from SharePoint Online pages to external identity providers, custom JavaScript code needs to be developed which can:

1. Detect user click actions for login and acquire consent.
2. Initiate call to federated authentication endpoint of providers by passing relevant parameters.
3. Handle redirects during protocol-specific authentication sequence.
4. Capture tokens, user claims received and submit back to SharePoint Online apps for validation.
5. Render appropriate UI elements showing login, logout statuses.

Key JavaScript APIs and Modules

Some of the key JavaScript interfaces which can used are:

• MSAL.js Library: Provides methods for OAuth 2.0 and OpenID Connect flows like acquireTokenSilent, acquireTokenRedirect.
• ADAL.js: Facilitates similar flows for older Azure environments supporting Active Directory Authentication Library.
• HTTP Cookies: Used for storing tokens, authentication state values across redirects.
• Session Storage: Temp storage mechanism for capturing response parameters during redirects.

Sample Flow using MSAL and OIDC

A sample authentication flow leveraging MSAL and OIDC would be:

1. Detect login action on page and acquire auth code using acquireAuthCodeRedirect API.
2. Azure AD tenant will initiate authentication request to external providers like Auth0, Okta configured.
3. Once user consent received, tokens and claims will be posted back to redirect URLs provided.
4. Tokens can be acquired using acquireTokenRedirect and further validated on server-side.
5. Once validated, SharePoint sites will render as authenticated experiences.

Relevant Security Guidelines

Some security best practices while developing the custom JavaScript code:

• Use mechanisms like CORS, token renewal, nonce validation to prevent CSRF attacks.
• Securely transmit tokens over HTTPS channels to prevent information disclosure.
• Hash or encrypt tokens before storing in cookies or browser storage.
• Set up token expiration times to enforce fresh logins.

Calling Custom JavaScript from SharePoint Pages

Once the custom JavaScript for managing federated authentication flows has been developed, it needs to be hosted and invoked from relevant SharePoint site pages like:

Library Pages

For document libraries containing access-protected files and folders, the JavaScript can be embedded in page templates used by these libraries.

Application Pages

For secure application pages which need authentication, JavaScript can be added in the header placeholders or web part sections.

Common Embedding Techniques

Some options for embedding JavaScript code into SharePoint pages include:

• Refer script library using Content Editor/Script Editor web parts
• Add code snippets in master pages or page layouts using SharePoint Designer
• Provision assets like JS files using SharePoint Framework extensions
• Refer scripts stored in document libraries using Content Search Web Part

Invoking Authentication Functions

The functions initiating login redirects can be invoked on actions like:

• Clicking buttons/links with ids like “login”, “sign-in” etc.
• Checking empty user profile values on page load
• Triggering code on unauthorized errors to protected resources

Testing and Troubleshooting External Authentication

Testing and troubleshooting tips for common issues faced while integrating SharePoint Online with external identity providers:

Check Network Connectivity

Use online tools to verify TCP connectivity checks between SharePoint login page and identity provider endpoints on required ports and protocols.

Capturing HTTP Traces

Enable HTTP tracing on SharePoint site using ULS viewer and capture any redirect errors thrown during authentication sequence.

Analyzing Token Signatures

Use online JWT decoder tools to decode raw value of access tokens received and ensure token signature matches with public certificate of identity providers.

Monitoring Service Health Status

Use Office 365 service health dashboards to check if SharePoint Online or Azure AD services indicate any service degradation incidents.

Generating Test Accounts

Create test user accounts in the external identity provider system and validate all propagation steps needed for account on-boarding are followed before accessing protected SharePoint resources.

Best Practices for External Authentication Integrations

Some recommended best practices for better managing federated authentication integrations between SharePoint Online and external identity providers include:

Enforce Conditional Access Policies

Use Azure AD conditional access capabilities to enforce controls like multi-factor authentication, approved device compliance for accessing SharePoint resources.

Automate Provisioning Workflows

Automate provisioning of user accounts from external identity providers to SharePoint Online using Azure AD B2B invite workflows or SCIM-based sync.

Monitor Usage and Threat Analytics

Use Microsoft tools like Azure AD risk events and usage analytics dashboard to monitor anomalies in authentication patterns and security threats.

Backup Authentication Artifacts

Regularly backup and store authentication artifacts which are non-exportable outside Azure AD like certificates, passwords, client secrets etc. for recovery needs.