Client Application

The client application is, quoting the rfc:

An application making protected resource requests on behalf of the resource owner and with its authorization.

The client application must be registered in the rodauth-oauth-enabled OAuth provider before it can start authorizing its users. This can be done by:

• using dynamic client registration
• using the management dashboard plugins
• add them directly to the database and build your own features around it

or all of the above.

Client applications are stored in a database table identified by the oauth_applications_table option (:oauth_applications by default). You can see an example of a db migration to bootstrap client applications here

Attributes

A client application is identified by to following attributes:

Client ID

• option: oauth_applications_client_id_column
• default: :client_id

The client ID is the unique identifier used in all OAuth protocol operations. It’s assigned to the application on registration.

Client Secret

• option: oauth_applications_client_secret_hash_column

• default: :client_secret

• option: oauth_applications_client_secret_column
• default: :client_secret

The client secret is assigned on registration, and ideally should be known only by the client application. It is not used for identifying the client application, and must only be used in TLS-enabled server-to-server OAuth operations (such as using the token endpoint).

By default, the client secret is hashed (using bcrypt) before being stored in the DB (in the column pointed by the oauth_applications_client_secret_hash_column option).

This may an issue if you’re required to use certain OAuth/OIDC options which require the provider to know client secrets (such as the client_secret_jwt auth method), so if you need to store them in plaintext, you’ll have to do the following:

plugin :rodauth do
  # ...
  oauth_applications_client_secret_hash_column :nil
  oauth_applications_client_secret_hash_column :client_secret
end

If you’d like to replace the hashing function (for, let’s say, argon2), you’ll need to perform the following overrides:

plugin :rodauth do
  # ...

  secret_matches? { |oauth_application, secret| Argon2::Password.verify_password(secret, oauth_application[oauth_applications_client_secret_hash_column]) }
  secret_hash { |secret| Argon2::Password.create(secret) }
end

Client Name

• option: oauth_applications_name_column
• default: :name

The name by which the application wishes to be identified.

Scopes

• option: oauth_applications_scopes_column
• default: :scopes

A group of codes describing what the application is allowed to do or have access to on behalf of resource owners.

The application can therefore ask for authorization for all or a subset of these scopes.

Multiple scopes are stored as a whitespace-separated string.

Redirect URI

• option: oauth_applications_redirect_uri_column
• default: :redirect_uri

The URI where the result of authorization requests will be sent to.

An application can have multiple redirect URIs.

The authorize URL can therefore have a redirect uri, and it must match one of the defined redirect URIs.

Multiple redirect URIs can be stored as a whitespace-separated string.

Homepage URL (optional)

• option: oauth_applications_homepage_url_column
• default: :homepage_url

The main link to the application website (used as a link in the default authorization form).

Description (optional)

• option: oauth_applications_description_column
• default: :description

Brief explanation of what the application is.

Logo URI (optional)

• option: oauth_applications_logo_uri_column
• default: :logo_uri

The application logo URI should point to an image of the application logo, which is loaded in the default authorization form for branding.

Token Endpoint Auth Methods (optional)

• option: oauth_applications_token_endpoint_auth_method_column
• default: :token_endpoint_auth_method

Used to limit the auth methods used by requests which require client authorization, i.e. token or token introspection. Examples of possible values are client_secret_basic or client_secret_post (if the oauth_jwt_bearer_grant plugin is used, then client_secret_jwt or private_key_jwt can also be used).

When not used, requests can be authorized by any of the auth methods supported by your rodauth-oauth configuration.

Grant Types (optional)

• option: oauth_applications_grant_types_column
• default: :grant_types

The application can limit the grant types it can be used with, in case the rodauth-oauth loaded plugins support multiple grant types.

When not used, all grant types supported by your rodauth-oauth configuration will be used.

Response Types (optional)

• option: oauth_applications_response_types_column
• default: :response_types

The application can limit the response types it can be used with, in case the rodauth-oauth enabled server supports multiple grant types.

When not used, all response types supported by your rodauth-oauth configuration will be used.

Code Challenge (optional)

This column can be omitted unless you’re using the oauth_pkce feature.

• option: oauth_applications_code_challenge_column
• default: :code_challenge

The code challenge sent from the authorization request.

Code Challenge (optional)

This column can be omitted unless you’re using the oauth_pkce feature.

• option: oauth_applications_code_challenge_method_column
• default: :code_challenge_method

The code challenge method sent from the authorization request.

Policy URI (optional)

• option: oauth_applications_policy_uri_column
• default: :policy_uri

The application can set a policy URI, which the default authorization form links to.

Terms of Service URI (optional)

• option: oauth_applications_tos_uri_column
• default: :tos_uri

The application can set a “terms of Service” URI, which the authorization form will link to.

Contacts (optional)

• option: oauth_applications_contacts_column
• default: :contacts_uri

The application can set a group of contacts, which the authorization form exposes.

Registration Access Token (optional)

This column can be omitted unless you’re using the oauth_dynamic_client_registration feature and the registration client URI.

• option: oauth_applications_registration_access_token_column
• default: :registration_access_token

Used to store the access token used to interact with the client registration URI.

JWKs (optional)

This column can be omitted unless you’re using the oauth_jwt feature.

• option: oauth_applications_jwks_column
• default: :jwks

The application can set the JWKs to be used for signing and encryption of JWT tokens.

Must not to be set if JWKs URI are used instead.

JWKs URI (optional)

This column can be omitted unless you’re using the oauth_jwt feature.

• option: oauth_applications_jwks_uri_column
• default: :jwks_uri

The application can set a URI from where to load the JWKs (it’s recommended you prefer to use this option rather than the previous one, as it’s tolerant to cache-busting and is usually more friendly towards key rotation).

Must not be set if JWKs are used instead.

Software ID and Version (optional)

• option: oauth_applications_software_id_column
• default: :software_id
• option: oauth_applications_software_version_column
• default: :software_version

The application can set these two opaque values, which usually allow for registering different client application accounts for the same vendor, as per RFC.

Sector identifier URI (optional)

This column can be omitted unless you’re using the oidc feature.

• option: oauth_applications_sector_identifier_uri_column
• default: :sector_identifier_uri

URI which references a file with a single JSON array of redirect_uri values. Providers that use pairwise sub (subject) values SHOULD provide a sector_identifier_uri.

Application type (optional)

• option: oauth_applications_application_type_column
• default: :application_type

Kind of the application. Can be native or web.

Subject type (optional)

This column can be omitted unless you’re using the oidc feature.

• option: oauth_applications_subject_type_column
• default: :subject_type

Subject type requested for responses to this client_id. Valid types include "pairwise" and "public".

ID Token Response Signing Algorithm (optional)

This column can be omitted unless you’re using the oidc feature.

• option: oauth_applications_id_token_signed_response_alg_column
• default: :id_token_signed_response_alg

Can be used to define the signing algorithm (i.e. "RS256") with which its ID Tokens will be signed.

ID Token Response Encryption Algorithm (optional)

This column can be omitted unless you’re using the oidc feature.

• option: oauth_applications_id_token_encrypted_response_alg_column
• default: :id_token_encrypted_response_alg

Can be used to define the encryption algorithm (i.e. "RSA-OAEP") with which its ID Tokens will be encrypted.

ID Token Response Encryption Method (optional)

This column can be omitted unless you’re using the oidc feature.

• option: oauth_applications_id_token_encrypted_response_enc_column
• default: :id_token_encrypted_response_enc

Can be used to define the encryption method (i.e. "A256CBC-HS512") with which its ID Tokens will be encrypted.

Userinfo Response Signing Algorithm (optional)

This column can be omitted unless you’re using the oidc feature.

• option: oauth_applications_userinfo_signed_response_alg_column
• default: :userinfo_signed_response_alg

Can be used to define the signing algorithm (i.e. "RS256") with which the payload of the userinfo endpoint will be signed.

Userinfo Response Encryption Algorithm (optional)

This column can be omitted unless you’re using the oidc feature.

• option: oauth_applications_userinfo_encrypted_response_alg_column
• default: :userinfo_encrypted_response_alg

Can be used to define the encryption algorithm (i.e. "RSA-OAEP") with which the payload of the userinfo endpoint will be encrypted.

Userinfo Response Encryption Method (optional)

This column can be omitted unless you’re using the oidc feature.

• option: oauth_applications_userinfo_encrypted_response_enc_column
• default: :userinfo_encrypted_response_enc

Can be used to define the encryption method (i.e. "A256CBC-HS512") with which the payload of the userinfo endpoins will be encrypted.

Initiate login URI (optional)

This column can be omitted unless you’re using the oidc feature.

• option: oauth_applications_initiate_login_uri_column
• default: :initiate_login_uri

Used to store the client-defined login URI to initiate the 3rd party login.

Request object Response Signing Algorithm (optional)

This column can be omitted unless you’re using the oauth_jwt_secured_authorization_request feature.

• option: oauth_applications_request_object_signed_response_alg_column
• default: :request_object_signed_response_alg

Can be used to define the signing algorithm (i.e. "RS256") which will be used to verify secured authorization request JWT tokens.

Request object Response Encryption Algorithm (optional)

This column can be omitted unless you’re using the oauth_jwt_secured_authorization_request feature.

• option: oauth_applications_request_object_encrypted_response_alg_column
• default: :request_object_encrypted_response_alg

Can be used to define the encryption algorithm (i.e. "RSA-OAEP") which will be used to decrypt secured authorization request JWT tokens.

Request object Response Encryption Method (optional)

This column can be omitted unless you’re using the oauth_jwt_secured_authorization_request feature.

• option: oauth_applications_request_object_encrypted_response_enc_column
• default: :request_object_encrypted_response_enc

Can be used to define the encryption method (i.e. "A256CBC-HS512") which will be used to decrypt secured authorization request JWT tokens.

Require push authorization request (optional)

This column can be omitted unless you’re using the oauth_pushed_authorization_request feature.

• option: oauth_applications_require_pushed_authorization_requests_column
• default: :require_pushed_authorization_requests

Whether an application requires PAR-based authorization requests.

TLS client cert Subject DN (optional)

This column can be omitted unless you’re using the oauth_tls_client_auth feature.

• option: oauth_applications_tls_client_auth_subject_dn_column
• default: :tls_client_auth_subject_dn

Stores the string representation of the expected subject distinguished name of the certificate that the OAuth client will use in mutual-TLS authentication.

TLS client cert SAN DNS (optional)

This column can be omitted unless you’re using the oauth_tls_client_auth feature.

• option: oauth_applications_tls_client_auth_san_dns_column
• default: :tls_client_auth_san_dns

Stores the string representation of the expected dNSName SAN entry of the certificate that the OAuth client will use in mutual-TLS authentication.

TLS client cert SAN URI (optional)

This column can be omitted unless you’re using the oauth_tls_client_auth feature.

• option: oauth_applications_tls_client_auth_san_uri_column
• default: :tls_client_auth_uri_dns

Stores the string representation of the expected uniformResourceIdentifier SAN entry of the certificate that the OAuth client will use in mutual-TLS authentication.

TLS client cert SAN IP (optional)

This column can be omitted unless you’re using the oauth_tls_client_auth feature.

• option: oauth_applications_tls_client_auth_san_ip_column
• default: :tls_client_auth_ip_dns

Stores the string representation of an iPAddress SAN entry of the certificate that the OAuth client will use in mutual-TLS authentication.

TLS client cert SAN Email (optional)

This column can be omitted unless you’re using the oauth_tls_client_auth feature.

• option: oauth_applications_tls_client_auth_san_email_column
• default: :tls_client_auth_email_dns

Stores the string representation of the expected rfc822Name SAN entry of the certificate that the OAuth client will use in mutual-TLS authentication.

TLS client cert bound access tokens (optional)

This column can be omitted unless you’re using the oauth_tls_client_auth feature.

• option: oauth_applications_tls_client_certificate_bound_access_tokens_column
• default: :tls_client_certificate_bound_access_tokens

Stores whether the generated access tokens will be bound to the client certificate.

Post logout redirect uris (optional)

This column can be omitted unless you’re using the oidc_rp_initiated_logout feature.

• option: oauth_applications_post_logout_redirect_uris_column
• default: :post_logout_redirect_uris

URI used during the OIDC logout process.

Account ID (optional, but recommended)

• option: oauth_applications_account_id_column
• default: :account_id

The account ID should reference the application owner, i.e. the user account in the OAuth provider this application is assigned to. This will allow it to manage the registered application, and to have a point-of-contact one can direct queries to.

However, if you want to do this ad-hoc, you don’t need to have it from the get go.

Response mode Authorization Signing Algorithm (optional)

This column can be omitted unless you’re using the oauth_jwt_secured_authorization_response_mode feature.

• option: oauth_applications_authorization_signed_response_alg_column
• default: :authorization_signed_response_alg

Can be used to define the signing algorithm (i.e. "RS256") which will be used to sign secured authorization response mode JWT tokens.

Response mode Authorization Encryption Algorithm (optional)

This column can be omitted unless you’re using the oauth_jwt_secured_authorization_response_mode feature.

• option: oauth_applications_authorization_encrypted_response_alg_column
• default: :authorization_encrypted_response_alg

Can be used to define the encryption algorithm (i.e. "RSA-OAEP") which will be used to encrypt secured authorization response mode JWT tokens.

Response mode Authorization Encryption Method (optional)

This column can be omitted unless you’re using the oauth_jwt_secured_authorization_response_mode feature.

• option: oauth_applications_authorization_encrypted_response_enc_column
• default: :authorization_encrypted_response_enc

Can be used to define the encryption method (i.e. "A256CBC-HS512") which will be used to encrypt secured authorization request JWT tokens.

Home