Important Notice
This public repository is read-only and no longer maintained.
SAP Cloud Platform Neo API Client
A Java client for SAP Cloud Platform Neo Platform APIs. List of currently supported platform APIs:
- Authorization Management
- Configuration Service
Prerequisities and Dependencies
- Java 8
- SAP Rest API Client
- Apache HTTP Client
- Jackson Faster XML
- Apache commons lang
- Apache commons io
Installation
Build the library using the following maven command.
mvn clean install
Testing
Unit tests
The unit tests of the library can be executed with the following Maven command
mvn clean install -Punit-tests
Integration tests
Prerequisites
- SAP CP Subaccount - the subaccount that would be integrated
- Application - an application, deployed in the subaccount, in which destinations will be managed
- SAP CP Provider Subaccount - the subaccount that Provided Application is deployed in
- Provided Application - an application that SAP CP Subaccount is subscribed to
- SAP Cloud Platform Neo Platform API OAuth Client - SAP Cloud Platform API OAuth client with scopes for at least all currently supported APIs
Configuration Properties
Property | Description |
---|---|
regionAlias | the region alias of the landscape on which APIs are being invoked. |
subaccount | the platform ID of SAP CP Subaccount |
applicationName | the name of Application |
providerSubaccount | the platform ID of SAP CP Provider Subaccount |
providerApplication | the name of Provided Application |
platformClientId | the client ID of Platform API Client |
platformClientSecret | the client secret of Platform API Client |
Trigger Integration Tests
mvn clean install -Pintegration-tests \
-DregionAlias=<subaccountRegionAlias> \
-Dsubaccount=<subaccountId> \
-DplatformClientId=<platformClientId> \
-DplatformClientSecret=<platformClientSecret> \
-DapplicationName=<applicationName> \
-DproviderSubaccount=<providerSubaccountId> \
-DproviderApplication=<providerApplicationName>
Usage
Add the following dependency to your maven pom.xml file.
<dependency>
<groupId>com.sap.cloud.rest</groupId>
<artifactId>neo-api-client</artifactId>
<version>${latest.version}</version>
</dependency>
Creating Neo API Client and Obtaining Service Clients
OAuthAuthentication authentication = PlatformClientsOAuthAuthenticationBuilder.getBuilder()
.subaccount("<subaccount>")
.regionAlias("<region_alias>")
.clientID("<client_id>")
.clientSecret("<client_secret>".toCharArray())
.build();
// Create Neo API Client Factory
NeoClientFactory neoClientFactory = new NeoClientFactory(authentication);
// Get Authorization Management Service Client
AuthorizationManagementService authorizationService = neoClientFactory.getAuthorizationManagementService("neo-region","subaccount");
// Get Configiration Service Client
DestinationConfigurationService destinationService = neoClientFactory.getDestinationConfigurationService("neo-region");
or you could construct the clients on your own by passing a RestApiClientConfig to the constructor. Refer to the rest-api-client library for more info.
OAuthServerConfig oAuthServerConfig = OAuthServerConfigBuilder.getBuilder()
.oAuthServerHost("<oauth_server_host>")
.oAuthServerApiPath("<oauth_server_port>")
.clientID("<client_id>")
.clientSecret("<client_secret>".toCharArray())
.build();
RestApiClientConfig restApiClientConfig = RestApiClientConfigBuilder.getBuilder()
.host("<host>")
.oAuthAuthentication(oAuthServerConfig)
.build();
// Create Authorization Management Service Client
AuthorizationManagementService authorizationService = new AuthorizationManagementRestApiClient(restApiClientConfig);
// Create Configiration Service Client
DestinationConfigurationService destinationConfigurationService = new DestinationConfigurationRestApiClient(restApiClientConfig);
Destination Configuration Service
- Upsert a Destination on Tenant level (destinationConfiguration parameter could be instance of DestinationConfiguration or any of its subclasses, for example BasicDestination, SAMLBearerDestination)
destinationConfigurationService.upsertDestinationOnTenantLevel(<subaccountId>, <destinationConfiguration>)
- Retrieve Destination with OAuth2SAMLBearerAssertion Authentication Type on Tenant Level
OSAMLBearerDestination destination = destinationConfigurationService
.retrieveSAMLBearerDestinationOnTenantLevel(<subaccountId>, <destinationName>)
- Retrieve Destination with Basic Authentication Type on Tenant Level
BasicDestination destination = destinationConfigurationService
.retrieveBasicDestinationOnTenantLevel(<subaccountId>, <destinationName>)
- Retrieve Destination on Tenant Level (supported Authentication types are NoAuthentication, BasicAuthentication, ClientCertificateAuthentication or OAuth2SAMLBearerAssertion)
DestinationConfiguration destination = destinationConfigurationService
.retrieveDestinationOnTenantLevel(<subaccountId>, <destinationName>)
- Delete Destination on Tenant Level
destinationConfigurationService.deleteDestinationOnTenantLevel(<subaccountId>, <destinationName>)
- Upsert a Destination on Application level (destinationConfiguration parameter could be instance of DestinationConfiguration or any of its subclasses, for example BasicDestination, SAMLBearerDestination)
destinationConfigurationService.upsertDestinationOnApplicationLevel(<subaccountId>, <applicationName>, <destinationConfiguration>)
- Retrieve Destination with OAuth2SAMLBearerAssertion Authentication Type on Application Level
OAuth2SAMLBearerAssertionDestination destination = destinationConfigurationService
.retrieveSAMLBearerDestinationOnApplicationLevel(<subaccountId>, <applicationName>, <destinationName>)
- Retrieve Destination with Basic Authentication Type on Application Level
BasicDestination destination = destinationConfigurationService
.retrieveBasicDestinationOnApplicationLevel(<subaccountId>, <applicationName>, <destinationName>)
- Retrieve Destination on Application Level (supported Authentication types are NoAuthentication, BasicAuthentication, ClientCertificateAuthentication or OAuth2SAMLBearerAssertion)
DestinationConfiguration destination = destinationConfigurationService
.retrieveDestinationOnApplicationLevel(<subaccountId>, <applicationName>, <destinationName>)
- Delete Destination on Application Level
destinationConfigurationService.deleteDestinationOnApplicationLevel(<subaccountId>, <applicationName>, <destinationName>)
- Upsert a Destination on Subscription Level (destinationConfiguration parameter could be instance of DestinationConfiguration or any of its subclasses, for example BasicDestination, SAMLBearerDestination)
destinationConfigurationService.upsertDestinationOnSubscriptionLevel(<consumerSubaccountId>, <providerSubaccountId>, <applicationName>, <destinationConfiguration>)
- Retrieve Destination with OAuth2SAMLBearerAssertion Authentication Type on Subscription Level
SAMLBearerDestination destination = destinationConfigurationService
.retrieveSAMLBearerDestinationOnSubscriptionLevel<consumerSubaccountId>, <providerSubaccountId>, <applicationName>, <destinationName>)
- Retrieve Destination with Basic Authentication Type on Subscription Level
BasicDestination destination = destinationConfigurationService
.retrieveBasicDestinationOnSubscriptionLevel(<consumerSubaccountId>, <providerSubaccountId>, <applicationName>, <destinationName>)
- Retrieve Destination on Subscription Level (supported Authentication types are NoAuthentication, BasicAuthentication, ClientCertificateAuthentication or OAuth2SAMLBearerAssertion)
DestinationConfiguration destination = destinationConfigurationService
.retrieveDestinationOnSubscriptionLevel(<consumerSubaccountId>, <providerSubaccountId>, <applicationName>, <destinationName>)
- Delete Destination on Subscription Level
destinationConfigurationService.deleteDestinationOnSubscriptionLevel(<consumerSubaccountId>, <providerSubaccountId>, <applicationName>)
Creating a Destination Configuration
AuthenticationType authenticationType; // initialize
ProxyType proxyType; // initialize
DestinationType destinationType; // initialize
DestinationConfiguration destinationConfiguration = new DestinationConfiguration("<destinationName>", "<url>",
authenticationType, proxyType, destinationType);
You can also provide custom properties in a Map
Map<String, String> additionalProperties = new HashMap<>();
additionalProperties.put("property", "value");
DestinationConfiguration destinationConfiguration = new DestinationConfiguration("<destinationName>", "<url>",
authenticationType, proxyType, destinationType, additionalProperties);
Creating a Basic Destination
ProxyType proxyType; // initialize
BasicDestination basicDestination new BasicDestination("<destinationName>",
"<url>", proxyType, "<user>", "<password>".toCharArray);
You can also provide custom properties in a Map
Map<String, String> additionalProperties = new HashMap<>();
additionalProperties.put("property", "value");
BasicDestination basicDestination new BasicDestination("<destinationName>",
"<url>", proxyType, "<user>", "<password>".toCharArray, additionalProperties);
Creating a SAML Bearer Destination
ProxyType proxyType; // initialize
SAMLBearerDestination oAuthDestination = new SAMLBearerDestination("<destinationName>", "<url>",
proxyType, "<audience>", "<client_key>".toCharArray, "<tokenServiceUrl>", "<tokenServiceUser>",
"<tokenServicePassword>".toCharArray());
You can also provide custom properties in a Map
Map<String, String> additionalProperties = new HashMap<>();
additionalProperties.put("property", "value");
SAMLBearerDestination oAuthDestination = new SAMLBearerDestination("<destinationName>", "<url>",
proxyType, "<audience>", "<client_key>".toCharArray, "<tokenServiceUrl>", "<tokenServiceUser>",
"<tokenServicePassword>".toCharArray(), additionalProperties);
Authorization Management Service
- Create a new role with the specified name, for the specified account and application
authorizationManagementService.createRole("accountName", "appName", "providerAccount", "role");
- Create a list of new roles for the specified account and application
List<String> roles = Arrays.asList("role1", "role2");
authorizationManagementService.createRoles("accountName", "appName", "providerAccount", roles);
- Retrieve a list of all roles for the specified account and application
List<Role> roles = authorizationManagementService.retrieveRoles("accountName", "appName", "providerAccount");
- Deletes a role for the specified account and application
authorizationManagementService.deleteRole("accountName", "appName", "providerAccount", "role");
- Deletes a list of roles for the specified account and application
List<String> roles = Arrays.asList("role1", "role2");
authorizationManagementService.deleteRoles("accountName", "appName", "providerAccount", roles);
- Assigns the specified user a role for the specified account and application
authorizationManagementService.assignUserToRole("accountName", "appName", "providerAccount", "role", "username");
- Assigns a list of users a role for the specified account and application
List<String> usernames = Arrays.asList("user1", "user2");
authorizationManagementService.assignUsersToRole("accountName", "appName", "providerAccount", "role", usernames);
- Retrieve all users which have the specified role assinged for the specified account and application
List<User> users = authorizationManagementService.retrieveUsersAssignedToRole("accountName", "appName", "providerAccount", "role");
- Unassigns the specified user from a role for the specified account and application
authorizationManagementService.unassignUserFromRole("accountName", "appName", "providerAccount", "role", "username");
- Unassigns a list of users from a role for the specified account and application
List<String> usernames = Arrays.asList("user1", "user2");
authorizationManagementService.unassignUsersFromRole("accountName", "appName", "providerAccount", "role", usernames);
- Unassigns all roles assigned to the specified user
authorizationManagementService.unassignAllRolesFromUser("accountName", "userName");
Utility Classes
ConfigApiHostProvider
Provides the host for the Neo Configuration API by specified region alias.
AuthorizationManagementHostProvider
Provides the host for the Authorization Management API by specified region alias and subaccount.
Thrown Exceptions
General
- ConnectionException if an IOException occurs while executing an HTTP request.
- ResponseException if an error HTTP status code is received.
- UnauthorizedException if the user is not authorized to do the operation.
Configuration Service
- DestinationNotFoundException if the destination to be retrieved or deleted is not found
- PermissionDeniedException if required authorization scope is missing
Contribution
We welcome any exchange and collaboration with individuals and organizations interested in the use, support and extension of this library.
License
Copyright (c) 2019 SAP SE or an SAP affiliate company. All rights reserved. This file is licensed under the Apache Software License, v. 2 except as noted otherwise in the LICENSE file