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 Admin Portal, see Optional configuration settings.

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

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.

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. Users with existing Microsoft Online tenants can continue using basic authentication until Microsoft ends support in the second half of 2021; however, new tenants are required to use token-based authentication.

Refer to Microsoft's statement for more information.

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

We recommend registering a new Azure application that is specific to its intended purpose. For example, if you are adding Azure Active 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 an Azure application.

  1. Log in to your Azure account as an administrator.

    https://portal.azure.com

  2. Go to App registrations, then 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.

    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, you only need one of the following permissions.

    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

    Azure 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.

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

  7. 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.

  8. 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 Admin Portal

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

Step 1: Add the Office 365 application in the Admin Portal

  1. In Admin 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.

    Admin 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.

Step 3: Federate your Office 365 domain.

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

    If you’re also deploying a native mobile version of this application into a Samsung KNOX container, enter the Application ID.

    The CyberArk Identity uses the Application ID to provide single sign-on to the native Samsung KNOX mobile application. The Application ID must match the SAML Target referenced inside the Samsung KNOX container.

    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.

    The Select User, Group, or Role window appears.

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

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

  3. Select the desired permissions, then 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. Change the permissions if you want to add additional control or you prefer not to automatically deploy the application.

    Refer to the following table for more information about applications-specific permissions.

    Permission

    Description

    Manage

    Users can modify application settings and application sets. Selecting this option also selects the View permission.

    Additionally, a user in a role with the Application Management administrative right can enable this permission to allow other users or roles (without the Application Management right) to administer the application. See Delegate application management for more information.

    Note that you cannot delete applications from the Admin Portal > Web Apps and Mobile Apps pages with just this permission. Add the Delete permission if you want a delegated application administrator to have the ability to delete applications.

    Delete

    Users with this permission can delete applications from the Admin Portal > Web Apps and Mobile Apps pages. Selecting this option also selects the View permission.

    Run

    Allows users to launch the application from the User Portal.

    Automatically Deploy

    Automatically deploys the application to the User Portal. If Automatically Deploy is not selected, users can find the application in the Recommended tab when adding applications to the User Portal.

    The Show in user app list option takes priority over the Automatically Deploy permission. For example, if Show in user app list is not selected, applications do not appear in the User Portal or in the Recommended tab even if you select the Automatically Deploy permission.

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 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 Shared credentials visible to user with "View" permission to allow users to view User Identity (User Name and Password) information for an application in User Portal > Application Settings (select the gear icon in the application tile). Users must have the View permission enabled. This can be helpful to users who may need offline access to the application.

The ability to view the User Identity information in the application is only applicable for application passwords stored in CyberArk Identity and does not apply to applications where the passwords are stored in the PAS Vault.

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

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 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 CyberArk Identity User Portal if they are not currently signed in to the CyberArk Identity User Portal. If they are signed in to the CyberArk 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.