Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Add OAuth 2.0 & JWT how-to #204
docs: Add OAuth 2.0 & JWT how-to #204
Changes from all commits
79f07e5
db70366
cd97545
b9a0b73
421c90d
1ff6778
2445ce5
d9b652d
25bae94
1e62a9e
498ab8a
File filter
Filter by extension
Conversations
Jump to
There are no files selected for viewing
Overview
OAuth 2.0 is a popular open standard authorization framework that enables you to verify that incoming requests are authorized to use your API.
There are three main pieces to using OAuth 2.0 with Huma:
Issue an Access Token
Huma does not provide any built-in access token issuing functionality. Instead, you can use any existing library or service to issue tokens. For simplicity's sake, we will assume you are using a third-party service for managing users and issuing tokens, like Auth0 or Okta. A simplified flow chart for OAuth2.0 authorization looks something like this:
The access token may be issued in different flavors & formats, but for the remainder of this document we will assume they are JWTs.
You will configure the third-party service to issue access token from OAuth 2.0 flows like Authorization Code or Client Credentials (among others) and will be given e.g. authorization and token URLs, which will be used later in the OpenAPI and to configure clients to fetch access tokens.
If not using a third-party service, you will need to set up a signing authority, publish your own JWKS, and issue short-lived tokens yourself. This is outside the scope of this guide, but take a look at github.com/lestrrat-go/jwx for a library that can help.
Document the Auth Scheme in OpenAPI
Next, you need to document the auth scheme in your OpenAPI document. This is done using the
SecuritySchemes
component. Here is an example defining an OAuth 2.0 Authorization Code flow with the URLs mentioned above and a couple of defined scopes:When registering your operation you can refer to the auth scheme and required scopes for that operation:
!!! Warning
Authorize Incoming Requests
Where authentication & authorization happen depends on how your service is set up. In some scenarios you may have an API gateway that handles auth and forwards requests to your service. In other scenarios you may want to handle auth in your service.
API Gateway Auth
In an API gateway scenario, you typically configure the gateway to check the
Authorization
header for a token and validate it against the JWKS URL. If the token is valid, then the gateway will forward the request to your API service. There are many such gateways (e.g. Traefik, Istio, etc) and ways of configuring them, but the general idea is similar between them:In this case and depending on your security requirements, you may be able to skip this section since all incoming requests to your API will have already been vetted by the gateway. In this scenario, the Huma code frome the previous section serves mostly as documentation for your clients.
Huma Auth Middleware
Huma provides middleware functionality that can be used to authorize incoming requests within the API service itself. Here is an example that will check the
Authorization
header for a token and validate it against the JWKS URL given by your JWT issuer (e.g. Auth0/Okta). It will also check that the token has the required scopes for the operation, if any are defined.Lastly, when configuring your API, be sure to include this middleware:
Supporting different Token Formats
As mentioned previously, the Oauth2.0 standard does not specify the format of the access token - it merely defines how to get one. Although JWT is a very popular format, a given OAuth2.0 service or library may issue access token in different formats. The gist of what is outlined above should be adaptable to support such tokens as well, but will obviously require different methods for validation and information extraction. In the case of opaque tokens, additional interaction with an IAM server may be required inside the middleware, e.g. calling an introspection endpoint.
Optional: Client Auto-Configuration
Some clients like Restish support OpenAPI-based auth auto-configuration. This means that you can configure your client to fetch the OpenAPI document and automatically configure itself to use the correct auth mechanism. This is done by adding the
x-cli-config
extension to the OpenAPI: