1. REST API for Oracle Field Service Cloud Service REST API for Oracle Field Service Cloud Service
  2. Learn More
  3. Authenticate and Authorize

Authenticate and Authorize

Before you start using the REST APIs, you must authenticate and authorize their usage. This section explains:

  • The different types of authentication mechanisms that the client uses to send credentials.
  • The process to authorize user access to RESTful Web Resources

Authenticate

Oracle Field Service REST APIs support the following list of mechanisms that the client uses to send authentication credentials:

  • HTTP Basic Authentication: Ensures secure and encrypted access to data over a network.
  • OAuth 2.0 Authentication: Streamlines integrations with Oracle products and other middleware.

Using HTTP Basic Authentication

From Release 17.2 onwards, all new customers should use the client ID and client secret for performing Basic authentication.

To get the Client ID and Client Secret, you need to perform the following steps:

  1. Register an application
    1. In the Field Service Manage interface, click Configuration and select Applications.
    2. In the left pane, click the plus icon to open the New application window, specify the Application Name and Application ID, and click Submit.
    3. Under Authentication settings, select the Authenticate using Client ID/Client Secret check box.
    4. Set up the permissions for accessing the resources. For more information on configuring application permissions, see Authorization for details.
    5. Click Save.
  2. Select the application and under Authentication settings section, click Show Client ID / Client secret to view the Client ID and Client Secret.
  3. Make a note of the Client ID and Client Secret.

The Authorization header is used to specify the authentication information. The Field Service Authorization header has the following format:

Authorization: Basic BASE64(<CLIENT_ID>@<INSTANCE-NAME>:<CLIENT-SECRET>)

For example, if Client ID is 'my_test_app', Instance Name is 'bestcustomer.test', and Client Secret is 'ae596e96d15cfed1d137c2e99de50754', the Authentication header is:

Authorization: Basic BASE64("my_test_app@bestcustomer.test:ae596e96d15cfed1d137c2e99de50754")

The Base64 encoded value of the Authorization header is:

Authorization: Basic bXlfdGVzdF9hcHBAYmVzdGN1c3RvbWVyLnRlc3Q6YWU1OTZlOTZkMTVjZmVkMWQxMzdjMmU5OWRlNTA3NTQ=

You can use a cURL request to perform the authentication. For example:

curl -k -u 'my_test_app@bestcustomer.test:ae596e96d15cfed1d137c2e99de50754' \
     -H 'Accept: application/json' \
     'https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1'

In this code example, the 'u' cURL parameter specifies the Client ID, the Instance Name, and the Client Secret separated by '@' and ':' respectively. The cURL command automatically generates the Base64 encoded credentials and builds the Authorization header.

The response to the example request is 200 on success and 401 on authentication failure.

Using OAuth 2.0 Authentication

Oracle Field Service supports OAuth 2.0 authentication for API access. Using OAuth 2.0 authentication allows third-party applications, such as a mobile app to access the REST APIs on behalf of a user.

To use OAuth 2.0 authentication, you register the client application with Oracle Field Service. Then your client application requests an access token from Oracle Field Service or other external token service. The client application then sends the token to the API that you want to access.

Step 1: Registering the OAuth Client Application

Register the application that you want to integrate with Oracle Field Service as follows:

  1. In the Field Service Manage interface, click Configuration and select Applications.
  2. In the left pane, click the plus icon to enter the details of the application that you want to register.
  3. In the New application window, specify the Application Name and Application ID. In the Token service drop-down list, select the type of token service. By default, the type of token service is OFSC.
  4. Click Save.

Step 2: Determining the type of Authentication

After you register the application and specify the type of token service, you must configure the application to use the token service. Oracle Field Service supports three types of token service:

  • Oracle Field Service Token Service: The client application uses Oracle Field Service token service to obtain an OAuth 2.0 access token and authenticate with the APIs. Oracle Field Service token service supports two types of authentication:
    • Client Credentials: Authentication using client credentials is primarily used for backend-to-backend integration. For example, an application that requires pushing data to Oracle Field Service.
    • JWT Assertion: JWT assertion authentication can be used for backend-to-backend integration or for mobile applications. The access token generated using assertion flow has the user information in it and Oracle Field Service performs actions by impersonating that user.

      The advantage of using assertion flow is that users' credentials are not shared with Oracle Field Service.

    For more information, see Configuring Authentication Using Oracle Field Service Token Service.

  • External Token Service: The client application uses an external token service to obtain an OAuth 2.0 access token and authenticate with the APIs.

    For more information, see Configuring Authentication Using External Token Service.

  • Oracle Identity Cloud Service: The client application uses Oracle Identity Cloud Service to obtain an OAuth 2.0 access token and authenticate with the APIs. Oracle Identity Cloud Service provides an innovative, fully integrated service that delivers all the core identity and access management capabilities through a multi-tenant Cloud platform. For more information, see Integrating Using REST APIs topic in the Administering Oracle Field Service guide.

Step 3: Enabling Access to Specific APIs for Your Application

After you register the application and determine the type of authentication with the token service authentication, you set up the permissions for accessing the resources. For more information on configuring application permissions, see Authorize.

Step 4: Obtaining the Access Token and Using It

You can obtain an access token from the token service using the 'Get access token' function. The following is a cURL command example requesting access token from a token service:

curl 	-X POST -u '<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>'\
	-d 'grant_type=client_credentials' \
	'https://<instance_name>.fs.ocs.oraclecloud.com/rest/oauthTokenService/v1/token'

The response contains the access token in the 'token' field:

{
   "token": "eyJ0eXAiOiJ...SKIP...qtCqNDk6qy_utky5M",
   "token_type": "bearer",
   "expires_in": 3600
}

You need to provide the 'token' field value from the token service response in the cURL request to the API. The following is an example:

curl -H 'Authorization: Bearer eyJ0eXAiOiJ...SKIP...qtCqNDk6qy_utky5M'\
	'https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4224031'

The response contains the JSON data that the API returns. In this case, it will return the properties of the activity that has the 'activityId' as 4224031.

Authorize

Access to the REST web resources is determined by performing the following tasks:
  • Register the application with Oracle Field Service. To register an application with Oracle Field Service, see Registering an Application with Oracle Field Service.
  • Define the APIs that the application can access.
  • Define the users who can access the APIs.

    Note:

    By default, all users can access the APIs.

To authorize access to REST web resources:

  1. Define the APIs that the application can access:
    1. In the Field Service Manage interface, click Configuration and select Applications.
    2. In the left pane, select the application.
    3. Under API access, click Add new.
    4. Select the APIs, for example, Core API and Metadata API.
    5. Click the icon next to the respective API and select Available methods.
    6. Select the methods that users can access and select ReadWrite for the objects that the user type can modify.
  2. Define the users who can access the APIs:
    1. Under Additional Restrictions, select the Allow access only to certain resources check box.
    2. Click Add, and select the resources.
    3. To restrict access by IP addresses, select the Allow access only for certain IP-addresses check box. In the text box, enter the IP addresses.
  3. Click Save.