> ## Documentation Index
> Fetch the complete documentation index at: https://developers.entri.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secure Configuration

> showEntri() config keys for Secure: ssl on dnsRecords, secureRootDomain, applicationUrl.

## Configure your Entri account

Before you can provision SSL certificates on Entri, you'll need to provide some basic information. Log into the [Entri Dashboard](https://dashboard.entri.com/), navigate to the SSL section, and enter the following information:

* The `applicationUrl`, which is the URL of the application that responds to requests coming from your clients' URLs. This is also commonly referred to as an origin server.
* Your company’s `cname_target`. This is the CNAME record that your customers need. It needs to be pointed to `ssl.goentri.com` and will be the target domain for your clients’ requests, providing a layer of security and encryption.

For example, if you run `saascompany.com`. You would first create a CNAME record:

```json json theme={null}
{
  "type": "CNAME",
  "host": "domains",
  "value": "ssl.goentri.com",
  "ttl": 300,
}
```

You're now ready to provision SSL certificates for your customers.

## Provision a certificate

After you've configured your account for SSL, there are two methods of provisioning an SSL certificate for your customer's domain: utilizing the ***Entri modal***, or making a direct API request.

### Provisioning an SSL certificate via the Entri Modal (recommended)

Provisioning a certificate for a subdomain is effortless with the ***Entri modal***. Add an extra property, `ssl: true`, to the CNAME record that will be set by Entri (as shown in the configuration object below) and set `value` to be `{CNAME_TARGET}`.

`{CNAME_TARGET}` will automatically use the **CNAME target** entered in the dashboard in step 1.

```JSON JSON theme={null}
{
  "type": "CNAME",
  "host": "www",
  "value": "{CNAME_TARGET}",  // This will match the CNAME target defined in the Entri dashboard in step 1
  "ttl": 300,
  "ssl": true,
}
```

We suggest this method because it guarantees that your user has properly added the required `cname_target` record. Without this CNAME record added to your customer's DNS, Entri cannot provision an SSL certificate.

Additionally, if the user has a conflicting CAA record, Entri will automatically fix it during the DNS setup process.

<Note>
  For more information about configuring the ***Entri modal***, see: [Create the
  configuration object](/connect/configuration#entrishowentriconfig).
</Note>

### SSL certificates for the root domain via the Entri Modal

You can also create an SSL certificate for the root domain using Entri. It will require you to add an extra dnsRecord to the configuration, and Entri will do all the rest for you. This feature will create 2 new A records with Entri's IPs on the root domain's dns configuration and will use Entri as proxy to encrypt and forward the traffic to your application.

```JSON JSON theme={null}
{
  type: "A",
  host: "@",
  value: "{ENTRI_SERVERS}",
  ttl: 300,
  ssl: true,
  applicationUrl: "my.applicationurl.com", // [Optional] overrides the pre-configured applicationUrl
  redirectTo: "some.domain.com" //[Optional] Allows you to create a custom redirect policy from the secured domain to any other domain or subdomain.
}
```

You should only use the `applicationUrl` key, whenever you need to override the applicationUrl configured on your Customer Dashboard.

## Get notified when the SSL certificate is provisioned

You can use [Entri's Webhook functionality](/webhooks-overview) to listen for when an SSL certificate has been provisioned on a domain. Check for `"secure_status": "success"` in the webhook payload.

## Appended Headers on Incoming Traffic

As part of the SSL provisioning process, all incoming traffic will have specific headers appended to each request. These headers provide additional context about the original request, including information about the host and IP address. The following headers will be added automatically to every incoming request:

* **X-Forwarded-Host**: This header contains the original `Host` value of the incoming request before any proxy or load balancer has modified it. It helps in identifying the initial destination for the request.

* **x-entri-forwarded-host**: Similar to `X-Forwarded-Host`, this is a custom header used by Entri to track the original host at the time the request was forwarded through Entri’s system.

* **X-Forwarded-IP** or **X-Forwarded-For**: These headers contain the original IP address of the client making the request. It is useful for understanding where the request originated from, even if it passed through proxies or load balancers.

* **X-Entri-Auth**: The X-Entri-Auth header is a configurable authentication token that you can set in the Entri Dashboard. Once enabled, it is automatically included in every outgoing request, allowing your system to verify that the request originated from Entri. The token can be rotated at any time to align with your internal security policies.

These headers ensure that downstream services can access critical metadata about the request, facilitating better logging, security, and handling of the requests in your system.

### Secure root domains

This feature allows you to create a valid SSL certificate for the root domain, in a way that it can be used either as a redirect rule to the `www` subdomain or as a way to show the content directly. This feature, in all cases, will create 2 new `A` records with Entri's IPs to the root domain's dns configuration, and will use Entri as proxy to encrypt and forward the traffic to your application.

IMPORTANT: This feature requires to have [Entri Secure](/secure/overview) or [Entri Power](/power/overview) enabled on your account.

#### Basic usage (wwwRedirect only)

This configuration may be used for securing the root domain (e.g. `https://mydomain.com`) and redirect it to `www` (eg. `https://www.mydomain.com`)

```JSON JSON theme={null}
{
  applicationId: "12345",
  token: mySavedToken,
  secureRootDomain: true,
  wwwRedirect:true,
  dnsRecords: [...]
}
```

#### Advanced usage (display content)

This configuration may be used for securing the root domain (e.g. `https://mydomain.com`) and show the content directly on the root domain level, without redirections.

```JSON JSON theme={null}
{
  applicationId: "12345",
  token: mySavedToken,
  secureRootDomain: true,
  wwwRedirect:true,
  dnsRecords: [
    {
      type: "A",
      host: "@",
      value: "{ENTRI_SERVERS}",
      ttl: 300,
      ssl: true,
      applicationUrl: "my.applicationurl.com" // [Optional] overrides the pre-configured applicationUrl
    },
    ... //Other records
  ]
}
```