-
Notifications
You must be signed in to change notification settings - Fork 0
Configuration
This page details every configuration option available inside config/initializers/rails_iam.rb.
config.user_class
Default: 'RailsIam::User'
Defines the main model used for user login, authentication, and authorization lookup. Change it to your own model name string (e.g., 'User' or 'Account') if you have an existing auth model.
config.current_user_method
Default: :current_user
Specifies the method your controllers use to load and reference the logged-in user. Change this to match your existing authentication setup (e.g., :current_member).
config.audit_performer_method
Default: :email
Determines which field or lambda string to save in the created_by, updated_by and deleted_by audit columns. Pass a different column symbol or a custom proc to track more advanced user footprint details. e.g., ->(user) { "#{user.first_name}:#{user.last_name}" }
config.authentication.access_token_key
Default: 'access_token'
Sets the key name used to read or write short-lived access tokens from cookie or bearer token.
config.authentication.refresh_token_key
Default: 'refresh_token'
Sets the key name used to read or write long-lived session renewal tokens.
config.authentication.authentication_strategies
Default: [:cookie]
Sets the accepted transport channels where the engine will look for incoming tokens. Use [:cookie], [:bearer] (for HTTP Authorization headers), or include both [:cookie, :bearer].
config.authentication.cookie_options
Default: { httponly: true, secure: Rails.env.production?, same_site: :lax }
Configures the security, domain, and expiration attributes for issued httponly cookies.
config.authentication.access_token_expires_in
Default: 15.minutes
The lifetime of the access token. When using the :cookie authentication strategy, this value is also used as the HttpOnly cookie expiration. It should always match the JWT expiration time to keep both values in sync.
config.authentication.refresh_token_expires_in
Default: 30.days
Refresh token life span. Configure if you want to shorten the time.
config.authentication.refresh_token_transport
Default: :header
Determines where the engine looks for a refresh token during token renewal requests when using authentication strategies :bearer. Set to :header (looks for HTTP_X_*#{refresh_token_key}) or :request_body (looks inside request body using #{refresh_token_key} params key).
config.authentication.session_strategy
Default: :single
Sets whether users can have multiple concurrent active login sessions. Change to :multi to invalidate other sessions immediately when a user logs in on a new device.
config.authentication.sign_in_path
Default: '/auth/sign_in'
Defines the automatic internal HTTP routing path exposed by the engine's built-in sign in path. Change the route string if you want a different path. Set to nil to disable engine paths or if you don't use rails_iam authentication feature.
config.authentication.sign_out_path
Default: '/auth/sign_out'
Defines the automatic internal HTTP routing path exposed by the engine's built-in signout path.
config.authentication.refresh_token_path
Default: '/auth/refresh'
Defines the automatic internal HTTP routing path exposed by the engine's built-in refresh token path.
config.authentication.token_error
Default: "The provided authentication token is invalid or malformed."
Configures the human-readable text strings returned in JSON payloads when authentication fails or token raises errors. You can also use localization here using I18n.translate('...').
config.authentication.token_expired_error
Default: "The authentication token has expired. Please re-authenticate."
Configures the human-readable text strings returned in JSON payloads when access token expired.
config.authentication.authentication_error
Default: "Invalid email or password."
Configures the human-readable text strings returned in JSON payloads when authentication fails due to mismatch credentials.
config.authorization.missing_role_error
Default: "Missing roles: {role_name}, You only have: {role_name}"
Formats the error messaging returned to a client when they lack required system roles. Override with a custom string or pass a dynamic keyword lambda to translate or reformat the output. e.g., ->(required:, actual:) { ... }
config.authorization.missing_permission_error
Default: "Missing permission(s): permission_code"
Formats the error messaging returned to a client when they lack required system permissions. Override with a custom string or pass a dynamic keyword lambda to translate or reformat the output. e.g., ->(required:, actual:) { ... }
config.authorization.authorization_rule_error
Default: "No authorization rule for {action_name}"
Sets the system error message prefix triggered when an endpoint has missing authorization rules. Change this text string if your application requires specialized internal exception notifications.
config.authorization.cache_store
Default: Rails.cache
Selects the system caching engine used to store resolved roles and permission queries. Will work with Redis, Memcache, or Solid Cache.
config.authorization.cache_ttl
Default: 15.minutes
Determines how long a user's resolved role and permission data remains cached before re-querying the database.
config.authorization.excluded_controller_patterns
Default: []
Exempts specific controller families entirely from automatic endpoint authorization checks. Pass an array of Regexp matchers to exclude external engines like Devise or Sidekiq. Example: [/\ADevise::/, /\ARailsIam::/]
config.jwt.secret
Default: ENV['JWT_SECRET'] or secret_key_base
The cryptographic key used to sign JWT tokens to prepare access tokens. Falls back to Rails secret_key_base.
config.jwt.algorithm
Default: 'HS256'
Sets the digital signature cipher method used to encrypt your payload signatures.
config.jwt.jwt_expires_in
Default: 15.minutes
Configures the precise duration lifespan of an encrypted jwt token before it becomes unusable.
config.jwt.issuer
Default: nil
Validates standard RFC-7519 security claims to verify token source origins and target client systems. Provide this value if your application needs it. You can also pass issuer and audience dynamically from JWTencoder
config.jwt.audience
Default: nil
Validates standard RFC-7519 security claims to verify token source origins and target client systems. Provide this value if your application needs it.