This quickstart covers building an API protected by an Auth0-issued access token. This type of API is typically consumed by:

• Mobile, desktop, and other native applications using the Native login flow
• CLIs, daemons, or services running on your back-end using the Client Credentials Flow

If this API is only consumed by a web application on the same domain (in the case of AJAX actions or lazy loading content for an authenticated user) then the API protection should be handled by the application itself and the login flow secured by Auth0.

Protecting your Laravel API requires a middleware which will check for and verify a bearer token in the Authorization header of an incoming HTTP request. We'll do that using tools provided by the laravel-auth0 package.

Install laravel-auth0 using Composer.

The laravel-auth0 plugin comes with a configuration file that can be generated using Artisan. First, generate the configuration file from the command line:

Select the Auth0\Login\LoginServiceProvider option. After the file is generated, it will be located at config/laravel-auth0.php. Edit this file to add the configuration values needed to verify incoming tokens:

In more detail:

• authorized_issuers is an array of allowed token issuers. In this case it would simply be an array with just your tenant URL.
• api_identifier is the Identifier field of the API created above.
• supported_algs is the Signing Algorithm field of the API created above. This value should be an array but only have a single value, RS256.

By default, Apache does not parse Authorization headers from incoming HTTP requests. You may need to add the following to the .htaccess file for your application:

For the two private API routes, we'll need a middleware to check for a bearer token in an Authorization header for the request and then verify that the token is valid. We'll create that middleware using the make:middleware Artisan command:

Now, let's implement the handle() method that Laravel will call automatically for the route:

This middleware:

• Checks that there is a Bearer token and stops the request if one was not found.
• Pulls in the configuration values needed to verify the token.
• Attempts to decode the token, catching any exceptions thrown if it is expired, malformed, or otherwise invalid.

Next, we register this middleware we in the HTTP Kernel with the name jwt:

We are now able to protect individual API endpoints by applying the jwt middleware:

The /api/private route is now only accessible if a valid Access Token is included in the Authorization header of the incoming request. We can test this by manually generating an Access Token for the API and using a tool like Postman to test the routes.

In the Auth0 Dashboard:

1. Go to the Machine to Machine Applications tab for the API created above.
2. Authorize the API Explorer Application but leave all scopes unchecked.
3. Click the Test tab, then COPY TOKEN.

Now, let's turn on the Laravel test server:

Send a GET request to the public route - http://localhost:3000/api/public - and you should receive back:

Now send a GET request to the private route - http://localhost:3000/api/private - and you should get a 401 status and the following message:

Add an Authorization header set to Bearer API_TOKEN_HERE using the token generated above. Send the GET request to the prviate route again and you should see:

The middleware we created above checks for the existence and validity of an Access Token but does not check the scope of the token. In this section, we will modify the middleware created above to check for specific scopes.

Here are the changes to make to the CheckJWT middleware created above:

In summary:

• We added a $scopeRequired parameter to the handle() method with a default value of null. This will allow us to still handle private routes that do not need to check scope.
• At the end of handle(), we check if the route requires a scope and, if so, that the token includes it.
• We added a tokenHasScope() method to look for a specific scope within a decoded token.

Now, we can create a new middleware group that will check for both a valid token and a specific scope:

This route is now only accessible if an Access Token used in the request has a scope of read:messages.

To test this route, first send a GET request with no token to the private, scoped route - http://localhost:3000/api/private-scoped - and you should get a 401 status and the following message:

Add an Authorization header set to Bearer API_TOKEN_HERE using the same token from the previous section. Send the GET request to the prviate, scoped route again and you should get a 403 status and the following message:

Back in the Auth0 Dashboard:

1. Go to the Machine to Machine Applications tab for the API created above.
2. Expand the API Explorer Application, check the read:messages scope,and click Update
3. Click the Test tab, then COPY TOKEN.

Change the Authorization header to use the new token and send the GET request again. You should get a 200 status and the following message:

The example above uses manually-generated tokens which are not long-lived. Once your API is live on the web and ready to accept requests, the applications making the requests will need to create their tokens using one of a few ways:

• Mobile, desktop, and other native applications will use a Mobile/Native Login Flow
• CLIs, daemons, or services running on your back-end will use an Machine-to-Machine Flow
• Web applications can use the Authorization Code Flow

Regardless of the type, the application will need to request the audience of this API during the login flow to receive a correctly-formed access token.

To configure CORS, you should add the laravel-cors dependency. You can check it out here.

After installation, add HandleCors middleware in the application's global middleware stack:

Add the following to the configuration file for CORS: