ssl-enforcement.md

description
This page provides the technical details of the SSL Enforcement policy

SSL Enforcement

{% hint style="warning" %} This feature requires Gravitee's Enterprise Edition. {% endhint %}

Overview

You can use the ssl-enforcement policy to filter incoming SSL requests. It allows you to restrict or allow access only to requests with client certificate authentication or only to a subset of valid clients.

This policy is mainly used in plan configuration to allow access to consumers for a given set of certificates.

Functional and implementation information for the ssl-enforcement policy is organized into the following sections:

• Examples
• Configuration
• Compatibility Matrix
• Errors
• Changelogs

Examples

{% hint style="warning" %} This policy can be applied to v2 APIs and v4 proxy APIs. It cannot be applied to v4 message APIs. {% endhint %}

{% tabs %} {% tab title="Proxy API example" %} Sample policy configuration:

"ssl-enforcement" : {
    "requiresSsl": true,
    "requiresClientAuthentication": true,
    "whitelistClientCertificates": [
        "CN=localhost,O=GraviteeSource,C=FR"
    ]
}

{% endtab %} {% endtabs %}

Configuration

The implementation of the ssl-enforcement policy supports Ant-style path patterns, where URL mapping matches URLs using the following rules:

• ? matches one character
• * matches zero or more characters
• ** matches zero or more directories in a path

Phases

The phases checked below are supported by the ssl-enforcement policy:

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	true	onRequest	true
onResponse	false	onResponse	false
onRequestContent	false	onMessageRequest	false
onResponseContent	false	onMessageResponse	false

Options

The ssl-enforcement policy can be configured with the following options:

Property	Required	Description	Type	Default
requiresSsl	false	Is SSL requires to access this resource?	boolean	true
requiresClientAuthentication	false	Is client authentication required to access this resource?	boolean	false
whitelistClientCertificates	false	List of allowed X.500 names (from client certificate)	array of strings	-

Compatibility matrix

The following is the compatibility matrix for APIM and the ssl-enforcement policy:

Plugin version	Supported APIM versions
1.x	All

Errors

HTTP status code	Message
401	Access to the resource is unauthorized according to policy rules
403	Access to the resource is forbidden according to policy rules

You can use the response template feature to override the default responses provided by the policy. These templates must be defined at the API level (see the API Console Response Templates option in the API Proxy menu).

The error keys sent by this policy are as follows:

Key	Parameters
SSL_ENFORCEMENT_SSL_REQUIRED	-
SSL_ENFORCEMENT_AUTHENTICATION_REQUIRED	-
SSL_ENFORCEMENT_CLIENT_FORBIDDEN	name (X.500 name from client certificate)

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-ssl-enforcement/blob/master/CHANGELOG.md" %}