The oauth_authorize_code_grant feature implements the authorization code grant flow. It’s considered the most secure one, and the most widely deployed, so if you don’t have any idea what to set up, this this feature up.
As the standard way to use OAuth, this should be the default way to start.
plugin :rodauth do
enable :oauth_authorization_code_grant
oauth_application_scopes %w[profile.read profile.write]
end
The authorization form is available under GET /authorize by default. Only logged in users are able to access this endpoint.
You can override this behaviour by overwriting the require_authorizable_account rodauth hook.
The URI under which the journey begins is (by default) /authorize. You must (in some cases, can) pass the following query parameters:
"client_id" (required): the client ID of the client application;"redirect_uri" (required if the application defines multiple, optional otherwise): the uri to redirect the user after authorization;"scope" (optional): whitespace-separated permission scopes; if not passed, the grant will be generated with the application-defined scopes;"state" (optional): opaque value used by the client application to maintain state between the request and callback;"response_type" (required): identifies the type of grant desired by the application (default: code);"response_mode" (optional): identifies how the code/token will be delivered
"query": the default mode, will deliver the authorization code in the query param of a redirect_uri GET redirect request"fragment": will deliver the token as a URL fragment"form_post": will set the authorization code in the body of a POST request to redirect_uri (recommended)oauth_response_mode defines is the default);Example: https://oauth-server.com/authorize?client_id=23uhu23d89u3298du21j38q&redirect_uri=https%3A%2F%2Fclient.com%2Fcallback&scope=bricks.build+bricks.destroy&state=23r0rif3j0923j
The request triggered by the successful authorization form submission.
The authorization code will be sent in the request POST body (when using "form_post" response mode), or the query params of the redirect URI (when using "query"), i.e. code=23393id39d309d320d9k.
There are a few reasons why authorization may fail: scope might be invalid, uri parameter might be invalid, the resource owner might have pressed “Cancel”; in these cases, The user agent will redirect back to the same redirect uri, with error information sent as query params.
Example: https://client.com/callback?error_code=invalid_request&error_description="Request+is+missing+a+required+parameter
The form_post Response Mode is an extension to the original OAuth 2.0 framework, specifically targeting OIDC. It aims at mitigating security risks from the original strategies, by delivering the authorization code in a POST request’s body sent to the redirect URI of a client application.
You can use it by setting the response_mode=form_post query param in the authorize URL. However, if you want all authorizations to default to form_post when no response_mode is passed, you can set the oauth_response_mode:
plugin :rodauth do
enable :oauth_authorization_code_grant
oauth_response_mode "form_post"