Technology Blog Posts by SAP
cancel
Showing results for 
Search instead for 
Did you mean: 
jamiePower
Advisor
Advisor
1,159

Introduction

The Data Export and Data Import API's offer a holistic solution to manage data of various different artefacts within the SAP Analytics Cloud Modeling Ecosystem. The API's allow the extraction and modification of Model Fact, Audit and Master Data as well as Currency, Unit and Public Dimension Tables. 

The purpose of this blog is to provide a clear step by step instruction on how to configure the correct Authorization in order to interact with the API's both in a Technical context as well as an SAC User Context. Both API's rely on the OAuth 2.0 Authentication which is known and widely used Authentication standard for API's.

Configuring an OAuth Client

In order to make any request to the Export/Import API's, We need a Bearer Token. The Bearer Token is included in the Authorization header of every request made to service and is essential to authorize all requests to the API. 

To fetch our Bearer Token we need to establish an OAuth Client on our SAC Tenant. An OAuth client is an application or service that uses the OAuth protocol to interact with resources hosted by another application or service, in our case we need an OAuth in order to grant permission to a client (Postman/Bruno/Browser etc.) to given resources in the SAC Tenant. Once we have configured our OAuth client we can request a bearer token using the clients credentials and get access to the required API.

Note: An Admin role is required in order to create an OAuth Client.

Setup

Navigate and login to an SAC Tenant. From the side navigation, choose System then Administration.Figure 1. SAC HomepageFigure 1. SAC Homepage

From the side navigation, Choose App Integration tab.

Figure 2: AdministrationFigure 2: Administration

Under Configure Clients, copy the Token URL. It will be needed later in this procedure.

Figure 3: App IntegrationFigure 3: App Integration

Under Configured Clients, select Add a New OAuth Client. This will open a dialog to input the details of your OAuth Client. 

Figure 4: Add OAuth ClientFigure 4: Add OAuth Client

In the dialog, add a Name for the OAuth client. When configuring an OAuth client, we can specify the Purpose to be API Access or Interactive Usage.

Interact Usage will prompt the client to login to SAC when a token is requested, this flow will ensure the logged in users' context is applied to the received token and the restrictions to certain SAC artefacts are applied such as Data Access Control Filters for Models or restrictions to certain Models, Currencies, Dimensions etc. The set up for this flow is as follows:

  1. In the dialog, add a Name for the OAuth client.
  2. Under Purpose, select Interactive Usage.
  3. The Redirect URI is the URL that the server will direct the client to once they have completed login, if you have a preferred URL to hand this you can input it here, otherwise for the sake of using the API Client you can specify a placeholder such as https://oauth.pstmn.io/v1/callback

Figure 5: OAuth Client ConfigurationFigure 5: OAuth Client Configuration

Client Credentials are considered a technical connection to the API which allows unrestricted access to resources via the API. This type of client is typically used by an Admin user or is created for an Integration to another application or system so that client is authorized to use the API. The setup for this flow is as follows:

  1. In the dialog, add a Name for the OAuth client.
  2. Under Purpose, select API Access (Technical Connection).
  3. Under Access, select Data Import Service and/or Data Export Service depending on whether you wish to use one of the API's or both
  4. Under Authorization Grant select Client Credentials

Figure 6: New configured OAuth ClientFigure 6: New configured OAuth Client

Optional: You can specify the lifetime of your token the client returns. By default they are valid for one hour but can be extended if this is required for your use case. 

Once you click Add, your new client will be created. Make sure to take note of the Client ID and Client Secret. You should also have the Token URL seen at the top of the App Integration tab. If your client has purpose Interactive Usage then you will also need to make note of the Authorization URL.

⚠️The Client Secret of an OAuth Client can only be viewed on creation so make sure to take note of it during this time, otherwise a new client will need to be created. Always keep the Client Secret secure as it is sensitive information. 

Figure 7:  OAuth Client ID and SecretFigure 7:  OAuth Client ID and Secret

Once you click Save, your OAuth Client will be added to the list of entries under Configured OAuth Clients in App Integration.

 

Using the OAuth Client to fetch a Token

There are various different clients which you can use for the API in this section we will discuss the usage of the different clients and the required setup.

External Applications 

There are number of possible integrations with external applications such as replication to a BW or S4HANA System using Data Export Service or Importing Data from one system to an SAC tenant. As a prerequisite to many of these integrations, the details of an OAuth Client are required. See the following example for integration with S/4, BW and SAP HANA for Data Export Service.

Leverage the SAP Analytics Cloud Data Export Servi... - SAP Community

API Client 

API Clients are useful tools to test and interact with API's in a user friendly way, examples of notable clients are Postman, Bruno or Insomnia. For the purpose of this article we will look at the authentication setup for Bruno.

As a prerequisite, ensure you have a collection to start. Create a new request, navigate to the Auth tab in the toolbar above.

Figure 8: API Client Auth TabFigure 8: API Client Auth Tab

Once inside the Auth tab, Select the OAuth 2.0 protocol from the dropdown list. 

Figure 9: OAuth 2.0Figure 9: OAuth 2.0

You will now see a list of fields to input to configure your authorization in Bruno for the client you created in SAC. The setup will be slightly different based on whether your client has the purpose API Access or Interactive Usage. 

ℹ️ In both of these scenarios I am using Bruno environment variables for my credentials but they can also be inputted manually.

API Access Setup 

If you setup your OAuth Client for API Access you were given the following details:

  • Client ID 
  • Client Secret
  • Token URL

You can proceed to fill the form in order to configure the Bruno client to fetch a token from your SAC tenant with your credentials.

Figure 10: Client Credentials OAuth 2.0 ConfigurationFigure 10: Client Credentials OAuth 2.0 Configuration

Interactive Usage

If you configured the OAuth Client with Purpose Interactive Usage, you should have the following details:

You can proceed to fill the form in order to configure the Bruno client to fetch a token from your SAC tenant with your credentials

Figure 11: Interactive Usage OAuth 2.0 ConfigurationFigure 11: Interactive Usage OAuth 2.0 Configuration

Fetching a Token

Once you have configured your Auth workflow in your API client you can proceed to click Get Access Token. For the Client Credential scenario the request should response with the bearer token in the response body 

Figure 12: Fetch Bearer TokenFigure 12: Fetch Bearer Token

In the case of the Interactive Usage Client, the SAC server will prompt the client to log in to SAC will will provide the user context to the token as previously mentioned. You should see a small login window appear in your chosen API client tool.

Figure 13: SAC Login DialogFigure 13: SAC Login Dialog

Once you have your Bearer Token, In can be copied and attached to all requests to the Data Export Service or Data Import Service. Once you have created the request in the API Client you can include the Bearer Token in the Auth tab of the request 

Figure 14: Attach Token to RequestFigure 14: Attach Token to Request

With the Bearer Token you will be Authenticated for all GET requests to the API, however in order to be authorized to perform CRUD (Create, Replace, Update, Delete) operations via the APIs, you will need a CSRF Token. 

 

Browser Authentication

Both the Data Export and Data Import APIs are available to use within the tenant via an SAC users identity. The API can be utilized via the browser for any valid GET request in either API. When you attempt to call the API via the URL bar in your browser you will be directed to login to SAC. 

Figure 15: SAC LoginFigure 15: SAC Login

Once you have successfully logged in your session can be used to authenticate you for any further requests via the browser, this is the same type of authentication as seen in the Interactive Usage configuration previously shown. 

Figure 16: Browser RequestFigure 16: Browser Request

 

Fetching a CSRF Token

CSRF Token (Cross-Site Request Forgery) is a user specific token which is granted to a client in order to manage a session and prevent malicious operations on SAC Artefacts. In order to perform any consequential operation via the API, the client must request a CSRF token. 

In terms of the Data Export API it is required to delete and create subscriptions, in the Data Import API it is essential  for posting data, creating import jobs or writing to tables. There are two methods available for fetching a CSRF token. 

Fetch via API GET Request (Preferred)

 Any valid GET request to the API can be used to request a CSRF token. For this example we will we use the  /models/<ModelID> endpoint from Data Import API to query some information about the job settings and import types for a model and to also request a CSRF Token. When we request a CSRF token from the API we need to ensure we have included the following request heade.

KeyValue
x-csrf-tokenfetch

You can include a request header by navigating to the Headers tab below the request URL and selecting + Add Header. 

Figure 17: CSRF Token HeadersFigure 17: CSRF Token HeadersWhen this header is included in your request, the API will return the same x-csrf-token header with its own unique value.

Figure 18: CSRF Token Response HeaderFigure 18: CSRF Token Response Header

CSRF Token Endpoint

There is also a dedicated endpoint available in SAC which can used to request a CSRF Token. The endpoint is as follows:

<tenant-url>/api/v1/csrf (GET)

The important thing to note when requesting a CSRF token this way is the following request headers must be included.

KeyValue
x-csrf-tokenfetch
x-sap-sac-custom-authtrue

Once you have included these two Request Headers, then the CSRF token should be included in the Response Headers.

Figure 19: CSRF Token EndpointFigure 19: CSRF Token Endpoint

 

 

Conclusion

As previously mentioned, the bearer token is required for all requests however it only provides at most the ability to read resources from the API. By now you should have acquired our CSRF token either via the dedicated tenanted endpoint or directly from the API via any valid GET request. 

You can now attach your x-csrf-token in order to be able to alter resources via the API. For example, we can create an Import job using Data Import API, Push Rows to Staging , Write to Artefacts and Delete Jobs. All of which require the x-csrf-token.

Figure 20: Attached CSRF TokenFigure 20: Attached CSRF Token

Now that you are successfully Authorized and Authenticated to use the Data Import and Data Export API's,  you can unlock the power of complete end-to-end management and extraction of your data and explore a variety of use cases and integrations within the SAC ecosystem and beyond. 

 

Useful Resources

api/v1/dataimport | SAP Help Portal

api/v1/dataexport | SAP Help Portal

Overview | Data Export Service | SAP Business Accelerator Hub

Overview | Data Import Service | SAP Business Accelerator Hub

Bruno API Client

OAuth - Wikipedia

 

1 Comment
brahmareddy_kolli
Participant
0 Kudos

Thank you for the detailed blog on APIs. We are currently trying to write back to SAP ECC. Could you please provide some insights on this? What is the process for writing back to SAP ECC from SAC MODEL?

If it is not possible to write back to SAP ECC, what alternatives are available besides Excel import and export?