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 Homepage
From the side navigation, Choose App Integration tab.
Figure 2: Administration
Under Configure Clients, copy the Token URL. It will be needed later in this procedure.
Figure 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 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:
Figure 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:
Figure 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 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 Tab
Once inside the Auth tab, Select the OAuth 2.0 protocol from the dropdown list.
Figure 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:
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 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 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 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 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 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 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 Request
Fetching a CSRF Token
A 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.
Key | Value |
x-csrf-token | fetch |
You can include a request header by navigating to the Headers tab below the request URL and selecting + Add Header.
Figure 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 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.
Key | Value |
x-csrf-token | fetch |
x-sap-sac-custom-auth | true |
Once you have included these two Request Headers, then the CSRF token should be included in the Response Headers.
Figure 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 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
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
User | Count |
---|---|
8 | |
6 | |
6 | |
5 | |
4 | |
4 | |
4 | |
4 | |
4 | |
4 |