# OpenCTI

## Presentation

OpenCTI is an open source platform allowing organizations to manage their cyber threat intelligence knowledge and observables.

OpenCTI allows SSO via the SAML or OIDC protocols.

## Configuring OpenCTI (SAML)

### Prerequisites

First, generate a key/certificate pair for OpenCTI

    openssl req -x509 -newkey rsa:4096 -keyout octi-saml-key.pem -out octi-saml-cert.pem -sha256 -days 3650 -nodes

Then, download the LemonLDAP::NG SAML metadata at https://auth.example.com/saml/metadata/idp

In this certificate, extract the `ds:X509Certificate` element inside the `KeyDescriptor use="signing"` element, and remove all spaces, you will get a long Base64 string that looks like

    # On a single line, with no spaces
    MIIFazCCA1OgAwIBAgIUDuUn+nT550rK0Qsej28PlQpZoFkwDQYJKoZIhvcN....

Do the same with `octi-saml-key.pem` in order to get a long Base64 string representing the OpenCTI signing key.

### Regular installation

In your OpenCTI configuration

    "saml": {
    "identifier": "saml",
    "strategy": "SamlStrategy",
    "config": {
        "issuer": "opencti",
        "entry_point": "https://auth.example.com/saml/singleSignOn",
        "saml_callback_url": "https://opencti.example.com/auth/saml/callback",
        "private_key": "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwg...",
        "cert": "MIICmzCCAYMCBgF2Qt3X1zANBgkqhkiG9w0BAQsFADARMQ8w...",
        "roles_management": {
          "role_attributes": ["groups"],
          "roles_mapping": ["my_lemonldap_group:Administrator"]
        }
    }

- `private_key` must contain the concatenated content of `octi-saml-key.pem`

- `cert` must contain the concatenated content of the LemonLDAP::NG signing certificate, from SAML metadata

- The `roles_management` element is only useful if you want to automatically affect roles to your LemonLDAP::NG users depending on their groups.

### Docker

In a docker setup, add the following environment variables

    - PROVIDERS__SAML__STRATEGY=SamlStrategy
    - "PROVIDERS__SAML__CONFIG__LABEL=Login with SAML"
    - PROVIDERS__SAML__CONFIG__ISSUER=opencti
    - PROVIDERS__SAML__CONFIG__ENTRY_POINT=https://auth.example.com/saml/singleSignOn
    - PROVIDERS__SAML__CONFIG__SAML_CALLBACK_URL=https://opencti.example.com/auth/saml/callback
    - PROVIDERS__SAML__CONFIG__CERT=MIICmzCCAYMCBgF2Qt3X1zANBgkqhkiG9w0BAQsFADARMQ8w...
    - PROVIDERS__SAML__CONFIG__PRIVATE_KEY=MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwg...
    - "PROVIDERS__SAML__CONFIG__ROLES_MANAGEMENT__ROLE_ATTRIBUTES=[\"groups\"]"
    - "PROVIDERS__SAML__CONFIG__ROLES_MANAGEMENT__ROLES_MAPPING=[\"my_lemonldap_group:Administrator\"]"

- `PRIVATE_KEY` must contain the concatenated content of `octi-saml-key.pem`

- `CERT` must contain the concatenated content of the LemonLDAP::NG signing certificate, from SAML metadata

- The `ROLES_MANAGEMENT` variables are only useful if you want to automatically affect roles to your LemonLDAP::NG users depending on their groups.

## Configuring LemonLDAP (SAML)

### Generating OpenCTI metadata

Edit the following template to create the metadata for OpenCTI

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <EntityDescriptor
     entityID="opencti"
     xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
     <SPSSODescriptor
       AuthnRequestsSigned="true"
       WantAssertionsSigned="true"
       protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
       <KeyDescriptor use="signing"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>
       ###paste the content of octi-saml-cert.pem here, without the BEGIN and END line###
       </ds:X509Certificate></ds:X509Data></ds:KeyInfo></KeyDescriptor>
       <AssertionConsumerService
         index="0"
         isDefault="true"
         Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
         Location="https://opencti.example.com/auth/saml/callback" />
     </SPSSODescriptor>

    </EntityDescriptor>

Don’t forget to replace the `Location=` attribute and the content of `X509Certificate`.

### Adding OpenCTI::NG to LemonLDAP configuration

Add a new new SAML Service Provider to the LemonLDAP::NG configuration with the following parameters:

- Metadata

    - Copy the Metadata generated at the previous step

- Exported Attributes

    - variable name: `groups`

    - attribute name: `groups`

## OIDC Interconnection

This section describe the OpenID Connect configuration

### Configure OpenCTI (OIDC)

Here is the basic configuration for a docker installation

Define and replace `<clientid>` and `<clientsecret>`, and also adapt issuer and redirect uri:

    - PROVIDERS__OPENID__STRATEGY=OpenIDConnectStrategy
    - "PROVIDERS__OPENID__CONFIG__LABEL=Login with OpenID"
    - PROVIDERS__OPENID__CONFIG__ISSUER=https://auth.example.com
    - PROVIDERS__OPENID__CONFIG__CLIENT_ID=<clientid>
    - PROVIDERS__OPENID__CONFIG__CLIENT_SECRET=<clientsecret>
    - "PROVIDERS__OPENID__CONFIG__REDIRECT_URIS=[\"https://opencti.mydomain.com/auth/oic/callback\"]"

For an advanced usage, you can also map lemonldap groups to openCTI groups with these paramters:

    - "PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__GROUPS_SCOPE=groups"
    - "PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__GROUPS_PATH=[\"groups\", \"realm_access.groups\", \"resource_access.account.groups\"]"
    - "PROVIDERS__OPENID__CONFIG__GROUPS_MANAGEMENT__GROUPS_MAPPING=[\"OpenID_Group_1:OpenCTI_Group_1\", \"OpenID_Group_2:OpenCTI_Group_2\", ...]"

### Configure LemonLDAP (OIDC)

Configure LemonLDAP as an OpenID Connect provider.

As describe in documentation link above, also define a new Relying Party in LL::NG.

Take care to configure at least these parameters:

- `Public client`: disabled

- `Client ID`: client id defined in previous section

- `Client secret`: client secret defined in previous section

- `Allowed redirection addresses for login`: redirect uri defined in previous section

- `Security -> ID Token signature algorithm`: make sure you select RS256, as HS512 is not supported in OpenCTI

- `Advanced -> User attribute`: take care to use the user unique identifier defined in OpenCTI, usually `mail`

Advanced usage, for group mapping:

- `Exported attributes (claims)`: add claim `groups -> groups`

- `Options -> Scope`: add scope `groups -> groups`