@jackdbd/fastify-authorization-endpoint

@jackdbd/fastify-authorization-endpoint

Fastify plugin that adds an IndieAuth Authorization Endpoint to a Fastify server.

An IndieAuth Authorization Endpoint is responsible for obtaining authentication or authorization consent from the end user and generating and verifying authorization codes.

• Installation
• Authorization Endpoint Options
  • components: object
  • templates[]: array
• Obtaining an authorization code
  • Authorization Request Querystring
• Verifying the authorization code
  • Access Token Request Body
• Dependencies
• Authorization codes
• References
• License

Installation

npm install @jackdbd/fastify-authorization-endpoint

Authorization Endpoint Options

Options for the Fastify authorization-endpoint plugin

Properties

Name	Type	Description	Required
ajv		Instance of Ajv	no
authorizationCodeExpiration	string	Default: "10 minutes" Minimal Length: 1	no
components	object	Filepaths to WebC components	no
redirectPathOnSubmit	string	Default: "/consent" Minimal Length: 1	no
includeErrorDescription	boolean	Whether to include an error_description property in all error responses. This is meant to assist the client developer in understanding the error. This is NOT meant to be shown to the end user. Default: false	no
issuer	string	The authorization server's issuer identifier. It's a URL that uses the "https" scheme and has no query or fragment components. It MUST also be a prefix of the indieauth-metadata URL. Format: "uri"	no
logPrefix	string	Default: "authorization-endpoint "	no
onAuthorizationCodeVerified	Function	Handler that runs after the authorization code has been verified. You should use this handler to inform your storage backend that the authorization code has been used.	yes
onUserApprovedRequest	Function	Handler executed after the user approves the authorization request on the consent screen. You should use it to persist the authorization code generated by the authorization code generated by the authorization endpoint into your storage backend.	yes
reportAllAjvErrors (report all AJV errors)	boolean	Whether to report all AJV validation errors. Default: false	no
retrieveAuthorizationCode	Function	Function that retrieves an authorization code from a storage backend.	yes
templates	string[]	Filepaths to WebC templates	no

Example

{
    "authorizationCodeExpiration": "10 minutes",
    "components": {},
    "redirectPathOnSubmit": "/consent",
    "includeErrorDescription": false,
    "logPrefix": "authorization-endpoint ",
    "reportAllAjvErrors": false
}

components: object

Filepaths to WebC components

Properties

Name	Type	Description	Required
consent-form	string	Minimal Length: 1
scope-list	string	Minimal Length: 1
the-footer	string	Minimal Length: 1
the-header	string	Minimal Length: 1

templates[]: array

Filepaths to WebC templates

Items

Item Type: string
Item Minimal Length: 1
Minimum Items: 1

Obtaining an authorization code

When the end user accesses the authorization endpoint, they are presented with a consent screen. The details displayed on the consent screen are populated based on the information provided in the query string of the request.

Authorization Request Querystring

Properties

Name	Type	Description	Required
client_id	string	The ID of the application that asks for authorization. An IndieAuth client ID is a URL. Format: "uri"	yes
code_challenge (PKCE code challenge)	string	The PKCE code challenge. See Client Creates the Code Challenge. Minimal Length: 43 Maximal Length: 128	yes
code_challenge_method (PKCE code challenge method)		The hashing method used to calculate the code challenge in the PKCE OAuth 2.0 flow. See Client Creates the Code Challenge.	yes
me			yes
redirect_uri	string	Holds a URL. A successful response from this endpoint results in a redirect to this URL. Format: "uri"	yes
response_type (OAuth 2.0 response_type)		Tells the authorization server which grant to execute. Default: "code"	yes
scope (OAuth 2.0 scope (scopes) claim)	string	Scope values. See RFC8693 scope claim Minimal Length: 1	no
state (OAuth 2.0 state parameter (CSRF token))	string	An opaque value used by the client to maintain state between the request and callback. The parameter SHOULD be used for preventing cross-site request forgery. See OAuth 2.0 Authorization Request. Minimal Length: 1	yes

Example

{
    "response_type": "code"
}

Verifying the authorization code

To verify that the authorization code is valid, the token endpoint of the authorization server makes a POST request to the authorization endpoint.

Access Token Request Body

Properties

Name	Type	Description	Required
client_id	string	The ID of the application that asks for authorization. An IndieAuth client ID is a URL. Format: "uri"	yes
code	string	The authorization code generated by the authorization endpoint. The code MUST expire shortly after it is issued to mitigate the risk of leaks, and MUST be valid for only one use. A maximum lifetime of 10 minutes is recommended. See Authorization Response. Minimal Length: 1	yes
code_verifier	string	PKCE code verifier. A high-entropy cryptographic random string. See Client Creates a Code Verifier. Minimal Length: 43 Maximal Length: 128	yes
grant_type	string	Constant Value: "authorization_code"	yes
redirect_uri	string	Holds a URL. A successful response from this endpoint results in a redirect to this URL. Format: "uri"	yes

Dependencies

Package	Version
@fastify/formbody	^8.0.2
@fastify/response-validation	^3.0.3
@hapi/hoek	^11.0.7
@jackdbd/canonical-url	^0.0.0-canary.1
@jackdbd/fastify-webc	^0.0.0-canary.1
@jackdbd/indieauth	^0.0.0-canary.1
@jackdbd/oauth2	^0.0.0-canary.1
@jackdbd/oauth2-error-responses	^0.0.0-canary.1
@jackdbd/pkce	^0.0.0-canary.1
@jackdbd/schema-validators	^0.0.0-canary.1
@sinclair/typebox	^0.34.14
ajv	^8.17.1
ajv-formats	^3.0.1
dayjs	^1.11.13
dayjs-plugin-utc	^0.1.2
fastify-plugin	^5.0.1
ms	3.0.0-canary.1

⚠️ Peer Dependencies

This package defines 1 peer dependency.

Peer	Version range
fastify	>=5.0.0

Authorization codes

The authorization codes issued by the authorization endpoint implemented by this plugin are Nano IDs generated with nanoid.

References

• Redeeming the Authorization Code
• Authorization Code Grant - The OAuth 2.0 Authorization Framework (RFC 6749)
• Authorization Endpoint - The OAuth 2.0 Authorization Framework (RFC 6749)
• Authorization Request - The OAuth 2.0 Authorization Framework (RFC 6749)
• Authorization Response - The OAuth 2.0 Authorization Framework (RFC 6749)
• Authorization Request - IndieAuth
• Authorization Response - IndieAuth
• IndieAuth Rocks! (validator for testing IndieAuth client and server implementations)
• IndieAuth scopes: email, profile
• Micropub scopes: create, update, delete, undelete, draft, media

License

© 2024 - 2025 Giacomo Debidda // MIT License