This articles details a Forum Sentry use case utilizing the OAuth 2.0 Password grant type.
The OAuth 2.0 Password Grant type is a simple way to obtain an access token by providing a username and password. The Password Grant type is typically used by first-party clients (e.g. a service’s own mobile apps) and is not usually made available to third party developers.
As this grant type involves the client application asking the user for their username and password, it should not be used by third party clients. In this flow, the user credentials (username and password) are validated by the OAuth provider and then exchanged directly for an access token.
Forum Sentry plays two roles in this use case sample:
1. API Security Gateway - Securing the online OpenWeatherMap REST API, requiring a valid OAuth access token in order to access the API.
2. OAuth Server - Validating a pre-shared client ID and client secret (client app credential) along with a username/password (user's credentials) and returning an access token. Later, the Sentry OAuth policy (Authorization Server) also validates the provided access tokens and returns the corresponding scope and user attribute details.
Please note that this is just one example of a Password grant type use case supported by Forum Sentry.
For more information on the OAuth 2.0 Password Grant please see:
Step 1. Get an OAuth Access Token
1. A secure (confidential) web app client makes a call to the /token directory of the OAuth policy in Sentry to get an access token. In this sample the 'Client Type' is 'Confidential', so there are 2 sets of credentials that need to be provided:
a. Client App credentials - HTTP basic auth header (Authorization header)
b. The User credentials - username/password query parameters in the payload of the HTTP POST
Figure 1. Example request to obtain an access token
2. The Sentry OAuth policy (figure 2) validates both sets of credentials, stores user attribute data with the access token, and then returns the access token to the client (figure 3)
Figure 2. The Sentry OAuth Policy configured for the Password grant type with two ACLs set
Figure 3. Example response from the OAuth Policy with an access token
Step 2. Invoke the OpenWeather Map API with an Access Token
1. A secure web app client makes an API call into Sentry and includes the Access Token as a Bearer token in the HTTP Authorization Header.
Figure 4. Example GET request to the OpenWeatherMap API via Forum Sentry
2. The Sentry REST Policy validates the access token by calling the OAuth policy at the /userinfo endpoint. Upon successful validation of the access token, the OAuth policy returns the user attribute information associated to the token.
Figure 5. Sentry log showing access token validation and user attribute data returned
3. Sentry authorizes (allows or blocks) the API call based on the user attribute information returned from the OAuth policy.
Figure 6. The Sentry task list on the REST Policy that validates the access token and checks user attribute data for authorization
Attached are Sentry policies (FSG) and a SOAPSonar project file (SSP) that can be used to test this use case.
1. Sentry Policies - The FSG can be imported into Sentry v8.7 and later. The import password is password. This FSG contains both the OAuth Policy and the REST Policy with all dependencies (network policies, task lists, user groups, etc). It is recommended that you back up your existing Sentry config (FSX) prior to importing this sample.
2. SOAPSonar Project - This SOAPSonar project file has test cases for obtaining access tokens, obtaining refresh tokens, obtaining the user information, and accessing the OpenWeatherMap API.
The following changes are needed to test this use case with the provided files:
1. After importing the FSG file into Sentry, change the HTTPS remote policy "HTTPS_8443_to_Sentry_OAuth" to point to your own Sentry listener IP.
2. After importing the SOAPSonar project file, change the Request URI of each test case, replacing the REPLACE_ME value with your Sentry IP or hostname.
3. Use the test case "Token" to obtain an access token directly from the OAuth policy.
4. Use the test case "UserInfo" to provide an access token to the OAuth policy directly to get back a JSON payload with the user attribute data. This simulates with the Sentry REST Policy task list does to validate the access token.
5. Use the test case "WeatherAPI with Token - DevOps" to invoke the Weather API via Sentry. Include the access token in the HTTP Authorization header.
6. Use the test case "Refresh Token" to obtain a new access token. Pass the refresh token obtained from the original /token call to get a new access token.