Module: Machina

Defined in:
lib/machina.rb,
lib/machina/engine.rb,
lib/machina/errors.rb,
lib/machina/current.rb,
lib/machina/version.rb,
lib/machina/authorized.rb,
lib/machina/test_helpers.rb,
lib/machina/configuration.rb,
lib/machina/workspace_ref.rb,
lib/machina/identity_client.rb,
lib/machina/permission_sync.rb,
lib/machina/webhook_receiver.rb,
lib/machina/workspace_scoped.rb,
lib/machina/controller_helpers.rb,
lib/machina/middleware/authentication.rb,
lib/generators/machina/install_generator.rb,
app/controllers/machina/webhooks_controller.rb,
lib/machina/middleware/authentication/hints.rb,
app/controllers/machina/callbacks_controller.rb

Overview

Machina is a Ruby gem that provides authentication and authorization integration with the ZAR Machina Console identity service.

Defined Under Namespace

Modules: ControllerHelpers, Generators, Middleware, TestHelpers, WorkspaceScoped Classes: Authorized, CallbacksController, Configuration, ConfigurationError, Current, Engine, Error, IdentityClient, PermissionSync, Unauthorized, WebhookReceiver, WebhooksController, WorkspaceRef

Constant Summary collapse

VERSION = 
'1.0.2'

Class Method Summary collapse

Class Method Details

.authorize_url(redirect_to: nil, return_to: nil, state: nil) ⇒ String

Builds the Console authorize URL.

The Console's /authorize endpoint requires a redirect_to query param so it knows where to send the user after workspace selection. This method always produces that param — the two keyword arguments control how:

  1. Callback-based (preferred) — uses the configured identity_callback_uri as the redirect target. Pass return_to to append the user's intended destination as a query param on the callback.
  2. Explicit — pass redirect_to directly to bypass callback resolution. Intended for backwards compatibility only.

Parameters:

  • redirect_to (String, nil) (defaults to: nil) —

    explicit product redirect URL; when present the callback URI config is ignored

  • return_to (String, nil) (defaults to: nil) —

    user's intended destination, appended to identity_callback_uri so the product app can restore it after auth

  • state (String, nil) (defaults to: nil) —

    CSRF nonce appended to the redirect target; Console echoes it back and the callback rejects a mismatch

Returns:

  • (String) —

    the full Console authorize URL

Raises:

  • (ConfigurationError) —

    when redirect_to is omitted and identity_callback_uri is not configured



79
80
81
82
83
84
85
 
# File 'lib/machina.rb', line 79

def authorize_url(redirect_to: nil, return_to: nil, state: nil)
  redirect_target = redirect_to.presence || callback_redirect_target(return_to)
  redirect_target = append_query_param(redirect_target, 'state', state) if state.present?

  base = config.identity_service_url.to_s.sub(%r{/\z}, '')
  "#{base}/authorize?redirect_to=#{CGI.escape(redirect_target)}"
end

.cache ⇒ Object 



54
55
56
 
# File 'lib/machina.rb', line 54

def cache
  config.cache_store || Rails.cache
end

.config ⇒ Object 



41
42
43
 
# File 'lib/machina.rb', line 41

def config
  @config ||= Configuration.new
end

.configure {|config| ... } ⇒ Object

Yields:



37
38
39
 
# File 'lib/machina.rb', line 37

def configure
  yield(config)
end

.identity_client ⇒ Object 



50
51
52
 
# File 'lib/machina.rb', line 50

def identity_client
  @identity_client ||= IdentityClient.new(config:)
end

.login_url(return_to:, state: nil) ⇒ String

Convenience wrapper that delegates to authorize_url with return_to.

Parameters:

  • return_to (String) —

    the user's intended destination

  • state (String, nil) (defaults to: nil) —

    CSRF nonce (see authorize_url)

Returns:

  • (String) —

    the full authorize URL



92
93
94
 
# File 'lib/machina.rb', line 92

def (return_to:, state: nil)
  authorize_url(return_to:, state:)
end

.reset! ⇒ Object 



45
46
47
48
 
# File 'lib/machina.rb', line 45

def reset!
  @config = Configuration.new
  @identity_client = nil
end

.secure_cookies? ⇒ Boolean

True when session/state cookies must carry the Secure flag. Forced on outside development/test: request.ssl? is false behind TLS-terminating load balancers unless the app sets assume_ssl, silently downgrading the cookie.

Returns:

  • (Boolean) 


100
101
102
 
# File 'lib/machina.rb', line 100

def secure_cookies?
  !Rails.env.local?
end