379 lines
9.3 KiB
Markdown
379 lines
9.3 KiB
Markdown
# Connectivity Reference
|
|
|
|
Complete guidance for SAP BTP connectivity including destinations and Cloud Connector.
|
|
|
|
**Source**: [https://github.com/SAP-docs/sap-btp-cloud-platform/tree/main/docs/30-development](https://github.com/SAP-docs/sap-btp-cloud-platform/tree/main/docs/30-development)
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Destinations Overview](#destinations-overview)
|
|
2. [Authentication Methods](#authentication-methods)
|
|
3. [Cloud Connector](#cloud-connector)
|
|
4. [Principal Propagation](#principal-propagation)
|
|
5. [Destination Service API](#destination-service-api)
|
|
|
|
---
|
|
|
|
## Destinations Overview
|
|
|
|
Destinations abstract connection details from application code:
|
|
|
|
### Benefits
|
|
|
|
- Separation of configuration from code
|
|
- Secure credential storage
|
|
- Runtime resolution of connection details
|
|
- Central management in BTP Cockpit
|
|
|
|
### Destination Types
|
|
|
|
| Type | Description |
|
|
|------|-------------|
|
|
| **HTTP** | REST APIs, web services |
|
|
| **RFC** | SAP RFC connections |
|
|
| **LDAP** | Directory services |
|
|
| **Mail** | SMTP connections |
|
|
|
|
### Proxy Types
|
|
|
|
| Proxy | Use Case |
|
|
|-------|----------|
|
|
| **Internet** | Cloud services, public APIs |
|
|
| **OnPremise** | On-premise systems via Cloud Connector |
|
|
| **PrivateLink** | AWS/Azure private connectivity |
|
|
|
|
---
|
|
|
|
## Authentication Methods
|
|
|
|
### NoAuthentication
|
|
|
|
Public APIs without authentication:
|
|
|
|
```json
|
|
{
|
|
"Name": "public-api",
|
|
"Type": "HTTP",
|
|
"URL": "[https://api.example.com",](https://api.example.com",)
|
|
"ProxyType": "Internet",
|
|
"Authentication": "NoAuthentication"
|
|
}
|
|
```
|
|
|
|
### BasicAuthentication
|
|
|
|
Username/password (testing only):
|
|
|
|
```json
|
|
{
|
|
"Name": "basic-auth",
|
|
"Type": "HTTP",
|
|
"URL": "[https://api.example.com",](https://api.example.com",)
|
|
"ProxyType": "Internet",
|
|
"Authentication": "BasicAuthentication",
|
|
"User": "username",
|
|
"Password": "password"
|
|
}
|
|
```
|
|
|
|
### OAuth2ClientCredentials
|
|
|
|
Service-to-service:
|
|
|
|
```json
|
|
{
|
|
"Name": "oauth2-client",
|
|
"Type": "HTTP",
|
|
"URL": "[https://api.example.com",](https://api.example.com",)
|
|
"ProxyType": "Internet",
|
|
"Authentication": "OAuth2ClientCredentials",
|
|
"clientId": "my-client-id",
|
|
"clientSecret": "my-client-secret",
|
|
"tokenServiceURL": "[https://auth.example.com/oauth/token"](https://auth.example.com/oauth/token")
|
|
}
|
|
```
|
|
|
|
### OAuth2SAMLBearerAssertion
|
|
|
|
User propagation to cloud services:
|
|
|
|
```json
|
|
{
|
|
"Name": "saml-bearer",
|
|
"Type": "HTTP",
|
|
"URL": "[https://api.example.com",](https://api.example.com",)
|
|
"ProxyType": "Internet",
|
|
"Authentication": "OAuth2SAMLBearerAssertion",
|
|
"audience": "[https://audience.example.com",](https://audience.example.com",)
|
|
"clientKey": "my-client-id",
|
|
"tokenServiceURL": "[https://auth.example.com/oauth/token",](https://auth.example.com/oauth/token",)
|
|
"tokenServiceURLType": "Dedicated",
|
|
"authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession"
|
|
}
|
|
```
|
|
|
|
### OAuth2JWTBearer
|
|
|
|
Token exchange (preferred over OAuth2UserTokenExchange):
|
|
|
|
```json
|
|
{
|
|
"Name": "jwt-bearer",
|
|
"Type": "HTTP",
|
|
"URL": "[https://api.example.com",](https://api.example.com",)
|
|
"ProxyType": "Internet",
|
|
"Authentication": "OAuth2JWTBearer",
|
|
"clientId": "my-client-id",
|
|
"clientSecret": "my-client-secret",
|
|
"tokenServiceURL": "[https://auth.example.com/oauth/token"](https://auth.example.com/oauth/token")
|
|
}
|
|
```
|
|
|
|
### PrincipalPropagation
|
|
|
|
On-premise with Cloud Connector:
|
|
|
|
```json
|
|
{
|
|
"Name": "onprem-pp",
|
|
"Type": "HTTP",
|
|
"URL": "[http://virtualhost:port",](http://virtualhost:port",)
|
|
"ProxyType": "OnPremise",
|
|
"Authentication": "PrincipalPropagation",
|
|
"CloudConnectorLocationId": "location1"
|
|
}
|
|
```
|
|
|
|
### ClientCertificateAuthentication
|
|
|
|
mTLS:
|
|
|
|
```json
|
|
{
|
|
"Name": "mtls",
|
|
"Type": "HTTP",
|
|
"URL": "[https://api.example.com",](https://api.example.com",)
|
|
"ProxyType": "Internet",
|
|
"Authentication": "ClientCertificateAuthentication",
|
|
"KeyStoreLocation": "keystore.p12",
|
|
"KeyStorePassword": "password"
|
|
}
|
|
```
|
|
|
|
> **Note**: The keystore file (`.p12` or `.jks`) must be uploaded to the destination
|
|
> configuration in BTP Cockpit before referencing it. Upload via: Connectivity →
|
|
> Destinations → destination properties → Upload and Delete Certificates.
|
|
|
|
### Authentication Method Compatibility
|
|
|
|
| Method | Internet | OnPremise | Private Link |
|
|
|--------|----------|-----------|--------------|
|
|
| NoAuthentication | Yes | Yes | Yes |
|
|
| BasicAuthentication | Yes | Yes | Yes |
|
|
| OAuth2ClientCredentials | Yes | No | Yes |
|
|
| OAuth2SAMLBearerAssertion | Yes | No | Yes |
|
|
| OAuth2JWTBearer | Yes | No | Yes |
|
|
| PrincipalPropagation | No | Yes | No |
|
|
| ClientCertificateAuthentication | Yes | Yes | Yes |
|
|
|
|
---
|
|
|
|
## Cloud Connector
|
|
|
|
### Overview
|
|
|
|
Lightweight on-premise agent providing:
|
|
- Secure tunnel to SAP BTP
|
|
- No inbound firewall ports required
|
|
- Fine-grained access control
|
|
- Principal propagation support
|
|
|
|
### Installation
|
|
|
|
1. Download from SAP Software Download Center
|
|
2. Install on on-premise network
|
|
3. Configure connection to SAP BTP subaccount
|
|
4. Define accessible resources
|
|
|
|
### Architecture
|
|
|
|
```
|
|
SAP BTP Application
|
|
↓ (HTTPS)
|
|
Connectivity Service
|
|
↓ (TLS tunnel)
|
|
Cloud Connector (on-premise)
|
|
↓ (HTTP/RFC)
|
|
On-Premise System
|
|
```
|
|
|
|
### Configuration Scopes
|
|
|
|
| Scope | Configuration |
|
|
|-------|---------------|
|
|
| **Subaccount** | One Cloud Connector per subaccount |
|
|
| **Location ID** | Multiple connectors per subaccount |
|
|
| **Access Control** | Resource-level permissions |
|
|
|
|
### Virtual Host Mapping
|
|
|
|
Map internal systems to virtual hosts:
|
|
|
|
```
|
|
Virtual Host: sap-erp-virtual:443
|
|
→ Internal System: erp.internal.company.com:443
|
|
```
|
|
|
|
### Access Control
|
|
|
|
Define which resources are accessible:
|
|
|
|
| Setting | Description |
|
|
|---------|-------------|
|
|
| **Protocol** | HTTP, HTTPS, RFC |
|
|
| **Internal Host** | Actual system hostname |
|
|
| **Virtual Host** | Exposed hostname to BTP |
|
|
| **Path** | URL path prefix |
|
|
| **Method** | HTTP methods allowed |
|
|
|
|
### High Availability
|
|
|
|
**Architecture**:
|
|
- **Master connector**: Active, handles all traffic
|
|
- **Shadow connector**: Standby, monitors master health
|
|
- Automatic failover if master becomes unavailable
|
|
|
|
**Setup**:
|
|
1. Install Cloud Connector on two separate hosts
|
|
2. Configure first as master (connects to BTP)
|
|
3. Configure second as shadow (points to master)
|
|
4. Shadow automatically takes over if master fails
|
|
|
|
**Configuration**:
|
|
```
|
|
Master: cc-master.internal.company.com:8443
|
|
Shadow: cc-shadow.internal.company.com:8443
|
|
→ Points to master for health checks
|
|
→ Same subaccount/location ID configuration
|
|
```
|
|
|
|
**Best Practices**:
|
|
- Deploy master and shadow on different physical hosts
|
|
- Use different network segments if possible
|
|
- Monitor both instances via Cloud Connector admin UI
|
|
- Test failover periodically
|
|
|
|
### Monitoring
|
|
|
|
- Connection status in BTP Cockpit
|
|
- Audit logs
|
|
- Performance metrics
|
|
|
|
---
|
|
|
|
## Principal Propagation
|
|
|
|
### On-Premise via Cloud Connector
|
|
|
|
Forward user identity to on-premise systems:
|
|
|
|
```
|
|
User authenticates → BTP App → Cloud Connector → On-Premise
|
|
(SAML) (X.509 cert) (user context)
|
|
```
|
|
|
|
**Requirements**:
|
|
1. Cloud Connector with SNC or X.509
|
|
2. Destination with `PrincipalPropagation`
|
|
3. On-premise system configured for SSO
|
|
|
|
### SAP System Configuration
|
|
|
|
For SAP ERP/S4:
|
|
1. Configure trusted certificate in STRUST
|
|
2. Enable SSO in SICF
|
|
3. Map certificate subject to user
|
|
|
|
### Cloud-to-Cloud
|
|
|
|
Use `OAuth2SAMLBearerAssertion` or `OAuth2JWTBearer`:
|
|
|
|
```javascript
|
|
// Using SAP Cloud SDK
|
|
const destination = await getDestination('my-destination');
|
|
const response = await executeHttpRequest(destination, {
|
|
method: 'GET',
|
|
url: '/api/resource'
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Destination Service API
|
|
|
|
### Get Destination
|
|
|
|
```bash
|
|
# Get single destination
|
|
curl -X GET "[https://destination-configuration.cfapps.<region>.hana.ondemand.com/destination-configuration/v1/destinations/<name>"](https://destination-configuration.cfapps.<region>.hana.ondemand.com/destination-configuration/v1/destinations/<name>") \
|
|
-H "Authorization: Bearer <token>"
|
|
```
|
|
|
|
### Response
|
|
|
|
```json
|
|
{
|
|
"owner": {
|
|
"SubaccountId": "...",
|
|
"InstanceId": "..."
|
|
},
|
|
"destinationConfiguration": {
|
|
"Name": "my-destination",
|
|
"Type": "HTTP",
|
|
"URL": "[https://api.example.com",](https://api.example.com",)
|
|
"Authentication": "OAuth2ClientCredentials",
|
|
"ProxyType": "Internet"
|
|
},
|
|
"authTokens": [
|
|
{
|
|
"type": "Bearer",
|
|
"value": "...",
|
|
"expires_in": "3600"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Using in Applications
|
|
|
|
**Node.js (CAP/Cloud SDK)**:
|
|
```javascript
|
|
const { getDestination, executeHttpRequest } = require('@sap-cloud-sdk/core');
|
|
|
|
const destination = await getDestination('my-destination');
|
|
const response = await executeHttpRequest(destination, {
|
|
method: 'GET',
|
|
url: '/api/resource'
|
|
});
|
|
```
|
|
|
|
**Java (Cloud SDK)**:
|
|
```java
|
|
HttpDestination destination = DestinationAccessor
|
|
.getDestination("my-destination")
|
|
.asHttp();
|
|
|
|
HttpClient client = HttpClientAccessor.getHttpClient(destination);
|
|
HttpResponse response = client.execute(new HttpGet("/api/resource"));
|
|
```
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- Connectivity Service: [https://help.sap.com/docs/connectivity](https://help.sap.com/docs/connectivity)
|
|
- Cloud Connector: [https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/cloud-connector](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/cloud-connector)
|
|
- Destinations: [https://github.com/SAP-docs/sap-btp-cloud-platform/tree/main/docs/30-development](https://github.com/SAP-docs/sap-btp-cloud-platform/tree/main/docs/30-development)
|