Still not clear? Let me explain using a real world example. When you stay in a hotel you get a plastic keycard (mag stripe or chip) that will give access to your room. Just swipe or wave the card and you have access. Simple as that. Let’s say that you take the card with you and some weeks later return to the hotel for another stay. Your card that gave you access before is now null and void. Since you are not a guest anymore (among others you stopped paying) your access is revoked.
That is the mechanism behind an OAUTH2 token. You are granted access to a resource for a specific amount of time, after which the access is revoked unless the token is refreshed.
This mechanism is extremely handy when you want to give access to a resource, service or an API. It is not only WSO2 API Manager, a lot of online services like Google use OAUTH2 to give (and revoke) access to resources.
Adding OAUTH2
When definining your API you can add the need for OAUTH2 tokens to the specific items / URI templates of your API as you can see from this screenshot. When adding the OAUTH2 requirement you can choose between the following options:
- None
- Application
- Application User
- Application & Application User
Each of these options (in the dropdown window when you click the down arrow) will define a specific level of OAUTH2. None of course does not require any OAUTH2 token. Application: Authentication is done by the application. The resource accepts application access tokens. Application User: Authentication is done by the application user. The resource accepts user access tokens. Application and Application User: Both application and application user level authentication is applied.
The differences are subtle and the choice for each of the scenarios depends on your use case of the API Store.
Token time
By default the predefined time for a token is 3600 seconds which of course is an hour. However that can be changed. A value of -1 in the duration will make the token valid for ever, or at least for a very long time of about 3 million centuries.
Grant types
OAUTH2 works with so called grant types that actually determine how an access token is requested.
The OAUTH2 specification (https://tools.ietf.org/html/draft-ietf-oauth-v2-22) defines four grant types: authorization code, implicit, resource owner password credentials, and client credentials, as well as an extensibility mechanism for defining additional types.
You have the possibility to write custom grant types, in conjunction with the WSO2 Identity Server. OF course you need to change the configure the API Manager to use the Identity Server as key manager rather than the embedded keymanager in the API Manager. Please see the documentation https://docs.wso2.com/display/AM210/Configuring+WSO2+Identity+Server+as+a+Key+Manager for more information.
Extending the grant types means writing a java program, making it into a .jar file and adding it to the server. The highlevel steps are:
- In your java program, implement the following two extensions:
GrantTypeHandler– This is the implementation of the grant type. Here you can implement the way, it must be validated and how token must be issued.GrantTypeValidator– This is used to validate the grant request that is sent to the /tokenendpoint. You can define what parameters must be in the request and define the validation of them.
- When you finished your implementation, package your class as a .jar file (mvn clean install) and place it in the
<IS_HOME>/repository/component/libdirectory. It will be hot deployed but the grant type must also be registered so a restart of the Identity Server is needed - To register the custom grant type, configure the
<IS_HOME>/repository/conf/identity/identity.xmlfile by adding a new entry, in a manner similiar to the following example, under the<OAuth><SupportedGrantTypes>element.
This will allow you to use other claims / credentials
Please check the WSO2 Identity Server documentation for more complete instructions.
Currently, the WSO2 API Manager supports the following grant types:
| Grant type | Purpose / Goal | Required Parameters | Use |
| Authorization Code Grant | Two step approach to obtain a token by first getting an authorization code and exchanging it for a token. | Grant, type. Client id, scope(s), redirect URL | For single webpages and untrusted third party apps |
| NTLM Grant | Two step approach, base 64 encode the client key and secret. Reguest an NTLM token and submit these for an OAUTH2 token | NTLM token, base64 encoded client key / client secret | NTLM is the successor of the authentication protocol in Microsoft LAN Manager (LANMAN), an older Microsoft product. |
| Password Grant | You can obtain an access token by providing the resource owner’s username and password as an authorization grant. It requires the base64 encoded string of the consumer-key:consumer-secret combination | Username, password, base64 encoded client key and client secret | |
| SAML Extension Grant | The SAML extention grant uses an Identity Provider (for the SAML assertions) and the definition of a Sservice provider to exchange the tokens | SAML token, client key, client secret | For exchanging of SAML tokens to OAUTH2 tokens in case of Single Sign On |
| Client Credentials Grant | Client credentials are used as an authorization grant when the client requests access to protected resources based on an authorization previously arranged with the authorization server | Client key, client secret | Client credentials can be used when the authorization scope is limited to the protected resources belonging to the client.. |
| Refresh Token Grant | After an access token is generated, sometimes you might have to renew the old token due to expiration or security concerns. Use the refresh token that was issued when the access token was generated. | Refresh token that was issued with the access token. | Refresh tokens are issued for all other grant types other than the implicit grant as recommended by the OAuth 2.0 specification. |
As an example the Client Credentials Grant setting in SOAPUI where you can clearly see the parameters is takes.
Signing up of an API
When you sign up for an API you will see that when you generate the client key (sometimes called Client Identification / Client Secret you can indicate the grant types to generate Access Token. The client key and client secret are very long keys that are used in many grant types.
Refreshing and Revoking an Access Token
As we can determine the time an access token is valid, from ‘forever’ with -1 as a value to the default of 3600 seconds we must be able to refresh as well as revoke an access token. Changing the default expiration time is done in the
<APIM_HOME>/repository/conf/identity/identity.xml.
Look for the <AccessTokenDefaultValidityPeriod> xml tag BEFORE you start the API Manager. Additionally, consider any Time Skew for servers which clocks are not synchronized.
For refresh, there is a specific grant type: Refresh Token Grant which will give you upon sending your refresh token, a new access token as well as a new refresh token. The latter of course can be used to get a new set of tokens.
If you do not have a refresh token you need to get a new access token using one of the grant types we discussed earlier like client credentials grant or password grant.
To revoke an access token, someone with admin credentials (or sufficient user credentials) can use the Revoke API to revoke the access token. This entails making a REST call to the revoke api that is deployed on the API Manager with the token to be revoked and the base64 encoded client key and client secret.
If you wish to remove old tokens that might remain active in the Gateway cache, you need to configure the <RevokeAPIURL> element in the <API-M_HOME>/repository/conf/api-manager.xml file by providing the URL of the Revoke API that is deployed in the API Gateway node. The revoke API invokes the cache clear handler. Revoked, inactive and expired tokens are stored in IDN_OAUTH2_ACCESS_TOKEN table that needs periodical cleaning otherwise it might impact performance.
Keep in mind that when tokens are cached the tokens may live for the duration of the cache expiry. See the documentation on how to clear the token cache.
Key, secret and tokens
So, what do all these things look like:
Here you see an example of a Consumer Key and Consumer Secret. The actual generated token is shown a bit lower. The API Manager as part of the Tryit functionality allows you to regenerate an Access token.
This is the generated token that needs to be included in a call to the API, whether you are using a tool like Curl, Postman or Advanced Rest Client or from a java program or any other client.
Wrapping up
OAUTH2 is all about authorization. With an OAUTH2 token you are granted access to a resource because of the fact that you have the token. It can be renewed and revoked offering a temporary access rather than an eternal access (the analogy of having a house key, if you do not change the locks you have access for ever).
OAUTH2 however requires a key manager that can validate tokens, issue and renew tokens and even revoke them. The possibility to create a custom OAUTH2 grant type allows you to use your preferred client ID in generating these token, modifying the system to your liking!
OAUTH2 is here to stay, that is for sure.
Dowload our white paper below to read more about API Management / API Gateway.
