OAuth for SAP Document Center

This blog describes how OAuth can be configured for SAP Document Center (formerly known as SAP Mobile Documents) running on SAP HANA Cloud Platform (HCP).

This is a recommendation if you use a dedicated Identity Provider for your SAP Mobile Documents HCP account. As a result, the OAuth enabled clients of SAP Mobile Documents are able to authenticate themselves using an OAuth token. The lifetime of this token can be configured.

Prerequisite:

The usage of the REST Config UI for SAP Mobile Documents requires the Admin role for Mobile Documents

I. Create an OAuth Client Entry in HCP Cloud Cockpit

1. Open the HCP Cockpit for your account

2. In the left navigation menu, select OAuth

3. Navigate to the tab Clients

4. Click Register New Client

a) Provide a meaningful name, such as SAP Mobile Documents OAuth

b) Select the Mobile Documents Subscription

c) Leave the ID as is

d) Leave Authorization Grant as Authorization Code

e) Configure the Redirect URI as https://<DNS name of your Mobile Documents Account>/

like https://mdocs-p1941693435trial.hanatrial.ondemand.com/

f) You can define how long the OAuth token should be valid until a re-authentication is triggered.

5. You will need the following information from the HCP Cockpit:

– The ID value generated on the OAuth Settings Client page (the one you just created)

– The Authorization Endpoint URL and the Token Endpoint URL. Both URLs you can get from the Branding tab of the OAuth Settings page (see screenshot below)

II. Configure OAuth with the REST Admin UI

You will configure the following parameters using the values of the previous step:

     oauth.authURL

     oauth.tokenURL

     oauth.clientId

     oauth.redirectURL

     client.authorization.mode

To set the values, call the Admin REST UI of SAP Mobile Documents.

Open the following URL (replace <DNS name of your Mobile Documents account> with the respective value of your instance):

https://<DNS name of your Mobile Documents Account>/mcm/admin/rest.html.

Hint: You can get the first part of the URL from the HCP Cockpit, when you navigate to Services – Mobile Documents – Configure Mobile Documents)

This will look similar to my example:

https://mdocs-p1941693435trial.hanatrial.ondemand.com/mcm/admin/rest.html

1. Set oauth.authURL

a) Enter the following values into the JSON field:

     {

     “name”: “oauth.authURL“,

     “value”: “<insert the Authorization Endpoint URL from chapter I.5 here>“

     }

b) Set target to /mcm/admin/v1/configs

c) Set POST

d) Click Send

2. Set oauth.tokenURL

a) Enter the following values into the JSON field:

     {

     “name”: “oauth.tokenURL“,

     “value”: “<insert the Token Endpoint URL from chapter I. 5. here>“

     }

b) Set target to /mcm/admin/v1/configs

c) Set POST

d) Click Send

3. Set oauth.clientId

a) Enter the following values into the JSON field:

     {

     “name”: “oauth.clientId“,

     “value”: “<insert the ID value of the Client entry that you created in chapter I. 4. here>“

     }

b) Set target to /mcm/admin/v1/configs

c) Set POST

d) Click Send

4. Set oauth.redirectURL

a) Enter the following values into the JSON field:

     {

     “name”: “oauth.redirectURL”,

     “value”: “https://<DNS name of your Mobile Documents account>”

     }

b) Set target to /mcm/admin/v1/configs

c) Set POST

d) Click Send

5. Set oauth.authorization.mode

a) Enter the following values into the JSON field:

     {

     “name”: “client.authorization.mode”,

     “value”: “oauth,certificate”

     }

b) Set target to /mcm/admin/v1/configs

c) Set POST

d) Click Send

Once you have successfully configured OAuth on the server, you are able to authenticate with the Mobile Documents clients.

Congratulations!

Appendix: Updating an OAuth entry (only if you want to change an existing one)

If you want to re-configure the values, e.g. you want to change the sequence of the authentication method to be used, follow these steps:

Copy the ID of the entry from https://<DNS name of your Mobile Documents Account>/mcm/rest/v1/configs

Search for the respective entry that you want to change, e.g. the entry for the sequence of the authentication to be used (“client.authorization.mode”):

{“creationDate”:1456765302550,”id”:”c652d322-f23b-4813-ad17-38ee6a9fa039″,”modificationDate”:1456765302550,”tenantId”:”e908f5b6-f70a-4a6c-88ea-d28669ad9c81″,”name”:”client.authorization.mode”,”value”:”basic,certificate,oAuth”}

Copy the entries id, name and value

Open the following URL:

https://<DNS name of your Mobile Documents Account>/mcm/admin/rest.html.

Paste the changed values into the JSON field.

As target enter /mcm/admin/v1/configs/<the ID of the entry>

Change the dropdown value to PUT

Click Send