oauth_base.rdoc

doc/oauth_base.rdoc
Last Update: 2024-06-17 10:14:17 +0000

Documentation for OAuthBase feature

The oauth_base feature implements all basic functionality in order to set up an authorization server and verify OAuth tokens.

It sets up the token URL, used to generate OAuth access tokens.

datatracker.ietf.org/doc/html/rfc6749

In your routing block, you can require OAuth token based authorization via:

rodauth.require_oauth_authorization

# or

rodauth.require_oauth_authorization("books.read") # scope-based authorization

It also implements the refresh token grant flow.

Auth Value Methods

oauth_application_scopes

default scopes to assign to a client application, ["profile.read"] by default.

oauth_token_type

type of the generated access token, "bearer" by default.

oauth_grant_expires_in

The number of seconds an oauth grant is valid after creation, 5 minutes by default.

oauth_access_token_expires_in

The number of seconds an oauth token is valid after creation, 5 minutes by default.

oauth_refresh_token_expires_in

The number of seconds a refresh token is valid after creation, 1 year by default.

oauth_refresh_token_protection_policy

protection policy for the refresh token (rotation by default).

oauth_scope_separator

character used to separate scopes in the db field value, white-space by default.

oauth_token_endpoint_auth_methods_supported

list of supported auth methods for the token endpoint (contains “client_secret_basic” and “client_secret_post” by default).

oauth_grant_types_supported

list of supported grant types.

oauth_response_types_supported

list of supported response types.

oauth_response_modes_supported

list of supported response modes.

oauth_valid_uri_schemes

list of supported URI schemes for a client application’s “redirect_uri”, %w[https] by default.

oauth_applications_table

the db table where oauth applications are stored, :oauth_applications by default.

oauth_applications_id_column

the db column where the oauth application primary key is stored, :id by default.

oauth_applications_account_id_column

the db column where the oauth application account ID it belongs to is stored, :account_id by default.

oauth_applications_name_column

the db column where the oauth application name is stored, :name by default.

oauth_applications_description_column

the db column where the oauth application description is stored, :description by default.

oauth_applications_scopes_column

the db column where the oauth allowed scopes are stored, :scopes by default.

oauth_applications_client_id_column

the db column where the oauth application client ID is stored, :client_id by default.

oauth_applications_client_secret_column

the db column where the oauth application plaintext client secret is stored, :client_secret by default.

oauth_applications_client_secret_hash_column

the db column where the oauth application hashed client secret is stored, :client_secret by default.

oauth_applications_redirect_uri_column

the db column where the oauth application redirect URI is stored, :redirect_uri by default.

oauth_applications_homepage_url_column

the db column where the oauth application homepage URL is stored, :homepage_url by default.

oauth_applications_contacts_column

the db column where the oauth application contacts are stored, :contacts by default.

oauth_applications_grant_types_column

the db column where the oauth application supported grant types are stored, :grant_types by default.

oauth_applications_response_types_column

the db column where the oauth application supported response types are stored, :response_types by default.

oauth_applications_response_modes_column

the db column where the oauth application supported response modes are stored, :response_modes by default.

oauth_applications_jwks_column

the db column where the oauth application JSON Web Keys are stored, :jwks by default.

oauth_applications_jwks_uri_column

the db column where the oauth application JSON Web Keys URI is stored, :jwks_uri by default.

oauth_applications_logo_uri_column

the db column where the oauth application logo URL is stored, :logo_uri by default.

oauth_applications_policy_uri_column

the db column where the oauth application policy URL is stored, :policy_uri by default.

oauth_applications_tos_uri_column

the db column where the oauth application terms of service URL is stored, :tos_uri by default.

oauth_applications_software_id_column

the db column where the oauth application software ID is stored, :software_id by default.

oauth_applications_software_version_column

the db column where the oauth application software version is stored, :software_version by default.

oauth_applications_token_endpoint_auth_method_column

the db column where the oauth application supported auth method for the token endpoint is stored, :software_id by default.

oauth_grants_table

the db table where oauth grants are stored, :oauth_grants by default.

oauth_grants_id_column

the db column where the oauth grant primary key is stored, :id by default.

oauth_grants_oauth_application_id_column

the db column where the oauth grant oauth application ID is stored, :oauth_application_id by default.

oauth_grants_account_id_column

the db column where the oauth grant account ID is stored, :account_id by default.

oauth_grants_type_column

the db column where the grant type is stored, :type by default.

oauth_grants_code_column

the db column where the oauth grant authorization code is stored, :code by default.

oauth_grants_redirect_uri_column

the db column where the oauth grant redirect URI is stored, :redirect_uri by default.

oauth_grants_scopes_column

the db column where the oauth grant scopes are stored, <tt>:scopes<tt> by default.

oauth_grants_expires_in_column

the db column where the oauth grant expiration time is stored, :expires_in by default.

oauth_grants_revoked_at_column

the db column where the oauth grant revocation time is stored, :revoked_at by default.

oauth_grants_token_column

the db column where the oauth token access token is stored (when it’s stored), :token by default.

oauth_grants_refresh_token_column

the db column where the refresh token is stored, :refresh_token by default.

oauth_grants_token_hash_column

the db column where the access token hash is stored, <tt>:token<tt> by default.

oauth_grants_refresh_token_hash_column

the db column where the refresh token hash is stored, <tt>:refresh_token<tt> by default.

json_response_content_type

The content type to set for json responses, application/json by default.

json_request_regexp

The regexp to retrieve a valid json content type.

oauth_authorization_required_error_status

HTTP status code used for authorization errors, 401 by default.

oauth_invalid_response_status

HTTP status code used for invalid responses, 400 by default.

oauth_already_in_use_response_status

HTTP status code used for already in use responses, 409 by default.

only_json?

whether the application responds only with json.

oauth_invalid_client_message

error description for the “invalid_client” OAuth error code, "Invalid client" by default.

oauth_invalid_grant_type_message

error description for the “invalid_grant_type” OAuth error code, "Invalid grant type" by default.

oauth_invalid_grant_type_error_code

oauth error code for using invalid grants, "unsupported_grant_type" by default.

oauth_invalid_grant_message

error description for the “invalid_grant” OAuth error code, "Invalid grant" by default.

oauth_invalid_scope_message

error description for the “invalid_scope” OAuth error code, "Invalid scope" by default.

oauth_unsupported_token_type_message

error description for the “unsupported_token_type” OAuth error code, "Invalid token type hint" by default.

oauth_already_in_use_error_code

oauth error code for when a token is already in use, "invalid_request" by default.

oauth_already_in_use_message

error description for the “already_in_use” OAuth error code.

oauth_metadata_service_documentation

OAuth service documentation URL, nil by default.

oauth_metadata_ui_locales_supported

UI locales supported in the OAuth journey, nil by default.

oauth_metadata_op_policy_uri

OAuth use of data and client requirements URL, nil by default.

oauth_metadata_op_tos_uri

OAuth terms of service, nil by default.

is_authorization_server?

flag to signal whether it’s an authorization server, true by default.

token_route

the route for token generation, defaults to token.

oauth_unique_id_generation_retries

max retries for token generation.

oauth_reuse_access_token

when true, it’ll reuse the same access token for a given account/client application for each new verified grant.

require_authorization_error_flash

The flash error to display when authorization is required.

revoke_unauthorized_account_error_flash

The flash error to display when an unauthorized account tries to revoke a token.

oauth_cancel_button

button label which cancels the device verification.

http_request

performs a GET http request to the given URL (or a POST with url-encoded body, if form data is passed)

http_request_cache

store where http requests get cached according to the HTTP cache rules.

authorization_server_url

returns the authorization server origin URL.

oauth_grants_unique_columns

uniqueness index to use in ON CONFLICT queries (when supported).

Auth Methods

before_token_route

Run arbitrary code before the token route.

before_token

Run arbitrary code before generating an access token.

fetch_access_token

retrieves the access token from the request (defaults to fetching from the “Authorization” header).

secret_matches?

verifies if provided secret matches the application’s client secret.

secret_hash

calculates the hash of a given client secret.

generate_token_hash

hashes an access token (when the token hash is stored in the db).

oauth_unique_id_generator

generates random base64 strings, used for raw access tokens, client IDs, etc.

require_authorizable_account

requires the account to be logged in by default (calls ‘require_account`), can be overriden to add more functionality (i.e. requiring 2FA before authorization).

oauth_account_ds

returns a dataset filtered for an account id (overriden in rails to use Active Record Account model)

oauth_application_ds

returns a dataset filtered for an oauth application id (overriden in rails to use Active Record OAuthApplication model)