Initial commit
This commit is contained in:
Zhongwei Li
378
references/connectivity.md
Normal file
378
references/connectivity.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user