Configure Office 365 for single sign-on

The following steps are specific to this application and are required in order to enable SSO. For information on optional configuration settings available in the Identity Administration portal, see Configure optional application settings.

Make sure that your existing deployment is configured and ready to use CyberArk for Office 365. For details, see Office 365 deployment checklists.

In order for the Outlook desktop application to work with Office 365, do not rename the Office 365 application. The application must be named Office 365 and there can be only one application deployed with that name.

Before you begin

Microsoft does not support Microsoft Online Services (MSOL) cmdlets in PowerShell after March 30, 2024, as described here. CyberArk Identity uses these cmdlets in the O365/Azure integration to connect with Microsoft for domain federation. CyberArk Identity is beginning to use the Microsoft Graph to connect with Microsoft for domain federation. Before you federate, unfederate, or view federated domains with Microsoft, confirm if the Microsoft Graph module is installed. Use the following command:

Get-InstalledModule Microsoft.Graph

If the module is not installed, install it using this command: 

Install-Module Microsoft.Graph -Scope CurrentUser

If you need additional help, see https://learn.microsoft.com/en-us/powershell/microsoftgraph/installation?view=graph-powershell-1.0.

Configure an Azure application for authentication

Microsoft has deprecated basic authentication access to Exchange Online APIs. To increase security, Microsoft has switched to modern authentication, which is based on OAuth 2.0.

Support for basic authentication ends on October 1, 2023. For new tenants, use token-based authentication.

See Microsoft's statement for more information.

To use Modern Authentication for CyberArk's Office 365 application, you need to register an application in your Microsoft Entra ID account with appropriate access to the Microsoft Graph API. You can then authenticate using the Microsoft Entra ID application's Application ID, Directory ID, and Client Secret.

CyberArk recommends registering a new Azure application that is specific to its intended purpose. For example, if you are adding Microsoft Entra ID Directory as a directory source in CyberArk Identity in addition to integrating Office 365 for SSO and provisioning, you would register two Azure applications - one for each task. In addition, each registered application should have the minimum set of API permissions required to perform its function.

Step 1: Register a Microsoft Entra ID application.

  1. Log in to your Microsoft Entra ID account as an administrator.

    For global service, use https://portal.azure.com

    For US government, use https://portal.azure.us

  2. Go to App registrations, and click New registration.

  3. Enter a name for your app.

  4. Select Accounts in this organizational directory only.

  5. Click Register.

    The overview page for your registered app appears.

Step 2: Add Certificates & secrets to allow access to the resource server.

  1. Go to Certificates & secrets, then click New client secret.

  2. Enter a description and select an expiration date option, then click Add.

  3. Copy the client secret value and paste it into a text editor for later use. You can click the copy icon to the right of the row.

    The client secret value will be unavailable once you logout, so it's critical to capture the value now.

Step 3: Grant the necessary API permissions to your newly registered app.

  1. Go to API permissions, then click Add a permission.

  2. Click Microsoft Graph.

  3. Click Application permissions.

  4. Scroll down the permissions list and select the following permissions, then click Add permissions.

    If you are using CyberArk Identity just for SSO, select all permissions associated with one of the following permission types.

    Permission type Permissions (from least to most privileged)

    Delegated (work or school account)

    		 Directory.Read.All

    Application

    Domain.Read.All

    Domain.ReadWrite.All

    Directory.Read.All

    5. The following permissions are needed if you plan to use the provisioning feature.

    Delegated Application

    Directory.AccessAsUser.All

    Application.ReadWrite.All

    Directory.ReadWrite.All

    Application.ReadWrite.OwnedBy

    Group.ReadWrite.All

    Directory.ReadWrite.All

    GroupMember.ReadWrite.All

    Domain.ReadWrite.All

    Organization.ReadWrite.All

    Group.Create

    User.ManageIdentities.All

    Group.ReadWrite.All
    User.ReadWrite.All

    GroupMember.ReadWrite.All
     

    Organization.ReadWrite.All
     

    User.ManageIdentities.All

     

    User.ReadWrite.All

    Microsoft Entra ID updates the permissions for your app; however, you still need to provide admin consent.

    Refer to Microsoft's documentation for more information on the difference between Delegated and Application permissions, as well as reference material for each permission.

  5. Click Grant admin consent for <your company>.

  6. Click Yes on the confirmation prompt.

    Since you are already logged in as an administrator, a notification Successfully granted admin consent for the requested permissions. appears at the top of the page.

  7. Return to the overview page for the registered application; you will need the information there for the following steps.

Configure the Office 365 application in the Identity Administration portal

After you register an application with appropriate API permissions in Azure, you can add and configure the Office 365 application in the Identity Administration portal to finish configuring Office 365 for single sign-on.

Step 1: Add the Office 365 application in the Identity Administration portal

  1. In the Identity Administration portal, click Apps, then click Add Web Apps.

    If you have multiple Office 365 accounts or domains, you can add an application for each account or domain.

    The Add Web Apps screen appears.

  2. On the Search tab, enter the partial or full application name in the Search field and click the search icon.

    The description of how to choose and download a signing certificate in this document might differ slightly from your experience. See Choose a certificate file for the latest information.

  3. Next to the application, click Add.

  4. In the Add Web App screen, click Yes to confirm.

    Identity Administration portal adds the application.

  5. Click Close to exit the Application Catalog.

    The application that you just added opens to the Application Settings page.

Step 2: Verify your Office 365 administrator credentials.

The domain that the administrator uses for basic authentication in the Application Settings does not appear in the Office 365 domains list. For basic authentication, use a domain that is different from the one being enabled for SSO with Office 365.

Click here if you are using basic authentication

    Support for basic authentication ends on October 1, 2023. For new tenants, use token-based authentication.

  1. Select Basic Authentication, then enter the user name and password for your Office 365 administrator account of the default domain <MyCompany>.onmicrosoft.com and click Verify.

  2. CyberArk Identity verifies the credentials and connects to your account.

    Once the verification succeeds, the Application Settings page displays the Office 365 domains section.

Click here if you are using token-based authentication.

  1. Select Token Based Authentication, then copy the following values from the overview page of your registered app in the Azure portal and paste them into the Microsoft Entra Domain Services window in the Identity Administration portal.

    • Application (client) ID
    • Directory (tenant) ID

  2. Enter the client secret that you saved previously.

  3. Click Verify.

  4. (Optional) Select Allow authentication by certificate to enable zero sign-on ("ZSO") for Office 365 on Android and iOS devices.

    The Microsoft Authenticator application is also required for ZSO on Office 365 on iOS devices.

Step 3: Federate your Office 365 domain.

If you federated with a subdomain (for example, sub.domain) and configured O365 federation with CyberArk Identity prior to version 23.10, then you need to unfederate and federate to AD with sub.domain.com. In previous versions, only the root domain was processed for authentication.

See Before you begin to download the Microsoft Graph module.

  1. Select the domain that you want to federate or take ownership of with CyberArk for Office 365, then click Actions.

    If the domain is in Managed state, you federate it. If the domain is already federated, you take ownership of it and federate it with CyberArk for Office 365. If you change the security certificate used with CyberArk for Office 365, you will need to refederate the domain. Refer to Choose a certificate file for more information about changing the certificate file.

    Taking ownership of a domain is useful in cases where you’ve already federated your account using another system or another instance of the Office 365 + Provisioning application.

    If you have multiple Office 365 domains, you create a separate application in the Identity Administration portal for each domain.

    In the pop-up menu that displays:

    • If you selected a managed domain, click Federate Domain.

    • If you selected a federated domain, click Take Ownership.

    • If you changed the security certificate on the Application Settings page, click Refederate Domain.

      The domain must be owned by the Office 365 application to refederate the domain.

      A message displays that prompts you for confirmation.

  2. Click Yes to continue.

    • If you selected to federate a managed domain, CyberArk Identity changes the selected domain in Office 365 to federated status.
    • If you selected to take ownership of a federated domain, CyberArk Identity changes the selected domain in Office 365 to use your current CyberArk Identity tenant as the identity provider.

    Future logins will be handled by CyberArk Identity.

    If your Office 365 domain was previously federated by using Microsoft DirSync or DirSync and ADFS, then you should go stop those services from running. CyberArk Identity takes ownership of the federated domain, but it doesn’t stop your previous tools, such as DirSync, from running. You must disable DirSync manually, and you may notice synchronization issues if you do not disable DirSync after switching to CyberArk for Office 365 for SSO.

See Before you begin to download the Microsoft Graph module.

A PowerShell script (O365FederationScript.ps1) is available to view, federate, or unfederate your domain if you are using token-based authentication.

Refer to https://docs.microsoft.com/en-us/microsoft-365/enterprise/connect-to-microsoft-365-powershell?view=o365-worldwide to make sure that your PowerShell environment is properly configured to connect to Office 365.

  1. On the Application Settings page, select the domain that you want to federate, then click Actions > Download Powershell Script.

  2. Run the downloaded PowerShell script O365FederationScript.ps1, entering R at the security warning to confirm that you want to run the script.

  3. Enter your Microsoft Entra ID administrator credentials.

    The script presents options to view, federate, or unfederate the domain.

  4. Enter F to federate the domain you selected in the Identity Administration portal.

  5. Run the script again, this time entering V to view the federation settings, confirming success.

Configure the ADFS server

Go to the ADFS server and perform the following steps from PowerShell.

The following steps are applicable for the ADFS version 2012. For other versions, the steps may vary.

Set-MsolADFSContext -Computer <adfs server>

Set-MsolDomainAuthentication -Authentication Managed -DomainName <domain name>

Get-MsolDomain | fl name,status,auth*

Expected values

Variable

Description

adfs server

The computer name of your adfs server.

domain name

Your managed domain name. For example, example.com.

Run the PowerShell script you downloaded in Step 1 to change from managed to federated level.

Step 4: Configure settings that identify the Office 365 application.

  1. On the Application Settings page, expand the Additional Options section and specify the following settings.

    Once you provision users to this application, changing the application ID in any way will prevent users from launching the application. If you change the application ID, you will have to save the application, then unfederate and take ownership of your domain to restore access.

    Setting

    Description

    Application ID

    Configure the Application ID field if you are deploying a mobile application that uses the CyberArk mobile SDK. CyberArk Identity uses the Application ID to provide single sign-on to mobile applications. Note the following: The Application ID has to be the same as the text string that is specified as the target in the code of the mobile application written using the mobile SDK. If you change the name of the web application that corresponds to the mobile application, you need to enter the original application name in the Application ID field. There can only be one SAML application deployed with the name used by the mobile application. The Application ID is case-sensitive and can be any combination of letters, numbers, spaces, and special characters up to 256 characters.

    Show in User app list

    Select Show in User app list so that this web application displays in the user portal. (By default, this option is selected.)

    If this web application is only needed in order to provide SAML for a corresponding mobile application, deselect this option. This web application won’t display for users in the user portal.

  2. (Optional) On the Description page, you can change the name, description, category, and logo for the application.

    For some applications, the name cannot be modified.

    The Category field specifies the default grouping for the application in the user portal. Users have the option to create a tag that overrides the default grouping in the user portal.

Step 5: Deploy the application by setting permissions on the application or by adding the application to a set.

  1. On the Permissions page, click Add.

  2. Select the user(s), group(s), or role(s) that you want to grant permissions to, then click Add.

    The added object displays on the Permissions page with View, Run, and Automatically Deploy permissions selected by default.

  3. Select the permissions you want and click Save.

    Default permissions automatically deploy the application to the User Portal if the Show in user app list option is selected on the Settings page. Do not select this option if you intend to use only SP-initiated SSO.

    Change the permissions if you want to add additional control or if you prefer not to automatically deploy the application.

Step 6: (Optional) Apply an authentication profile to the application.

Refer to Secure apps with MFA for details.

Step 7: Configure account mapping.

 Configuring the account mapping (for initial testing)

If you are continuing to use the Microsoft Directory Synchronization tool, make sure that you configure the account mapping details. If you’re going to use automatic user provisioning, it’s a good idea to configure the account mapping information for initial testing and verification before you add provisioning.

Available options vary depending on your application type.

Option

Description

Directory Service Field

 

Use this option if the user accounts are based on user attributes. For example, specify an Active Directory field such as mail or userPrincipalName or a similar field from the CyberArk Cloud Directory.

Also see Configure authentication security options for information on the option to use the password supplied by Active Directory users.

 

All users share one name

Use this option if you want to share access to an account (for example, some people share an application developer account).

Check Allow users to view credentials to allow users to view User Identity (User Name and Password) for an application in the User Portal > Application Settings (select the gear icon in the application tile). Users must have the View permission enabled. This can help users who may need offline access to the application.

The ability to view the User Identity information in the application only applies to application passwords stored in CyberArk Identity. It does not apply to applications where passwords are stored in the PAM - Self-Hosted Vault.

If this option is not checked (default), User Identity information for an application is not shared in the User Portal > Application Settings.

Contact CyberArk Support to disable the Allow users to view credentials option.

Use the Authentication Key to enable TOTP for admin-added applications. For instructions, see Enable time-based one-time passwords (TOTP) for two-factor authentication.

Prompt for user name

Use this option if you want users to supply their own user name and password. This option only applies to some application types such as user password, custom NTLM, and browser extension applications. The first time that users launch the application, they enter their login credentials for that application. The CyberArk Cloud Directory stores the user name and password so that the next time the user launches the application, the CyberArk Cloud Directory logs in the user automatically.

 

Account Mapping Script

You can customize the user account mapping here by supplying a custom JavaScript. For example, you could use the following line as a script:

LoginUser.Username = LoginUser.Get('mail')+'.ad';

The script sets the login user name to the user’s mail attribute value in Active Directory and adds ‘.ad’ at the end. For example, if the user’s mail attribute value is Adele.Darwin@acme.com then the account mapping script sets LoginUser.Username to Adele.Darwin@acme.com.ad. For more information about writing a script to map user accounts, see the SAML application scripting.

Also see Configure authentication security options for information on the option to use the password supplied by Active Directory users.

 

Step 8: Save changes and review the new user sign-in experience.

Click Save.

After federating a domain and taking ownership of it, the sign in experience changes for your users. Instead of entering user credentials on the Office 365 sign-in page, users will see their identity listed as a possible account to sign in to. For example:

After users click their identity, they are redirected to the Identity User Portal if they are not currently signed in to the Identity User Portal. If they are signed in to the Identity User Portal, they are automatically signed in to Office 365.

For example, users see the following message after clicking their identity on the Office 365 sign-in page.

Refer to SAML and WS-Federation SSO options for additional information about how single sign-on works.