Authentication

#PropelAuth JWT Auth Policy

Authenticate requests with JWT tokens issued by PropelAuth. This is a customized version of the OpenId JWT Policy specifically for PropelAuth.

#Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

{
  "name": "my-propel-auth-jwt-inbound-policy",
  "policyType": "propel-auth-jwt-inbound",
  "handler": {
    "export": "PropelAuthJwtInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "allowUnauthenticatedRequests": false,
      "authUrl": "https://6587563.propelauthtest.com",
      "verifierKey": "$env(PROPEL_VERIFIER_KEY)"
    }
  }
}

json

#Policy Configuration

name <string> - The name of your policy instance. This is used as a reference in your routes.
policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be propel-auth-jwt-inbound.
handler.export <string> - The name of the exported type. Value should be PropelAuthJwtInboundPolicy.
handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
handler.options <object> - The options for this policy. See Policy Options below.

#Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

allowUnauthenticatedRequests <boolean> - Allow unauthenticated requests to proceed. This is use useful if you want to use multiple authentication policies or if you want to allow both authenticated and non-authenticated traffic. Defaults to false.
authUrl (required) <string> - Your PropelAuth authUrl. For example, https://6587563.propelauthtest.com.
verifierKey (required) <string> - Your public (verifier) key that is used to verify access tokens. This key has a value that begins with '-----BEGIN PUBLIC KEY-----'. Make sure to remove all line breaks from the key before saving the variable.

#Using the Policy

Adding PropelAuth to your route takes just a few steps, but before you can add the policy you'll need to have PropelAuth setup for API Authentication.

#Setup PropelAuth

You'll need a PropelAuth account to use this policy. If you don't already have a client to call your API, the easiest thing to do is start with one of the PropelAuth examples such as the React example. Follow the instructions for setting up the example, then you can change the authenticated API the example calls with your Zuplo API or just use the example to get an access token.

#Set Environment Variables

Before adding the policy, there are a few environment variables that will need to be set that will be used in the PropelAuth JWT Policy.

In the Zuplo Portal open the Environment Variables section in the Settings tab.
Click Add new Variable and enter the name PROPEL_AUTH_URL in the name field. Set the value to your PropelAuth Auth URL. You can find this value in the Backend Integration tab in the PropelAuth portal.
Click Add new Variable and enter the name PROPEL_VERIFIER_KEY in the name field. Set the value to your PropelAuth Public (Verifier) Key. You can find this value in the Backend Integration tab in the PropelAuth portal.

#Add the PropelAuth JWT Policy

The next step is to add the PropelAuth JWT policy to a route in your project.

In the Zuplo Portal open the Route Designer in the Files tab then click routes.oas.json.
Select or create a route that you want to authenticate with PropelAuth. Expand the Policies section and click Add Policy. Search for and select the PropelAuth JWT Auth policy.

With the policy selected, notice that there are two properties, authUrl and verifierKey that are pre-populated with environment variable names that you set in the previous section.

Click OK to save the policy.

#Test the Policy

Finally, you'll make two API requests to your route to test that authentication is working as expected.

In the route designer on the route you added the policy, click the Test button. In the dialog that opens, click Test to make a request.
The API Gateway should respond with a 401 Unauthorized response.

Now to make an authenticated request, add a header to the request called Authorization. Set the value of the header to Bearer YOUR_ACCESS_TOKEN replacing YOUR_ACCESS_TOKEN with the value of the Auth0 access token you saved from the first section of this tutorial.

Click the Test button and a 200 OK response should be returned.

You have now setup PropelAuth JWT Authentication on your API Gateway.

See this document for more information about OAuth authorization in Zuplo.