Until Now!
PHP has progressed a long way in the past year. We now have a package manager with many tools to help in project development, but there is still a lack of good API authentication tools out there. Sure, people try to roll their own API authentication setup for their PHP application, but we have a saying in the office.
“Friends don’t let friends build authentication.”
The Stormpath PHP SDK is here to help with all of your API Authentication requirements.
We have shown you before what goes into making a great RESTful API. Now we can help you protect that API with PHP API authentication!
Create API Keys for Your PHP Application
In the past, APIs used a basic username and password to authenticate developers trying to access them. This is a less secure way of maintaining security of your API. A much more secure way is using API Keys for each user. With the Stormpath PHP SDK, this is now very easy!
Stormpath supports two different ways to grant API keys to developers using your service. The first is to create the keys manually through the Stormpath admin UI. This is quick and easy for small API’s with few users, but will soon become overwhelming as you gain more users. That is why we introduced API Key creation and management from the SDK.
The first step is to create a new user for the developer. Use the Account resource to instantiate a new account, then create it on the application.
|
1 2 3 4 5 6 7 |
$account = \Stormpath\Resource\Account::instantiate( array('givenName' => 'Joe', 'surname' => 'Stormtrooper', 'password' => 'Changeme1')); $application->createAccount($account); |
If a developer already has an account, just get the user object in the same way. Using the account object, run the method createApiKey. This will create an API key for the user and return the id and secret.
|
1 2 3 4 |
$apiKey = $account->createApiKey(); $apiKeyId = $apikey->id; $apiKeySecret = $apikey->secret; |
Understanding PHP API Authentication
Now that your developers have API keys for your API, we can authenticate them. First though, we need to understand the different kinds of authentication. Stormpath offers two different kinds of authentication for your convenience.
Basic Authentication for API
Basic authentication is, well, the most basic form of authentication. It passes an authorization header as part of the request. This header is base64 encoded and prefixed with the basic keyword.
The PHP SDK responds to these requests in an intuitive way. As the developer of the API, you have two ways to handle these requests. The ApiRequestAuthenticator or the BasicRequestAuthenticator will both respond to this request. We will go into examples on how to use this a little
later.
OAuth2 Authentication for PHP API
Stormpath gives you seamless integration of the OAuth2 client credentials authentication type. Client credentials is one of four different types of of OAuth authentication. The developer will use a token created from the ID and secret for all future requests. For more information on this, please read the OAuth RFC. Again, the PHP SDK makes development easy to respond to these requests. ApiRequestAuthenticator will respond to these requests and decide what kind of request it is. To force your developers into the OAuth Authentication, use OAuthRequestAuthenticator. This will not allow Basic Authentication like ApiRequestAuthenticator does.
The Different Types of Authenticators
The Stormpath PHP SDK has a few different types of Authenticators that you can use. We try to make it as easy as possible for the API developer to respond to requests as broad or as specific as they want. To understand this, we must first understand the different ideologies. The PHP SDK has four different ways to authenticate a developer on an API:
-
API Request Authenticator
The first is the API that does not care how we authenticate. This will use the
ApiRequestAuthenticator. The SDK will determine for you how the developer wants to authenticate. This will work for both Basic and OAuth authentication types. -
Basic Request Authenticator
The second is where the API will only respond to basic authentication requests. For this, you will use
BasicRequestAuthenticator. -
OAuth Client Credentials Request Authenticator
Next, we have the API that wants to respond to only OAuth requests. This will use
OAuthRequestAuthenticatorand will not respond to basic requests. The SDK also offersOAuthClientCredentialsRequestAuthenticatorthat will respond only when requesting a token. This allows you to add in logic during the token creation process. -
OAuth Bearer Request Authenticator
The last authenticator is the one that responds to only a bearer request.
OAuthBearerRequestAuthenticatorwill respond only when the developer passes a Bearer authorization header. The header will need to contain the token that the client credentials authenticator created.
Protecting Your API
As you can see from above, the Stormpath PHP SDK tries to make it easy for you to protect your API. For our PHP API authentication examples below, we are going to be protecting an API for our Stormtrooper inventory. Let’s assume we have an endpoint to get all equipment for trooper tk421.
Setting up Basic PHP API Authentication Requests
Our first task will be setting up the route for our developers to get the equipment for the trooper. We will use /troopers/tk421/equipment. Now, we will need to create some logic in this route that needs authentication. To have this logic available for other routes, set it up as middleware.
|
1 2 3 |
$request = \Stormpath\Authc\Api\Request::createFromGlobals(); $result = new BasicRequestAuthenticator($application)->authenticate($request); |
So what is going on here? You first need to create a new request object. You do this from the function createFromGlobals() on the Request class. In the background, the SDK is pulling the headers from the request headers. It then generates the Request object we can use to authenticate against.
Create a new instance of the BasicRequestAuthenticator next and pass in the application object. You are now ready to authenticate the request. If all is valid and the user has access, the SDK will return the account object. What does this look like from the developer’s end? They make a request to your API with the basic authorization header.
|
1 2 3 4 5 |
GET /troopers/tk421/equipment Accept: application/json Authorization: Basic MzRVU1BWVUFURThLWDE4MElDTFVUMDNDTzpQSHozZitnMzNiNFpHc1R3dEtOQ2h0NzhBejNpSjdwWTIwREo5N0R2L1g4 Host: api.trooperapp.com |
Remember the API key we generated for the developer at the beginning of this post? This is what the authorization header consists of. The encryption is a base64 encoded apiKeyID:apiKeySecret.
That is it for basic authentication for your trooper API. Of course, you can use ApiRequestAuthenticator in place of BasicRequestAuthenticator. They both return the same data, but BasicRequestAuthenticator only allows basic authorization headers.
Setting Up OAuth Requests
The OAuth requests are a lot more secure. This is because the developers only have to pass their id and secret once. They will make a post request to your API which returns a bearer token. This token is what all future requests use to authenticate themselves.
There are two steps here. The first step is to respond to the post request to supply a bearer token. The standard for this endpoint is /oauth/token. The developer makes a post request to this route. This post request looks like basic authentication, but has a body of ‘grant_type=client_credentials’.
|
1 2 3 4 5 6 7 |
POST /oauth/token Accept: application/json Authorization: Basic MzRVU1BWVUFURThLWDE4MElDTFVUMDNDTzpQSHozZitnMzNiNFpHc1 Content-Type: application/x-www-form-urlencoded Host: api.trooperapp.com grant_type=client_credentials |
The second step is to create another route to respond to this request. Your middleware for this request will look close to the basic request. The difference here is you can use one of three authenticators. We will use the OAuthClientCredentialsAuthenticator for this example.
|
1 2 3 |
$request = \Stormpath\Authc\Api\Request::createFromGlobals(); $result = new OAuthClientCredentialsRequestAuthenticator($application)->authenticate($request); |
Side Note: For more general authenticators you would use;
ApiRequestAuthenticatorandOAuthRequestAuthenticator.
These respond to all requests or OAuth only requests, respectively.
Your request object will now give you access to the token to provide to your developer. This token allows the developer to authenticate with a bearer token instead of id and secret. For all future requests, the developer will use the bearer token for authorization.
|
1 2 3 4 5 |
GET /troopers/tk421/equipment Accept: application/json Authorization: Bearer 7FRhtCNRapj9zs.YI8MqPiS8hzx3wJH4.qT29JUOpU64T Host: api.trooperapp.com |
Then for your middleware on your route, you can use one of three request authenticators again. For our example we will be verbose and use OAuthBearerRequestAuthenticator.
|
1 2 3 |
$request = \Stormpath\Authc\Api\Request::createFromGlobals(); $result = new OAuthBearerRequestAuthenticator($application)->authenticate($request); |
The result of a successful authentication will contain the account object. From here, the developer has access to the API and your application can continue.
PHP API Authentication Summary
So now you know API Authentication doesn’t need to be difficult. I’ve shown you how to create API keys for your developers easily and efficiently. I’ve discussed the two basic types of authenticators, basic and Oauth2, and how to make them work for you. Lastly, and most importantly, I’ve laid out how Stormpath PHP SDK makes protecting your API straightforward and uncomplicated.
Now, you can move forward knowing your API is safe and secure!
Feel free to drop a line to our support team or to me personally anytime.
Like what you see? Follow @goStormpath to keep up with the latest releases.