oauth_base.rdoc

doc/oauth_base.rdoc
Last Update: 2023-04-29 00:05:41 +0000

Documentation for OAuthBase feature

The oauth_base feature implements all basic functionality in order to set up an authorization server, which can emit and verify tokens.

datatracker.ietf.org/doc/html/rfc6749

It alternatively can set up a resource server.

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.

before_token_route

Run arbitrary code before the token route.

before_token

Run arbitrary code before generating an access 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.

Auth methods

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).

authorization_server_url

returns the authorization server origin URL.

oauth_unique_id_generator

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

oauth_grants_unique_columns

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

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)