Office 365 Connector 2.1

Transcription

1 Office 365 Connector 2.1

2 Contents 2 Contents Copyright... 3 PingFederate Office 365 Connector Guide Connector overview...4 System requirements...4 Choose a SSO configuration path...4 Installation and setup...5 Setup overview diagram... 6 Prerequisites... 6 Create an Azure account... 7 Install the Office 365 connector...7 Upgrade the Office 365 connector...7 Configure SAML SSO... 9 Configure provisioning PingFederate initial configuration Add SP connection Troubleshooting...24 Attribute index Release notes...27 Change list by version...27 Qualification statement ZIP manifest...29

3 Copyright 3 Copyright PingFederate Office 365 Connector Guide 2017 Ping Identity Corporation. All rights reserved. PingFederate Office 365 Connector 2.1 March, 2017 Ping Identity Corporation th Street, Suite 100 Denver, CO U.S.A. Trademarks Ping Identity, the Ping Identity logo, PingAccess, PingFederate, PingID, and PingOne are registered trademarks of Ping Identity Corporation ("Ping Identity"). All other trademarks or registered trademarks are the property of their respective owners. Disclaimer The information provided in these documents is provided "as is" without warranty of any kind. Ping Identity disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. In no event shall Ping Identity or its suppliers be liable for any damages whatsoever including direct, indirect, incidental, consequential, loss of business profits or special damages, even if Ping Identity or its suppliers have been advised of the possibility of such damages. Some states do not allow the exclusion or limitation of liability for consequential or incidental damages so the foregoing limitation may not apply.

4 PingFederate Office 365 Connector Guide PingFederate Office 365 Connector Guide 2.1 The PingFederate Office 365 Connector enables enterprises to provision users and groups to Office 365. The Office 365 Connector includes a quick connection template to easily set up a connection with O365, which can be used for Single Sign On (SSO) and/or provisioning. The connector makes use of the Azure Active Directory Graph API v1.6 to communicate with Azure, which acts as the user and group repository for Office 365. The connector includes licensing support (skuid and disabledplans attributes) and the ability for managers to be assigned to provisioned users (manager and pingsourcedn attributes). Note: This provisioner is for outbound provisioning only and is not intended for inbound or hybrid environments Connector overview on page 4 System requirements on page 4 Choose a SSO configuration path on page 4 Installation and setup on page 5 Attribute index on page 24 Connector overview The PingFederate administrative console uses a quick-connection template to configure most of the settings needed to use the Office 365 Connector for SSO and provisioning. This document provides instructions for entering site-specific connection settings. Once the settings are complete, you can configure provisioning settings according to your deployment needs. Before configuring an SSO or provisioning connection to Office 365, you must configure (or verify) several system settings in PingFederate. System requirements The Office 365 Connector 2.0 requires installation of PingFederate or higher. In order for the connector to work properly you must configure PingFederate to "Omit Line Breaks in Digital Signatures" by adding the following java startup option to your run.sh, run.bat and/or PingFederateService.conf file: -Dorg.apache.xml.security.ignoreLineBreaks=true Choose a SSO configuration path After installing the Connector use the table below as a reference to determine how to configure your Office 365 SSO deployment with PingFederate. Tip: If you are upgrading from a previous version of the Office 365 Connector, see Upgrade the Office 365 connector on page 7. If you want: SSO only to Office 365 Then: Use the SAML 2.0 Microsoft solution and configure SSO using the steps marked SAML SSO outlined in this document.

5 PingFederate Office 365 Connector Guide If you want: SSO and SLO to Office 365 Active federation Then: Note that some instructions include WS-Federation settings to ease transition to WS-Federation at a later time if desired. To implement this solution, follow instructions in Create a Federated Domain andcreating a Connection to Office 365 and skip the steps marked with SAML SSO in this document. For active federation, refer to the guidelines and instructions in SSO to Office 365 (PF 6.10+). Important: SAML SLO is currently not supported due to a compatibility issue in the SAML implementation between PingFederate and Azure. Once resolved, SAML SLO will work using the instructions provided in this document. Installation and setup This section describes how to perform the installation, setup and configuration of the Office 365 Connector. The instructions are organized in such a way that SSO, provisioning only or both SSO and provisioning can be configured. Refer to the Setup overview diagram on page 6 for information regarding the organization of the steps involved. Tip: The title of steps specific to provisioning or SSO contain the phrase Provisioning Only or SAML SSO as appropriate. If the mentioned feature will not be used, that step can be skipped. Prerequisites on page 6 Setup overview diagram on page 6 Create an Azure account on page 7 Install the Office 365 connector on page 7 Upgrade the Office 365 connector on page 7 Add application to Azure AD (provisioning only) on page 18 Get Azure application ClientId and secret (provisioning only) on page 18 Download Office 365 SAML Metadata (SAML SSO) on page 9 Install Powershell account connection software (SAML SSO) on page 10 Add federated domain (SAML SSO) on page 10 DNS updates (SAML SSO) on page 10 Verify federated domain (SAML SSO) on page 11 Configure federation settings (SAML SSO) on page 11 PingFederate initial configuration on page 22 Add SP connection on page 24 Configure connection (SAML SSO) on page 11 Browser SSO (SAML SSO) on page 13 Credentials certificate management (SAML SSO) on page 13 Add the signing certificate to Azure (SAML SSO) on page 13 Configure outbound provisioning (provisioning only) on page 18 Synchronize existing Office 365 users (provisioning only) on page 20 Provision groups to Office 365 (provisioning only) on page 20 Map users to groups (provisioning only) on page 21 Configure for license management (provisioning only) on page 21 Configure for manager assignment (provisioning only) on page 22

6 PingFederate Office 365 Connector Guide Setup overview diagram The following diagram outlines the high level steps required for installing and configuring the Office 365 Connector for SSO and/or provisioning. Prerequisites A pre-existing Office 365 account is required For SSO: A domain must exist which has been created for use as a federated domain. The domain must be accessible and DNS resolvable by Microsoft. Administrative access to modify DNS records for the federated domain. The PingFederate server must be externally accessible.

7 PingFederate Office 365 Connector Guide A Windows platform is required in order to run SSO related configuration using Powershell. The Windows platform must be able to access the Azure management portal. Create an Azure account Navigating to the Azure management portal and creating an Azure account using the same credentials as those used to log in to the Office 365 admin portal will provide access to the Azure active directory used by that Office 365 tenant. This step is required for both provisioning and SSO. 1. Navigate to the Azure management portal here. ( 2. Create an account using the same credentials as the Office 365 account Install the Office 365 connector 1. Stop the PingFederate server if it is running. 2. Unzip the Office 365 Connector distribution ZIP file into a holding directory. 3. From the dist directory, copy the file pf-office365-quickconnection-2.1.jar into the directory <pf_install>/ pingfederate/server/default/deploy 4. If the connector will be used for provisioning, edit the run.properties file located in <pf_install>/ pingfederate/bin, changing the property pf.provisioner.mode to STANDALONE for example: pf.provisioner.mode=standalone Note: For information about using the FAILOVER setting for runtime deployment, see the PingFederate Server Clustering Guide. 5. Start the PingFederate server. Upgrade the Office 365 connector 1. Before stopping the PingFederate server to upgrade the Office 365 Connector, access the Attribute Mapping screen for existing channel configurations and note the current configuration. Warning: The upgrade process may remove existing mappings and defaults on the Attribute Mapping screen. These may need to be reconfigured again before activating the channel configuration. 2. Disable the existing SP Connection where the Office 365 Connector is configured. 3. Stop the PingFederate server if it is running. 4. Unzip the Office 365 Connector distribution ZIP file into a holding directory. 5. Remove any versions of prov-aad.x.jar from: <pf_install>/pingfederate/server/default/deploy 6. Also remove the following files from the same directory if they are present: pf-office365-quickconnection-x.x.jar commons-lang jar mockito-all jar prov-cpl jar Tip: Do not delete any versions of the Common Provisioning Layer (prov-cpl-x.x.x.jar) from the deploy folder that are required for other SaaS Connectors. 7. From the dist directory, copy the files: pf-office365-quickconnection-2.1.jar into the directory: <pf_install>/pingfederate/server/default/deploy Important: Make sure to remove existing versions of Office 365 Connector files.

8 PingFederate Office 365 Connector Guide Access the Target configuration screen for existing connections and choose the appropriate option for the REMOVE LICENSES FROM USER WHEN SKUID IS EMPTY field: Disabled (default)ff - When disabled, if you choose to not configure the skuid field in your channel configuration's Attribute Mappings, or if the user's skuid field is cleared in the datastore, the user's licenses will not be removed from them. Enabled - When enabled, if you choose to not configure the skuid field in your channel configuration's Attribute Mappings, or if the user's skuid field is cleared in the datastore, the user's licenses will be removed from them. 9. Access the Attribute Mapping for existing channel configurations and click Refresh Fields.

9 PingFederate Office 365 Connector Guide Ensure all new required fields (if any), are mapped appropriately or have a default value. 11. (Optional) If you did not previously support updating the mobile attribute, make sure you make this field Createonly by editing its settings before saving. Updating the mobile attribute requires additional privleges set using Powershell. See this KB article for more information. 12. Once completed with the attribute configuration, click Done, Done, and Save. 13. Re-Activate the SP Connection to resume Outbound Provisioning. Configure SAML SSO Download Office 365 SAML Metadata (SAML SSO) on page 9 Install Powershell account connection software (SAML SSO) on page 10 Add federated domain (SAML SSO) on page 10 DNS updates (SAML SSO) on page 10 Verify federated domain (SAML SSO) on page 11 Configure federation settings (SAML SSO) on page 11 Configure connection (SAML SSO) on page 11 Credentials certificate management (SAML SSO) on page 13 Add the signing certificate to Azure (SAML SSO) on page 13 Browser SSO (SAML SSO) on page 13 Download Office 365 SAML Metadata (SAML SSO) The Office 365 quick-connection template uses SAML 2.0 metadata from Office 365 to configure SSO endpoints and other information. Download the Office 365 metadata XML file before creating the Office 365 connection in PingFederate.

10 PingFederate Office 365 Connector Guide Access the following URL to download the SAML 2.0 Metadata for Office 365 here. ( nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml) 2. Save the XML file to a desired location. Install Powershell account connection software (SAML SSO) Some SSO configuration settings can only be updated through the execution of Powershell commands. Connection to Azure from Windows is done through installation of Microsoft software, allowing the Powershell commands executed on the server to modify the SSO configuration in Azure. Follow the links below for instructions on how to install the required software. 1. Install Online Services Sign-In Asistant using instructions here. ( details.aspx?id=39267&fwlinkid=286152) 2. Install Windows Azure AD Module using instructions here. ( Add federated domain (SAML SSO) 1. On the Windows machine with the account connection software, run the Windows Azure Active Directory Module for Windows Powershell application Tip: Any instructions beginning with PS> indicate that the command to the right of the mentioned text is to be executed at the Powershell command line in the Windows Azure Active Directory Module for Windows Powershell command prompt. 2. PS> Connect-MsolService 3. Enter the username and password for the Azure account with administrative privileges. Tip: Text surrounded by < and > is intended to be replaced with a substitution indicated by the text between the symbols. For example: If the name of your federated domain is myfederateddomain.com, then <federated_domain_name> should be replaced by myfederateddomain.com before execution of the command. 4. Add the federated domain: PS> New-MsolDomain -name <federated_domain_name> -Authentication Federated 5. Get the domain label prefix value to aid in domain verification: PS> Get-MsolDomainVerificationDns -DomainName <federated_domain_name> Note the prefix of the value in the Label field and save for later use. (The prefix will be in the format ms######## - see example below) Tip: To preserve some of the setup completed in the previous steps, leave the Windows Azure Active Directory Module for Windows Powershell command prompt window open until configuration of the Office 365 Connector has been completed. DNS updates (SAML SSO) 1. Add a DNS redirect from a sub-domain of the federated domain to point to the PingFederate server so that <subdomain>.<federated_domain_name> points to <PingFederate_domain_name_or_IP> where <sub-domain> is a unique identifier for the PingFederate server.

11 PingFederate Office 365 Connector Guide For example: redirect pf.myfederateddomain.com to pfnode.mycompany.com where pfnode.mycompany.com resolves to the PingFederate server. 2. To assist in verification of the domain, add a TXT record to the DNS settings of the federated domain. Insert the domain label prefix recorded recorded in the Add federated domain (SAML SSO) on page 10 step where indicated below. type: TXT, alias/host destination/points to address: MS=<domain_label_prefix>, ttl: 1hour Verify federated domain (SAML SSO) Confirm ownership of the federated domain. For more information on the verification command, see the online documentation here. ( msdn.microsoft.com/en-us/library/azure/dn aspx ) Execute the Powershell commands below in the command prompt window used in Add federated domain (SAML SSO) on page 10. PS> $domainname = <federated_domain_name> PS> $hostname = <sub-domain>.$domainname PS> $port = 9031 PS> $pingfederate = PS> $brandname = <federated_domain_alias> PS> $issuer = <PingFederate_SAML_2_entity_id> PS> $spid = urn:federation:microsoftonline PS> $activelogon = $pingfederate/idp/sts.wst PS> $logoff = $pingfederate/idp/startslo.ping PS> $metadata = $pingfederate/pf/sts_mex.ping?partnerspid=$spid PS> $passivelogonpf= $pingfederate/idp/startsso.ping?partnerspid=$spid PS> Confirm-MsolDomain -DomainName $domainname -FederationBrandName $brandname -IssuerUri $issuer -LogOffUri $logoff -PassiveLogOnUri $passivelogonpf Configure federation settings (SAML SSO) Set the federation type to SAML. PS> Set-MsolDomainAuthentication -DomainName $domainname -Authentication Federated -PreferredAuthenticationProtocol Samlp Configure connection (SAML SSO) 1. On the Connection Template page, select the Use a template for this connection option and choose Office 365 from the Connection Template drop-down list. Tip: If this selection is not available, verify the Connector installation and restart PingFederate. 2. Click Choose File to locate and select the Office 365 SAML metadata XML you downloaded in Download Office 365 SAML Metadata (SAML SSO), and click Next.

12 PingFederate Office 365 Connector Guide On the Connection Type screen, ensure that Browser SSO Profiles is selected Note: If Outbound Provisioning will also be used, select Outbound Provisioning profile as well. The screenshot below shows an example where both are selected. 4. Click Next. 5. On the Connection Options screen, ensure Browser SSO is selected and click Next.

13 PingFederate Office 365 Connector Guide Credentials certificate management (SAML SSO) 1. On the Credentials screen, click Configure Credentials. 2. On the Digital Signature Settings screen, select a 2048 bit signing certificate, and RSA SHA1 as the signing algorithm. If none of the existing certificates meet the requirements, follow the instructions to create a new certificate or import an existing one here. 3. Export the selected certificate by following the instructions here. 4. Click Next. 5. On the Signature Verification Settings screen, click Manage Signature Verification Settings. 6. On the Trust Model screen, select the appropriate value and complete the steps for configuring the trust model and signature verification according to instructions here. 7. On the Signature Verification Summary screen, click Done. 8. On the Credentials screen, click Next. Add the signing certificate to Azure (SAML SSO) The active signing certificate in PingFederate must be saved in Azure to secure the SSO communications between PingFederate and Office 365. SSO transactions cannot take place without the correct certificate added to Azure. Use the following procedure to add the signing certificate previously exported in Credentials certificate management (SAML SSO) on page 13 to Azure. 1. Open the exported certificate using a text editor. 2. Copy the certificate text to the clipboard without header, footer, whitespace or carriage returns. 3. Execute the Powershell commands below in the command prompt window used in Configure federation settings (SAML SSO) on page 11. PS> $cert = <SAVED_CERTIFICATE_TEXT> PS> Set-MsolDomainFederationSettings -DomainName $domainname - SigningCertificate $cert Browser SSO (SAML SSO) 1. On the General Info screen, ensure that the Partner s Entity ID (Connection ID) and the Connection Name are accurate. Change details if required and click Next. Note: By default, some fields are pre-populated as a result of using the Office 365 Connector template.

14 PingFederate Office 365 Connector Guide On the Browser SSO screen, click Configure Browser SSO. 3. On the Assertion Creation screen, click Configure Assertion Creation.

15 PingFederate Office 365 Connector Guide On the IdP Adapter Mapping screen, click Map New Adapter Instance. If an HTML form adapter form already exists, select it from the drop down list and click Next. Otherwise, perform the following steps to create a new HTML form adapter: a) If an LDAP instance has not been configured in PingFederate, follow the instructions for Configuring an LDAP Connection here. b) If a credential validator has not already been created, follow the instructions here. c) Complete the creation of the HTML form adapter using the instructions here. d) Once the above are completed, return to the IdP Adapter Mapping screen and click Next. 5. On the Assertion Mapping screen, select Retrieve additional attributes from a data store--includes options to use alternate data stores and/or a failsafe mapping. Click Next. 6. Click Add Attribute Source. 7. Fill in the Attribute Source Description field with an identifier of your choosing. Select the desired source datastore in the Active Datastore drop down list, then click Next. 8. On the LDAP Directory Search page, enter the following values: Base DN: where the users are found in the source datastore Search Scope: select the appropriate value Attributes to return from search:

16 PingFederate Office 365 Connector Guide objectguid userprincipalname 9. Click Next. 10. If you are in the LDAP Binary Attribute Encoding Types screen, confirm objectguid is set to base64, click Next, and proceed to the next step. If you are NOT in the LDAP Binary Attribute Encoding Types screen, then objectguid is not currently retrieved in binary format and the datastore settings must be udpated. To update objectguid in LDAP perform the following steps: a) Open a new private browser session and log in to the PingFederate Admin Console b) Click Data Stores, then Manage Datastores c) Select your source datastore d) Click LDAP Configuration e) Click Advanced f) Select the LDAP Binary Attributes tab g) Enter objectguid in the BINARY ATTRIBUTE NAME field and click Add h) Click Done, Done, and Save i) Return to the LDAP Binary Attribute Encoding Types screen j) Confirm objectguid is set to base64 and click Next

17 PingFederate Office 365 Connector Guide On the LDAP Filter screen, enter samaccountname=${username} in the Filter field. 12. Click Next. 13. On the Attribute Contract Fulfillment page, set the following values: Attribute Contract Source Value IDP LDAP userprincipalname SAML_SUBJECT LDAP objectguid SAML_NAME_FORMAT text urn:oasis:names:tc:saml:2.0:nameidformat:persistent 14. Click Next. 15. On the Attribute Source Summary screen, click Done. 16. On the Attribute Sources & User Lookup screen, click Next. 17. On the Failsafe Attribute Source screen, select Abort the SSO transaction and click Next.

18 PingFederate Office 365 Connector Guide On the IdP Adapter Mapping summary screen, click Done. 19. On the Adapter Mapping Instance screen, click Done. 20. On the IdP Assertion Creation screen, click Done. 21. On the Browser SSO screen, click Next. Configure provisioning Add application to Azure AD (provisioning only) Add an application to Azure Active Directory to create and expose Azure Graph API endpoints for provisioning. For information on adding an application in Azure, see Azure s online documentation here. ( msdn.microsoft.com/en-us/library/azure/dn aspx#bkmk_adding) Get Azure application ClientId and secret (provisioning only) To get the application key, follow the instructions here. ( Tip: Azure uses key as the term for what is also referred to as the secret or client secret. The terms may be used interchangeably. Record the client id and key in a safe place for later use. Important: The client key will no longer be retrievable once you navigate away from the screen. Configure outbound provisioning (provisioning only) Use the following procedure to configure Outbound Provisioning for Office If provisioning is used and SSO is not, Outbound Provisioning Connection Template must be selected in the Connection Type screen, and Office 365 Connector selected as the Type in the drop down list. Click Next. 2. On the Outbound Provisioning screen, click Configure Provisioning. 3. On the Target screen, fill in the following fields: Field Name ClientId ClientSecret TenantDomain Value The client id for the application created in Azure. The key generated during application creation. The tenant domain configured in Azure, which is retrieved by going to the application properties and selecting view endpoints, and copying the ID from the URL under "Windows Azure AD Graph API Endpoint".

19 PingFederate Office 365 Connector Guide Field Name DoBase64Conversion DefaultUserPassword RemoveLicensesWhenSkuIdEmpty Value True (default) is recommended. Set to false if the ImmutableId is not base64. The default password. Only used if the password attribute is not mapped, or value of the mapped field is empty. False (default) - When disabled, if you choose to not configure the skuid field in your configuration's Attribute Mappings, or if the user's skuid field is cleared in the datastore, the user's licenses will not be removed from them. True - When enabled, if you choose to not configure the skuid field in your configuration's Attribute Mappings, or if the user's skuid field is cleared in the datastore, the user's licenses will be removed from them. Important: For user provisioning to succeed, the users userprincipalname domain must match a verified domain in Azure. 4. Enter the values on the Target screen, then click Next. 5. On the Manage Channels screen, click Create. 6. On the Channel Info screen, enter a channel name in the Channel Name field, then click Next. 7. On the Source screen, select the appropriate data store from the drop down list, then click Next. 8. On the Source Settings screen, accept the default values, then click Next. 9. On the Source Location screen, enter values for: Base DN User: Group DN or Filter Group: Group DN or Filter

20 PingFederate Office 365 Connector Guide Tip: For more information, see Configuring Outbound Provisioning Settings in the PingFederate Administrator s Manual. 10. Click Next. 11. On the Attribute Mapping screen, map the attributes as appropriate. Recommendations for specific fields are shown in the next section. Tip: If you are not ready to complete the provisioning configuration, you can click Save and return to the configuration screen later (from the Manage Connections screen select Manage All SP on the Main Menu). 12. When done mapping attributes in the Attribute Mapping screen, click Next. 13. On the Channel Activation & Summary screen, select Active for the Channel Status and click Done. 14. On the Manage Channels screen, click Done. 15. On the Outbound Provisioning screen, click Next. 16. Optional: On the Activation & Summary screen, select Active for the Connection Status. 17. On the Activation & Summary screen, click Save. Synchronize existing Office 365 users (provisioning only) Ensure that the value mapped to the userprinciplename attribute, (when configuring the connector) matches the existing Office 365 Users userprinciplename exactly as it appears in Office 365. For example, on the Attribute Mapping screen, the User userprinciplename attribute on Office 365 is mapped to the User userprinciplename attribute in your LDAP. This will synchronize a User that already exists on Office 365 with a userprinciplename in Office 365 of john.smith@mydomain.com. In this case, the Users ss in LDAP would also have to be john.smith@mydomain.com. When the Office 365 connector provisions for the first time, this address will be used to synchronize the User in your LDAP data store with the User in Office 365. Provision groups to Office 365 (provisioning only) The Connector enables an organization to provision and manage groups to Office 365.

21 PingFederate Office 365 Connector Guide Important: The connector is not able to manage groups or add users to groups that it has not created. Creating Groups To create a group, target a group in LDAP to be provisioned. The Office 365 Connector will create the group in Office 365 with the name of the group from LDAP. To provision existing Group accounts on Office 365 Important: The connector is not able to synchronize with existing groups in Office 365. If your Office 365 has groups that you want the connector to manage, you will need to do the following: 1. Use the connector to provision new duplicate groups. 2. Use the connector to provision users to the new groups (see mapping users to groups). Updating Groups Renaming the group in LDAP will update the group name in Office 365 on the next provisioning cycle. Deleting Groups The Office 365 Connector supports the ability to delete groups from Office 365. Deleting a group in LDAP will harddelete the group in Office 365 on the next provisioning cycle. Map users to groups (provisioning only) The Office 365 Connector supports the ability to manage user s group memberships. A user can be a member of one or more groups. Important: The connector is not able to manage groups or add users to groups that it has not created. There are two ways to add a user to a group in LDAP: Invoke the user Properties from Active Directory Users and Computers and enter the group name in the Member Of tab. Invoke the group Properties from Active Directory Users and Computers and enter the user name in the Members tab. The user(s) will be added to the group(s) on the next provisioning cycle. Configure for license management (provisioning only) The Office 365 Connector supports the ability to manage the Office 365 licenses assigned to a user. 1. The usagelocation field must be set to a static value, or mapped to an attribute containing the ISO character country code for the location of the user. 2. The skuid field must either be set to a single static value or an attribute containing one or more license keys to be assigned to the user. Note: Each license specified in the skuid field can be either the actual id of that license or the specified name of the license. 3. (Optional) The disabledplans field may either be set to a single static value, an attribute containing one or more product keys to be disabled for the user. Note: If no disabledplans are specified, the user will have access to all products available through their assigned licenses specified in their skuid field. Note: Each product specified in the disabledplans field can be either the actual id of that product or the name of the product. 4. Ensure the appropriate option for the REMOVE LICENSES FROM USERS WHEN SKUID IS EMPTY connection field is configured on the SP Connection configured for the Office 365 Connector:

22 PingFederate Office 365 Connector Guide Disabled (default) - When disabled, if you choose to not configure the skuid field in your configuration's Attribute Mappings, or if the user's skuid field is cleared in the datastore, the user's licenses will not be removed from them. Enabled - When enabled, if you choose to not configure the skuid field in your configuration's Attribute Mappings, or if the user's skuid field is cleared in the datastore, the user's licenses will be removed from them. Configure for manager assignment (provisioning only) The Office 365 Connector supports the ability to assign a manager to a user. 1. The pingsourcedn field must be mapped to an attribute containing a unique identifier for the user. Note: By default this is mapped to the distinguishedname field. We recommend leaving this field mapped to the default mapping. 2. The manager field must either be set to a static value, or mapped to an attribute containing the value of the assigned manager's pingsourcedn field. Note: By default this is mapped to the manager field. We recommend leaving this field mapped to the default mapping. An example of how assigning a manager to a user works Note: The following assumes the default mappings for the pingsourcedn and manager fields. 1. The manager's user is provisioned to Azure. 2. The employee's user is provisioned to Azure. 3. The employee's manager, under their Organization tab in AD, is set to the manager's AD user in AD. 4. The Office 365 Connector will assign the manager's Azure user as the employee's Azure user's manager in Azure. Tip: To update or clear the employee's manager in Azure, change or clear the employee's manager, under their Organization tab in AD. PingFederate initial configuration If you have not yet used PingFederate, follow the instructions under Running PingFederate for the First Time in the Getting Started guide. To enable quick connections to Office 365, the following procedure is required on the Choosing Roles and Protocols page under PingFederate Server Settings. If you have already run and configured the PingFederate server, you may need to verify or change settings on the Choosing Roles and Protocols page, including enabling Outbound Provisioning, as described in the following procedure. Enable quick connections to Office On the Roles and Protocols page, ensure the IdP role is enabled and the following options selected in that role according to the desired functionality: SSO: Select SAML 2.0 and WS-Federation Provisioning: Select Outbound Provisioning Tip: Select Server Settings on the Main PingFederate Menu to locate this screen after initial installation. Tip: This setting enables provisioning globally for all connections to supported providers. However, you have a choice of including provisioning or not during the configuration of specific connections.

23 PingFederate Office 365 Connector Guide The screenshot below shows an example of the selections required to enable both provisioning and SAML SSO. 2. Click Next. 3. The Federation Info screen will display fields for SAML 2.0 Entity ID and WS-Federation Realm. For more information, see Specifying Federation Information in the PingFederate Administrator s Manual. 4. Click Next to continue the Configure My Server task (or Save for an existing configuration).

24 PingFederate Office 365 Connector Guide Add SP connection Note: Enabling Outbound Provisioning adds a new screen to the task flow, requiring selection of a database used to monitor provisioning status. For more information, see Configuring Outbound Provisioning Settings in the PingFederate Administrator s Manual Use the following procedure to configure an SP connection for SSO and/or provisioning to Office 365. Tip: This procedure provides instructions for configuring minimum required connection settings. The instructions do not go into detail where all necessary information is automatically configured (or in which standard defaults are used). The administrative console guides you to enter required configuration steps automatically by displaying prompts at entry points for the task flows. In general, you may add or change settings on all screens to suit your special 1. If you have not already done so, use PingFederate to configure the IdP adapter you want to use. For information and instructions, see Configuring IdP Adapters in the PingFederate Administrator s Manual. 2. On the Main Menu, select Create New under SP Connections in the IdP Configuration section. Troubleshooting The following table lists potential problems administrators might encounter during the setup or deployment of the Office 365 Connector, along with possible solutions: Problem Possible Solution The Exception In some cases the App created to provision using the "{"code":"authorization_requestdenied","message": Azure Graph API may not have the necessary permissions {"lang":"en","value":"insufficient to access and modify all attributes. If you are seeing some privileges to complete provisioning events failing due to "Insufficient privileges the operation."}" appears to complete the operation." elevating the permission level in server.log of the App may fix this. More information on this issue, as well as the script needed to elevate the permissions using Azure AD Module for Windows PowerShell can be found here. Attribute index The following table consists of the attributes that can be mapped on a User during provisioning. userprincipalname displayname mailnickname city The user principal name (UPN) of the user. The UPN is an Internet-style login name for the user based on the Internet standard RFC 822. Note: This must match the domain configured in the Azure Environment. The name displayed in the address book for the user. This property is required when a user is created and it cannot be cleared during updates. The mail alias for the user. This property must be specified when a user is created. The city in which the user is located.

25 PingFederate Office 365 Connector Guide country department facsimiletelephonenumber givenname jobtitle mobile physicaldeliveryofficename postalcode perferredlanguage state streetaddress surname telephonenumber usagelocation usertype password The country/region in which the user is located; for example, "US" or "UK". The name for the department in which the user works. The telephone number of the user's business fax machine. The given name (first name) of the user. The user's job title. The primary cellular telephone number for the user. Note: To update a user s mobile number, the Office 365 Connector requires elevated permissions. To elevate these permissions please see this KB. If you do not wish to elevate these permissions, please make the mobile attribute Create-Only when configuring the connection s Attribute Mappings. The office location in the user's place of business. The postal code for the user's postal address. The postal code is specific to the user's country/region. In the United States of America, this attribute contains the ZIP code. The preferred language for the user. Should follow ISO Code; for example "en-us". The state or province in the user's address. The street address of the user's place of business. The user's surname (family name or last name). The primary telephone number of the user's place of business. Required for the licensing feature. Needs to be mapped to an attribute that contains the ISO-3166 formatted country (a two letter country code) of license usage. Required for users that will be assigned licenses due to legal requirement to check for availability of services in countries. Examples include: "US", "JP", and "GB". A string value that can be used to classify user types in your directory, such as "Member" and "Guest". Map password to a field so the content will become the user s initial password instead of the less secure default. The field can also be set to a static default value. This field is required when a user is created. It can not be updated, but the user can be forced to update

26 PingFederate Office 365 Connector Guide their password on their next login by setting their resetpassword field to true. The password must satisfy minimum requirements as specified by the user's PasswordPoliciesproperty. By default, a strong password is required. resetpassword manager pingsourcedn skuid disabledplans immutableid othermails Determines if a user needs to do a password reset the next time they login. Default value is true, but can be mapped to an attribute. Required for the manager feature. Sets the user DN of the associated manager. Required for the manager feature. A custom field that we set on a User in Azure, which holds the User s DN from AD and is used to lookup Users in Azure in order to set the manager field on a User in Azure. Sets the user DN. Users and managers must be created or updated with the pingsourcedn information for the manager association to succeed. Required for the licensing feature. Can be mapped in PingFederate to a single or multi-valued attribute in LDAP. Used for the IDs or names of the license(s) assigned to users. The usagelocation field must also be set for a license to be successfully assigned. Part of the licensing feature. Can be mapped in PingFederate to a single or multi-valued attribute in LDAP. Used for the IDs or names of disabled plans for individual users licenses. This property is used to associate an on-premises Active Directory user account to their Azure AD user object. This property must be specified when creating a new user account in the Graph if you are using a federated domain for the user's userprincipalname (UPN) property. This field can not be updated by the Office 365 Connector. A list of additional addresses for the user.

27 Release notes 27 Release notes Product: PingFederate Office 365 Connector The PingFederate Office 365 Connector enables enterprises to provision users to Office 365. The Office 365 Connector includes a quick connection template to easily set up a Single Sign-On (SSO) connection requiring Office 365 provisioning. The connector makes use of the Azure Active Directory Graph API v1.6 to communicate with Azure Active Directory, which acts as the user and group repository for Office 365. For information on features and setup, please refer to the product documentation. If you have problems with deployment, installation, or configuration, please visit the Ping Identity Support Center (ping.force.com/support). Change list by version on page 27 Qualification statement on page 28 ZIP manifest on page 29 Change list by version Office 365 Connector March 2017 (Current Release) Added configuration options for CRUD capabilities Added support for proxy connections Office 365 Connector January 2017 Fixed deserialization issue due to a SaaS API change Office 365 Connector July 2016 Fixed Group membership issue Office 365 Connector 2.0 January 2016 Added support for provisioning additional user attributes Added support for deleting groups Added additional license configuration support Azure Active Directory Graph API updated from version v1.5 to v1.6 Improved exception handling and reporting Minor bug fixes Updates to user group mappings resulting in the removal of the memberof attribute Office 365 Connector December 2015 Fixed exception handling issue Office 365 Connector June 2015 Fixed compatibility issues Office 365 Connector 1.1 February 2015 Support added for provisioning users with licenses Capability to assign managers to provisioned users Capability to update userprincipalname Support for rename group Attribute changes require administrators to refresh the target and attribute mapping screens Support for non-base64 immutableid

28 Release notes 28 Resource and memberof attributes removed Office 365 Connector 1.0 May 2014 Initial Release Support for SSO and SLO Support for User Provisioning Support for Group Provisioning Qualification statement This section documents testing performed with the PingFederate Office 365 Connector 2.1 with PingFederate versions listed below as of March Version Tested pf-office365-connector-2.1.zip Operating Systems Tested Windows Server 2012 R2 64-bit Java Development Kit Versions Tested JDK Update bit JDK Update bit Browsers Tested Firefox Internet Explorer Chrome PingFederate Versions Tested PingFederate PingFederate 7.3 PingFederate Office 365 Configurations Tested User Store LDAP (Active Directory) Windows Server 2012 R2 Data Store (Internal Provisioning Database) Hypersonic MySQL 5.6 Oracle 11g PingFederate Common Provisioning Layer Version prov-cpl Prerequisites/Assumptions The Java SE Development Kit (JDK) should comprise the correct Java version for your PingFederate installation Known Issues/Problems/Limitations Due to a limitation with PingFederate 8.1 and earlier versions, when configuring two SP connections with the same provisioner, the second connection built may be pre-populated with the channel from the first connection. To avoid conflicts, delete this pre-populated channel and create a unique channel for each connection. User delete is not supported. (Disable only) Users cannot be created in a disabled state. They must first be created in an active state and then disabled

29 Release notes 29 Cookies must be enabled in the selected browser for SLO to work Updating the mobile attribute requires that the service principal representing the provisioner (the place the user gets the client key & secret) be assigned a role with Company Administrator privileges (using Powershell). See this KB article for more information Updating ImmutableID and Password attributes is not supported User updates containing a manager that has not yet been provisioned / updated by the new version will fail, as the manager will not have the new extended attribute holding their distinguished name from AD If the DoBase64Conversion field is switched to false, expect conflicts / failures on federated domains containing pre-existing users provisioned by dirsync / V1.0 Only outbound provisioning is supported Syncing with existing Groups is not supported SAML SLO is not supported. (WS-Fed SLO is supported and set as default) ZIP manifest The distribution ZIP file for the Connector contains the following: ReadMeFirst.pdf contains links to this online documentation. /legal: Legal.pdf copyright and license information. /dist contains libraries needed for the Connector: pf-office365-quickconnection-2.1.jar PingFederate Office 365 Connector