Federating SharePoint with EmpowerID

Owned by Universal Importer for Confluence
Last updated: Aug 17, 2018 by Kim Landis (Unlicensed)
Home / Installation and Configuration Guide / Configuring EmpowerID / Connecting to Directory Systems / SharePoint / Current: Federating SharePoint with EmpowerID



In an environment with Microsoft SharePoint, you can configure EmpowerID as a claims-based authentication provider for your SharePoint farm. Using EmpowerID in this way allows you to extend EmpowerID's RBAC model to your corporate SharePoint environment, giving you greater flexibility and control over how you assign user's access. Before configuring EmpowerID as a SharePoint claims provider, the following prerequisites must be met:

   

Prerequisites


  • A network reachable EmpowerID Web Role server (over port 443) must be configured for SSL and SAML SSO Claims.
  • The EmpowerID SharePoint 2013 Web Services package (for SharePoint 2013) or EmpowerID SharePoint 2016 Web Services package (for SharePoint 2016) must be installed on all SharePoint servers in the farm. Doing so makes the following changes to the SharePoint servers:
    • It adds a new TheDotNetFactory key to the registry with EmpowerID and Federation subkeys.
    • It creates a new Web application, named either EmpowerIDWebService45 for SharePoint 2013) or EmpowerIDWebService4516 (for SharePoint 2016), and an application pool, named either EmpowerIDSharePoint2013 or EmpowerIDSharePoint2016, for that application in IIS.
    • It adds the EmpowerID.BPM.SharePoint.EventReceiver2013 (for SharePoint 2013) or EmpowerID.BPM.SharePoint.EventReceiver2016 (for SharePoint 2016) assembly to the GAC.

  • The public key of the SharePoint SSL certificate and the private key of the client certificate must be exported to the EmpowerID Web Role server.

    The SharePoint server needs to have two certificates, one that can be used for SSL between the server and EmpowerID (known as the SSL certificate), as well as one for EmpowerID to authenticate itself to the SharePoint Web services (known as the client certificate). The SSL certificate is used by EmpowerID to create the endpoint identity for the SharePoint Web services, while the client certificate is used to perform certificate-based authentication for obtaining a security token.

  • The public key and root of the EmpowerID federation (STS) certificate must be exported to each SharePoint server in the farm. This allows SharePoint to authenticate itself to EmpowerID.
  • The EmpowerID > Federation key of each SharePoint server in the farm must have its values configured for EmpowerID. These Federation key values include the following:
    • SPVersion - Specifies the version of SharePoint.

    • EmpowerIDServerFQDN - Specifies the fully qualified name of the EmpowerID Web Role server.

      The URL specified here must have the following entries in theCertificateAppliesTotable of the EmpowerID Identity Warehouse:

        https://<empoweridserverFQDN>/EmpowerIDWebServices/SharePointEventNotificationService.svc

        https://<empoweridserverFQDN>/EmpowerIDWebServices/EmpowerIDSTS.svc

        https://<empoweridserverFQDN>/EmpowerIDWebServices/EmpowerIDCertSTS.svc

        https://<empoweridserverFQDN>/EmpowerIDWebServices/SecureService.svc

      These entries can be generated by navigating to each service URL in a Web browser or by manually adding Trust URIs for each in Workflow Studio. For general information on adding Trust URIs in Workflow Studio within the context of this topic, see Trusted EndPoint for any DNS aliases.


    • ClientAuthCertificate - Specifies the certificate that SharePoint uses to authenticate to the EmpowerID Web services. The public key for this certificate must be installed on the EmpowerID Web Role server.

      Every SharePoint service account needs to have access to the private key of this certificate. This includes all application pool identities on the SharePoint server, as well as all SharePoint service application service accounts.

    • FederationCertificate - Specifies the EmpowerID federation certificate. The public key for this certificate must be installed on the SharePoint server.
    • APILogExceptionsPath - Specifies the folder path to log hidden exceptions. This is only used for diagnosis.
    • ExcludedWebApplications - Specifies a list of Web application URLs to exclude from the UserInfo table sync.
    • SPServerSSLCertificate - Specifies the SSL certificate on the SharePoint server. The public key for the certificate must be installed on the EmpowerID Web Role server.

  • The identity associated with the EmpowerIDSharePoint2013 (for SharePoint 2013) or the EmpowerIDSharePoint2016 (for SharePoint 2016) application pool on each SharePoint server must be changed from NetworkService to an identity that has the following rights:
    • Local administrator
    • Farm admin within SharePoint
    • Web application policy user within SharePoint for each site collection configured for EmpowerID claims augmentation
    • DBO permissions to the Content Databases, Central Admin databases and EmpowerID database

  • The identity associated with the EmpowerIDSharePoint2013 (for SharePoint 2013) or the EmpowerIDSharePoint2016 (for SharePoint 2016) application pool must be registered as the User Profile Service application
  • The identity associated with the EmpowerIDSharePoint2013 (for SharePoint 2013) or the EmpowerIDSharePoint2016 (for SharePoint 2016) application pool must be registered as a Managed Account

Once you have met the above prerequisites, you can configure the federated trust between EmpowerID and your SharePoint farm.

To enable the SharePoint WCF service

  1. On an EmpowerID Web Role server, log in to the EmpowerID Management Console as an administrative user.
  2. From the EmpowerID Management Console, click the application icon and select Configuration Manager from the menu.
  3. In Configuration Manager, click the EmpowerID Servers and Roles node in the application navigation tree and locate the SharePoint Management Web Service in the Jobs grid.
  4. Enable the SharePoint Management Web Service on each desired EmpowerID Web Role server.

To create a SharePoint account store in EmpowerID

  1. On the EmpowerID Web Role server, log in to the EmpowerID Management Console as an administrative user.
  2. From the EmpowerID Management Console, click the application icon and select Configuration Manager from the menu.
  3. In Configuration Manager, expand the User Directories node in the navigation tree and then click Account Stores.
  4. Click the Add New button.



  5. In the Add New Security Boundary window that opens, select Microsoft SharePoint from the Security Boundary Type drop-down and then click OK.



  6. In the Security Boundary Details screen that appears, enter the Name, Display Name, and FQDN for the SharePoint account store.



  7. Click Save.


To configure the SharePoint account store

  1. From the Account Stores grid of Configuration Manager, double-click the SharePoint Account Store you just created, or right-click it and select Edit from the context menu.
  2. In the General pane of the Account Store Details screen that appears, click the Edit button to the right of the SharePoint Agent Server setting. 



    This opens the Choose Servers dialog, which allows you to select one or more EmpowerID Web Role servers running the SharePoint Management Web Service.



  3. From the Choose Servers dialog, toggle the Server button to the left of each desired EmpowerID Web Role server so that the icon for the button changes from a red sphere to a green check box and then click OK to close the dialog. 



  4. In the General pane of the Account Store Details screen, toggle the Allow RET Provisioning button from a red sphere to a green check box if you want EmpowerID to create a Profile record in the SharePoint Profile store. This record is owned by a Person and is used to flow attribute changes to and from the SharePoint Profile record.
  5. In the General pane of the Account Store Details screen, toggle the Allow RET De-Provisioning button from a red sphere to a green check box if you want EmpowerID to delete the Profile record in the SharePoint Profile store when the corresponding EmpowerID Person is deprovisioned or loses this RET policy. SharePoint Profiles exist in a One-to-One relationship with Person objects in EmpowerID.
  6. In the General pane of the Account Store Details screen, select Allow Create Account On Membership Request to allow users without accounts to request group membership and automatically have an account created.
  7. In the Inventory pane of the Account Store Details screen, toggle the Enable Inventory button from a red sphere to a green check box to enable EmpowerID to inventory your SharePoint objects.
  8. In the SharePoint Group Claim Enforcement pane of the Account Store Details screen, click the Edit button to the right of Resource Enforcement Type and select the desired type of enforcement from the Change Resource Enforcement Type dialog that appears. The following options are available:

    • No Action - No rights enforcement action occurs.
    • Projection with No Enforcement - Changes to rights within EmpowerID occur only within EmpowerID; they are not passed on to the native SharePoint environment.
    • Projection with Enforcement - Changes to rights within EmpowerID occur within EmpowerID and are enforced within the native SharePoint environment. This is the default setting.

    • Projection with Strict Enforcement - EmpowerID overrides any changes made in the native SharePoint environment. All changes made must occur within EmpowerID to be accepted. Strict Enforcement only applies to SharePoint Groups.

      EmpowerID inventories SharePoint groups and enforcement adds one EmpowerID claim as a member of each group. The claim has the same name as the group with a GUID as the unique identifier. Getting access to the member Resource Role in EmpowerID means that this SharePoint group membership is added as a claim to the login token. SharePoint sees from the token that the member has a claim which is a member of this group.

  9. In the SharePoint Group Enforcement pane of the Account Store Details screen, toggle the Enable this Functionality button from red sphere to a green check box to enable SharePoint Group Claim Enforcement to occur.

Next, we need to add the SharePoint configuration settings to each SharePoint Resource System EmpowerID created for each connected SharePoint server.

To add the SharePoint configuration settings

  1. In Configuration Manager, click the Resource Systems tree node and then double-click the SharePoint Resource System or right-click it and select Edit from the context menu. 



  2. Click the Settings tab in the SharePoint Resource System screen. 



  3. Click Add New and then do the following:
    1. Type SPVersion in the Name field.
    2. Type your SharePoint version (2013 or 2016) in the Value field.
    3. Click Save.

  4. Click Add New again and then do the following:
    1. Type SPServerFQDN in the Name field.
    2. Type the fully qualified domain name of your SharePoint server in the Value field.
    3. Click Save.

  5. Click Add New again and then do the following:
    1. Type SPServerClientCertificate in the Name field.
    2. Type the thumbprint of the client certificate in the Value field. This is the SharePoint server certificate that EmpowerID uses to authenticate to the SharePoint Web services.
    3. Click Save.

  6. Click Add New again and then do the following:
    1. Type SPServerSSLCertificate in the Name field.
    2. Type the thumbprint of the SSL certificate in the Value field. This is the SharePoint SSL certificate that EmpowerID uses to create the endpoint identity for the SharePoint Web services.
    3. Click Save.

When you have completed the above, you have four Name/Value pairs that look similar to the below image. The Names must be identical to those depicted, while the Values may differ accordingly.

Next, we need to add the SharePoint certificates to the EmpowerID Certificate store. We demonstrate this in the section below.


To add the SharePoint Certificates to EmpowerID

  1. In Configuration Manager, expand the EmpowerID Servers and Role node in the application navigation tree and then click the Manage Certificates node.
  2. Click the Add New button located above the Certificates grid and select From Local Store from the context menu.



  3. In the Windows Security dialog that appears, select the SharePoint SSL certificate you exported earlier, click OK and then click No when asked if the certificate requires a password. If you are using the EmpowerID SSL/STS certificate for your SharePoint server you can skip to step 5 below.
  4. Click Add New again and select From Local Store.
  5. In the Windows Security dialog that appears, select the SharePoint client certificate you exported earlier, click OK and then click Yes when asked if the certificate requires a password.
  6. Type the password for the certificate and then click OK.


Next, we need to map the SharePoint client certificate to an EmpowerID Person. Because the SharePoint Web services are claims-based, EmpowerID uses this Person to access those services. Create a new Person account strictly for this purpose.


To map the SharePoint Client Certificate to an EmpowerID Person

  1. Log in to the EmpowerID Web application as an administrator.
  2. From the Navigation Sidebar, expand Identities and click People.



  3. In the Actions pane, click the Create Person Advanced link.
  4. Enter a first name and a last name for the Person account in the First Name and Last Name fields, respectively. As this Person account serves as a claims identity for the SharePoint Web service, you should name it accordingly. In our example, we are naming the Person "SharePoint Person Service Account."
  5. Specify a login in the Login field. (This user should never have to log in to EmpowerID.)
  6. Underneath Primary Business Role and Location, click Select a Role and Location.
  7. In the Business Role pane of the Business Role and Location selector that appears, type Temp, press ENTER and then click Temporary Role to select it.



  8. Click the Location tab to open the Location pane and then type Temp, press ENTER and click Temporary Role to select it.



  9. Click Select to select the Business Role and Location for the Person account and close the Business Role and Location.
  10. Type All Access in the Management Role field and then click the tile for that role to select it.



  11. Click Save to create the EmpowerID Person.
  12. Once EmpowerID creates the person, navigate back to Person Manager by clicking the Find People breadcrumb at the top of the page.
  13. In Person Manager, search for the person you just created and then click the EmpowerID Login link for that person.



    This directs you to the View One page for the person.View One pages allow you to view details about an object in EmpowerID and make changes to those objects as needed.



  14. From the View One page for the person, expand the Editable Multivalued Fields accordion and then click the Edit link in the Mapped Login Certificates pane.



  15. Search for the SharePoint client certificate and then click the tile for the certificate to select it.



  16. Click the Save link.


Next, we need to create a WS Federation Connection for SharePoint in EmpowerID. We demonstrate this in the section below.


To create a WS-Fed Connection for SharePoint

  1. From the Configuration Manager application tree, expand the Federation > WS-Federation nodes and then click WS-Federation Connections.



  2. Click the Add New button located above the Configuration Manager grid. In the WS-Federation Single Sign-On Details screen that appears, do the following:

    1. Type a name for the WS-Federation connection in the Name field.
    2. Type a description for the WS-Federation connection in the Description field.
    3. Type http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name in the Map to Account Claim Type field.
    4. Type ~/Resources/Content/Images/Logos/EmpowerIDDark.png in the Image field.
    5. Select EmpowerID from the Account Store drop-down list.

      The screen looks similar to the following image.



  3. Click Save.

Next, we need to configure a federated trust between the EmpowerID Security Token Service (STS) and your SharePoint.

To configure a federated trust between EmpowerID and SharePoint

  1. Log in to Workflow Studio as an administrative user and from Solution Explorer, click the SharePoint tab to view the SharePoint resource system you just added to EmpowerID. 



    The following steps need to be performed once for each SharePoint farm in your environment.

  2. Click the node for your SharePoint system and wait for Workflow Studio to load your SharePoint sites.

    You should now see your sites in the SharePoint tree under your SharePoint resource system.

    If your SharePoint sites do not appear in the SharePoint tree, ensure that the SharePoint Management Web Service is enabled on at least one EmpowerID Web Role server and that the SharePoint Agent Server is set on the SharePoint Account Store Details screen.




  3. From the SharePoint tree, expand the node for your SharePoint site and then right-click your SharePoint Site Collection URL and select Enable SignIn/SignOut with Federation Trust from the context menu.



  4. Click Yes to confirm that you want to proceed with the overwrite.
  5. Right-click your SharePoint site collection URL again and select Register Federation Trust Claims Provider from the context menu.



  6. Click Yes to confirm you want to register the EmpowerID SharePoint Claims Provider.
  7. Click OK to close the Success message box.
  8. From the SharePoint tree, right-click your SharePoint site URL again and select Configure Security Token Service Federation Trust from the context menu.



  9. In the Federation Trust wizard that appears, click Next.



    1. Select the STS certificate and the Root Authority certificate and then click Next. (This is the Server certificate and the CA for that certificate configured for each EmpowerID Service.)



    2. Verify that the values for Identity Provider, Passive STS, Service Provider Connection and Realm are correct and click Next. The following image shows what the wizard looks like with the above values entered for our environment.



    3. Click Next to complete the registration.

  10. From the SharePoint tree, expand the SharePoint Central Administration node and then right-click the Central Administration site URL and select Open Web Site from the context menu.



  11. From Central Administration, click Security section and then click the Manage Trust link underneath General Security. 



    You should see EmpowerID listed as a Trusted Service Provider.

  12. Click the EmpowerID link to select it and then click the Edit button in the Trust Relationships ribbon.



  13. In the Establish Trust Relationship dialog that appears, verify the following and then click OK to close the dialog.
    • The Root Certificate thumbprint matches the STS root or STS intermediate certificate used in Step 10.
    • The Security Token Service (STS) certificate thumbprint matches the STS certificate used in Step 10.



  14. (Optional) - If the STS certificate used in Step 10 chains to a root certificate that has not yet been added to the SharePoint certificate store, return to the Trust Relationships page and click New. 



    In the Establish Trust Relationship dialog that appears, type a name of your choosing in the Name field and then click the Browse button under Root Authority Certificate.



  15. Browse the file system and select the certificate that serves as the root certificate in the STS certificate chain and click OK.
  16. Click OK to close the Establish Trust Relationship dialog.

Now that the federated trust has been configured, you can convert your SharePoint sites from Windows Auth to Claims-based. We demonstrate this below.

To convert existing SharePoint sites to Claims Auth


The following steps need to be performed for each SharePoint web application that you wish to use Claims-based Authentication

  1. In Workflow Studio, right-click the root SharePoint site collection of the SharePoint web application that you wish to convert from Windows authentication to claims-based and select Use Claims-based Authentication Provider from the context menu.



    1. Click Yes to confirm you want to use EmpowerID as a claims-based authentication provider for the site collection.
    2. Click OK to close the Success message box.

  2. Back in the SharePoint tree of Workflow Studio, right-click the SharePoint site collection and select Recycle Web Server (IIS Reset) to Reset IIS one more time.



    1. Click Yes to reset IIS.
    2. Click OK to close the IIS reset completed message box.

  3. From the SharePoint tree, expand the SharePoint Central Administration node and then right-click the Central Administration site URL and select Open Web Site from the context menu.



  4. In the SharePoint Central Administration page that appears, under the Application Management section, click Manage web applications.



  5. In the Web Applications Management page that appears, click the SharePoint web application you are federating with EmpowerID and then click the Authentication Providers button in the ribbon.



  6. In the Authentication Providers dialog that appears, click the desired SharePoint zone for the SharePoint web application you are federating with EmpowerID.



  7. In the Edit Authentication page that appears, scroll to the Claims Authentication Types pane, select Trusted Identity Provider and then select EmpowerID.



  8. Scroll down to the bottom of the Edit Authentication page and click Save.

    The following steps need to be performed for each SharePoint site collection that resides within a SharePoint web application that uses Claims-based Authentication.

  9. From Central Administration, click Application Management and then click Change site collection administrators under Site Collections.



  10. In the Site Collection Administrators page, click the Browse button to the right of the Secondary site collection administrator field.



  11. In the Select People dialog that appears, click the People node under the EmpowerID Identity Provider node and then click EmpowerID Built-In Administrator. This is necessary to allow the EmpowerID Administrator the ability to log in to the SharePoint site to set permissions for your EmpowerID users once the site has been converted.



  12. Click OK to close the Select People dialog and then click OK to close the Site Collection Administrators page.

    The following steps need to be performed for each SharePoint server that services the web application being federated

  13. From the SharePoint tree of Workflow Studio, right-click the SharePoint site again and select Configure Web.Config for Security Token Service Federation Trust from the context menu.



    Make a backup of the Web config file before proceeding with the steps below.

  14. In the EmpowerID STS SharePoint Web.Config Configuration dialog that appears, do the following:

    1. Ensure the Site Collection, Passive STS, and Realm fields are populated correctly. If any are incorrect, add the correct values.
    2. Select the Relying Party certificate from the Relying Party Certificate drop-down. (This is the same Server certificate configured for each EmpowerID Service.)
    3. Click the Web.Config button (...) and type the path to the Web.config file for your SharePoint site in the dialog. By default, this file is located at "\\servername\c$\inetpub\wwwroot\wss\VirtualDirectories\".
    4. Ensure that both the Passive STS Require STS and Create Federation Trust with EmpowerID based on the RP certificate, Realm and Site Collection if one does not already exist options are selected.
    5. Ensure that the Realm value is the FQDN of your SharePoint server and/or load balancer with /_trust appended.

    The EmpowerID STS SharePoint Web.Config Configuration dialog looks similar to the following image:



  15. Click the Update Web.Config button.
  16. Click Yes in the Confirmation message box.
  17. Click OK to close the Success message box.


If you have an external DNS alias for your SharePoint site, you must configure a trusted endpoint for it in Workflow Studio, as demonstrated below.

To configure a Trusted Endpoint for a DNS alias

  1. If you have an external DNS alias for your SharePoint site, log in to Workflow Studio and click the Application Menu, click the Management Tools link and then click Trusted EndPoint Configuration.



  2. On the Trusted EndPoint Configuration tab, on the right hand side under Certificates, right click your certificate and choose Add New Trust URI.



  3. Enter the external DNS alias of your SharePoint environment appended with /_trust and click OK.

Now that EmpowerID has been configured as a claims provider for the SharePoint Site Collection, you need to turn on inventory and enable SharePoint Group Enforcement claims in EmpowerID. We demonstrate this below.

To enable inventory and claims enforcement

  1. Return to the SharePoint Account Store Details screen in the EmpowerID Management Console.
  2. In the Inventory pane of the SharePoint Account Store Details screen, toggle the Enable Inventory button from a red sphere to a green check box to enable EmpowerID to inventory your SharePoint objects.
  3. In the SharePoint Group Claim Enforcement pane of the SharePoint Account Store Details screen, toggle the Enable this Functionality button from red sphere to a green check box to enable SharePoint Group Claim Enforcement to occur.


Now that EmpowerID has been configured as a claims provider for the SharePoint Site Collection, you can (optionally) grant permissions to your EmpowerID users for SharePoint access. We demonstrate this below by granting all EmpowerID Business Roles membership to the Viewers SharePoint group.

To grant SharePoint permissions to EmpowerID users

  1. From Workflow Studio, right-click the SharePoint Site and select Grant Business Role and Location Permission to SharePoint Group from the context menu.



  2. In the Business Role and Location Selector that opens, select the desired Business Role from the Business Roles tree and the desired location from the Locations tree and then click OK. In our example, we have selected Any Role in Anywhere.



  3. In the Grant Business Role and Location Permission dialog that appears, select the desired SharePoint group(s) from the lower pane and then click OK.



  4. Click Yes to confirm your decision.

    Your EmpowerID users should now be able to log in to the SharePoint site using EmpowerID as the claims provider. You can test this by navigating to the SharePoint site from your browser. You are redirected to the EmpowerIDWebIdPWSFederation application, where you are prompted to enter your EmpowerID credentials.



  5. Enter your credentials and click Login. You are authenticated in EmpowerID and redirected to the SharePoint site.


If you have customized SharePoint master pages for any Web application, you must add the Any Role in Anywhere Business Role and Location to the User Policy for that Web application; otherwise, SharePoint will deny your EmpowerID users access to your SharePoint sites.

  1. From Workflow Studio, right-click the SharePoint Site and select Apply EmpowerID Any Role in Anywhere Policies from the context menu.



  2. Make sure that the Any Role and Anywhere nodes are selected in the Business Role and Location Selector OK.





Related Content


On this page