Skip to end of metadata
Go to start of metadata

OAuth is an access control protocol that is a standardization of many well-established industry protocols. It is used by many companies such as Twitter, LinkedIn, Facebook, and TripIt. The goal of OAuth is to protect resources exposed by a service provider (AgileAssets Web API) and used by consumer applications on behalf of users.
With OAuth, an end user may grant access to its data to a service provider without providing its user credentials to the consumer application (Client flow).
For AgileAssets Web API, it means that a third-party application may access our services directly without any knowledge of our users (Server flow).

Server Flow (Two-legged OAuth)


This flow requires two identifiers in the authorization header:

  • The OAuth Access token granted for the Consumer Key
  • The Consumer Secret

Optionally, the request can include an additional header field identifying the user account to modify. It is the responsibility of the caller to provide the user ID if the web service needs it.
The diagram below illustrates the Server Flow type of OAuth.

Client Flow (Three-legged OAuth)


This flow requires end-user participation to complete the request. The affected user must log in and confirm that the client application is allowed to access the API.
The diagram below illustrates the Client Flow type of OAuth.

OAuth Configuration


Configuration is accomplished in three steps as described below.

Step 1: Add Consumer

The first step is to register a new consumer in the AgileAssets system in the OAuth Security window. (This window is typically launched from the Setup menu in the System module.) In this window, you enter the public key and the consumer secret that your client will use when making requests to the Web API as shown in the example below. After you have saved the information, ensure that OAuth authentication is enabled (that is, that a check mark appears in the Enabled column).

Note: The consumer secret is encrypted on the database side. For security reason the secret is never decrypted on the user-interface sided. When updating the secret, you must change it completely. If "Client Authorization Flow" is enabled, the client will be re-directed to an authorization page where the end user may give permission to the client application to log in.

Step 2: Configure the Application's web.xml

To activate API Security, you must ensure that the Init parameter com.sun.jersey.spi.container.ContainerRequestFilters is set for the RestService as shown in the example below.

Step 3: Configure the Client

The client will require the following information to make authentication requests to the Web API:

OAuth Config

Value

Request Token URL

WMS_BASE_URL + "/rest/v1/token/request"

Authorization URL

WMS_BASE_URL + "/Kernel/oauth_authorization.jsp""

Access Token URL

WMS_BASE_URL + "/rest/v1/token/access"

OAuth Signing Types

PLAINTEXT or HMAC-SHA1

Consumer Key

As configured in Step 1

Example of Two-legged OAuth


The following steps illustrate how to perform a two-legged OAuth authorization:

  1. Obtain a request token by making a request via CURL:

    The server responds as shown below:
  2. Obtain an access token by making a request via CURL:

    The server responds as shown below:
  3. Access a resource (the person identified by the User ID JEFF) by making a request via CURL:

    The server responds as shown below:

Example of Three-legged OAuth


The following steps illustrate how to perform a three-legged OAuth authorization:

  1. Obtain a request token by making a request via CURL:

    The server responds as shown below:
     
  2. Obtain an authorization token. The request is re-directed to the provider to collect additional information. The request should contain output from the server's response in Step 1.
    The server responds as shown below:
  3. Obtain an access token by making a request via CURL:

    The server responds as shown below:
  4. Access a resource (the person identified by the User ID JEFF) by making a request via CURL:

    The server responds as shown below:

 

Example of iPhone Authorizing


Shown below is an example of how to authorize an iPhone user via OAuth protocol:


Once authorized, the iPhone user could, for example, obtain a specific work order ID via the following code:

  • No labels