Migrate an External IDP from the Legacy Custom Authentication to the Modern Authenticator Framework

1. Configure the external IDP to communicate with Cylance Endpoint Security.

In your IDP management console, you must add a new single sign-on URL to the existing Application.  You must create a new application if your IDP does not support multiple single sign-on URLs. 

Single sign-on URL: https://idp.blackberry.com/_/resume

By default, the Cylance management console requires all SAML responses to include the users' email addresses. Important: The email addresses in your IDP must match the addresses that are registered in the Cylance management console.  

In this example, we are adding the new single sign-on URL to the existing configuration in Active Directory Federation Services (ADFS).

In the image, the numbers correspond to the Step number in the procedure; not all steps are represented in the image. 

1.  In the external IDP management console, open your existing SAML configuration and update the SAML settings.

2. Add the new single sign-on URL https://idp.blackberry.com/_/resume

a. In the management console > Replying Party Trusts, double-click the Relying Party Trust that was created for the custom SAML.    

b. On the Endpoints tab, click Add SAML and include the following settings:

       ·  Endpoint type: SAML Assertion Consumer

       ·  Binding: Post

       ·  Index: Set the index to the next indexing value.

       ·  Trusted URL: Enter https://idp.blackberry.com/_/resume

3.  Record the following information. We will be checking it against the Authenticator configuration in the Cylance console in the next step.  You will need to update the migrated authenticator with one or more of the following items if you create a new application.

a. Login Request URL: This is the Login URL for your IDP.  The name of this attribute may vary for different IDPs. This will be used to verify the Login Request URL in the Authenticator configuration in the next step. For more information on the Identity provider-initiated sign in, see your ADFS documentation. 

b. IDP Signing certificate: Base-64 encoded X.509 SAML Signing Certificate. In ADFS > Service > Certificate folder, double-click the primary token-signing certificate and on the Details tab, click Copy to File. Complete the on-screen steps.  This will be used to verify the certificate in the Authenticator configuration in the next step.

c. SP Entity ID:  In ADFS the “SP Entity ID” is called “Relying party Identifier”.

I.  In the management console > Replying Party Trusts, double-click the Relying Party Trust that was created for the custom SAML.

II. On the Identifiers tab, record the entry in the Relying party identifiers field. This will be used to verify the SP Entity ID field in the Authenticator in the next step.

d.  Attributes & Claims:  Cylance custom authentication uses the user’s email address as the User ID. Some IDPs use username as the User ID. In this example, use the existing configurations to map the User ID to the email address in your IDP settings.

Note: No action is required if your current configuration works as expected with the Cylance custom authentication. If necessary, verify the following information or create the required rules.

I. In the management console, Click Relying Party Trusts.

II.  Right-click the replying party trust that you updated in step 2 > Edit Claim Issuance Policy.

III. Follow the on-screen steps and include the following settings:

Rule 1

·  Claim rule template: Send LDAP Attributes as Claims

·  Attribute store: Active Directory

·  LDAP Attribute: E-Mail-Addresses

·  Outgoing Claim Type: E-Mail Address

Rule 2

·  Claim rule template: Transform an Incoming Claim

·  Incoming claim type: E-Mail Address

·  Outgoing claim type: Name ID

·  Outgoing name ID format: Email

For more information, visit https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-transform-an-incoming-claim.

2. In the Cylance console, update the Migrated Custom Authentication Connector: Custom - Configuration Required.

1. Sign in the to Cylance console.
2. On the menu bar, click Settings > Authentication.
3. Open Migrated Custom Authentication Connector: Custom - Configuration Required.
4. In the Login request URL field, verify that this field matches the IDP single sign-on URL that you recorded in step 1, 3a (see the image to the left). If it does not, replace the Login request URL field with the value you recorded in 1, 3a.
5. In the IDP signing certificate field, verify that the certificate that you copied in step 1, 3b, matches the certificate value in this field. If it does not, replace the value in this field with the certifciate value you coped in 1, 3b including the Begin Certificate and End Certificate lines. If you paste the body of the certificate, make sure that you don't alter any line breaks or the format of the certificate information (see image to the left).
6. In the SP Entity ID field, verify that the value matches the value you recorded in step 1, 3c. 
7. (Optional) Change the Name of this Authenticator in the Cylance console. The name can be anything you deem appropriate.  BlackBerry recommends that you at least remove the “Configuration Required” text from the name (see image to the left).

3. Create an authentication policy and assign it to users and groups.

Create a policy that includes the required authenticators for your environment. You can create a user policy or add the authenticator to the default authentication policies for the console, CylancePROTECT Mobile app, or CylanceGATEWAY agent. Assign the policy to one administrator to verify the sign-in policy is functioning as expected. You can then assign the authentication policy to your users.

In the image, the numbers correspond to the Step number in the procedure; not all steps are represented in the image.

1. On the menu bar, click Settings > User Policy.
2. Click the Authentication tab.
3. Click Add Policy.  
4. Enter a name and description for the policy (for example, Console Authentication Policy).
5. In the Authenticator rules section, click Add Authenticator. In the Add authenticator dialog box, select the “Migrated Custom Authentication Connector: Custom - Configuration Required” authenticator or find the name to which you changed the Authenticator in the last step (see image to the left).
6. Click Save.
7. To create the authentication policy, click Save.
8. Assign the policy to one administrator and then verify that the sign in is working as expected. Complete the following steps:

a. In the Assign the authentication policy dialog box, click Yes.

b. Click Add User or Group.

c. Start typing a name to search for the user that you want to add.

d. Select the user from the search results.

e. Click Add.

f. Sign out of the console, or open an In Private window and access the console sign-in page

g. Enter the email address of the administrator to which you assigned the authentication policy above and click Sign In.

h. When prompted, enter your credentials from your custom IDP.

i. Complete the sign in with your custom IDP credentials and verify that the administrator can successfully sign in to the Cylance console.

For more information on additional authentication policy settings, see Create an authentication policy.

Important: Make sure that the Allow Password Login check box (Settings > Application > Custom Authentication) is selected. This option allows you to log in to the console directly and use SSO. If this option is not enabled before you test your SSO settings, users cannot sign in to the console using SSO. For more information on managing authentication policies, see Manage authentication polices for your tenant. 

Optionally, it is recommended that you create a user policy (User policy > Authentication) that requires only a Cylance console password and assign it to one or more designated administrators. You should use a strong password for the user policy. You can use this policy as a failsafe while you migrate Custom Authentication to an authenticator.   

That's it!

You have successfully configured a custom SAML authenticator based on the existing custom authentication and assigned the authentication policy to users and groups. 

Users can now sign in to the Cylance console using their IDP credentials from the sign-in page.

Next steps: Disable Custom Authentication.

After you have verified that you can sign in to the Cylance console from the primary login page using your IDP credentials, you can go to Settings > Application and clear the Custom Authentication check box.

Sign out and sign in to the Cylance console from the sign-in page using the administrator account with the new authentication policy that was applied in step 3 of this workflow and your IDP credentials.

Warning: Make sure that you sign in to the Cylance console from the primary sign-in page using you external IDP credentials. If you test the sign in from the “Or sign in with your External Identity Provider” page and then Disable Custom Authentication, you may become locked out of the console.

BlackBerry recommends that you secure the Administrator account that you created with the password-only policy by assigning the IDP policy or changing the password-only policy to add an OTP code for better security.