Inbound OAuth - Delegated

When ONE is acting as the Resource Server to a third party system, we refer to this as "inbound" OAuth.

Because ONE's REST APIs are protected by OAuth, external client applications will need an OAuth token in order to access them "on behalf of" a user. The following process allows a client app to make the necessary OAuth-based authorization calls to get a token.

For the purposes of this example, we will assume that the ONE instance is at https://myinstance.onenetwork.com and the service calling ONE APIs is at https://generalledger.net

1. Register your service with One Network.

   An OAuthIBClient app record should be created for generalledger.net. This can be done through load data, through a Value Chain Admin UI, etc. In the future, this will be provided as a self-administration option in ONE's DevNet instance.

   This will grant them with:

   • Client ID - This is a unique identifier for your application. This is considered 'public' information and does not have to be secured. (For example, it will appear in URLs given to users)

   • Client Secret - This is a unique identifier for your application which is known only by the service and by you. It should be secured. (For example should never appear in a URL given to a users)

   The external app developer will have to provide a CallbackUrl, under which URL pattern any callbacks provided must fall in order to be honored. We will assume they provide: https://generalledger.net/oauth

2. Create a page which gives the user a URL to the OAuth authorization URL for ONE.

   Create a page in generalledger.net which will direct the user to ONE’s authorization page. ONE's authorization URL is:

   https://myinstance.onenetwork.com/oms/oauth/authorize

   When this link is followed, the User will be given a screen which describes the application requesting access, and gives a list of valid roles from which the user must select. The application will be able to access ONE "as" that user, with the role selected by the user.

   Table 16.17. Supported Parameters

   Parameter	Required?	Description
   client_id	Y	ID of your registered application in ONE
   redirect_uri	N	URI to which the authorization URL should redirect after the user grants access. If not provided, uses the base CallbackURL of the registered application. If provided, it must start with the value of CallbackURL. For example, if the CallbackURL is https://generalledger.net then redirect_uri can be https://generalledger.net/oauth/callback but not https://oauth.generalledger.net/callback
   state	N	The client should provide an unguessable random string. This will be provided in the redirect, and is designed to help prevent replay attacks.
   scope	N	If not provided, the user can grant the app access as any of their roles.If provided, this should be a comma-separated list of Role Types. Only Roles whose Role Types match or extend one of the Role Types in this list will be presented in the drop down. If there are no such Roles for the current user, they won't be able to grant access.

   The page will look like this:
   

   

3. Receive the callback.

   If the user grants the requested access, ONE will redirect to the redirect_uri (in this case at generalledger.net) with the following parameters:

   Table 16.18. Supported Parameters

   Parameter	Description
   code	A unique code you will provide in a subsequent request to get your OAuth Token.
   state	If you provided state in the previous URL, it is reflected back to you here. If the value doesn't match what you sent, you should fail the request.

4. Request your Token.

   At this point, generalledger.net should issue a request from its server to ONE's server to get the OAuth Token. The URL to use is:

   https://myinstance.onenetwork.com/oms/oauth/access_token

   Table 16.19. Supported Parameters

   Parameter	Required?	Description
   client_id	Y	ID of your registered application in ONE.
   client_secret	Y	Client secret given when you registered your application in ONE.
   code	Y	Value of the "code" parameter provided to your callback url.

   This will respond with your token as follows:
   {"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a", "token_type":"bearer"}

5. Access APIs.

   Once generalledger.net has its token, it can begin accessing ONE APIs. It can be passed as a URL parameter to any REST request:

   https://myinstance.onenetwork.com/oms/rest/userprofile/roles?access_token=e72e16c7e42f292c6912e7710c838347ae178b4a

   Or it can be passed as a request header:

   Authorization: token e72e16c7e42f292c6912e7710c838347ae178b4a