Skip to content

Customizing Views

Jump to bottom
Dick Davis edited this page Jan 23, 2026 · 3 revisions

Customizing Views

TokenAuthority's views are intentionally unstyled so you can customize them to match your application's branding.

Copied Views

The install generator copies views to your application at app/views/token_authority/:

View Purpose
authorization_grants/new.html.erb OAuth consent screen where users approve or deny client access
client_error.html.erb Error page shown when the OAuth client's redirect URL is invalid

Consent Screen

The consent screen (authorization_grants/new.html.erb) is shown when an OAuth client requests authorization. Users see the client name and can approve or deny access.

Available Variables

Variable Description
client_name The name of the OAuth client requesting access
scopes Array of scope tokens requested by the client. Empty if no scopes requested.
resources Array of resource URIs requested by the client (RFC 8707). Empty if no resources requested.
state The OAuth state parameter (must be included in the form)

Helper Methods

Method Description
scope_description(scope) Returns the configured description for a scope token, or the scope token itself if no description is configured.
resource_display_name(uri) Returns the configured display name for a resource URI, or the URI itself if no display name is configured.

Example Customization

<%# app/views/token_authority/authorization_grants/new.html.erb %>
<div class="oauth-consent">
  <div class="consent-header">
    <h1>Authorize <%= client_name %></h1>
    <p class="consent-lede"><%= t("token_authority.authorization_grants.new.lede") %></p>
  </div>

  <div class="consent-details">
    <p>This application wants to access your account.</p>

    <% if scopes.any? %>
      <p><%= t("token_authority.authorization_grants.new.scopes_heading") %></p>
      <ul class="scope-list">
        <% scopes.each do |scope| %>
          <li><%= scope_description(scope) %></li>
        <% end %>
      </ul>
    <% end %>

    <% if resources.any? %>
      <p><%= t("token_authority.authorization_grants.new.resources_heading") %></p>
      <ul class="resource-list">
        <% resources.each do |resource| %>
          <li><%= resource_display_name(resource) %></li>
        <% end %>
      </ul>
    <% end %>
  </div>

  <%= form_with url: token_authority.authorization_grants_path, method: :post, class: "consent-form" do |form| %>
    <%= form.hidden_field :state, value: state %>

    <div class="consent-actions">
      <%= form.submit t("token_authority.authorization_grants.new.approve"),
          name: "approve",
          value: "true",
          class: "btn btn-primary" %>
      <%= form.submit t("token_authority.authorization_grants.new.reject"),
          name: "approve",
          value: "false",
          class: "btn btn-secondary" %>
    </div>
  <% end %>
</div>

The scope_description helper returns the human-friendly description configured in config.scopes, or falls back to the scope token if no description is configured.

The resource_display_name helper returns the human-friendly name configured in rfc_8707_resources, or falls back to the URI if no display name is configured.

Form Requirements

The consent form must:

  1. POST to token_authority.authorization_grants_path
  2. Include a hidden field for state
  3. Include a submit button named approve with value "true" for approval
  4. Include a submit button named approve with value "false" for denial

Error Page

The error page (client_error.html.erb) is shown when the OAuth client provides an invalid redirect URL. This is a security measure - we can't redirect to an untrusted URL.

Example Customization

<%# app/views/token_authority/client_error.html.erb %>
<div class="oauth-error">
  <h1>Authorization Error</h1>
  <p>The application that sent you here has an invalid configuration.</p>
  <p>Please contact the application developer or try again later.</p>

  <a href="/" class="btn">Return Home</a>
</div>

Styling with CSS

Add CSS to your application's stylesheet:

/* app/assets/stylesheets/oauth.css */

.oauth-consent {
  max-width: 400px;
  margin: 4rem auto;
  padding: 2rem;
  border: 1px solid #e5e7eb;
  border-radius: 8px;
}

.consent-header h1 {
  font-size: 1.5rem;
  margin-bottom: 0.5rem;
}

.consent-lede {
  color: #6b7280;
  margin-bottom: 1.5rem;
}

.consent-actions {
  display: flex;
  gap: 1rem;
  margin-top: 1.5rem;
}

.btn {
  padding: 0.5rem 1rem;
  border-radius: 4px;
  font-weight: 500;
  cursor: pointer;
}

.btn-primary {
  background-color: #3b82f6;
  color: white;
  border: none;
}

.btn-secondary {
  background-color: white;
  color: #374151;
  border: 1px solid #d1d5db;
}

Using Rails I18n

The views use Rails I18n for text content. Customize the text by overriding keys in your locale files:

# config/locales/token_authority.en.yml
en:
  token_authority:
    authorization_grants:
      new:
        lede: "wants to access your account"
        scopes_heading: "This application is requesting the following permissions:"
        resources_heading: "This application is requesting access to:"
        approve: "Allow Access"
        reject: "Deny"

Available I18n Keys

See config/locales/token_authority.en.yml in the gem for all available keys:

bundle show token_authority
# Then browse to config/locales/ in the gem directory

Layout Customization

By default, TokenAuthority uses your application's layout. Configure different layouts in the initializer:

# config/initializers/token_authority.rb
TokenAuthority.configure do |config|
  config.consent_page_layout = "oauth"      # Uses app/views/layouts/oauth.html.erb
  config.error_page_layout = "oauth_error"  # Uses app/views/layouts/oauth_error.html.erb
end

When to Use Custom Layouts

Consider custom layouts when:

  • OAuth pages should have simpler navigation than your main app
  • You want to remove sidebars or footers from authorization screens
  • You need different JavaScript or CSS for OAuth flows

Example OAuth Layout

<%# app/views/layouts/oauth.html.erb %>
<!DOCTYPE html>
<html>
<head>
  <title>Authorization - <%= Rails.application.class.module_parent_name %></title>
  <%= csrf_meta_tags %>
  <%= stylesheet_link_tag "application" %>
</head>
<body class="oauth-layout">
  <main class="oauth-container">
    <%= yield %>
  </main>
</body>
</html>

See Also

Home

Getting Started

Process Flows

Development

Clone this wiki locally