Skip to content

Configuring and Testing Access Control in a Cloud Foundry Environment

This procedure allows you to verify that the client has permission to access a mobile services application in Cloud Foundry.

The basic steps for configuring the application environment and run a test case, consisting of the following tasks:

  1. In the SAP mobile service cockpit, set up Access Control for the application.

  2. In the SAP Business Technology Platform cockpit, set up Role Collections and map to IDP groups.

  3. Set up the user and related groups in IDP, then log in to SAP Mobile Services to get the Access Token.

  4. Send a request to the application to test that the access rule is satisfied via the 200 OK or 403 Forbidden responses.

The step-by-step procedure for configuring and testing the application environment:

  1. In the SAP mobile service cockpit, set up Access Control for the application:

    1. Log in to the SAP mobile service cockpit.

    2. Select an existing application or create a new one.

    3. On the Security tab, you can set up the Access Control properties, including Application Versioning and Role Settings.

    4. Click Edit in Application Versioning to enable Application Versioning. When Versioning is enabled, you need to add one or more Application Versioning items (v1.0 and V1.1, for example, where v1.1 is the active version) and click Save to save the configuration.

    5. Click Edit in Role Settings to enable role settings and add roles. Add role1, role2, role3, etc.

  2. In the SAP Business Technology Platform cockpit, set up the Role Collections and map to IDP groups:

    1. From the Security menu in the target tenant setting page, select Role Collections, and click New Role Collection to create a new Role Collection for the application.

    2. Fill in the required fields, including a role collection name (i.e. role_collection_app1), and click Save. The Role Collection is created.

    3. Click the link for the Role Collection name to open the Role Collections page. To add a role, click Add Role.

    4. In the Add Role dialog, select the Application Identifier (the XSUAA client ID listed on the Application Detail page.
    5. For Role Template, select role1.
    6. For Role, enter role1 and click Save.
    7. Repeat the previous three steps for role2 and role3.
    8. Return to the Security menu and choose Trust Configuration to set up mapping between the Role Collection and the Group in IDP configuration.
    9. Click the link in the Name column (xsuaa-monitoring-idp, for example).
    10. Click Role Collection Mappings to set up the mappings.
    11. Click Edit to create a new Role Collection Mapping.
    12. Choose the name of the Role Collection you created (role_collection_app1, for example) and enter the group name in the value field (group1, for example). The group name must already exist in the IDP settings.
    13. Click Save.
  3. Set up the user and related groups in IDP, then log in to mobile services to get the Access Token:

    1. Use a utility such as SoapUI to verify Access Control checking. Firstly, send a specific request to the Mock IDP xsuaa-monitoring-idp to generate a specific Access Token. Set username to testuser and group to group1. Also set the related URLs and Client ID.

    2. Generate the Access Token.

      The Access Token is generated and it includes role1, role2, and role3.

    3. Change the group to group2 and generate a new Access Token.

      The Access Token is generated and it does not include role1, role2, and role3.

  4. Send a request to the application to test that the access rule is satisfied via the 200 OK or 403 Forbidden responses:

    1. On the Native/MDK page, disable the Application Versioning check and leave the Role Settings check enabled.

    2. Send a request to the application using the Access Token that includes any of role1, role2, and role3.

      The response code is 201 OK, indicating that the request passed the Access Control check and the app can be onboarded successfully.

    3. Send a request to the application using the Access Token that does not include any of role1, role2, and role3.

      The response code is 403 Forbidden, indicating that the request was rejected by the Access Control check.

    4. On the Native/MDK page, enable the Application Versioning check and disable the Role Settings check.

    5. Set the header X-APP-VERSION value to a valid Application Version (i.e. the active version of the app, v1.1) and send the request

      The response code is 200 OK, indicating that the request passed the Access Control check.

    6. Set the header X-APP-VERSION value to an invalid Application Version (i.e. the inactive version of the app, v1.0) and send the request.

      The response code is 403 Forbidden, indicating that the request was rejected by the Access Control check.

    7. On the Native/MDK page, disable both the Application Versioning check and the Role Settings check.

    8. Send a request without any roles, and also with an invalid Application Version (i.e. the inactive version of the app, v1.0), and send the request to the application.

      The response code is 200 OK, indicating that no version or role check was performed and the request passed the Access Control check.

Configuring App Security

Configure security at the application level for the Cloud Foundry environment.

When you define a new application in the Cloud Foundry environment, an OAuth client is created automatically by the server. A non-null default value is set for client ID and the redirect URL once the application is created.

If you select OAuth or SAML for app security authentication, API Key is not enabled. If API Key is configured as part of SDK bootstrapping, services such as setting exchange, log upload, and usage upload are accessed before mobile services authentication.

If you select API Key Only for app security authentication, and enable API Key, anonymous access is used. This is similar to the "No authorization" option that is available in the Neo landscape. This combination also provides access to client resources. If you select API Key Only, you must enable API Key. The x-smp-deviceid header is mandatory when using API Key. You can use an arbitrary value for the device ID when testing using Postman.

To increase application security, you can provide a specific list or a range of Allowed IP/CIDR addresses and notations. Requests for the allowed list are performed; requests for addresses or notations that are not specified are ignored. If no entries are provided, there is no restriction, and requests are performed for all addresses.

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK.

  2. Select an application, and Security. View the current security settings, or select the edit icon to make changes.

  3. (Optional) Lock the application so others can't make changes to the same application.

  4. Under Application Settings, view or edit settings.

    1. (Web applications only) Select CSRF Protection to enable cross-site request forgery protection. When this option is selected, all services, such as registration, are protected with CSRF tokens. Proxied endpoints aren't protected, since they are likely to be protected on the back end.

    2. For Security Configuration, select a security option:

      • API Key Only ‒ uses an API key for authentication. The key is generated or you can select additional keys in a later step. No other authentication method can be used with this choice.

      • Basic ‒ enables stand-alone basic authentication either with or without SAP Cloud Connector. You must download and import a Trust Configuration into your cloud sub-account as described in Configuring Trust for Basic Authentication.

      • Basic with SAP Identity and Authentication Service ‒ authentication delegates to the SAP Identity and Authentication Service. If your SAP Business Technology Platform account uses a different identity provider, this choice fails.

      • HTTP ‒ enables you to use HTTP to call an OAuth endpoint and pass a client token to the back end for authentication. This is similar to the HTTP module available in SAP Mobile Platform, and is especially useful when migrating applications from SAP Mobile Platform to mobile services.

      • OAuth ‒ an open protocol for securely authorizing applications using a standard method. SAP Business Technology Platform must be the authorization server. This is the default option, and the OAuth client is generated automatically. You can use API keys with this choice.

        The Proof Key for Code Exchange (PKCE) extension, by OAuth Public Clients, is supported for Authorization Code Grant when using OAuth authentication type. The app must implement the OAuth APIs used by the SDK.

      • SAML ‒ uses SAML 2.0 supplied by SAP Business Technology Platform (the SAP Identity and Authentication Service authenticates users against both SAP user accounts and SAP Community Network (SCN) accounts). You can use API keys with this choice.

    3. If you select OAuth (the default), for OAuth Clients select the edit icon to make changes, and click the add icon to add an OAuth client.

      OAuth Client Settings

      Field Description
      Client ID To regenerate the client ID, select an ID and then Regenerate. The ID is automatically generated, and identifies the application client to the authorization server.
      Redirect URL The redirect URL for the OAuth client.

      Under OAuth APIs you can view and copy the URLs for OAuth Authorization and OAuth Token.

      Under Cross Context SSO, you can enable identity transfer for SSO. See Configuring Cross Context SSO for information about setting up identity transfer for use in application onboarding.

      Cross Context SSO Settings

      Field Description
      Enable Cross Context SSO Select this option to enable cross context SSO. Additional fields appear.
      SSO Token Timeout How long before the temporary login token expires in seconds. The default is 30 seconds.
      SSO Onboarding URL (Read/copy only) The onboarding URL.
      SSO Onboarding URL for Android Widget Support (Read/copy only) The onboarding URL that supports the Android Widget when it is enabled. You can make this link available to users.

      Under QR Code Signature Settings, you can enable use of digital QR code signatures for onboarding. See Configuring Digitally-Signed QR Codes for information about setting up QR code signature settings for onboarding users.

      QR Code Signature Settings

      Field Description
      Public Key The public key is used on the client side to verify the digital signature.
      Private Key The private key is used on the server side to sign the QR Code, and is not exposed to any client.
    4. If you select Basic with SAP Identity and Authentication Service, Basic, or SAML instead of OAuth, you are notified that the change affects the application availability for the device user, and that an application restart is required to update the application’s configuration. Select OK.

      If you select Basic, provide the Basic Settings, and select OK. The Mobile Connectivity feature is assigned automatically to the application to provide a proxy service, and cannot be removed (navigate to the Info tab to verify that Mobile Connectivity appears under Assigned Features).

      Basic Settings

      Field Description
      URL The URL to use for basic authentication. The URL entered here must return a 401 (Unauthorized) response message when random username and password are sent as Authorization: Basic header according to RFC 2617 (as described in: https://tools.ietf.org/html/rfc2617).
      Use SAP Cloud Connector Enables you to use SAP Cloud Connector.
      SAP Cloud Connector Location ID Your SAP Cloud Connector identifier.
    5. If you select HTTP, configure the HTTP settings, and then select OK to save and confirm. Once HTTP security is configured for a mobile application, the client must provide a Bearer Authorization header in the request. Mobile Services sends the Bearer Authorization header value to the configured server URL to validate the Bearer token value. Once the token is validated by the server, the user name is retrieved from the response, using the configured "Response Header for User Name Extraction" header name.

      Field Description
      URL Enter the server URL. You can find this on the APIs tab of the selected application.
      Response Header for User Name Extraction The response header to use to provide the user name for authentication, such as (authHeaderValue).
      Use Cloud Connector Enables you to use cloud connector.
      Cloud Connector Location ID Your cloud connector location ID.
  5. Under XSUAA Settings, view or edit extended services for UAA (XSUAA) settings. See Demystifying XSUAA in SAP Cloud Foundry for additional information.

    If the XSUAA Settings section does not appear, either the feature is not supported for your configuration or the IAS Settings option was selected instead. If the edit button does not appear, then values are read-only.

    XSUAA Settings

    Field Description
    XSUAA Service Select Default Instance or an existing service instance from the list. Using an existing XSUAA service instance is useful if you already have a Cloud Foundry application deployed and want to connect to this application from mobile services. Select the default instance for other scenarios. Note that if you select the default, you can select OAuth Settings.
    xs-security.json Select the JSON file that defines the authentication methods and authorization types used to access to your application. See Application Security Descriptor Configuration Syntax for additional information.
    Token Lifetime Enter the lifetime for a token in number of days, hours, or minutes (12 hours is the default). The entry is subject to any limitations imposed by the server. If user credentials are changed or the user account is disabled, the OAuth tokens are automatically revoked, and the user is not able to access mobile application content.
    Refresh Token Lifetime Enter the lifetime for a refresh token in number of days, hours, or minutes (30 days is the default). The entry is subject to any limitations imposed by the server.
    Approved Providers Indicate the approved identity providers for the application:
    • All (default) ‒ all identity providers are approved for the app.
    • Selected Providers ‒ enter one or more approved identity providers for the app (hit Enter after each entry).

    Note: Since SAP mobile service cockpit cannot validate the identity provider entries, it is very important to enter them correctly. Otherwise, users will not be able to log in successfully.

    The Selected Providers option enables you to be specific about the identity providers for the app, especially if you have multiple providers configured for the sub-account. For example, say you have two identity providers configured for the sub-account ‒ sap.default (origin of default identity provider SAP ID Service) and hanamobile_sci. Assume you have two mobile applications, and one application needs to be protected by the SAP ID Service, and another one by hanamobile_sci. You can configure sap.default as the approved provider for the first application, and hanamobile_sci for second application.

    System Attributes in Token The system-attributes property controls which properties should be included in the JWT token generated by an XSUAA service instance. Its purpose is to decrease the size of JWT by excluding some properties, especially when many groups have been assigned to a user in IDP. You can configure system-attributes for a mobile applications XSUAA service instance using: Rolecollections (default for new applications), or Groups.

    For legacy applications (those that were created before the introduction of this feature, and do not have this property set), the value of system-attributes might be:

    • If system-attributes was set in xs-security.json, retrieve the property value and use it as the system-attributes value.
    • If not, use the Groups or Rolecollections value as the system-attributes value.
    • This option is only available for OAuth. To learn more, see Application Security Descriptor Configuration Syntax.

  6. Under IAS Settings, view or edit Identity Authentication service (also called Authentication) settings.

    See Configuring IAS Settings for information about setting up Authentication integration support.

  7. (Does not appear if IAS Settings is selected) Under Role Settings, view or edit settings. In Edit Role Settings, select Enable Role Settings to use roles.

    Once enabled, you can specify one or more roles, such as Admin or Developer, and click OK. If you make any changes, you must restart the application.

  8. Under Application Versioning, select Enable Application Versioning to manage versions for this application. Once enabled, you can view and edit versions.

    1. Click the add icon to add a version.

    2. Modify the application version settings:

      Version Settings

      Field Description
      Version Application version
      Active Whether the application version is active or available for use
      Description Application version description
      Actions Actions you can perform, such as edit or delete
    3. Click OK to save, or Cancel. If you make any changes, you must restart the application.

  9. Under API Key, if you selected OAuth, SAML, or API Key Only as the Security Configuration, you can view or edit API keys. If you selected API Key Only, an API key is created using the current date and time. You must have at least one API key or you receive a warning. Select add to add or delete keys.

    Under Anonymous Access, view or edit settings. In Anonymous Access, select Allow Anonymous Access to enable the client-side applications to use API keys as credentials.

    1. To edit, click the add icon to add an API key.

    2. Add one or more valid API keys for the application.

      API Key Settings

      Field Description
      API Key When implemented, at least one API key is required.
      Creation Date The server generates the creation date once the API key is created.
      Actions Select delete to delete an API Key.
    3. Click OK to save, or Cancel. The API keys and their creation dates appear. If you make any changes, you must restart the application.

  10. Under Allowed IP/CIDR, view the list of allowed Internet Protocol/Classless Inter-Domain Routing (IP/CIDR) addresses, or ranges of addresses. Any request that includes one of these addresses will be performed; requests for addresses that are not in the list will be ignored. You can add, change, and delete entries.

    To make entries:

    1. Select the edit icon.

    2. In Edit Allowed IP/CIDR, select the add icon, and then enter an address or range of addresses, for example:

      • 10.0.0.3

      • 10.100.0.1/32

      • 2a0f:ed40::/29

    3. To delete an entry, select X.

    4. To modify an entry, make changes to a current entry.

    5. Select OK to save changes, and confirm. The change appears in the list.

  11. Under Cross Domain Access, view the list of cross-domain access entries. These entries enable application users to access additional security domains based on the values you provide. You can add, change, and delete entries. See also, Cross-Origin Resource Sharing Requests.

To make entries:

  1. Select the create icon to add an entry.

  2. In Create Cross Domain Access, enter the values.

    Cross Domain Access Properties

    Properties Descriptions
    URI Pattern A string of characters that matches the destination.
    Origin A comma-delimited list of URIs that can access the resource, for example, http://example.com or http://*.example.com. The default value * means any URI can access the resource. An empty value prevents cross-origin resource sharing; only URIs in the same origin can access the resource.
    Methods A comma-delimited list of HTTP methods (such as GET and DELETE) that are allowed when accessing the resource.
    Max Age The number of seconds for which the results of a request can be cached. The default is 3600 seconds (60 minutes).
    Allow Credential Always set to On. The server includes cookies when it submits requests.
    Headers A comma-delimited list of HTTP request headers that you can specify in requests. Note that an empty value means any requested headers are accepted. The following headers are usually used in requesting mobile services: accept, authorization, maxdataserviceversion, x-smp-appcid and x-smp-appid.
    Expose Headers A comma-delimited list of response headers that browsers can access.
  3. Select Save. The new entry appears in the list.

  4. If you locked the application while making changes, select Unlock to release it.

Configuring Micro App Security

Define the settings that control user authentication behavior for the selected Micro App.

  1. In the SAP mobile service cockpit cockpit, select Mobile Applications > Micro App.

  2. Select an application, then select Security to configure application security.

  3. Under Application Settings, select edit . Configure application-level security settings:

    Application Settings

    Field Value
    CSRF Protection Enables Cross-Site Request Forgery (CSRF) protection. Requires a CSRF token to work.
    Security Configuration (1) WeCom OAuth – WeCom-specific token-based authentication. Selected automatically for WeCom apps; (2) WeChat OAuth – WeChat-specific token-based authentication. Selected automatically for WeChat apps; (3) DingTalk OAuth – DingTalk specific token-based authentication. Selected automatically for DingTalk apps.
  4. Under WeCom Settings, view the current security settings.

  5. Under WeChat Settings, view the current security settings.

  6. Under DingTalk Settings, view the current security settings.

  7. For other security settings, such as XSUAA Settings, Role Settings, Anonymous Access, Allowed IP/CIDR, Cross Domain Access, see Configuring App Security for details.

Configuring Trust For Basic Authentication

Configure trust at the space level between mobile services and your SAP Business Technology Platform sub-account in the Cloud Foundry environment. This is required for applications using Basic authentication or API Key authentication, or multi-user/device sharing scenarios, or for Micro App applications in supported regions.

Default and custom trust configuration must already be established in SAP Business Technology Platform cockpit. For information about establishing trust, see Establish Trust and Federation with UAA Using Any SAML Identity Provider.

Importing trust configuration metadata into your cloud sub-account enables mobile services to generate user authentication tokens for users that are identified as using Basic Authentication or API key authentication, or tokens for multi-user, or Micro App applications. Importing the trust configuration only needs to be done once.

Note

If all configured applications only use OAuth or SAML authentication, this step is not required.

  1. In SAP mobile service cockpit, select Settings > Security.

  2. Select Metadata Download to download the trust configuration from SAP Business Technology Platform into your cloud sub-account (SAMLMetadata.xml). This only needs to be done once.

In Download Metadata, specify the metadata expiration date, and then select Download. You can select one year (default), or use the date picker to select the month and year.

If you do not see the Metadata Download button, this means that no standalone proxy service instance exists. SAMLMetadata.xml has been imported into the sub-account, or does not effect the Trust test result.

  1. From SAP Business Technology Platform, import the downloaded trust configuration file from the previous step, as a trusted identity provider, using your customer sub-account.

    Note

    When importing the Identity Provider in SAP Business Technology Platform, disable the “Available for User Login” checkbox, because the trusted Identity Provider is not a real identity provider and cannot be used for user login. Disabling the “Available for User Login” checkbox ensures the identity provider does not appear on the XSUAA login page.

  2. Select Test to make sure the metadata has been established successfully as a trusted provider.

    If the trust configuration is not established correctly, you may see a message like SAML metadata might not have been imported as trusted identity provider.

Configuring Cross Context SSO

Configure cross context SSO so that identity is transferred from a web app to a mobile app during onboarding. Depending on how the feature is implemented, this enables a user to login and configure an app either from the desktop or an Android or iOS mobile phone.

Keep in mind:

  • Onboarding SSO must be set for the app via the SAP BTP SDK for Android or SAP BTP SDK for iOS.

  • SAP Business Technology Platform must be used as the authorization server.

  • The app security configuration must be set to OAuth via SAP mobile service cockpit, as described in Configuring App Security.

  • The feature is supported for Android and iOS apps.

  • If users will onboard from an Android mobile phone by clicking a button, you must configure Android Application Links in SAP mobile service cockpit, as described in Creating Application Links.

  • The user experience for onboarding from an iOS device, when clicking a button, will depend on whether Apple Universal Links or custom URL scheme is configured for your app. If both are configured for your app then custom URL scheme is used to provide better user experience.

    Apple Universal Links have the effect that the app does not open automatically when a user browses a website in Safari and taps a universal link in the same domain. Instead, iOS opens the link in Safari, expecting the user to continue within the browser, and the user must actively tap the banner to open the app.

    Custom URL link avoids this extra step, which provides a better user experience. However, if custom URL schemes are not maintained by an administrator, then the Apple Universal Link technique is used. Both the custom URL scheme and Apple Universal Links can be configured in SAP mobile service cockpit through the Application Links tab, as described in Creating Application Links.

If cross context SSO is set via the SDK and configured through SAP mobile service cockpit, users can onboard in these ways:

  • From the desktop: The user opens the onboarding page in a browser, and scans a QR code using the phone's camera. The QR code provides information that can be interpreted by the SAP mobile app.

  • From an Android phone: The user opens the onboarding page using a Chrome browser, which is only supported browser. The page includes a button to click to start the onboard process. When the user selects the button, the Android mobile phone calls the SAP app.

  • From an iOS phone: The user opens the onboarding page using a Safari browser, which is the only supported browser. The page includes a button to click to start the onboard process. When the user selects the button, the iOS mobile phone calls the SAP app.

In all cases, a short-term token is used to pass authentication to the app. If the token times out, the user is offered additional chances to onboard using a new short-term token each time.

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK.

  2. Select an application, and Security. View the current security settings, or select the edit button to make changes.

  3. Under Application Settings, view or edit settings. Select the edit button to configure application settings. The Edit Application Settings window appears.

    1. Under Cross Context SSO, select Enable Cross Context SSO. Additional fields appear.

    2. Configure cross-context SSO settings.

      Field Description
      SSO Token Timeout Specifies how long before the temporary login token expires in seconds. The maximum is 300 seconds, and the default is 30 seconds.
      SSO Onboarding URL (Read/copy only) The onboarding URL. You can make this link available to users.
      SSO Onboarding URL for Android Widget Support (Read/copy only) The onboarding URL that supports the Android Widget when it is enabled. You can make this link available to users.
    3. Click OK to save changes.

When users click on the onboarding URL or scan the QR code, they are onboarded. If the security code expires before the user can be onboarded, the user is offered the chance to Get New Code.

Configuring IAS Security

When a mobile application is created with Identity Authentication service (IAS) support, a service instance for the SAP Business Technology Platform Identity Authentication is created and bound to the mobile application.

Identity Authentication is available to subaccount spaces, only if trust and federation has been established between the SAP Business Technology Platform subaccount and the Identity Authentication tenant. For more information, see:

1
2
3
* [Establish Trust and Federation Between UAA and Identity Authentication](https://help.sap.com/docs/CP_AUTHORIZ_TRUST_MNG/ae8e8427ecdf407790d96dad93b5f723/161f8f0cfac64c4fa2d973bc5f08a894.html)

* [Getting Started with the Identity Service of SAP BTP](https://help.sap.com/docs/IDENTITY_AUTHENTICATION/6d6d63354d1242d185ab4830fc04feb1/066bda825cb148629aa1934b770eb4ed.html).

If trust and federation has not been established between the Identity Authentication tenant and the SAP Business Technology Platform subaccount, only mobile applications using XSUAA can be created in subaccount spaces.

When creating or updating IAS-based mobile applications on SAP mobile service cockpit, you can upload a customized security configuration to use as the default Identity Authentication service instance. For configuration syntax see Reference Information for the Identity Service of SAP BTP.

Mobile Services supports protecting mobile applications with your SAP Cloud Identity Services - Identity Authentication tenant using Open ID Connect (OIDC). When a mobile application is created with IAS support, a service instance for the SAP Identity Service is created and bound to the mobile application. This redirects mobile application users to the IAS tenant upon login, and generates an IAS token from the IAS tenant after login completes. Mobile clients also use IAS tokens to access the mobile application, and use the IAS token to propagate the user to the back-end server.

The IAS token is an identification token, and does not include authorization information (scopes or roles). SAP Mobile Services supports using the "groups" property to grant authorization to users. SAP Mobile Services treats those groups that start with "SAPMS_" as roles, and the role names are the values that remain when the "SAPMS_" prefix is removed.

For example, a user might create an "SAPMS_Administrator" group in IAS tenant, and assign users to the group. These users are granted access to APIs that require the "Administrator" role in Mobile Services. Mobile Services supports the "Administrator" and "Helpdesk" roles that enable runtime users to access the single-application cockpit. The "Administrator" role is a read-write role, and "Helpdesk" is a read-only role.

Note that since the Identity Authentication service does not support revoking user tokens, the revoke user token action is not supported for IAS-based mobile applications.

To configure IAS security for an app:

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK.

  2. Select an application, and Security. View the current security settings, or select the edit button to make changes to a section.

  3. Under IAS Settings, view or edit settings. Select the edit button to configure settings. The Edit IAS Settings window appears.

    For information about IAS Service Token Settings, see Token Policy Configuration for Applications.

    IAS Settings

    Field Value
    IAS Service Select Default Instance or an existing service instance from the list.
    Security-config.json Select the JSON file that defines the authentication methods and authorization types used to access your application. See Reference Information for the Identity Service of SAP BTP for additional information.
    Token Lifetime Enter the lifetime for a token in number of hours, or minutes (15 minutes is the default). Values include 10 minutes through 1 hour. The entry is subject to any limitations imposed by the server.
    Refresh Token Lifetime Enter the lifetime for a refresh token in number of days, hours, or minutes (30 days is the default). Values include 1 hour through 180 days. The entry is subject to any limitations imposed by the server.
  4. Click OK to save changes.

Configuring Digitally-Signed QR Codes

Configure a digitally-signed QR code that enables users to scan a QR code and onboard securely to a mobile services application. The digitally-signed QR code helps prevent a malicious person from gaining access. An administrator configures the public and private key pair used to sign the QR code in JSON Web Signature (JWS) format. Use Mobile Services to generate the keys, or add your own keys. This feature requires the OAuth security configuration.

When the signature feature is enabled:

  • The QR code on the Mobile Application > Native/MDK > {app_name} > APIs tab is signed, including Configuration, Application Link, generic URI scheme, and MDK URI scheme.

  • The Cross Context SSO on Mobile Application > Native/MDK > {app_name} > Security tab is also signed.

To configure digitally-signed QR codes for OAuth onboarding:

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK.

  2. Select an application, and Security. View the current security settings, or select the edit button to make changes.

  3. Under Application Settings, verify that the security configuration type is OAuth.

  4. Scroll down to QR Code Signature Settings, and select Enable QR Code Signature. Additional fields appear.

    Configure QR code signature settings.

    Field Description
    Public Key The public key is used on the client side to verify the digital signature.
    Private Key The private key is used on the server side to sign the QR Code, and is not exposed to any client.

    You have two ways to manage the key pair: one way is to click Generate Key Pair to generate a new key pair; another way is to copy and paste your own public key, and upload a private key. Keep in mind:

    • The key pair algorithm only supports RSA and EC (Elliptic Curve).

      • For the RSA algorithm, supported bits lengths are 2048, 3072, 4096.

      • For the EC algorithm, supported bits lengths are 256, 384, 521.

    • Only the PEM-Encoded PKCS#8 unencrypted key format is supported:

      • Public Key should start with -----BEGIN PUBLIC KEY----- and end with -----END PUBLIC KEY-----.

      • Private Key should start with -----BEGIN PRIVATE KEY----- and end with -----END PRIVATE KEY-----.

    • When you use the Generate Key Pair button, an RSA key pair is generated with a 3072 bits length.

    • The Public key and Private key should appear and update in pairs.

    • When Enabled QR Code Signature is not enabled, Public Key and Private Key values are stored (and not deleted), but they do not appear and are not used in onboarding until they are again enabled.

    • You can generate your own key pairs using a third-party tool such as OpenSSL. Examples:

      • Generate an RSA key pair with OpenSSL tool:

        openssl genrsa -out privkey.pem 4096
        openssl rsa -in privkey.pem -pubout -out public.pub
        openssl pkcs8 -topk8 -inform pem -in privkey.pem -outform pem -nocrypt -out private_pkcs8.pem
        
      • Generate an EC key pair with OpenSSL tool:

        openssl ecparam -genkey -name secp521r1 -noout -out ec512-key-pair.pem
        openssl ec -in ec512-key-pair.pem -pubout -out public.pem
        openssl pkcs8 -topk8 -inform pem -in ec512-key-pair.pem -outform pem -nocrypt -out ec512-key-pair_private_pkcs8.pem
        
  5. In QR Code Signature Settings, click Generate Key Pair to generate a new key pair. The Public Key and Private Key fields are populated with the keys. (Alternatively you can copy and paste your own public key, and upload a private key.)

  6. In Secret, provide at least eight characters of Secret to generate an encrypted private key. The public key changes, and the private key is downloaded from the server.

    Be sure to save the private key in a secure location and remember the secret in case you need to redeploy the app. You can also upload a private key, and are prompted to supply the Secret if the private key is encrypted.

  7. Select Save and OK to confirm. The encrypted private key appears as ********.

    The public and private keys are saved to the SAP Mobile Services server, and are available to iOS or Android clients to verify access during onboarding. When users click on the onboarding URL or scan the QR code, they are onboarded using the keys.

    Once you input or generate a new key pair, you must not change it. The key pair has been saved to the device application configuration, and changing it would affect the device application.

Defining Client Password Policy

Define the client password policy used to unlock the secure store, for the selected application. Application developers must add code to enforce the policy to the secure store used by the application. An administrator enters the application password policy used to unlock the secure store during application initialization.

The client password policy applies only to the application password that unlocks the secure store during application initialization; it affects neither SAP Mobile Services security profiles nor the back-end security systems with which it integrates. Password policies for back-end security systems are administered by customer information technology departments using native security administration tools.

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK or SAP Mobile Cards.

  2. Select an application, then select Mobile Settings Exchange under Assigned Features.

  3. On Client Configuration, under Passcode Policy, select Enable Passcode Policy, and enter:

    Property Default Description
    Expiration Time Frame Days 0 The number of days a password remains valid. The default value, 0, means the password never expires.
    Minimum Length 8 The minimum password length.
    Retry Limit 20 The number of retries allowed when entering an incorrect password. After this number of retries, the client is locked out, the secure store and all its contents are permanently deleted, the application is unusable, and encrypted application data is inaccessible.
    Minimum Unique Characters 0 The minimum number of unique characters required in the password.
    Lock Timeout 0 The number of seconds the secure store remains unlocked within an application, before the user must reenter his or her default password to continue using the application (similar to a screen-saver feature).
    No Passcode Required Disabled If enabled, a default password can be generated by the secure store; from the user's point of view, this turns off the password.
    Biometric Authentication Allowed Disabled If enabled, it allows the use of native biometric techniques to unlock the app.
    Upper Case Character Required Disabled If enabled, the password must include uppercase letters.
    Lower Case Character Required Disabled If enabled, the password must include lowercase letters.
    Special Character Required Disabled If enabled, the password must include special characters.
    Digits Required Disabled If enabled, the password must include digits.
  4. Select Save.

Defining Lock and Wipe Policy

Define the policy for locking and wiping the application running on a device.

The app must include SDK logic to support locking and wiping policies. For example, the developer may implement locking and/or wiping for when a device is lost or stolen, or a user wants to delete data stored locally.

From SAP mobile service cockpit, the administrator can create locking and wiping policies for the app:

  • Locking refers to locking the app on the device client. Once the app is locked, the user can unlock it by connecting to the server and authenticating. All existing data (in particular the offline OData store) remains on the device. You can set the number of days before locking occurs.

  • Wiping refers to resetting the application on the device. This deletes existing data on the device. You can set the number of days before wiping occurs.

The server informs the app when the policy takes effect, and the application responds according to its SDK programming.

Note

The locking policy is not the same as the blocking policy, which prevents the application user from registering the application or receiving traffic. See Managing Apps.

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK or SAP Mobile Cards.

  2. Select an application, then select Mobile Settings Exchange under Assigned Features.

  3. Select Client Configuration.Under Locking and Wiping Policy, select Enable Locking and Wiping Policy.

  4. Configure the locking and wiping features.

    Locking and Wiping Policy

    Policy Description
    Offline Days Before Locking Set the number of days before the application will be locked on the user device. If locked, the user must reconnect to the server and authenticate.
    Offline Days Before Wiping Set the number of days before the application is reset on the user device. If wiped, the application remains, but the data is deleted.
  5. Select Save.

Revoking OAuth Tokens

Revoke an OAuth token to force a registered user to login using a new OAuth token.

An administrator can revoke an OAuth token for a registered user. This action revokes all OAuth tokens that were issued for the user before the time of revocation. When the user logs in again, a new OAuth token is generated, ensuring that the most current OAuth token is used.

If the Revoke button does not appear, the feature is not supported for the configuration.

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK or SAP Mobile Cards.

  2. Select an application, then select Mobile Settings Exchange under Assigned Features.

  3. (Optional) Under Registered Users, you can narrow the focus of the registered users to view by setting filters, such as User Name, Registration Time Frame, Device Type or Email Address; and selecting Go. Select Reset Filter to clear your filter entries.

    The filtered list of registered users appears. You can also use Sort and Customize Table Columns to further change the list.

  4. Find your target registration user, and under Actions, select Revoke.

    In Confirm Revoke, select OK to confirm that all OAuth tokens registered to the user will be revoked.

  5. Check the date and time stamp under Last Revocation (UTC+0000) to confirm the change.

    The date and time stamp is updated when you click the Revoke button, and when the user logs out from a device. When the user logs out from a device, all tokens under the same user name are revoked.

When the registered user logs in to the app, a new OAuth token is generated.

Configuring Android Attestation

(Native/MDK only) Device attestation enables developers and administrators to learn about the software and hardware environment of devices that are trying to connect to enterprise apps and work spaces.

Keep in mind these important prerequisites:

  • Ensure that the correct version of Google Play services is installed on the user's device.

  • Make sure customers can access Google server.

  • Obtain a Google API Key. This key is needed in order to call the SafetyNet Attestation API. To create an API key, see Obtain an API Key.

  • Obtain SHA-256 Certificate Fingerprints. This value is used to validate whether client requests come from the app signing with the expected keystore. To obtain SHA-256 Certificate Fingerprints, use the keytool utility provided by Java via the command line: keytool -list -v -alias <key-alias> -keystore <keystore-path>.

    You are prompted to enter the keystore password. From the output, copy the “SHA256” value under “Certificate fingerprints” (it is a 64-byte hex string). You can add multiple SHA-256 Certificate Fingerprints if needed.

The attestation feature is only available for SAP BTP SDK for Android 5.1 and above. It is not available for SAP Mobile Platform SDK, and not yet available for SAP BTP SDK for iOS. Once attestation is enforced, any requests from an app built via an unsupported SDK, like SAP BTP SDK for iOS or SAP Mobile Platform SDK, are rejected.

Caution

Please turn on enforcement with caution. If your Mobile Services application is not solely used for the app developed by BTP SDK for Android 5.1 and above, we recommend you deploy a separate mobile service application for enabling Android attestation.

With device attestation integrated with mobile services, you can safeguard your server API by examining the device's software and hardware environment at runtime, determining whether your server is communicating with a genuine app and deice, then deciding whether to accept or reject the client's requests. Administrators can monitor non-compliant Android devices / apps, and enforce compliant runtime checking.

The Android attestation implementation is based on the SafetyNet Attestation API. Each time the client calls the SafetyNet Attestation API, usage quota is consumed. The default quota per project is 10,000 times per day. You are alerted if you exceed your quota. To monitor the quota usage, see: Set Up Quota Monitoring and Alerting. To apply for more quota when needed, see SafetyNet Attestation API - Quota Request.

Note

When you enable attestation, an event log subscription is created automatically and you are notified through My Alerts if you exceed quota. Look for a message similar to Android attestation quota exceeded. See Managing My Alerts.

To configure Android attestation:

  1. In mobile services cockpit, select Mobile Applications > Native/MDK.

  2. Select an application, and Attestation.

  3. Select edit , and then the Enabled checkbox. When you enable attestation, an event log subscription is created automatically, so you are notified through My Alerts if you exceed quota.

  4. In Edit Android Attestation Settings, configure the Android attestation settings, and select Save. These values are used to validate an Android app's integrity.

    Android Attestation Settings

    Field Description
    Google API Key (Required) The access key required to call the SafetyNet Attestation API.
    Package Name (Required) The name of the application package. The package name is used to check whether the client requests come from the app using the expected package name.
    Attestation Token Lifetime (Required) How long an attestation token is valid, in minutes, hours, or days. When the client passes attestation validation, SAP Mobile Services issues a token. Within the token lifetime, the client doesn’t need go through the attestation token flow again. The minimum value of token lifetime is 30 minutes, the maximum value is 7 days.
    Debug Token Once Android attestation is enabled,you can provide a debug token for debugging and testing. This enables you to skip attestation check. To do so, attach the following header when accessing the SAP Mobile Services API: x-ms-attestation-token:<debug_token_value>. For security, be cautious about not leaking the debug token value. You can select Generate to generate a new token for debugging, and Revoke to remove the token. The value is masked automatically.
    SHA-256 Certificate Fingerprints (Required) This value is used to validate whether the client requests come from the app signing with the expected keystore. Provide the 64-byte hex string generated by keytool. You can add multiple SHA-256 Certificate Fingerprints, and add or delete values.

    Once you save, the Attestation Request Monitor appears, and Android attestation for the selected application begins. Mobile Services validates the attestation token and logs the results for each request, but does not reject requests that do not include an attestation token. The Status appears as Unenforced.

  5. When you are ready (keeping in mind the guidelines provided above), select the Enforce button. Then, only requests that pass attestation validation are accepted, and the rest are rejected. The Status changes to Enforced.

    The Attestation Request Monitor provides a graph showing the number of requests, in specific categories, by platform and time frame. Change filters to view specific information.

    Attestation Request Monitor Filters

    Filter Description
    Time Frame Select the time frame from the list, including last hour, last 24 hours, last 7 days, and last month.
    Platform Select the platform to include, such as Android or Unknown.

    The graph may include these request types:

    • Verified: the requests passed the attestation validation.

    • Outdated Client: the requests can’t provide the attestation token. This may indicate an older application version.

    • Invalid: the requests failed the attestation token check.

    • Unknown Origin: the requests did not come from an Android device; for example, they may have come from a browser or the Postman platform.

  6. (Optional) Under Android Attestation, select edit to change settings.

  7. Under SafetyNet Attestation API Quota Monitoring, follow the links to learn more about setting up quota monitoring and alerting, and requesting additional quota.

    If you exceed quota, you see an event log message similar to Quota exceedance on {number_of_days} of the last 30 days. If this happens frequently, consider requesting additional quota.

Data Protection and Privacy

SAP Mobile Services does not track or store personal data, but tracks data that is related to mobile services and set-up details.

Data protection is associated with numerous legal requirements and privacy concerns. In addition to compliance with general data privacy regulation, it is necessary to consider compliance with industry-specific legislation in different countries. SAP provides specific features and functions to support compliance with regard to relevant legal requirements, including data protection. SAP does not give any advice on whether these features and functions are the best method to support company, industry, regional, or country-specific requirements. Furthermore, this information should not be taken as advice or a recommendation in regards to additional features that would be required in specific IT environments; decisions related to data protection must be made on a case-by-case basis, taking into consideration the given system landscape and the applicable legal requirements.

Note

SAP does not provide legal advice in any form. SAP software supports data protection compliance by providing security features and specific data protection-relevant functions, such as simplified blocking and deletion of personal data. In many cases, compliance with applicable data protection and privacy laws will not be covered by a product feature. Definitions and other terms used in this document are not taken from a particular legal source.

Important Terms

Term Definition
Consent The action of the data subject confirming that the usage of his or her personal data shall be allowed for a given purpose. A consent functionality allows the storage of a consent record in relation to a specific purpose and shows if a data subject has granted, withdrawn, or denied consent.
Deletion The irreversible destruction of personal data.
Personal data Any information relating to an identified or identifiable natural person ("data subject"). An identifiable natural person is one who can be identified, directly or indirectly, in particular by reference to an identifier such as a name, an identification number, location data, an online identifier or to one or more factors specific to the physical, physiological, genetic, mental, economic, cultural, or social identity of that natural person.
SAP Mobile Services and set-up Any information related to using the mobile services and setting up access, authentication, operations, security, and so forth. It may be related to a "data subject" but in the context of processing authentication, data, usage, and so forth.
Purpose A legal, contractual, or in other form justified reason for the processing of personal data. The assumption is that any purpose has an end that is usually already defined when the purpose starts.

SAP Mobile Services (Cloud Foundry)

SAP Mobile Services and set-up details typically include the following.

  • Tenant Data

    Tenant Data is stored in a SAP Business Technology Platform mobile services provider account.

    When the customer deletes a mobile application, its related data are all purged. If a sub-account\org\space is deleted, mobile applications and related data deployed in them will be eventually purged by our scheduler

  • Application Client Logs and Usage Reports

    Client logs and usage data is maintained by SAP Mobile Services, but no sensitive data is stored.

    Client application developers can use our SDK to build an opt-in form to collect consent for usage analysis from their users. The customer can customize the form for each application. The application user gives consent from the device for specific Usage Report data to be collected. The Usage Report does not contain personal data, only anonymized information about the usage of the app (for example, which pages were opened, how long the pages were open, and so forth). The server records the response, retains the last five versions of the consent form, and the version used to give consent.

    Tenant dev/ops personnel set the schedule to purge logs, or can purge them immediately, using the SAP mobile service cockpit.

    Client Usage is kept 365 days. Any need to purge them immediately, please initiate a support ticket.

  • Network Trace

    SAP Mobile Services does not deal with personal data directly but rather acts as a proxy to the back end. The platform has the option to temporarily capture network traffic to the back end for debugging purposes. This network trace information might contain personal data exchanged from device to back end.

    Enabling/disabling network trace is audited, and accessing network trace (downloading from SAP mobile service cockpit) is also audited in our audit log table. Network trace is retained for 7 days. We also provide functionality to purge network trace manually.

  • Export User Data

    SAP Mobile Services provides the feature in SAP mobile service cockpit to export user data based on username in each application. It can be used to export all data relevant to a user within the application.

  • Applications that You Create

    The cloud service does not store personal data, but only synchronizes data exchanged between the mobile device and the back end.

    Developers can create applications that store sensitive data in an offline data store. In this case, developers should set the client password policy that is used to unlock the data store when an application initializes, as described in Defining Client Password Policy, and should also encrypt the contents of the offline data store using the storeEncryptionKey method. This ensures that data is automatically encrypted when the store is used for the first time.

    WeChat Micro App applications collect users’ nickname and profile photo, only after users provide consent and their WeChat ID. The purpose is to help users log on to mobile services cockpit using Single Sign On from WeChat (client app on devices), and to help Micro App applications to access the nickname and profile photo for personalization.

    After users unsubscribe, the collected information is deleted. When, customers / tenants cancel mobile services or delete WeChat Micro Apps, the collected information is deleted.


Last update: November 15, 2022