Okta

This page explains using Okta to validate JWTs (JSON Web Tokens).

Introduction¶

This article will walk you through a basic configuration of using Okta for JWT validation with Traefik Hub.
JWTs are used to control the access to APIs and API Gateways.

You will learn how to configure Okta and how to connect Traefik Hub to your Okta instance.

Note

This article covers a basic example configuration of Okta.
This is not a production grade Okta environment!

Good to know

If you switch from the default configuration to JWT, all API keys generated in the API Portal will be turned off.

Before you begin¶

Before getting started, make sure to read our JWT overview to learn about JWTs and Traefik Hub.

Please ensure you have the following:

An Okta instance with admin permissions.
Admin permissions for the Traefik Hub workspace.

jq
curl

Create an authorization server¶

As the first step, create a custom authorization server in Okta.

Add an access policy¶

Now it is time to add an access policy to the new authorization server.

In the overview of the new authorization server, select Access Policies followed by Add New Access Policy.

Enter the Name, the Description and assign a client.
In this example, the policy is assigned to all clients.

Configure the ACP — Configure the access policy

Once you're done, select Create Policy.

Add an access policy rule

After the new policy is created, it is time to add a new rule to the policy.
In a rule, you define the access permissions.

Select Add rule in the access policy overview.

Enter a Rule Name and select Create rule.

This example uses the default rule configuration.
You may want to adjust that for your production environment.

Claims¶

As the last part of the custom authorization server configuration, you will add a custom claim for groups.
In Traefik Hub, every user must be a member of a user group. These groups are used to configure API access and rate limiting.

Create an application integration¶

After you created and configured the custom authorization server, it's now time to create an Okta application.

Validate JWT against Okta¶

Use curl to generate a JWT and validate it against your Okta instance.

The following example uses the password grant type as a validation method.

CLI

curl -L -s -X POST 'https://${yourOktaOrg}/oauth2/${authorizationServerId}/v1/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode '[email protected]' \
--data-urlencode 'password=${your-secure-password}' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'scope=openid' \
--data-urlencode 'client_id=${your-client-id}'
{"token_type":"Bearer","expires_in":3600,"access_token":"eyJraWQiOiJ2OTlWWWpEWDRPWWhfM19HQTdPSWFtNkFyQkp4bmxlblp2NGd5ampheFJJIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULjJRbkZlakEzMUVLOHkzUExlTGxZczlBaDZxdWZaUDRBQ0w4VDdWMnFaVDQiLCJpc3MiOiJodHRwczovL2Rldi04NjU4NTAzMS5va3RhLmNvbS9vYXV0aDIvYXVzZDhzbG5kaWFTZzF2NGg1ZDciLCJhdWQiOiJhcGk6Ly9odWIiLCJpYXQiOjE3MDA3MjcwMTgsImV4cCI6MTcwMDczMDYxOCwiY2lkIjoiMG9hZDlma21vNTY0VDNqUjM1ZDciLCJ1aWQiOiIwMHVkZ2UyZnIwT3E4SU1xSzVkNyIsInNjcCI6WyJvcGVuaWQiXSwiYXV0aF90aW1lIjoxNzAwNzI3MDE4LCJzdWIiOiJzdmVuQHNvMzYubmV0IiwiZ3JvdXBzIjpbIkV2ZXJ5b25lIl19.oShJ-QKYIPFBHn3CD2jSqpRDacxm64qt6iPsPxxQBDtK-Cfgfj9L641skhxCzwHtmThIMQICqZL5zUZjik9s1cZE0O7l9dIhDYOT5PyAIsomLKkzcPx62UqPwKDQrpm7U3_BklvRj8iskV2hb7eINGmoN3VWBaIH-6NQ0eIBG9kS0iLw0EMni7mWLfCWeB7FueBwN-6sI6lg8clA-ZESPCzUQZSSDGq0Ah_YSqSr-1RofvuUuStsm6QaZgzb_CgLTbwoPty_wf2WRgZi2M-Sx0UR0x6JO0JUn0vd_WKrXIMCurbKCjgxAX0F4IHQT1LHYDf1izV9qUlrTeQfBhYdow","scope":"openid","id_token":"eyJraWQiOiJ2OTlWWWpEWDRPWWhfM19HQTdPSWFtNkFyQkp4bmxlblp2NGd5ampheFJJIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIwMHVkZ2UyZnIwT3E4SU1xSzVkNyIsInZlciI6MSwiaXNzIjoiaHR0cHM6Ly9kZXYtODY1ODUwMzEub2t0YS5jb20vb2F1dGgyL2F1c2Q4c2xuZGlhU2cxdjRoNWQ3IiwiYXVkIjoiMG9hZDlma21vNTY0VDNqUjM1ZDciLCJpYXQiOjE3MDA3MjcwMTgsImV4cCI6MTcwMDczMDYxOCwianRpIjoiSUQuWV8wdzRpR2t4elRLWXB4WmFMVGxYdmthNEx1eHZWUmw5NVoxNWk5YXl4byIsImFtciI6WyJwd2QiXSwiaWRwIjoiMDBvZDhzOXljak15ZDlCeTA1ZDciLCJhdXRoX3RpbWUiOjE3MDA3MjcwMTgsImF0X2hhc2giOiJCVzRRcmpla1JQTnVOdXdOSHotaEVRIn0.CdL4HBKBOc4onL_sdCWr4v4rIZXzwCV2lLqGxjbuIh1BPc8yxV1kBwDG8dQ8DVKO0z8uXWkn0adrdx3MDHAhHTDAgC7CDEepxD-n0SczpaVUpgXy5bvk7ByzTuUmZYBxyIDwLebXLQOWzT5qRt2pNiipVqukvEupdCGQmnVhM-Sthv4z24y9Vy0-e69GiVjCDp-TkljoCRTPuG_UCCOvdHGrVKpSbntLhpavX37N2idtDAkJvC1_aw7WPbnmCURUU9AHijslgBNGTz-rtvN3eUVks-Cr1yeXGuEAnNf-aekRxQ-U4IGUz6WSqcWsfNKSXqRRUXqC8EiCImylsi9v1A"}

Enable JWT in Traefik Hub¶

If you switch from the default configuration to JWT, all API keys generated in the API Portal will be turned off.

First, select Auth settings to go to the authentication and authorization overview.

Second, enable JWT in the token configuration.

Third, configure the JWT key validation method and claims.

Choose one of the following key validation techniques for your JWT.

Method	Description
`signingSecret`	The `signingSecret` option can be set to the secret used for signing the JWT certificates.
`publicKey`	The `publicKey` option can be used as an alternative to a signing secret to verify incoming requests. In that case, users should sign their token using a private key, and the public key can be used to verify the signature.
`jwksFile`	The `jwksFile` option can be used to define a set of JWK to be used to verify the signature of JWTs.
`jwksUrl`	The `jwksUrl` option can be used as an alternative to a signing secret to verify incoming requests. It is the URL of the host serving a JWK set. This option can either be set to a full URL: https://${yourOktaOrg}/oauth2/${authorizationServerId}/v1/keys.

The following configuration example will use jwksUrl to validate JWT against an Okta instance, using the claims groups and sub.

Setting	Value	Example
`Token validation method`	JWKs URL	https://${yourOktaOrg}/oauth2/${authorizationServerId}/v1/keys
`Claims configuration`	Groups	`groups`
`Claims configuration`	User ID	`sub`

Once you're done, select Save.

If you want to strip the authorization header or a forward header, you can do that under Additional configuration.
These settings are not required.

Configure the JWT validation and claims — Configure additional settings

Once you're done, select Save.

Swagger UI¶

In the last part, you will configure JWT for authorization in the Swagger UI.

First, generate a fresh JWT and copy the public access token.

Run the following curl command to get your access token.

CLI

curl -L -s -X POST 'https://${yourOktaOrg}/oauth2/${authorizationServerId}/v1/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode '[email protected]' \
--data-urlencode 'password=${your-secure-password}' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'scope=openid' \
--data-urlencode 'client_id=${your-client-id}' | jq .access_token
"eyJraWQiOiJ2OTlWWWpEWDRPWWhfM19HQTdPSWFtNkFyQkp4bmxlblp2NGd5ampheFJJIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULkZxUXZ4dzN1TmY5WWVLUXNadkluMWxROE9oUWNMM2ZwV2p4eEh6WEtFRlUiLCJpc3MiOiJodHRwczovL2Rldi04NjU4NTAzMS5va3RhLmNvbS9vYXV0aDIvYXVzZDhzbG5kaWFTZzF2NGg1ZDciLCJhdWQiOiJhcGk6Ly9odWIiLCJpYXQiOjE3MDA3MjcxMjksImV4cCI6MTcwMDczMDcyOSwiY2lkIjoiMG9hZDlma21vNTY0VDNqUjM1ZDciLCJ1aWQiOiIwMHVkZ2UyZnIwT3E4SU1xSzVkNyIsInNjcCI6WyJvcGVuaWQiXSwiYXV0aF90aW1lIjoxNzAwNzI3MTI5LCJzdWIiOiJzdmVuQHNvMzYubmV0IiwiZ3JvdXBzIjpbIkV2ZXJ5b25lIl19.Sn4xIVlNTwJvWi0TahrErplVYvdfHA3fE2CRC2NEf7YoaeT-G9a9S57eTOPWxfhDCRvWVBsji9yp_x_-DqRFUuiYE3VG0FwcLybLy4LVn83kDEs8Xawo_xUHVzFadIaHIXUM7fb1we6vvHy-1N6EKn7u2TjRvWfsfVycNvWSKVRQ3TDRXvKQEihKYcnBy1Eo_ddUecX6IEnB-tlsK1gOevc6hBjakBIr16k2YZ8554w8U0ogUU_ytLpKUYrEoQeb2Eyl2DbHo9HHX7fYPUt-WmaYsBMlc4yvd7iTjZEX9q9lzc7f4PJW94ZqTs7wyRI8pwed95HAQowoYFCBAQbcbQ"

Second, copy the access token, this is everything between "".

Access token example

eyJraWQiOiJ2OTlWWWpEWDRPWWhfM19HQTdPSWFtNkFyQkp4bmxlblp2NGd5ampheFJJIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULkZxUXZ4dzN1TmY5WWVLUXNadkluMWxROE9oUWNMM2ZwV2p4eEh6WEtFRlUiLCJpc3MiOiJodHRwczovL2Rldi04NjU4NTAzMS5va3RhLmNvbS9vYXV0aDIvYXVzZDhzbG5kaWFTZzF2NGg1ZDciLCJhdWQiOiJhcGk6Ly9odWIiLCJpYXQiOjE3MDA3MjcxMjksImV4cCI6MTcwMDczMDcyOSwiY2lkIjoiMG9hZDlma21vNTY0VDNqUjM1ZDciLCJ1aWQiOiIwMHVkZ2UyZnIwT3E4SU1xSzVkNyIsInNjcCI6WyJvcGVuaWQiXSwiYXV0aF90aW1lIjoxNzAwNzI3MTI5LCJzdWIiOiJzdmVuQHNvMzYubmV0IiwiZ3JvdXBzIjpbIkV2ZXJ5b25lIl19.Sn4xIVlNTwJvWi0TahrErplVYvdfHA3fE2CRC2NEf7YoaeT-G9a9S57eTOPWxfhDCRvWVBsji9yp_x_-DqRFUuiYE3VG0FwcLybLy4LVn83kDEs8Xawo_xUHVzFadIaHIXUM7fb1we6vvHy-1N6EKn7u2TjRvWfsfVycNvWSKVRQ3TDRXvKQEihKYcnBy1Eo_ddUecX6IEnB-tlsK1gOevc6hBjakBIr16k2YZ8554w8U0ogUU_ytLpKUYrEoQeb2Eyl2DbHo9HHX7fYPUt-WmaYsBMlc4yvd7iTjZEX9q9lzc7f4PJW94ZqTs7wyRI8pwed95HAQowoYFCBAQbcbQ

Third, browse to an API Portal and select an API, this example uses the Flight API.

Select the Authorize button on the right.

Paste your public token into the Value field and select Authorize.

To send requests using the Swagger UI, choose an API endpoint and select Try it out.

Select Execute to send requests.

The recipients that the tokens are intended for. This becomes the audience claim in an access token. Currently, Okta supports only one audience. See the official Okta docs. ↩

Field	Description	Example
Name	Name of the claim needed by Traefik Hub.	groups
Include in token type	Select Access Token for(OAuth 2.0). For ID tokens, in the second dropdown, choose Always.	Access Token and Always
Value type	Choose whether the values defined in the claim use a Group filter or an Expression written using the Okta Expression Language.	`.*`
Disable claim	Check this option to temporarily disable the claim for testing or debugging.	Empty
Include in	Specify whether the claim is valid for any scope, or select the scopes for which it’s valid.	Any Scope