Enable Restricted Access Control Using Access Tokens with Dynamic Scope

You can use Oracle Field Service Cloud (OFSC) REST APIs to grant Public API access to your customers without creating specific accounts in OFSC or in other Oracle applications. However, the scope of the access must be restricted to a particular claim to prevent them from accessing the data of other OFSC customers.

You can restrict your customer's access by using the 'ofsc_dynamic_scope' parameter in the 'Get an access token' operation to specify a custom claim. The 'ofsc_dynamic_scope' claim has the format of a URL with optional query parameters. You can specify several URLs at once using the space character as a separator.

You can use the OFSC token service or any other external token service to implement dynamic scope support for API calls. Here's the flow when you use the OFSC token service:

  1. Your OFSC application uses its credentials with restrictions to get an access token for specific requests.
  2. Your application transfers the access token to your customer's web/mobile app.
  3. Your customer's web/mobile app can only query OFSC for the specific requests. OFSC rejects all other requests.

If you plan to use an external token service, then these prerequisites need to be met:

  • The OFSC application is registered as a resource server with the dynamic custom claim enabled.
  • The signing key certificate is available to OFSC so that it can accept the tokens issued by the external token service.
  • An OAuth client must be registered with access to the OFSC resource server and the credentials are saved to the application.

Here's the dynamic scope support flow when the you use an external token service:

  1. Your OFSC application uses its OAuth client credentials to request an access token with external token service, specifying the custom claim in the request.
  2. The token service returns the access token with custom claim.
  3. The application passes the token to your customer's web/mobile.
  4. Your customer's web/mobile app may call OFSC REST API using this token, but it can only access the requests specified in the custom claim. OFSC rejects all other requests.

Example cURL Command

Here's an example of the cURL command. In this example, the 'ofsc_dynamic_scope' is set to 'https://<instance_name>.etadirect.com/rest/ofscCore/v1/whereIsMyTech?activityId=12345' (value is URL-encoded in the command):

curl -u 'client_id@instance_name:client_secret' \
  -X POST \
  --url 'https://<instance_name>.etadirect.com/rest/oauthTokenService/v1/token' \
  -d 'grant_type=client_credentials' \
  -d 'ofsc_dynamic_scope=https%3A%2F%2F<instance_name>.etadirect.com%2Frest%2FofscCore%2Fv1%2FwhereIsMyTech%3FactivityId%3D12345'

Example Response

Here's an example of the response containing the OAuth2 access token

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJvZnNjOmtseXN5eTo1MzRmODJhOGQxYWMyYTQ3ZGE5Y2ZlOTVhNGM4YmY5Yjg3YjY2NTUzIiwiaXNzIjoib2ZzYzprbHlzeXk6NTM0ZjgyYThkMWFjMmE0N2RhOWNmZTk1YTRjOGJmOWI4N2I2NjU1MyIsInN1YiI6IjUzNGY4MmE4ZDFhYzJhNDdkYTljZmU5NWE0YzhiZjliODdiNjY1NTMiLCJzY29wZSI6IlwvcmVzdCIsImlhdCI6MTUyMjY5NzM4NywiZXhwIjoxNTIyNzAwOTg3LCJvZnNjX2R5bmFtaWNfc2NvcGUiOiJodHRwczpcL1wvYXBpLmV0YWRpcmVjdC5jb21cL3Jlc3RcL29mc2NDb3JlXC92MVwvd2hlcmVJc015VGVjaD9hY3Rpdml0eUlkPTEyMzQ1In0.BDt9RUWtIwZu0D8u92YSLXP6JarW2Uuj8XXR_9LHbCbeFxd0yMWvNVbvyaSP9oGwbtdyXOG0az2msa6Xn0e8AkdkIZqdUn5cc3YZwrZo-O5HR-VLV9ySc0r8tue3bMJqRgfLa49_lTH9WB-Ib3Q_MQ7DcuuBA8Lf7CR9HhBRvgSAHsu9lVIvC1mE4BbsR6C1BLRiVxVfdb4qNaMTrw27li7cDLMjewEs067njHcJj9ni2thH-UmxcLzaE5CQYQT7Gm68Op3aFfPnZBiXuNIhc1EFGM0aXgj6wOu7_C0JwXrL4b7DGStUrG-tXcGLeaZntKHqDEgYFpiiijZbV2kdbw",
    "token_type": "bearer",
    "expires_in": 3600
}

Example Decoded OAuth2 Token

Here's an example of the decoded OAuth2 token containing the 'ofsc_dynamic_scope' claim:

{
  "aud": "ofsc:acme:myclient",
  "iss": "ofsc:acme:myclient",
  "sub": "myclient",
  "scope": "/rest",
  "iat": 1522697387,
  "exp": 1522700987,
  "ofsc_dynamic_scope": "https://<instance_name>.etadirect.com/rest/ofscCore/v1/whereIsMyTech?activityId=12345"
}

If 'ofsc_dynamic_scope' claim is present in OAuth2 access token, then these restrictions apply to the token:

  • endpoint: OFSC Public API rejects the token with HTTP 401 status code, if it is used to call a different endpoint other than the one specified in 'ofsc_dynamic_scope' claim.
  • query fields: OFSC Public API rejects the token with HTTP 401 status code, if the request URL doesn't contain all the query parameters specified in the 'ofsc_dynamic_scope' claim.
  • query values: OFSC Public API rejects the token with HTTP 401 status code, if the query parameter values specified in the request URL don't match with the query parameter values in the 'ofsc_dynamic_scope' claim.