Overview :
SAP API Management lets you enable one-way and two-way TLS/SSL support for virtual hosts.When you access an API proxy through a virtual host that supports TLS/SSL, API Management captures information about the TLS connection which can be accessed in an API proxy via flow variables.
The kind of TLS/SSL information captured depends upon whether the virtual host is enabled for one-way or two-way TLS. For example,
- For one-way TLS, API Management captures information about TLS cipher or TLS protocol used in the TLS connection.
- For two-way TLS, API Management not only captures the same information as captured for one-way TLS, but also captures information about the client’s certificate (cert). For example, the subject or issuer DN of the client cert, the serial number of the client cert and the client cert in the PEM format.
The following are the list of flow variables that contain TLS connection information pertaining to the client’s cert.
Flow Variable | Description |
tls.client.s.dn | The subject Distinguished Name (DN) of the client cert. This variable enables you to capture information about the subject (individual) being certified, including common name (client.cn), organization (client.organization), organization unit (client.organization.unit), e-mail address (client.email.address), country/region codes (client.country), locality (client.locality) etc. |
tls.client.i.dn | The issuer Distinguished Name (DN) of the client cert. |
tls.client.raw.cert | The client cert in the PEM format. |
tls.client.cert.serial | The serial number of the client cert. |
tls.client.cert.fingerprint | The SHA1 fingerprint of the client cert. |
tls.session.id | The session identifier. This flow variable is available when you set either <ConnectionProperties> or <ClientProperties> to true. |
Pre-Requisite :
To configure a virtual host to capture the TLS/SSL information, you need to request the API Management operations team (OPU-API-OD-OPS) to set the following properties to true in the virtual host configuration file:
Virtual Host Property | Description |
ConnectionProperties | Set it to true to capture TLS connection information for both one-way and two-way TLS. |
ClientProperties | Set it to true to capture additional information for two-way TLS. |
Policy template for reading Client certificate attributes
In the below template ,
- Assign message policy is used to set the TLS Flow variables as HTTP headers in the request .
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="true" enabled="true"
xmlns="http://www.sap.com/apimgmt">
<Set>
<Headers>
<Header name="tls.client.s.dn">{tls.client.s.dn}</Header>
<Header name="tls.client.i.dn">{tls.client.i.dn}</Header>
<Header name="tls.client.raw.cert">{tls.client.raw.cert}</Header>
<Header name="tls.client.cert.serial">{tls.client.cert.serial}</Header>
<Header name="tls.client.cert.fingerprint">{tls.client.cert.fingerprint}</Header>
<Header name="tls.session.id">{tls.session.id}</Header>
</Headers>
</Set>
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
<AssignTo createNew="false" type="request">request</AssignTo>
</AssignMessage>
- Assign message policy is used to set the TLS Flow variables as request payload .
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="true" enabled="true" xmlns="http://www.sap.com/apimgmt">
<Set>
<Payload contentType="application/json" variablePrefix="@" variableSuffix="#">{
"tls":
{
"client":
{
"s":
{
"dn": "@tls.client.s.dn:null#"
},
"i":
{
"dn": "@tls.client.i.dn:null#"
},
"serial":
{
"serial": "@tls.client.cert.serial:null#"
},
"fingerprint":
{
"fingerprint": "@tls.client.cert.fingerprint:null#"
},
"raw":
{
"cert": "@tls.client.raw.cert:null#"
}
}
}
</Payload>
</Set>
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
<AssignTo createNew="false" type="request">request</AssignTo>
</AssignMessage>
Test Your API via curl call:
- Create API Proxy
- Apply the template available in api.sap.com
- Execute the endpoint -> curl <ApiEndPOint> -s key <key.pem> --cert <cert.pem> -v
