Using OAuth 2.0 for Web Server Applications
The Web Service OAuth 2.0 endpoint supports web server applications (e.g. PHP, Java, Python, Ruby, .NET, etc.). These applications may access a Resource while the user is present at the application or after the user has left the application. This flow requires that the application can keep a secret.
This article describes how to use OAuth 2.0 when accessing a Resource from a web server application.
Overview
This scenario begins by redirecting a browser (popup, or full page if needed) to a SW Combine URL with a set of query parameters that indicate the type of resource access the application requires. Like other scenarios, SW Combine handles the user authentication and consent, but the result of the sequence is an authorization code (as opposed to directly delivering an access token).
SW Combine returns the authorization code to the web server application in the query string.
After receiving the authorization code, the application can exchange the code for an access token and, in some cases, a refresh token. The application presents its client_id and client_secret (obtained during application registration) along with the authorization code when obtaining an access token and refresh token.
The application may access a Resource after it receives the access token.
If a refresh token is present in the authorization code exchange, then it may be used to obtain new access tokens at any time. This type of access to a Resource is called offline, since the user does not have to be present at the browser when the application obtains a new access token.
Forming the URL
The URL used when authenticating a user is https://www2.swcombine.com/ws/oauth2/auth/. This endpoint is accessible over SSL, and HTTP connections are refused.
| Endpoint | Description |
|---|---|
| https://www2.swcombine.com/ws/oauth2/auth/ | This endpoint is the target of the initial request for an access token. It handles active session lookup, authenticating the user, and user consent. The result of requests of this endpoint include access tokens, refresh tokens, and authorization codes. |
The set of query string parameters supported by the Web Service Authorization Server for web server applications are:
| Parameter | Values | Description |
|---|---|---|
| response_type | code | Determines if the OAuth 2.0 endpoint returns an authorization code. For web server applications, a value of code should be used. |
| client_id | the client_id obtained from the Web Service console | Indicates the client that is making the request. The value passed in this parameter must exactly match the value shown in the Web Service console. |
| redirect_uri | The redirect_uri values registered at the Application Registration Form | Determines where the response is sent. The value of this parameter must exactly match the registered value in the Web Service console (including the http or https schemes, case, and trailing '/'). |
| scope | space delimited set of permissions the application requests | Indicates the resource access your application is requesting. The values passed in this parameter inform the consent page shown to the user. There is an inverse relationship between the number of permissions requested and the likelihood of obtaining user consent. |
| state | any string | Indicates any state which may be useful to your application upon receipt of the response. The Web Service Authorization Server roundtrips this parameter, so your application receives the same value it sent. Possible uses include redirecting the user to the correct resource in your site, nonces, and cross-site-request-forgery mitigations. |
| access_type | online or offline | Indicates if your application needs to access a Resource when the user is not present at the browser. This parameter defaults to online. If your application needs to refresh access tokens when the user is not present at the browser, then use offline. This will result in your application obtaining a refresh token the first time your application exchanges an authorization code for a user. |
| renew_previously_granted | Optional string with value: 'yes' | Indicates whether previously granted permissions should be renewed if not explicitly included within the scope parameter. Defaults to not renewing previously granted permissions. |
An example URL is shown below.
https://www2.swcombine.com/ws/oauth2/auth/? scope=character_read%2Fcharacter_write& state=%2Fprofile& redirect_uri=https%3A%2F%2Fwww.example.com.com%2Foauthcallback& response_type=code& client_id=812741506391
Handling the Response
The response will be sent to the redirect_uri as specified in an access token request. If the user approves the access request, then the response contains an authorization code and the state parameter (if included in the request). If the user does not approve the request the response contains an error message. All responses are returned to the web server on the query string, as shown below:
An error response:
https://www.example.com.com/oauthcallback?error=access_denied&state=/profile
An authorization code response:
https://www.example.com.com/oauthcallback?state=/profile&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7
After the web server receives the authorization code, it may exchange the authorization code for an access token and a refresh token. This request is an HTTPs post, and includes the following parameters:
| Field | Description |
|---|---|
| code | The authorization code returned from the initial request |
| client_id | The client_id obtained during application registration |
| client_secret | The client secret obtained during application registration |
| redirect_uri | The URI registered with the application |
| grant_type | As defined in the OAuth 2.0 specification, this field must contain a value of authorization_code |
The actual request might look like:
POST ws/oauth2/token/ HTTP/1.1 Host: www2.swcombine.com
Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=8819981768& client_secret={client_secret}& redirect_uri=https://www.example.com.com/oauthcallback& grant_type=authorization_code
A successful response to this request contains the following fields:
| Field | Description |
|---|---|
| access_token | The token that can be sent to a Resource |
| refresh_token | A token that may be used to obtain a new access token. Refresh tokens are valid until the user revokes access. This field is only present if access_type=offline is included in the authorization code request. |
| expires_in | The remaining lifetime on the access token |
A successful response is returned as a JSON array, similar to the following:
JSON
{
"access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in":3920
}
XML
<?xml version="1.0" encoding="utf-8"?> <OAuth> <access_token>1/fFAGRNJru1FTz70BzhT3Zg</access_token> <expires_in>3920</expires_in> </OAuth>
Other fields may be included in the response. Your application should allow additional fields to be returned in the response. The set shown above is the minimum set.
Calling a Resource
After your application has obtained an access token, your application can access a Reource by including it in either an access_token query parameter or an Authorization: OAuth HTTP header.
For example, a call to the Character Resource using the access_token query string parameter looks like the following:
GET https://www2.swcombine.com/ws/v2.0/character/Testing%20Character?access_token=1/fFBGRNJru1FQd44AzqT3Zg
A call to the same resource using the access_token Authorization: OAuth HTTP header looks like the following:
GET /ws/v2.0/character/Testing%20Character HTTP/1.1 Authorization: OAuth 1/fFBGRNJru1FQd44AzqT3Zg Host: www2.swcombine.com
You can try either out in the CURL command line application. Here's an example of the query string parameter option:
curl https://www2.swcombine.com/ws/v2.0/character/Testing%20Character?access_token=1/fFBGRNJru1FQd44AzqT3Zg
And the HTTP header option:
curl -H "Authorization: OAuth 1/fFBGRNJru1FQd44AzqT3Zg" https://www.swcombine.com/ws/v2.0/character/Testing%20Character
Offline Access
In some cases, your application may need to access a Resource when the user is not present. Examples of this include backup services and applications that make GNS posts exactly at 8am on Monday morning. This style of access is called offline, and web server applications may request offline access from a user. The normal and default style of access is called online.
When an application requests offline access, the user sees a consent page that indicates your application is requesting the ability to make requests without the user being present at the browser.
If your application needs offline access to a Resource, then the request for an authorization code should include the access_type parameter, where the value of that parameter is offline. An example request for offline access is shown below:
https://www2.swcombine.com/ws/oauth2/auth/? scope=character_read%2Fcharacter_write& state=%2Fprofile& redirect_uri=https%3A%2F%2Fwww.example.com.com%2Foauthcallback& response_type=code& client_id=812741506391& access_type=offline
The first time a given user's browser is sent to this URL, they see a consent page. If they grant access, then the response includes an authorization code which may be redeemed for an access token and a refresh token.
An example of an authorization code exchange is shown below:
POST ws/oauth2/token/ HTTP/1.1 Host: www2.swcombine.com
Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=8819981768& client_secret={client_secret}& redirect_uri=https://www.example.com.com/oauthcallback& grant_type=authorization_code
If this is the first time the application has exchanged an authorization code for a user, then the response includes an access token and a refresh token, as shown below:
JSON
{
"access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in":3920,
"refresh_token":"1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}
XML
<?xml version="1.0" encoding="utf-8"?> <OAuth> <access_token>1/fFAGRNJru1FTz70BzhT3Zg</access_token> <expires_in>3920</expires_in> <refresh_token>1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI</refresh_token> </OAuth>
Important
When your application receives a refresh token, it is important to store that refresh token for future use. If your application loses the refresh token, it will have to re-prompt the user for consent before obtaining another refresh token.After your application receives the refresh token, it may obtain new access tokens at any time. See the section on refresh tokens for more information.
The next time your application requests an authorization code for that user, the user will not be asked to grant consent (assuming they previously granted access, and you are asking for the same scopes). As expected, the response includes an authorization code which may be redeemed. However, unlike the first time an authorization code is exchanged for a given user, a refresh token will not be returned from the authorization code exchange. The following is an example of such a response:
JSON
{
"access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in":3920
}
XML
<?xml version="1.0" encoding="utf-8"?>
<OAuth>
<access_token>1/fFAGRNJru1FTz70BzhT3Zg</access_token>
<expires_in>3920</expires_in>
</OAuth>
Using a Refresh Token
As indicated in the previous section, a refresh token is obtained in offline scenarios during the first authorization code exchange. In these cases, your application may obtain a new access token by sending a refresh token to the Web Service OAuth 2.0 Authorization server.
To obtain a new access token this way, your application performs an HTTPs POST to https://www.swcombine.com/ws/oauth2/token/. The request must include the following parameters:
| Field | Description |
|---|---|
| refresh_token | The refresh token returned from the authorization code exchange |
| client_id | The client_id obtained during application registration |
| client_secret | The client secret obtained during application registration |
| grant_type | As defined in the OAuth 2.0 specification, this field must contain a value of refresh_token |
Such a request will look similar to the following:
POST ws/oauth2/token/ HTTP/1.1 Host: www2.swcombine.com
Content-Type: application/x-www-form-urlencoded client_id=8819981768& client_secret={client_secret}& refresh_token=1/6BMfW9j53gdGImsiyUH5kU5RsR4zwI9lUVX-tqf8JXQ& grant_type=refresh_token
As long as the user has not revoked the access granted to your application, the response includes a new access token. A response from such a request is shown below:
JSON
{
"access_token":"1/fFBGRNJru1FQd44AzqT3Zg",
"expires_in":3920
}
XML
<?xml version="1.0" encoding="utf-8"?>
<OAuth>
<access_token>1/fFAGRNJru1FTz70BzhT3Zg</access_token>
<expires_in>3920</expires_in>
</OAuth>
Revoking a Refresh Token
In some cases a user may wish to revoke access given to an application. A user can revoke access by visiting the Web Service Console in Account Settings and explicitly revoking access. It is also possible for an application to programmatically revoke the access given to it. Programmatic revocation is important in instances where a user unsubscribes or removes an application. In other words, part of the removal process can include a request to ensure the permissions granted to the application are removed.
To programmatically revoke a token, your application makes a request to https://www2.swcombine.com/ws/oauth2/revoke and includes the refresh token and client id as parameters:
curl https://www2.swcombine.com/ws/oauth2/revoke?token={refresh_token}&client_id={client_id}
If the revocation was successfully processed, then the status code of the response is 200. For error conditions, a status code 400 is returned along with an error code.
