Manage OAuth Clients

As an administrator, if you want to provide third-party access to protected SAP Analytics Cloud content, you must first set up secure delegated authentication using Open Authorization (OAuth) protocols. OAuth is an open standard that enables a trusted identity provider to authenticate users when information is passed between SAP Analytics Cloud and other systems without sharing actual credentials.

Prepare to Add OAuth Clients

SAP Analytics Cloud can be hosted either on SAP data centers or on non-SAP data centers (for example, Amazon Web Services (AWS)). Before you add OAuth Clients, you must determine which environment SAP Analytics Cloud is hosted on by inspecting your SAP Analytics Cloud URL:

  • A single-digit number, for example us1 or jp1, indicates an SAP data center.
  • A two-digit number, for example eu10 or us30, indicates a non-SAP data center.

Add a New OAuth Client (SAP Data Center)

Procedure

  1. From the side navigation, choose Start of the navigation path System Next navigation step  AdministrationEnd of the navigation path.
  2. Choose the App Integration tab.
  3. Under Configured Clients, select Add a New OAuth Client.
  4. In the dialog, add a Name for the OAuth client.
  5. From the list, select the intended use for your OAuth client:

    • Interactive Usage (default)

      Accessing protected SAP Analytics Cloud resources using an interactive usage OAuth client requires a valid SAML-based user context.

    • API Access

      An API access OAuth client allows a third-party application to access SAP Analytics Cloud public APIs without a SAML assertion. See the Authorize API Access for OAuth Clients section for more information about authorizing your application.

If you selected Interactive Usage, do the following:

  1. Under Authorization Grant, select the authorization method your clients will use to obtain an access token. There are two options available: Authorization Code or Client Credentials.

    Authorization Method Steps
    Authorization Code
    1. Provide an Authorization Code Lifetime. The lifetime is the duration that an authorization code will remain valid. Once this period is over, clients can no longer use the existing authorization code to obtain access tokens and refresh tokens. An administrator can set both the value and unit. Available time units include days, hours, and minutes.
      Note

      The lifetime value must be a positive integer. If this value is not provided, the lifetime value will be infinite by default.

    2. (Optional) Select Confidential. If selected, third-party applications must provide a secret value to obtain an OAuth access token to use with SAP Analytics Cloud. Enter a Secret value, and the Lifetime of the secret value. This is the duration that the secret remains valid. Once this period is over, an administrator must reset the secret value. This lifetime should be provided in days. For example, 30 days.

    3. Enter a Redirect URI. This is the URI where access or refresh tokens must be returned to.

    4. Enter the Token Lifetime.

      When the access token expires, clients must use a valid refresh token to obtain a new access token. An administrator can set both the value and unit. Available time units include days, hours, and minutes.The lifetime value must be a positive integer. If this value is not provided, the lifetime value will be infinite by default.

    5. Enter the Refresh Token Lifetime.

      An administrator can set both the value and unit of the refresh token lifetime. Available time units include days, hours, and minutes. The lifetime value must be a positive integer. If this value is not provided, the lifetime value will be infinite by default.
    Client Credentials

    1. Enter a Secret value, and the Lifetime of the secret value. This is the duration that the secret remains valid. Once this period is over, an administrator must reset the secret value. This lifetime should be provided in days. For example, 30 days.

    2. Enter the Token Lifetime.

      When the access token expires, clients must use a valid refresh token to obtain a new access token. An administrator can set both the value and unit. Available time units include days, hours, and minutes.The lifetime value must be a positive integer. If this value is not provided, the lifetime value will be infinite by default.
  2. Select Add.

If you selected API Access, do the following:

  1. Choose at least one option from the Access list:

    • Story Listing: This OAuth client privilege allows a third-party application to access a list of stories in your system.

    • User Provisioning: This OAuth client privilege allows a third-party application to manage users in your system.

  2. Enter a Secret value, and the Lifetime of the secret value.

    This is the duration that the secret remains valid. Once this period is over, an administrator must reset the secret value. This lifetime should be provided in days. For example, 30 days.

  3. Enter the Token Lifetime.

    When the access token expires, clients must use a valid refresh token to obtain a new access token. An administrator can set both the value and unit. Available time units include days, hours, and minutes.

    The lifetime value must be a positive integer. If this value is not provided, the lifetime value will be infinite by default.

  4. Select Add.

Add a New OAuth Client (Non-SAP Data Center)

  1. From the side navigation, choose Start of the navigation path System Next navigation step  AdministrationEnd of the navigation path.
  2. Choose the App Integration tab.
  3. Under Configured Clients, select Add a New OAuth Client.
  4. In the dialog, add a Name for the OAuth client.
  5. From the Purpose list, select the intended use for your OAuth client:
    • Interactive Usage (default)

      Accessing protected SAP Analytics Cloud resources using an interactive usage OAuth client requires a valid SAML-based user context.

    • API Access

      An API access OAuth client allows a third-party application to access public APIs without a SAML assertion. See the Authorize API Access for OAuth Clients section for more information about authorizing your application.

    • If you selected API Access, choose at least one option from the Access list:

      • Story Listing: This OAuth client privilege allows a third-party application to access a list of stories in your system.

      • User Provisioning: This OAuth client privilege allows a third-party application to manage users in your system.

  6. Enter a Redirect URI. The URI must be the exact URI where access or refresh tokens are returned too. If the URI has dynamic parameters, use a wildcard pattern for the URI. For example, https://redirect_host/**
  7. Select Add.
    Note

    The Token Lifetime and Refresh Token Lifetime cannot be configured.

  8. If you are using OAuth 2.0 you must provide the following information to your client application:
    • Authorization URL: The OAuth 2.0 Authorization URL.
    • Token URL: The OAuth 2.0 Token Service URL.
    • OAuth2SAML Token URL: The OAuth 2.0 Token Service URL to be used in the OAuth 2.0 SAML Bearer Assertion workflow.
    • OAuth2SAML Audience: The audience to be used by the OAuth 2.0 SAML Bearer Assertion workflow.

Authorize API Access for OAuth Clients

If you selected API Access as the Purpose for the OAuth client, follow these steps to authorize a third party application to use the public APIs without a SAML assertion:

  1. Perform a POST HTTPS call to the following address:

    <Token URL>?grant_type=client_credentials

    <Token URL> is the Token URL listed in the OAuth Clients section of the App Integration page.

  2. Use basic authentication, and set the OAuth client ID as the user and the secret as the password.

    This call returns an access token.

  3. Access the required public API endpoint with the following headers:

    Header name

    Value

    Notes

    Authorization

    Bearer <Token>

    <Token> is the access token returned by the previous step.

    x-sap-sac-custom-auth

    True

Add a Trusted Identity Provider

The OAuth 2.0 SAML Bearer Assertion workflow allows a third-party application access to protected SAP Analytics Cloud resources without prompting users to log into SAP Analytics Cloud when there is an existing SAML assertion from the third-party application identity provider. If you use the OAuth 2.0 SAML Bearer Assertion workflow, you must add a trusted identity provider to SAP Analytics Cloud. Both SAP Analytics Cloud and the third-party application must be configured with the same identity provider.

  1. From the side navigation, choose Start of the navigation path System Next navigation step  AdministrationEnd of the navigation path.

  2. Choose the App Integration tab.

  3. In Trusted Identity Providers, select Add a Trusted Identity Provider.

  4. In the dialog, add a unique Name for the trusted identity provider. This name is used only for identification purposes and will appear in the list of trusted identity providers.

  5. Add the identity provider name. For example, if a third-party application running on an SAP Business Technology Platform (BTP) system, this value is the local provider name of the BTP account. The Provider Name must meet the following criteria:

    • It must be unique.

    • It can contain only alphabet characters (a-z & A-Z), numbers (0-9), underscores (_), dots (.), and hyphens (-).

    • It cannot exceed 36 characters.

  6. Provide signing certificate information for the third-party application server. The signing certificate information must be in X.509 Base64 encoded format.

  7. Select Add.

  8. The identity providers that you added will appear in lists on the App Integration page. Hover over an identity provider and select Edit to update information or Delete to delete it. You may need to use the Authorization URL and Token URL listed here to complete setup on your OAuth clients.