Enable Restricted Access Control Using Access Tokens with Dynamic Scope

You can use Oracle Field Service REST APIs to grant Public API access to your customers without creating specific accounts in Oracle Field Service 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 Oracle Field Service 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 Oracle Field Service token service or any other external token service to implement dynamic scope support for API calls. Here's the flow when you use the Oracle Field Service token service:

1. Your Oracle Field Service 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 Oracle Field Service for the specific requests. Oracle Field Service rejects all other requests.

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

• The Oracle Field Service application is registered as a resource server with the dynamic custom claim enabled.
• The signing key certificate is available to Oracle Field Service so that it can accept the tokens issued by the external token service.
• An OAuth client must be registered with access to the Oracle Field Service 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 Oracle Field Service 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 Oracle Field Service REST API using this token, but it can only access the requests specified in the custom claim. Oracle Field Service 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>.fs.ocs.oraclecloud.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>.fs.ocs.oraclecloud.com/rest/oauthTokenService/v1/token' \
  -d 'grant_type=client_credentials' \
  -d 'ofsc_dynamic_scope=https%3A%2F%2F<instance_name>.fs.ocs.oraclecloud.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>.fs.ocs.oraclecloud.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: Oracle Field Service 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: Oracle Field Service 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: Oracle Field Service 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.