Integrate OKTA IdP

This topic describes how to integrate the OKTA IdP with Carbon Black EDR.

Procedure

Acquire metadata XML from the OKTA IdP and place it in the /etc/cb/sso directory on the Carbon Black EDR server host. (You are not required to use this directory, but it is a good default location.)
On the Carbon Black EDR server, navigate to /etc/cb/sso and:
1. Copy /etc/cb/sso/sso.conf.example.okta to /etc/cb/sso/sso.conf.
2. Copy attr_map.py.example.okta to attr_map.py.
3. Make appropriate changes to the attr_map.py file based on the attributes returned from Okta. Each configurable property is accompanied with additional inline documentation in the attr_map.py file to assist with this process.
Review and edit the /etc/cb/sso/sso.conf file as described here.

Caution:
The syntax of the sso.conf configuration file must fully conform to the JSON data-interchange format. Failure to do so can create an invalid configuration file, which prevents the services from launching properly. When changes are made to this file and cb-enterprise is restarted, check /var/log/cb/coreservices/debug.log to make sure there are no errors.

If an administrator configures the Single Logout (SLO) service in both the IdP Service and Endpoint sections and a user logs out of the Carbon Black EDR server, the user is also logged out of the Okta application. This effectively logs the user out of all Okta applications.
1. Specify the file path to the location of the metadata XML from the OKTA IdP. For example:
```
"metadata": {
      "local": [
        "<file path to location of IdP XML>"
      ]
    },
```
2. Make sure the attribute_mapper field has the path to the Python Mapper file:
```
"attribute_mapper": "/etc/cb/sso/attr_map.py",
```
3. Change the accepted_time_diff field if needed:
```
"accepted_time_diff": 600,
```
4. Update the service / sp / idp section with the appropriate appid from the OKTA IdP. For example:
```
"service": {
 "sp": {
     "nameid_format": "urn:oid:1.3.6.1.4.1.1466.115.121.1.15-NameID",
     "idp": {
         "http://www.okta.com/<appid>": {
```
5. Update the single_sign_on_service and single_logout_service sections with the appropriate name and appid from the OKTA IdP. For example:
```
# URLs in this section MUST be updated to match the URLs defined by the
# IdP you are integrating with
"single_sign_on_service": {
 "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect": "https://fakeidp.okta.com/app/<name>/<appid>/sso/saml"
},

"single_logout_service": {
 "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect": "https://fakeidp.okta.com/app/<name>/<appid>"
}
```
6. In the endpoints section, update the assertion_consumer_service and single_logout_service fields with the appropriate IP address of FQDN of Carbon Black EDR. For example:
```
"endpoints": {
   "assertion_consumer_service": {
      "https://<IP Address or FQDN of the CB Server>/api/saml/
assertion":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
   },
   "single_logout_service": {
      "https://<IP Address or FQDN of the EDR Server>/api/saml/
logout": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
   }
},
```
7. Update the entityid field with the appropriate IP address or FQDN of the Carbon Black EDR server. For example:
```
"entityid": "https://<IP Address or FQDN of the EDR Server>/",
```
8. Search the sso.conf file for “TODO” and ensure that all “TODO” tasks are completed.
Open the /etc/cb/cb.conf file and edit the SSOConfig property so that it contains the full path to the SSO configuration file that was previously created. This single property defines whether Carbon Black EDR server will be started in standalone vs. federated authentication mode.

Note: To deactivate SSO integration, comment out the SSOConfig property.
Generate Carbon Black EDR’s SSO service provider metadata XML file by issuing the following command:
```
usr/share/cb/cbssl sso --make-metadata > /<your file path>
```
Give the XML file to the IdP to complete the trust.
Restart the Carbon Black EDR server by issuing the following command:
```
sudo service cb-enterprise restart
```