Postman in the popular API development tool. RESTful Workshop recommends this tool when exploring the RESTful API Engine. The engine is an integral part of applications created with Code On Time. It supports the authentication with API Key and OAuth 2.0 Authorization Code flows. It relies on access tokens to identify users when client apps are making requests to the RESTful API.

Postman makes it easy to acquire an access token with OAuth 2.0 Authorization Code flow with PKCE. Native apps will follow a similar pattern when implementing the token acquisition from an app built with Code On Time.

Workshop segments SPA4 and SPA5 explain how to build a single page application capable of authenticating users with OAuth 2.0 Authorization Code flow with PKCE. This particular flow is suitable for native mobile applications and single page applications. Both are not able to “keep a secret”, since the source code, binaries, and external settings can be explored by 3rd parties.

Proof Key of Code Exchange (PKCE) provides the means of producing a dynamic secret instead of relying on a static secret. Dynamic secret ensures a secure exchange of an authorization code for an access token between the client application and the server.

Request Authorization

Authentication with most OAuth 2.0 flows starts when users are pressing the Login button in the client app.

1. The browser window is redirected to an Authorization URL pointing to the backend web application. Native apps open a special Web View for the same purpose.
2. Users are asked to sign into a familiar application they know and trust.
3. Users confirm their identity with the optional 2-Factor Authentication or set up a new account.
4. Authenticated users are asked to allow access to their account.
5. If account access is granted to the client app, then the backend application will redirect to the location specified in the Authorization Url.
6. Client application collects the authorization code specified in the redirect URL by the backend.
7. Client exchanges the authorization code for an access token.
8. The token is retained by the client application and specified in the Authorization header of requests to identify the user to the backend.

Postman will act as a native client acquiring an access token from the RESTful Application created with Code On Time.

Developers will need to know the details of the client application registration and OAuth 2.0 API endpoints.

Start Postman and create a new HTTP request. Enter the localhost address of the backend application followed by the /v2 path in the request URL. Select the Authorization tab and choose OAuth 2.0 in the Type field. Additional settings will appear.

The Current Token section allows selection of the access token for the request authorization. The tokens are retained by Postman after each successful authorization request approved by the user.

The Configure New Token section allows capturing and naming the new tokens. Captured tokens will appear in the Available Tokens drop down of the Current Token section.

New Token Configuration

Here is the full view of the parameters required to configure the capturing of new tokens. This set of parameters allows collecting access tokens from any OAuth 2.0 Authorization server.

Applications created with Code On Time have the built-in OAuth 2.0 Authorization API and will work with any OAuth 2.0 client including Postman.

Follow these steps to configure the request on behalf of SPA4 to acquire a new token from the RESTful Application Backend created with Code On Time:

1. Token Name: enter admin as the value. Typically this is the user account name.
2. Grant Type: choose Authorization Code (With PKCE) in the dropdown.
3. Callback URL: enter http://localhost:9090/spa4.html#auth) as the value. This is the redirect_uri from the client application registration.
4. Auth URL: enter https://demo.codeontime.com/oauth2/v2/auth as the value. This is the href value from the authorize hypermedia control available in OAuth 2.0 API of the backend.
5. Access Token URL: enter https://demo.codeontime.com/oauth2/v2/token as the value. This is the href value from the token hypermedia control of the OAuth 2.0 API.
6. Client ID: enter TKuyzeDmIQKWFVncJcKpCXCWEmcsJP3kB9QpudegTrC as the value. This is the client_id from the client application registration.
7. Client Secret: leave the field value blank.
8. Code Challenge Method: set value to SHA-256.
9. Code Verifier: leave the field value black. Postman will automatically generate the value.
10. Scope: enter offline_access openid profile email as the field value. This space-separated list of scopes will yield the access_token, id_token, and refresh_token if the authorization request is approved by the user.
11. State: enter any random sequence of characters. For example, enter 12345.The state is returned with the authorization code upon approval of account access by the user. Client application will compare the specified value with the one specified in the url to detect the forged request.
12. Client Authentication: leave the default value.

Note that the port number in the localhost addresses above will be different for each implementation of the backend. Use the client application registration property values of your own backend application.

Click the Get New Access Token button. Postman will open a hosted browser window.

Sign into the backend application with the username admin and password admin123% to be greeted with the Account Access confirmation.

Allow account access to the Standalone SPA4 with RESTful Hypermedia and OAuth 2.0 client application. Postman is impersonating the SPA4 here and therefore its name is displayed at the top of the account access prompt.

Backend application will redirect to the URL specified in the Callback URL parameter in the Configure New Token settings. URL will be altered to include the authorization code value. It will also have the copy of the state parameter from the Authorization Url.

Confirmation of the successful authentication will close automatically after a short delay since the Postman will have only two minutes to exchange the authorization code for an access token. The response from the exchange will be presented in the Manage Access Tokens window.

Press the Use Token button to set the user identity of the HTTP request.

Developers can see the current Access Token and Header Prefix on the Authorization tab.

Developing With Tokens

Developers impersonate users in three easy steps when configuring an HTTP request:

1. Select Authorization tab of the HTTP Request
2. Set Type to OAuth 2.0.
3. Choose Access Token from the list of available tokens.

Tokens will expire periodically. Requests submitted to the backend application will return an error with HTTP code 401 when this happens. Developers can revisit the Authorization tab of the request and acquire a new token. Postman preserves the Configure New Token settings. A single click on the Get New Access Token button will open the backend application in the hosted browser. Developer signs in on behalf of a user and approves account access. The new access token is available!

Learn how to build a single page application with OAuth 2.0 Authorization and OpenID.

This tutorial is part of the RESTful Workshop designed to empower individual developers and teams to create amazing enterprise-quality backends for mobile and web applications. Zero experience and no code is required to provide your data with the REST API conforming to the Level 3 of Richardson Maturity Model with the built-in OAuth 2.0 and Open ID Connect.