OAuth 2.0 Web Server Scenario

xTuple's OAuth 2.0 Web Server authentication scenario is modeled off of Google's OAuth 2.0 for Web Server Applications scenario. You should review Google's documentation for that scenario to become familiar with this type of OAuth 2.0 exchange.

To use the Web Server authentication scenario with xTuple's OAuth 2.0 Server, you need to install the OAuth 2.0 extension on your xTuple database. Installation instructions can be found in the OAuth 2.0 extension's README file. When adding a new OAuth 2.0 Client, be sure to select a "Client Type" of "Web Server". You will also need to enter at least one "Redirect URI" for that client. You can get the remaining items you will need to preform a "Web Server" OAuth 2.0 exchange from the fields on the OAuth 2.0 Client workspace in the Mobile-Web Client.

An OAuth 2.0 "Web Server" Client will need the following fields to make an authentication exchange with xTuple's OAuth 2.0 Server:

• OAuth 2.0 Client ID - Example:

  example_f8ad6a5f-883b-4d41-ea6a-1971af1919e8

• OAuth 2.0 Client Secret - Example:

  example_f8ad2a5f-886b-4d41-ea6a-1981af1914e6

• Scope - Example:

  https://your-demo.xtuplecloud.com/your-db-name/auth

• Note: You can get a list of valid scopes for your xTuple API requests from xTuple's APIs Discovery Service

• Authorization endpoint - Example:

  https://your-demo.xtuplecloud.com/your-db-name/dialog/authorize

• Token endpoint - Example:

  https://your-demo.xtuplecloud.com/your-db-name/oauth/token

The OAuth 2.0 "Web Server" Client will need to expose a "Redirect URI" that your xTuple OAuth 2.0 Server can POST an "authorization code" to. The OAuth 2.0 "Web Server" Client is responsible for the code needed to process that POST, extract the "authorization code" and exchange it for an "access token" by POSTing it to the Token endpoint of the OAuth 2.0 Server.

• Redirect URI - Example:

  https://your.oauth2.client.example.com/auth/your-app/callback

Client Examples:

Google's OAuth 2.0 Playground:

Since xTuple's OAuth 2.0 Server is modeled off of Google's, you can use Google's OAuth 2.0 Playground to access xTuple's REST API. Collect the OAuth 2.0 Client information outlined above for the client you added in the Mobile-Web's OAuth2 workspace. The Redirect URI that Google's OAuth 2.0 Playground uses is:

 https://developers.google.com/oauthplayground

Make sure and add this Redirect URI to the list in the Mobile-Web's OAuth 2.0 Client you will be using. Visit Google's OAuth 2.0 Playground and click the gear icon in the upper right. Change the "OAuth endpoints" to "Custom" and fill out the form using your registered OAuth 2.0 Client information outlined above. Set the "Access token location" to "access_token URL parameter". The "OAuth 2.0 configuration" setting should look similar to this:

Note: For the OAuth 2.0 exchange to work with your xTuple OAuth 2.0 Server, you need to have a few things ready first:

1. The datasource must be running
2. You should be able to access the login page of the Mobile-Web client
3. When using an "Auth flow" of "Server-side", Google will attempt the exchange from their backend server, not your browser. This means your xTuple OAuth 2.0 Server must be exposed to the public facing internet via a valid domain name. xTuple's Free Demo's fit this requirement, but if you are doing local development, this will not work. You will get a DNS error in the OAuth 2.0 Playgound (DNS lookup failed for...). For local development, try using one of the other examples where you run your own OAuth 2.0 Client as a Web Server. You can also consider pointing a DNS entry to your public IP and proxy a port to your local dev server so Google can access it from the public internet.

Close the "OAuth 2.0 configuration" settings and enter your own scope in the "Step 1" form. It should look similar to this:

Click "Authorize APIs" and you will be redirect to your xTuple Mobile-Web client login screen. Login with a valid account and approve the authorization request. You will then be redirected back to Google's OAuth 2.0 Playground, ready to complete "Step 2". Click "Exchange authorization code for tokens". The "authorization code" will be exchanged for an "access" and "refresh" token. It should look similar to this:

Note: Your "Access Token" will only be valid for 1 hour. You must click "Refresh access token" when it expires to get a new valid "Access Token".

You can now use the "Access Token" to make REST API requests to your xTuple server. See the REST Request methods for example requests.

Node.js:

With a few tweaks to Passport's Google OAuth 2.0 strategy, you can connect to an xTuple OAuth 2.0 Server. We have created a simple OAuth 2.0 Web Server Client Example app that you can use to perform an OAuth 2.0 exchange with your xTuple OAuth 2.0 Server. Collect the OAuth 2.0 Client information outlined above for the client you added in the Mobile-Web's OAuth2 workspace. The Redirect URI that the OAuth 2.0 Web Server Client Example uses will be displayed in the "OAuth 2.0 Client Settings" form when it first loads. Be sure to add this Redirect URI to the OAuth 2.0 Client settings in the xTuple Mobile-Web OAuth2 workspace.

First, follow the instructions in that Example Client's README file to get it up and running.

Next, visit the Example Client app in your browser and fill out the "OAuth 2.0 Client Settings" form. It should look similar to this:

Note: For the OAuth 2.0 exchange to work with your xTuple OAuth 2.0 Server, you need to have a few things ready first:

1. The datasource must be running
2. You should be able to access the login page of the Mobile-Web client
3. The OAuth 2.0 Web Server Client Example will attempt the exchange from the server, not your browser. This means your xTuple OAuth 2.0 Server must be accessible from the server running the OAuth 2.0 Web Server Client Example app. If they are on different machines, make sure and use the correct IP or domain in the client setting URLs instead of "localhost".

Next, click on "Save Client Settings". You will then be prompted to "Login using the OAuth 2.0 Server":

Click that link and login to your xTuple OAuth 2.0 Server:

Approve the access request:

You will then be redirected back to the OAuth 2.0 Client Example where it will display your Access and Refresh Tokens. You can also click on "Refresh Access Token" on that page to get a new Access Token. It should look similar to this:

You can now use the "Access Token" to make REST API requests to your xTuple server. See the REST Request methods for example requests.

Some Other Language:

• TODO: Make some web server examples in PHP, Java, .Net etc.