Contents
Introduction
1. The regular OAuth API access
2. Automatic Refresh of Expired Tokens
3. Authorization with the User Password
4. Application Only Access with client_credentials
Conclusion
Introduction
OAuth became the de facto standard to access Web based APIs that require an authorization before the API functions can be called.
Typically it is necessary that an user gives permission to access the API on his behalf. However, it is also possible to access an API without the user presence and in some cases without requiring the authorization of a real user.
The PHP OAuth class supports several ways of calling an API without user interaction. Lets take a look at each of these access methods and how you can implement them using the OAuth client class.
1. The regular OAuth API access
In the regular OAuth API access, the user must be present to grant authorization to the application to access the API. Once the authorization is granted, the user does not need to be present to let the application perform API calls.
So, as long as the authorization tokens are set and have not expired, your application can make as many API calls as necessary.
Keep in mind that by default the OAuth client class uses PHP sessions to store the OAuth tokens retrieved during the authorization process. PHP sessions are only valid when the user is accessing as Web page of the same site on which the session was created.
So, if your application needs to make API calls when the user is not present, it needs to store the tokens somewhere, so they can be retrieved when your application needs them.
The usual way to store and retrieve tokens is to use a database. You can write application your own code to store the tokens in your application database. Usually you store one database table record for each user that authorized API access via OAuth.
In that case you need to know which variables of the OAuth class you need to save and restore later. Those variables are: access_token, access_token_secret (OAuth 1 only servers), access_token_expiry (for tokens that expire), access_token_type, refresh_token (for tokens that can be renewed when they expire).
Alternatively you may use a sub-class of the OAuth client class that comes with this package for storing tokens in your database. Currently the package comes with mysqli_oauth_client.php sub-class script for storing token values in a MySQL database. You can create other sub-classes of the database_oauth_client.php sub-class if you prefer to use a different database.
2. Automatic Refresh of Expired Tokens
Some API servers issue OAuth tokens that expire after a while. Those tokens need to be exchanged for new tokens when they expire. This done by sending a new request to the API server using a refresh token obtained previously when the last access token was retrieved.
The new access token and an eventual new refresh token replace the old tokens. So you discard the old tokens and use the new ones from then on.
The new token replacement happens next time you make an API call and the old token is expired. So it is very important that your machine time is absolutely accurate, or at least not delayed.
Refreshing expired tokens is a bit complicated process but fortunately the OAuth client class takes care of that for you transparently. If you are using one the database classes mentioned above, they take care of the token replacing process storing the new tokens in the database.
If you are not using one of those database classes, you need to check the variables mentioned above and update the stored tokens if necessary.
Some APIs like for instance Google's, only issue refresh tokens if you use a special token retrieval URL. Fortunately, the OAuth class can also take care of that using the correct token URL. Just set the offline class variable to true, and it will use a special URL to get the refresh token, so it can renew expired tokens automatically later.
The access to API offline using a database to store retrieved tokens and refresh tokens to replace expired tokens was already explained in a more detail article about Offline access to OAuth based APIs.
Other APIs like for instance Facebook's, issue access tokens that expire after a while but cannot be renewed automatically. In that case you need to prompt the user to come to the site and go through the whole OAuth authorization process again from the start.
Anyway, when that happens, as long as you are asking another API access token with the same permissions, the user will not see the authorization dialog again.
3. Authorization with the User Password
Some applications do not intend to access APIs on behalf of other users, but rather just a single user that is the application developer. In that case there are APIs that can return an access token using just the application developer user name and password.
This is good because the developer user does not have to be present when the access token is requested. He just needs to provide his user name and password to his own application scripts that access the API. This is known as the Resource Owner Password Credentials authorization flow.
The OAuth client class also supports this password based authorization flow. All you need to do is to set the class variables oauth_username and oauth_password to the developer user name and password respectively.
The process of calling the API is the same as for the regular OAuth flow using the CallAPI function.
There are APIs like for instance Salesforce's, that support this type of password based authorization flow.
4. Application Only Access with client_credentials
Another form of performing API calls without user interaction is to make application only API calls using the client credentials, i.e. the application credential values that you set in the client_id and client_secret variables.
In this case you need to set the grant_type class variable to client_credentials. This way the class obtains an access token automatically without requiring an user to be present, just like with the password based authorization flow. The only difference is that you never need to provide any user name or password to your scripts.
APIs like Twitter's support this type of application only authorization using OAuth 2 protocol. Keep in mind that for regular OAuth API access on behalf of a real user, you need to use the OAuth 1.0a protocol instead. The OAuth client class supports both types of OAuth authorization flow.
Conclusion
OAuth is a reasonably complex protocol, especially because there are two main protocol versions and there is no consensus regarding which version each API uses.
Fortunately the OAuth client protocol tries to abstract all the protocol versions in a single class, so you do not need to learn too much about the inner workings of the protocol.
Additionally, the class comes with a separate configuration file named oauth_configuration.json that defines values to configure the class for different types of well-known OAuth based API servers. This way you practically only need to set the server class variable to the name of the API server you want to access, thus without having to waste too much time studying the OAuth protocol.
Still there may be other servers for which there is not yet any pre-defined configuration to get you started quickly. If you want to use one of those servers, or you have any other question, please post a comment to this article now.
