Sign up for an{" "}
Auth0 account
{" "}
or{" "}
console.log("log in")}>
log in
{" "}
to your existing account to integrate directly with your own tenant.
;
};
export const sections = [{
id: "define-permissions",
title: "Define permissions"
}, {
id: "install-dependencies",
title: "Install dependencies"
}, {
id: "create-an-auth0client-class",
title: "Create an Auth0Client class"
}, {
id: "define-a-secured-concern",
title: "Define a Secured concern"
}, {
id: "include-the-secure-concern-in-your-applicationcontroller",
title: "Include the Secure concern in your ApplicationController"
}, {
id: "create-the-public-endpoint",
title: "Create the public endpoint"
}, {
id: "create-the-private-endpoints",
title: "Create the private endpoints"
}];
This tutorial performs access token validation using the [jwt](https://github.com/jwt/ruby-jwt) Gem within a custom `Auth0Client` class. A Concern called
`Secured` is used to authorize endpoints which require authentication through an incoming access token.
If you have not created an API in your Auth0 dashboard yet, use the interactive selector to create a new Auth0 API
or select an existing API for your project.
To set up your first API through the Auth0 dashboard, review [our getting started
guide](https://auth0.com/docs/get-started/auth0-overview/set-up-apis).
Each Auth0 API uses the API Identifier, which your application needs to validate the access token.
**New to Auth0?** Learn [how Auth0 works](https://auth0.com/docs/overview)
and read about [implementing API authentication
and authorization](https://auth0.com/docs/api-auth) using the OAuth 2.0 framework.
Permissions let you define how resources can be accessed on behalf of the user with a given access token. For
example, you might choose to grant read access to the `messages` resource if users have the manager
access level, and a write access to that resource if they have the administrator access level.
You can define allowed permissions in the **Permissions** view of the Auth0 Dashboard's [APIs](https://manage.auth0.com/#/apis) section.
This example uses the `read:messages` scope.
Install the \*\*jwt \*\*Gem.
```bash lines theme={null}
gem 'jwt'
bundle install
```
Create a class called `Auth0Client`. This class decodes and verifies the incoming access token taken
from the `Authorization` header of the request.
The `Auth0Client` class retrieves the public key for your Auth0 tenant and then uses it to verify the
signature of the access token. The `Token` struct defines a `validate_permissions` method to
look for a particular `scope` in an access token by providing an array of required scopes and check if
they are present in the payload of the token.
Create a Concern called `Secured` which looks for the access token in the `Authorization`
header of an incoming request.
If the token is present, the `Auth0Client.validate_token` will use the `jwt` Gem to verify
the token's signature and validate the token's claims.
In addition to verifying that the access token is valid, the Concern also includes a mechanism for confirming the
token has the sufficient **scope** to access the requested resources. In this example we define a
`validate_permissions` method that receives a block and checks the permissions by calling the
`Token.validate_permissions` method from the `Auth0Client` class.
For the `/private-scoped` route, the scopes defined will be intersected with the scopes coming in the
payload, to determine if it contains one or more items from the other array.
By adding the `Secure` concern to your application controller, you'll only need to use a
`before_action` filter in the controller that requires authorization.
Create a controller to handle the public endpoint `/api/public`.
The `/public` endpoint does not require any authorization so no `before_action` is needed.
Create a controller to handle the private endpoints: `/api/private` and
`/api/private-scoped`.
`/api/private` is available for authenticated requests containing an access token with no additional
scopes.
`/api/private-scoped` is available for authenticated requests containing an access token with the
`read:messages` scope granted
The protected endpoints need to call the `authorize` method from the `Secured` concern, for
that you use `before_action :authorize`, this ensure the `Secured.authorize` method is
called before every action in the `PrivateController`.
### Make a Call to Your API
To make calls to your API, you need an Access Token. You can get an Access Token for testing purposes from the
**Test** view in your [API
settings](https://manage.auth0.com/#/apis).
Provide the Access Token as an `Authorization` header in your requests.
```bash cURL lines theme={null}
curl --request get \
--url 'http:///%7ByourDomain%7D/api_path' \
--header 'authorization: Bearer YOUR_ACCESS_TOKEN_HERE'
```
```csharp C# lines theme={null}
var client = new RestClient("http:///%7ByourDomain%7D/api_path");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
IRestResponse response = client.Execute(request);
```
```go Go lines theme={null}
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "http:///%7ByourDomain%7D/api_path"
req, _ := http.NewRequest("get", url, nil)
req.Header.Add("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```java Java lines theme={null}
HttpResponse response = Unirest.get("http:///%7ByourDomain%7D/api_path")
.header("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
.asString();
```
```javascript Node.JS lines theme={null}
var axios = require("axios").default;
var options = {
method: 'get',
url: 'http:///%7ByourDomain%7D/api_path',
headers: {authorization: 'Bearer YOUR_ACCESS_TOKEN_HERE'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
```
```objc Obj-C lines theme={null}
#import
NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_ACCESS_TOKEN_HERE" };
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"http:///%7ByourDomain%7D/api_path"]
cachePolicy:NSURLRequestUseProtocolCachePolicy
timeoutInterval:10.0];
[request setHTTPMethod:@"get"];
[request setAllHTTPHeaderFields:headers];
NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
if (error) {
NSLog(@"%@", error);
} else {
NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
NSLog(@"%@", httpResponse);
}
}];
[dataTask resume];
```
```php PHP lines theme={null}
#import
NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_ACCESS_TOKEN_HERE" };
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"http:///%7ByourDomain%7D/api_path"]
cachePolicy:NSURLRequestUseProtocolCachePolicy
timeoutInterval:10.0];
[request setHTTPMethod:@"get"];
[request setAllHTTPHeaderFields:headers];
NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
if (error) {
NSLog(@"%@", error);
} else {
NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
NSLog(@"%@", httpResponse);
}
}];
[dataTask resume];
```
```python Python lines theme={null}
import http.client
conn = http.client.HTTPConnection("")
headers = { 'authorization': "Bearer YOUR_ACCESS_TOKEN_HERE" }
conn.request("get", "/%7ByourDomain%7D/api_path", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
```
```ruby Ruby lines theme={null}
require 'uri'
require 'net/http'
url = URI("http:///%7ByourDomain%7D/api_path")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["authorization"] = 'Bearer YOUR_ACCESS_TOKEN_HERE'
response = http.request(request)
puts response.read_body
```
```swift Swift lines theme={null}
import Foundation
let headers = ["authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"]
let request = NSMutableURLRequest(url: NSURL(string: "http:///%7ByourDomain%7D/api_path")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "get"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
##### Checkpoint
Now that you have configured your application, run your application to verify that:
* `GET /api/public`is available for non-authenticated requests.
* `GET /api/private`is available for authenticated requests.
* `GET /api/private-scoped`is available for authenticated requests containing an Access
Token with the `read:messages`scope.
## Next Steps
Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.
This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:
* [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
* [omniauth-auth0 SDK](https://github.com/auth0/omniauth-auth0) - Explore the SDK used in this tutorial more fully
* [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
```rb app/controllers/concerns/secured.rb lines highlight={} theme={null}
# frozen_string_literal: true
module Secured
extend ActiveSupport::Concern
REQUIRES_AUTHENTICATION = { message: 'Requires authentication' }.freeze
BAD_CREDENTIALS = {
message: 'Bad credentials'
}.freeze
MALFORMED_AUTHORIZATION_HEADER = {
error: 'invalid_request',
error_description: 'Authorization header value must follow this format: Bearer access-token',
message: 'Bad credentials'
}.freeze
INSUFFICIENT_PERMISSIONS = {
error: 'insufficient_permissions',
error_description: 'The access token does not contain the required permissions',
message: 'Permission denied'
}.freeze
def authorize
token = token_from_request
return if performed?
validation_response = Auth0Client.validate_token(token)
@decoded_token = validation_response.decoded_token
return unless (error = validation_response.error)
render json: { message: error.message }, status: error.status
end
def validate_permissions(permissions)
raise 'validate_permissions needs to be called with a block' unless block_given?
return yield if @decoded_token.validate_permissions(permissions)
render json: INSUFFICIENT_PERMISSIONS, status: :forbidden
end
private
def token_from_request
authorization_header_elements = request.headers['Authorization']&.split
render json: REQUIRES_AUTHENTICATION, status: :unauthorized and return unless authorization_header_elements
unless authorization_header_elements.length == 2
render json: MALFORMED_AUTHORIZATION_HEADER,
status: :unauthorized and return
end
scheme, token = authorization_header_elements
render json: BAD_CREDENTIALS, status: :unauthorized and return unless scheme.downcase == 'bearer'
token
end
end
```
```rb app/controllers/application_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class ApplicationController < ActionController::API
include Secured
end
```
```rb app/lib/auth0_client.rb lines highlight={} theme={null}
```
```rb app/controllers/public_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class PublicController < ApplicationController
def public
render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
end
end
```
```rb app/controllers/private_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class PublicController < ApplicationController
def public
render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
end
end
```
```rb app/controllers/concerns/secured.rb lines highlight={} theme={null}
# frozen_string_literal: true
module Secured
extend ActiveSupport::Concern
REQUIRES_AUTHENTICATION = { message: 'Requires authentication' }.freeze
BAD_CREDENTIALS = {
message: 'Bad credentials'
}.freeze
MALFORMED_AUTHORIZATION_HEADER = {
error: 'invalid_request',
error_description: 'Authorization header value must follow this format: Bearer access-token',
message: 'Bad credentials'
}.freeze
INSUFFICIENT_PERMISSIONS = {
error: 'insufficient_permissions',
error_description: 'The access token does not contain the required permissions',
message: 'Permission denied'
}.freeze
def authorize
token = token_from_request
return if performed?
validation_response = Auth0Client.validate_token(token)
@decoded_token = validation_response.decoded_token
return unless (error = validation_response.error)
render json: { message: error.message }, status: error.status
end
def validate_permissions(permissions)
raise 'validate_permissions needs to be called with a block' unless block_given?
return yield if @decoded_token.validate_permissions(permissions)
render json: INSUFFICIENT_PERMISSIONS, status: :forbidden
end
private
def token_from_request
authorization_header_elements = request.headers['Authorization']&.split
render json: REQUIRES_AUTHENTICATION, status: :unauthorized and return unless authorization_header_elements
unless authorization_header_elements.length == 2
render json: MALFORMED_AUTHORIZATION_HEADER,
status: :unauthorized and return
end
scheme, token = authorization_header_elements
render json: BAD_CREDENTIALS, status: :unauthorized and return unless scheme.downcase == 'bearer'
token
end
end
```
```rb app/controllers/application_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class ApplicationController < ActionController::API
include Secured
end
```
```rb app/lib/auth0_client.rb lines highlight={} theme={null}
```
```rb app/controllers/public_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class PublicController < ApplicationController
def public
render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
end
end
```
```rb app/controllers/private_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class PublicController < ApplicationController
def public
render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
end
end
```
```rb app/controllers/application_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class ApplicationController < ActionController::API
include Secured
end
```
```rb app/lib/auth0_client.rb lines highlight={} theme={null}
```
```rb app/controllers/concerns/secured.rb lines highlight={} theme={null}
# frozen_string_literal: true
module Secured
extend ActiveSupport::Concern
REQUIRES_AUTHENTICATION = { message: 'Requires authentication' }.freeze
BAD_CREDENTIALS = {
message: 'Bad credentials'
}.freeze
MALFORMED_AUTHORIZATION_HEADER = {
error: 'invalid_request',
error_description: 'Authorization header value must follow this format: Bearer access-token',
message: 'Bad credentials'
}.freeze
INSUFFICIENT_PERMISSIONS = {
error: 'insufficient_permissions',
error_description: 'The access token does not contain the required permissions',
message: 'Permission denied'
}.freeze
def authorize
token = token_from_request
return if performed?
validation_response = Auth0Client.validate_token(token)
@decoded_token = validation_response.decoded_token
return unless (error = validation_response.error)
render json: { message: error.message }, status: error.status
end
def validate_permissions(permissions)
raise 'validate_permissions needs to be called with a block' unless block_given?
return yield if @decoded_token.validate_permissions(permissions)
render json: INSUFFICIENT_PERMISSIONS, status: :forbidden
end
private
def token_from_request
authorization_header_elements = request.headers['Authorization']&.split
render json: REQUIRES_AUTHENTICATION, status: :unauthorized and return unless authorization_header_elements
unless authorization_header_elements.length == 2
render json: MALFORMED_AUTHORIZATION_HEADER,
status: :unauthorized and return
end
scheme, token = authorization_header_elements
render json: BAD_CREDENTIALS, status: :unauthorized and return unless scheme.downcase == 'bearer'
token
end
end
```
```rb app/controllers/public_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class PublicController < ApplicationController
def public
render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
end
end
```
```rb app/controllers/private_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class PublicController < ApplicationController
def public
render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
end
end
```
```rb app/controllers/public_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class PublicController < ApplicationController
def public
render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
end
end
```
```rb app/controllers/application_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class ApplicationController < ActionController::API
include Secured
end
```
```rb app/lib/auth0_client.rb lines highlight={} theme={null}
```
```rb app/controllers/concerns/secured.rb lines highlight={} theme={null}
# frozen_string_literal: true
module Secured
extend ActiveSupport::Concern
REQUIRES_AUTHENTICATION = { message: 'Requires authentication' }.freeze
BAD_CREDENTIALS = {
message: 'Bad credentials'
}.freeze
MALFORMED_AUTHORIZATION_HEADER = {
error: 'invalid_request',
error_description: 'Authorization header value must follow this format: Bearer access-token',
message: 'Bad credentials'
}.freeze
INSUFFICIENT_PERMISSIONS = {
error: 'insufficient_permissions',
error_description: 'The access token does not contain the required permissions',
message: 'Permission denied'
}.freeze
def authorize
token = token_from_request
return if performed?
validation_response = Auth0Client.validate_token(token)
@decoded_token = validation_response.decoded_token
return unless (error = validation_response.error)
render json: { message: error.message }, status: error.status
end
def validate_permissions(permissions)
raise 'validate_permissions needs to be called with a block' unless block_given?
return yield if @decoded_token.validate_permissions(permissions)
render json: INSUFFICIENT_PERMISSIONS, status: :forbidden
end
private
def token_from_request
authorization_header_elements = request.headers['Authorization']&.split
render json: REQUIRES_AUTHENTICATION, status: :unauthorized and return unless authorization_header_elements
unless authorization_header_elements.length == 2
render json: MALFORMED_AUTHORIZATION_HEADER,
status: :unauthorized and return
end
scheme, token = authorization_header_elements
render json: BAD_CREDENTIALS, status: :unauthorized and return unless scheme.downcase == 'bearer'
token
end
end
```
```rb app/controllers/private_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class PublicController < ApplicationController
def public
render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
end
end
```
```rb app/controllers/private_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class PublicController < ApplicationController
def public
render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
end
end
```
```rb app/controllers/application_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class ApplicationController < ActionController::API
include Secured
end
```
```rb app/lib/auth0_client.rb lines highlight={} theme={null}
```
```rb app/controllers/concerns/secured.rb lines highlight={} theme={null}
# frozen_string_literal: true
module Secured
extend ActiveSupport::Concern
REQUIRES_AUTHENTICATION = { message: 'Requires authentication' }.freeze
BAD_CREDENTIALS = {
message: 'Bad credentials'
}.freeze
MALFORMED_AUTHORIZATION_HEADER = {
error: 'invalid_request',
error_description: 'Authorization header value must follow this format: Bearer access-token',
message: 'Bad credentials'
}.freeze
INSUFFICIENT_PERMISSIONS = {
error: 'insufficient_permissions',
error_description: 'The access token does not contain the required permissions',
message: 'Permission denied'
}.freeze
def authorize
token = token_from_request
return if performed?
validation_response = Auth0Client.validate_token(token)
@decoded_token = validation_response.decoded_token
return unless (error = validation_response.error)
render json: { message: error.message }, status: error.status
end
def validate_permissions(permissions)
raise 'validate_permissions needs to be called with a block' unless block_given?
return yield if @decoded_token.validate_permissions(permissions)
render json: INSUFFICIENT_PERMISSIONS, status: :forbidden
end
private
def token_from_request
authorization_header_elements = request.headers['Authorization']&.split
render json: REQUIRES_AUTHENTICATION, status: :unauthorized and return unless authorization_header_elements
unless authorization_header_elements.length == 2
render json: MALFORMED_AUTHORIZATION_HEADER,
status: :unauthorized and return
end
scheme, token = authorization_header_elements
render json: BAD_CREDENTIALS, status: :unauthorized and return unless scheme.downcase == 'bearer'
token
end
end
```
```rb app/controllers/public_controller.rb lines highlight={} theme={null}
# frozen_string_literal: true
class PublicController < ApplicationController
def public
render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
end
end
```
Sign up for an{" "}
Auth0 account
{" "}
or{" "}
console.log("log in")}>
log in
{" "}
to your existing account to integrate directly with your own tenant.
Provide the Access Token as an `Authorization` header in your requests.