Skip to content

Service Keys

For some features you can implement a service key, which enables an application to access a service instance using a service key for credentials.

SAP Mobile Services Service Keys

The SAP Mobile Services service must be able to support service keys. Currently this includes Mobile App Catalog, Mobile Client Resources, Mobile Client Usage and Feedback, Mobile Push Notification, Mobile Settings Exchange, Mobile Micro App, and Mobile Connectivity.

Service keys provide access to a set of services in an API Key or an X.509 manner. That means that a back-end service does not require user credentials, but the service key is limited to a specific use case. For example, you can enable an application to send push notifications using the server key as its credentials, without requiring a user to enter credentials, or you can enable back-end services to call service APIs.

Configure service keys at the provider level or the application level in SAP mobile service cockpit. If you do not see the Service Keys tab for a feature, the option is not available. The service keys for subscriber level and provider level are managed separately.

  • Subscriber level - the subscriber level app can manage its own service keys. The administrator can only view/delete service keys that exist in the subscriber level app, but can also accept provider service keys. The subscriber user can't see the provider service key in the subscriber SAP mobile service cockpit, but the subscriber application can use the provider service key in runtime.

  • Provider level - the provider level app can only accept provider service keys.

API Key Manner The API key is recommended for users that are accessing multiple services using the same authentication credentials. You have two options for sending the key to the service, using either the X-API-Key header or an Authorization header. See Next Steps below for usage.

X.509 Key Manner The X.509 key is recommended for service-to-service communication, enabling customer back-end services to call service APIs. See Next Steps below for usage.

A feature flag is available that determines whether a service key is visible in SAP mobile service cockpit after its initial creation. Industry best practices recommend that new service keys should be visible upon creation, and thereafter no longer appear. This provides additional security by minimizing the risk that someone can access and use the service key maliciously.

  • When the cpmscf-6405-protection-over-service-key feature flag is turned on (default), the service key is viewable only upon creation (you can copy the key, and paste it to a secure location). After that the service key is masked.

  • When the cpmscf-6405-protection-over-service-key feature flag is turned off, the service key remains viewable after creation (this provides a way for customers who rely on being able to retrieve the service key for customer support).

Rotate X.509 service keys before they expire by creating a new one. Once a service key expires, a `403 Forbidden`` response is returned, and the service cannot be called. Users can't obtain tokens from XSUAA, and they cannot access services without tokens.

To rotate certificates without downtime, create a new service key with a new certificate, and implement the new service key on the back end. When the back end is configured with the new service key, delete the old service key.

To configure SAP Mobile Services service keys:

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

  2. Select an application, and then select a feature under Assigned Features.

  3. Select Service Keys.

    View the list of service keys currently configured for the service instance.

    Properties Descriptions
    Type Rows are grouped by service key credential type: API Key and X.509.
    Alias A human readable name for the service key, from 1-64 characters, and used as the username to authenticate a request. Also used when an audit log record is created. Required.
    Key Properties For API Key, the URL used to access the service instance. The URL is generated, and cannot be edited. For X.509, properties, includes: Key Length, Validity Lifetime, Start Date, Expiration Date.
    API Key The API-key that is sent in the request header and used as the password to authenticate a request. The API-key cannot be edited.
    Roles The roles that are assigned to this service key. Required.
    Actions You can delete a service key, but you cannot edit one. To change a service key, you must delete it, and then create a new one. You can view details for X.509 service keys.
  4. To configure a new service key, select add .

    1. In Add Service Key, configure the service key properties.

      Service Key Properties

      Properties Descriptions
      Alias Enter a human readable name for the service key, from 1-64 characters, and used as the username to authenticate a request. Also used when an audit log record is created. Required.
      Roles Enter the roles that are assigned to this service key. Required.
      Type Select API Key or X.509 from the list to specify the service key type.
      Type: API Key If you select API Key, the API-key is sent in the request header and used as the password to authenticate a request. The API-key and URL cannot be edited.
      Type: X.509 If you select X.509, enter the properties. For API Key, the URL used to access the service instance. The URL is generated, and cannot be edited. For X.509, properties, properties include: Key Length, Validity Lifetime, Start Date, Expiration Date.

      X.509 Properties

      Property Description
      Key Length The key size in bits, for example 2048, 4096.
      Validity Lifetime How long the X.509 key is valid, such as 1 Day, 1 Month.
      Start Date Validity lifetime start date, in YYYY-MM-DD HH:MM(UTC+<xxxx>) format.
      Expiration Date Validity lifetime end date, in YYYY-MM-DD HH:MM(UTC+<xxxx>) format.
    2. Select OK to save.

    3. If the cpmscf-6405-protection-over-service-key feature flag is turned on (default), the Add Service Key dialog remains open. The new API Key or X.509 access token appears, along with a message recommending that you to use the copy button to save the value. Once you have saved the value in a secure place, click OK again. The new service key is added to the list, and is masked.

    4. If the cpmscf-6405-protection-over-service-key feature flag is turned off, the new service key is added to the list.

      • The API Key and URL are generated from service metadata.

      • The X.509 access token is generated by the customer back-end service using the uaa.clientid, uaa.certurl, uaa.certificate and uaa.key properties.

    To view details for an X.509 service key, select Details. The properties and generated certificate details appear in JSON format. You can copy or download the contents.

  5. To remove a service key, select delete .

    Note

    Since you cannot edit service keys, you must delete a service key and configure a new one in order to change a service key.

Next Steps

API Key Manner To send the API key to the service, you can either use the X-API-Key header or an Authorization header.

  • X-API-Key Header

    To authenticate, send the API-key along with the request in the X-API-Key header:

    X-API-Key: <API-Key>

  • Authorization Header

    To authenticate, send the API-key as Basic authentication in the Authorization header. The <Alias> is the username and the <API-Key> is the password. Both need to be joined with a colon (<Alias>:<API-Key>) and Base64-encoded.

    Authorization: Basic [Base64(<Alias>:<API-Key>)]

X.509 Key Manner The implementation for X.509 service keys is a little different. In the X.509 service key properties retrieved from SAP mobile service cockpit, the uaa property provides the credentials, which are generated by XSUAA and are used to generate the access token; and the url property is the base URL of mobile services feature.

The customer back-end service uses the uaa.clientid, uaa.certurl, uaa.certificate and uaa.key properties to generate the access token, and then uses the access token to access the back-end API of the mobile services feature.

Example request (based on curl):

curl --cert cert.pem --key key.pem -XPOST {uaa.certurl}/oauth/token -d 'grant_type=client_credentials&{uaa.clientid}'

Where, cert.pem includes the value of the uaa.certificate property, and key.pem includes the value of uaa.key property.

Note

The certificate and key string contain new line escape sequences (\n), which must be replaced with actual line breaks for your operating system, if used in cert.pem and key.pem.

The access token value can be obtained from the access_token attribute in the response body. When accessing the back-end API of mobile services feature, the access token needs to be included as "Authorization" header with "Bearer " prefix.

Authorization: Bearer <access_token>

SAP Data Custodian Key Management Service Integration

(Restricted Availability) An option is available for some customers to manage their own keys in the Cloud Foundry environment, rather than have SAP manage them.

SAP Mobile Services Services integration with the SAP Data Custodian Key Management Service (DCKMS) provides this option. The SAP Mobile Services environment must meet certain conditions and be approved by SAP. Once approved, some customer actions are required for onboarding.

For more information, see SAP Note 3348581 - SAP Data Custodian Key Management Service Integration for mobile services (login required).


Last update: July 25, 2023