This Elixir code sample demonstrates how to implement authorization in a Phoenix API server using Auth0 by Okta. This code sample shows you how to accomplish the following tasks:
-
Register a Phoenix API in the Auth0 Dashboard.
-
Use Phoenix plugs to enforce API security policies.
-
Perform access control in Phoenix using a token-based authorization strategy powered by JSON Web Tokens (JWTs).
-
Validate access tokens in JSON Web Token (JWT) format using Phoenix plugs.
-
Make authenticated requests to a secure Phoenix API server.
Code Sample Specs
This code sample uses the following main tooling versions:
- Phoenix
v1.6.2 - Elixir
v1.12
Quick Auth0 Set Up
First and foremost, if you haven't already, sign up for an Auth0 account to connect your API with the Auth0 Identity Platform.
Next, you need to create an API registration in the Auth0 Dashboard. You'll get two configuration values, the Auth0 Audience and the Auth0 Domain, that will help connect your API server with Auth0. You'll also need a test access token to practice making secure calls to your API.
Get the Auth0 audience
-
Open the APIs section of the Auth0 Dashboard.
-
Click on the Create API button and fill out the "New API" form with the following values:
Hello World API Server
https://hello-world.example.com
- Click on the Create button.
When setting up APIs, we also refer to the API identifier as the Audience value. Store that value in the following field to set up your API server in the next section:
Get the Auth0 domain
Now, follow these steps to get the Auth0 Domain value.
-
Open the Auth0 Domain Settings
-
Locate the bold text in the page description that follows this pattern:
tenant-name.region.auth0.com. That's your Auth0 domain! -
Paste the Auth0 domain value in the following field so that you can use it in the next section to set up your API server:
Get an Auth0 access token
You can get an access token from the Auth0 Dashboard to test making a secure call to your protected API endpoints:
- On the Auth0 API page, click on the "Test" tab.
-
Locate the section called "Response" and click on the copy button on the top-right corner.
-
Paste the access token value in the following field so that you can use it in the next sections to test your API server:
When you enter a value in the input fields present on this page, any code snippet that uses such value updates to reflect it. Using the input fields makes it easy to copy and paste code as you follow along.
Set Up and Run the Phoenix Project
Ensure that you have Elixir
v1.12.3or higher installed.
Start by cloning the Phoenix project:
git clone https://github.com/auth0-developer-hub/api_phoenix_elixir_hello-world.git
Make the project directory your current working directory:
cd api_phoenix_elixir_hello-world
Then, check out the basic-authorization branch, which holds all the code related to implementing token-based authorization to protect resources in a Phoenix API:
git checkout basic-authorization
Install the hex package manager if you don't have it already in your machine:
mix local.hex
Next, install the Phoenix project dependencies:
mix deps.get
Run the following command to generate a random secret key for Phoenix:
mix phx.gen.secret
Store the output from the command above in the following field:
Now, create a .env file under the project directory and populate it as follows:
PORT=6060CLIENT_ORIGIN_URL=http://localhost:4040AUTH0_DOMAIN=AUTH0-DOMAINAUTH0_AUDIENCE=AUTH0-AUDIENCESECRET_KEY_BASE=KEY-VALUE
Execute the following command to run the Phoenix API server:
mix phx.server
Alternatively, you can also run the server inside the Elixir interactive shell (IEx) by running the following command instead:
iex -S mix phx.server
Make an Authenticated API Request
You can use a terminal application to make an authenticated request to your API server. An authenticated request is a request that includes a bearer token in its authorization header. That bearer token is the access token in JSON Web Token (JWT) format that you obtained earlier from the Auth0 Dashboard.
You can structure the authenticate request as follows:
curl --request GET \--url http:/localhost:6060/api/messages/protected \--header 'authorization: Bearer AUTH0-ACCESS-TOKEN'
Execute the command above on your terminal and ensure that you get the following response:
{"text": "This is a protected message."}
Request API Resources from a Client Application
Let's simulate an essential feature of an API: serving data to client applications.
You can pair this API server with a client application that matches the technology stack that you use at work. Any "Hello World" client application can communicate with this "Hello World" API server sample.
You can simulate a secure full-stack application system in no time. Each client application sample gives you clear instructions to get it up and running quickly.
Pick a Single-Page Application (SPA) code sample in your preferred frontend framework and language:
Once you set up the client application, log in and visit the protected "Profile" page (http://localhost:4040/profile) to see all the user profile information that Auth0 securely shares with your application using ID tokens.
Then, visit the "Protected" page (http://localhost:4040/protected) or the "Admin" page (http://localhost:4040/admin) to practice requesting protected resources from an external API server using access tokens.