1. REST API for Oracle Field Service Cloud Service REST API for Oracle Field Service Cloud Service
  2. Learn More
  3. Configure OAuth 2.0 Authentication

Configure OAuth 2.0 Authentication

You can configure OAuth 2.0 authentication either by using the Oracle Field Service token service or by using an external token service. For more information, refer to the following sections:

Configuring Authentication Using Oracle Field Service Token Service

Before you configure the application to use Oracle Field Service token service, ensure that you synchronize the users from the external identity storage to Oracle Field Service

Note:

User synchronization between the client application and Oracle Field Service is beyond the scope of this document.

To configure Oracle Field Service token service:

  1. In the Field Service Manage interface, click Configuration and select Applications.
  2. In the left pane, select the application to configure token service.
  3. Under General info, ensure that the Active check box is selected.
  4. Select Token service as OFSC.
  5. For authentication using client credentials, perform the following steps:
    1. Under Authentication settings, select the Authenticate using Client ID/Client Secret check box.
    2. Click Show Client ID/Client Secret and note the Client ID and Client Secret. The application uses the Client ID and Client Secret to authenticate with the Oracle Field Service token service.
    3. Click Save.
  6. For authentication using JWT assertion, perform the following steps:
    1. Under Authentication settings, select the Authenticate using JWT assertion check box.
    2. Click Upload and upload your assertion signing key certificate.
    3. Click Save.

Example: Authentication Using Oracle Field Service Token Service

The following example explains the process to configure an application to use Oracle Field Service Token Service for authentication.

To configure authentication using Client Credentials:

  1. In the Field Service Manage interface, create a new application.
  2. Select the Active check box, Token service as OFSC.
  3. Under Authentication settings, select the Authenticate using Client ID/Client Secret check box.
  4. Note the Client ID and Client Secret.
  5. Click Save.
  6. Obtain the OAuth 2.0 access token

    Use the following cURL command with the Client ID, Client Secret, and Instance name:

    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 a JWT access token in the "token" field:

    {
   "token": "eyJ0eXAiOiJ...SKIP...qtCqNDk6qy_utky5M",
   "token_type": "bearer",
   "expires_in": 3600
}
  7. Copy the value of the "token" field from the token service response, and use it in the following cURL request to the API:
    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.

To configure authentication using JWT Assertion token:

  1. In the Field Service Manage interface, create a new application.
  2. Select the Active check box, Token service as OFSC.
  3. Under Authentication settings, select the Authenticate using JWT assertion check box.
  4. Click Upload and upload your assertion signing key certificate.
  5. Click Save.
  6. Your JWT assertion must be generated in the following table.
    Element Description

    Algorithm

    RS256

    Header

    		 
    {
  "alg": "RS256"
}

    Payload

    The payload must contain the following fields:

    • iss: Indicates who issued this assertion. This field is only for information and logging purposes and isn't used in validation.
    • aud: Indicates the audience for assertion. It's a string composed of the following parts each delimited by colon:
      • ofsc
      • Oracle Field Service instance name
      • Application ID that you entered when registering the application.
    • sub: If the call is made by an application, the value is equal to the value of aud value. Else, the value is equal to the login field of an Oracle Field Service user that you want to authorize to call REST APIs.
    • iat: Indicates the time stamp when this assertion was issued.
    • exp: Indicates the time stamp when this assertion expires. The value of expiration can be low, for example, a minute or a few minutes.

    Example:

    {
    "sub": "gabrielle.lee",
    "aud": "ofsc:<INSTANCE-NAME>:<Application-ID>",
    "iss": "Identity Authority",
    "iat": 1482382598,
    "exp": 2482382728
}

    Private key

    The assertion should be signed by the private key of the certificate you uploaded earlier in the Applications page.
  7. Obtain the OAuth 2.0 access token.

    Use the following cURL command with the Client ID, Client Secret, and Instance name:

    curl 	-X POST  -u '<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>' \
	-d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer' \
	-d 'assertion=YOUR-ASSERTION-TOKEN-FROM-JWT-IO' \
	'https://<instance_name>.fs.ocs.oraclecloud.com/rest/oauthTokenService/v1/token'

    The response contains a JWT access token in the "token" field:

    {
    "token": "eyJ0eXAiOiJ...SKIP...qtCqNDk6qy_utky5M",
    "token_type": "bearer",
    "expires_in": 3600
}
  8. Copy the value of the "token" field from the token service response, and use it in the following cURL request to the API:
    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.

Configuring Authentication Using External Token Service

Before you configure the application to use an external token service, ensure that all the required identity provider configurations are completed.

Note:

Adding the configuration details in the identity provider is beyond the scope of this document.

To configure External token service:

  1. In the Field Service Manage interface, click Configuration and select Applications.
  2. In the left pane, select the application to configure token service.
  3. Under General info, ensure that the Active check box is selected.
  4. Select Token service as External.
  5. Under Authentication settings, select the Authentication using external access token check box.
  6. Click Upload and upload your external token service's signing key certificate.

Example: Authentication Using External Token Service

The following example explains the process to use external token service for REST API authentication.

To configure authentication using external token service:

  1. Ensure to synchronize the users from the external identity storage to Oracle Field Service.
  2. In the Field Service Manage interface, click Configuration and select Applications.
  3. In the left pane, select the application to configure the token service.
  4. Under General info, ensure that the Active check box is selected.
  5. Select Token service as External.
  6. Under Authentication Settings, select the Authentication using external access token check box.
  7. Click Upload and upload your external token service's signing key certificate.
  8. Authenticate the REST API with the external token service.

    For example, if you're using Oracle Identity Cloud Service as the identity provider:

    Oracle IDCS Authentication Parameters

    An example bash script of how you would generate an assertion for external Token Service such as IDCS is as follows:

    AUTHORIZATION_SERVER='https://authorization-service.fs.ocs.oraclecloud.com/oauth2/v1/token'
CLIENT_ID=edd0f92d006240de8c5e35bea3ec8056
CLIENT_SECRET=2cf551aa-5b3f-4cca-beaf-90aa76319511
OFSC_INSTANCE=kh01_demo1
OFSC_APP_ID=c489ba38d24b7b6b29871efee2e882a50731552f
IDCS_ASSERTION=`jwt_encode_and_sign '{
 "sub":" Gabrielle.Lee@oracle.com",
 "aud":"https://identity.oraclecloud.com/",
 "iss":"edd0f92d006240de8c5e35bea3ec8056",
 "user_loginid":" Gabrielle.Lee@oracle.com ",
 "iat":1478013414,
 "exp":1478017024
}' client-key.pem`

    cURL command that uses the assertion to obtain access token from external token service

    Note:

    Configure the external token service such that the sub and the aud fields in the access token that it returns would be the same as explained in the preceding example. 
    curl -u "$CLIENT_ID:$CLIENT_SECRET" \
     -X POST \
     -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' \
     -H 'Accept: application/json' \
     -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer' \
     -d "scope=$OFSC_INSTANCE/$OFSC_APP_ID" \
     -d "assertion=$IDCS_ASSERTION" \
     -k -v \
     "$AUTHORIZATION_SERVER" > at-from-assertion.json

    JWT Access Token from Oracle IDCS

    cat at-from-assertion.json

    eyJraWQiOiJTSUdOSU5HX0tFWSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJrb
3N0eWFudHluLmx5c3lAb3JhY2xlLmNvbSIsImlzcyI6Imh0dHBzOi8vaWRlbn
RpdHkub3JhY2xlY2xvdWQuY29tLyIsInRva190eXBlIjoiQVQiLCJhdWQiOiJ
raDAxX2RlbW8xIiwic2NvcGUiOiIvYzQ4OWJhMzhkMjRiN2I2YjI5ODcxZWZl
ZTJlODgyYTUwNzMxNTUyZiIsImV4cCI6MTQ3NjY2NzgyMiwiaWF0IjoxNDc2N
jY0MjIyLCJqdGkiOiJkZjZhM2YxNS0wZDc1LTQ1Y2MtYjM0Ny0xNWVjMjRjMz
ZiMGMifQ.lLnjTBjKA2n6OmHO5ciKHeRycRCYS-omCKKBc_qUPSM
  9. Access the REST API with the access token.

    cURL command that uses the access token obtained from external token service to call REST APIs

    curl -X POST "$OFSC_HOST/rest/ofscCore/v1/activities"   \
-H "Authorization: Bearer `cat at-from-assertion.json`" \
--data-binary '{
    "resourceId": "33011",
    "date": "2016-11-01",
    "activityType": "4",
    "apptNumber": "testApptNumber",
    "customerName": "testCustomerName",
    "streetAddress": "8 Elm St",
    "timeZone": "Eastern",
    "country_code": "US"
}

    Oracle Field Service verifies the JWT signature, expiration, and so on and processes the request.