omniauth-txssc-sso2 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 7edb14517a8106484bdb94e93989e8e00ed06d3249e88b76b1175afa83feccba
4
+ data.tar.gz: e47521a5bde4e8d682212cab4d30d37ce9340c7ff20f9e5be7be734b68760eb6
5
+ SHA512:
6
+ metadata.gz: 110611dfd9cf503f00dc55394c1547a10648337b76ae958fd53bbadeb1c1fa745ad0a4fe47e1675ff51f0828be1c0b832e3d55008b9afd9e7dfffc698ce1f913
7
+ data.tar.gz: 9e034aed55556d8ab633eda02967a5ec1dca01cb21b49d81de22bb7c57570d1afbf66abaac2d45ec59aee7183856c226f2059a20da0104bd630c137c0cdbae3b
data/CHANGELOG.md ADDED
@@ -0,0 +1,14 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 (2026-11-19)
4
+
5
+ - First version: `txssc_sso2` OmniAuth strategy for SSO2's authorization code flow.
6
+ - Verifies the returned JWT (HS256 signature, `iss`, `aud`, `exp`, required claims).
7
+ - Verifies tokens with SSO2's signing key (`jwt_secret`), and also accepts tokens signed
8
+ with the app's client secret, in case SSO2 later signs per app.
9
+ - `OmniAuth::TxsscSso2.logout_url` helper.
10
+ - Supports Ruby 2.7 and newer, and Rack 2 or 3, so older apps can move to SSO2.
11
+ Requires OmniAuth 2.2+ (for `OmniAuth.config.allowed_hosts`).
12
+ - `relay_form_post` (on by default): SSO2's callback POST is answered with a 303 to the
13
+ same URL as a GET, so `SameSite=Lax` session cookies reach the state check even when
14
+ SSO2 and the app are on different sites.
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 TxSSC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,168 @@
1
+ # omniauth-txssc-sso2
2
+
3
+ OmniAuth strategy for signing users in to Rails apps through **TxSSC SSO2**.
4
+
5
+ SSO2 handles the campus login (SAML with the university IdP). Apps never talk SAML;
6
+ they use this strategy, which runs SSO2's authorization code flow:
7
+
8
+ 1. The app sends the browser to SSO2's login URL with its `client_id`, `redirect_uri` and a random `state`.
9
+ 2. SSO2 signs the user in, then POSTs `code` and `state` back to the redirect URI **registered for the app in SSO2**.
10
+ The strategy answers that POST with a redirect to the same URL as a GET, so the app's session cookie is sent
11
+ even when SSO2 and the app are on different sites (see `relay_form_post`).
12
+ 3. The strategy checks `state`, exchanges the code (plus the client secret) at SSO2's token URL,
13
+ and verifies the signed JWT it gets back: HS256 signature, issuer, audience (`aud` = this app's client ID),
14
+ expiry, and required claims.
15
+ 4. The app receives a standard OmniAuth auth hash.
16
+
17
+ > This gem replaces nothing in `omniauth-txssc` (the old SSO). An app uses one or the other.
18
+
19
+ ## Installation
20
+
21
+ ```ruby
22
+ # Gemfile
23
+ gem "omniauth-txssc-sso2"
24
+ gem "omniauth-rails_csrf_protection" # OmniAuth 2 requires a CSRF-protected POST to start login
25
+ ```
26
+
27
+ ## Setup
28
+
29
+ ### 1. Register the app in SSO2
30
+
31
+ In SSO2's admin, create a service with the app's callback URL as its redirect URI, e.g.
32
+ `https://myapp.txssc.txstate.edu/users/sso/callback`. Note the client ID (uid) and secret.
33
+
34
+ SSO2 only ever sends users to the registered URI, and the token request must send exactly
35
+ the same URI, so the app's callback URL has to match it character for character.
36
+
37
+ ### 2. Configure the provider
38
+
39
+ ```ruby
40
+ # config/initializers/omniauth.rb
41
+ Rails.application.config.middleware.use OmniAuth::Builder do
42
+ provider :txssc_sso2,
43
+ ENV.fetch("IDP_CLIENT_ID"),
44
+ ENV.fetch("IDP_CLIENT_SECRET"),
45
+ client_options: { site: ENV.fetch("IDP_BASE_URL") }, # e.g. https://sso2.txssc.txstate.edu
46
+ callback_path: "/users/sso/callback", # path of the registered redirect URI
47
+ redirect_uri: ENV.fetch("SP_CALLBACK_URL"), # the registered redirect URI, in full
48
+ jwt_secret: ENV.fetch("IDP_JWT_SECRET") # SSO2's token signing key (see "Signing keys")
49
+ end
50
+
51
+ OmniAuth.config.logger = Rails.logger
52
+ # Only start or finish logins on the app's own host. Without this, OmniAuth trusts
53
+ # the Host header (and logs a warning on every login). Requests on other hosts fail
54
+ # with /auth/failure?message=invalid_host. Request specs run as www.example.com.
55
+ OmniAuth.config.allowed_hosts = [ENV.fetch("APP_HOST", "localhost")]
56
+ ```
57
+
58
+ Keep the one-time `code` and the `state` value out of the logs. Use exact matches so fields like
59
+ `zip_code` still log:
60
+
61
+ ```ruby
62
+ # config/initializers/filter_parameter_logging.rb
63
+ Rails.application.config.filter_parameters += [/\Acode\z/, /\Astate\z/]
64
+ ```
65
+
66
+ ### 3. Routes
67
+
68
+ ```ruby
69
+ # config/routes.rb
70
+ get "/users/sso/callback", to: "sso_sessions#create" # SSO2's POST arrives here as a GET (relay_form_post)
71
+ get "/auth/failure", to: "sso_sessions#failure"
72
+ delete "/logout", to: "sso_sessions#destroy"
73
+ ```
74
+
75
+ ### 4. Controller
76
+
77
+ ```ruby
78
+ class SsoSessionsController < ApplicationController
79
+ # The callback reaches #create as a GET, already verified by the strategy
80
+ # (state check, code exchange, token signature and claims).
81
+ skip_before_action :authenticate_user!, only: %i[create failure], raise: false
82
+
83
+ def create
84
+ auth = request.env.fetch("omniauth.auth")
85
+ user = User.find_or_initialize_by(net_id: auth.info.nickname)
86
+ user.update!(email: auth.info.email, first_name: auth.info.first_name, last_name: auth.info.last_name)
87
+
88
+ reset_session
89
+ session[:user_id] = user.id
90
+ redirect_to session.delete(:return_to) || root_path
91
+ end
92
+
93
+ def failure
94
+ redirect_to root_path, alert: "Sign-in failed (#{params[:message]})."
95
+ end
96
+
97
+ def destroy
98
+ reset_session
99
+ redirect_to OmniAuth::TxsscSso2.logout_url(site: ENV.fetch("IDP_BASE_URL"), client_id: ENV.fetch("IDP_CLIENT_ID")),
100
+ allow_other_host: true
101
+ end
102
+ end
103
+ ```
104
+
105
+ With Devise, put the same logic in an `omniauth_callbacks` controller and add
106
+ `devise :omniauthable, omniauth_providers: [:txssc_sso2]` to the model instead of the middleware initializer.
107
+
108
+ ### 5. Sign-in button
109
+
110
+ Starting the login must be a POST with a CSRF token:
111
+
112
+ ```erb
113
+ <%= button_to "Sign in", "/auth/txssc_sso2", method: :post, data: { turbo: false } %>
114
+ ```
115
+
116
+ ## The auth hash
117
+
118
+ | Key | Value |
119
+ | --- | --- |
120
+ | `provider` | `"txssc_sso2"` |
121
+ | `uid` | SSO2 user ID (`sub` claim), stable per user |
122
+ | `info.nickname` | netID |
123
+ | `info.email` | email |
124
+ | `info.first_name`, `info.last_name`, `info.name` | names |
125
+ | `info.image` | avatar URL (SSO2 sends its default image URL when the user has no avatar) |
126
+ | `credentials.token` | the raw SSO2 JWT |
127
+ | `extra.raw_info` | all verified JWT claims |
128
+
129
+ ## Options
130
+
131
+ | Option | Default | Notes |
132
+ | --- | --- | --- |
133
+ | `client_options.site` | none (required) | SSO2 base URL. Also the expected `iss`. |
134
+ | `redirect_uri` | Rack's view of the callback URL | Set it to the registered URI in production. Behind nginx/kamal-proxy, Rack may see `http://`. |
135
+ | `callback_path` | `/auth/txssc_sso2/callback` | Must be the path of the registered URI. |
136
+ | `jwt_secret` | `nil` | The key SSO2 signs tokens with. Needed with SSO2's current setup. The app's client secret is also accepted. |
137
+ | `issuer` | `client_options.site` | Override only if SSO2's public URL differs from `site`. |
138
+ | `jwt_leeway` | `30` | Seconds of clock skew allowed on `exp`. |
139
+ | `relay_form_post` | `true` | Answer SSO2's callback POST with a 303 to the same URL as a GET (code and state in the query string). Turn off only if the app must handle the POST itself. |
140
+
141
+ ## Signing keys
142
+
143
+ The gem works with SSO2 as it is configured today: SSO2 signs tokens with one key, which each app
144
+ passes as `jwt_secret` (`IDP_JWT_SECRET`).
145
+
146
+ The gem also accepts tokens signed with the app's own client secret. If SSO2 ever moves to signing each
147
+ app's token with that app's client secret, apps keep working through the change and can remove
148
+ `jwt_secret` afterwards. No gem update is needed.
149
+
150
+ ## Requirements and caveats
151
+
152
+ - Ruby 2.7+, OmniAuth 2.2+, omniauth-oauth2 1.8+, jwt 2.7–3.x, Rack 2.2 or 3.
153
+ Tested on Ruby 2.7.4 (Rack 2 and 3, including the lowest allowed versions of each dependency), 3.4.8 and 4.0.7.
154
+ - The `state` check needs the app's session cookie on the callback. SSO2 sends the callback as a form POST,
155
+ and browsers leave `SameSite=Lax` cookies (the Rails default) off cross-site POSTs, for example during local
156
+ development (`localhost`) against SSO2 qual. `relay_form_post` turns that POST into a same-URL GET, where
157
+ Lax cookies are sent, so no cookie changes are needed in any environment.
158
+
159
+ ## Development
160
+
161
+ The source is at https://github.com/txst-txssc/omniauth-txssc-sso2 (private to TxSSC).
162
+
163
+ ```bash
164
+ git clone git@github.com:txst-txssc/omniauth-txssc-sso2.git
165
+ cd omniauth-txssc-sso2
166
+ bundle install
167
+ bundle exec rspec
168
+ ```
@@ -0,0 +1,167 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "jwt"
4
+ require "uri"
5
+ require "omniauth-oauth2"
6
+
7
+ module OmniAuth
8
+ module Strategies
9
+ # Signs users in through TxSSC SSO2.
10
+ #
11
+ # SSO2 runs an OAuth2 authorization code flow:
12
+ #
13
+ # 1. The app redirects to SSO2's login URL with client_id, redirect_uri and state.
14
+ # 2. SSO2 authenticates the user (SAML with the campus IdP), then POSTs code and
15
+ # state to the redirect URI registered for the app in SSO2.
16
+ # 3. The app exchanges the code and its client secret at SSO2's token URL and gets
17
+ # back a signed JWT describing the user.
18
+ #
19
+ # The JWT's signature, issuer, audience and expiry are verified as soon as it
20
+ # arrives; any failure ends the login through OmniAuth's normal failure path.
21
+ class TxsscSso2 < OmniAuth::Strategies::OAuth2
22
+ JWT_ALGORITHM = "HS256"
23
+
24
+ option :name, "txssc_sso2"
25
+
26
+ option :client_options, {
27
+ site: nil,
28
+ authorize_url: "/users/saml/login",
29
+ token_url: "/users/saml/token",
30
+ auth_scheme: :request_body
31
+ }
32
+
33
+ # Key(s) SSO2 signs tokens with: SSO2's HMAC secret in its current setup.
34
+ # Tokens signed with the app's client secret are also accepted, so apps keep
35
+ # working if SSO2 ever signs each app's tokens with that app's secret.
36
+ option :jwt_secret, nil
37
+
38
+ # Expected `iss` claim. Defaults to client_options.site.
39
+ option :issuer, nil
40
+
41
+ # Seconds of clock skew allowed when checking exp.
42
+ option :jwt_leeway, 30
43
+
44
+ # SSO2 returns code and state with an auto-submitting form POST. When SSO2 and
45
+ # the app are on different sites (e.g. local development against SSO2 qual),
46
+ # browsers leave the app's SameSite=Lax session cookie off that POST, so the
47
+ # state check would fail. With this on, the POST is answered with a 303 to the
48
+ # same callback URL as a GET carrying code and state in the query string (the
49
+ # standard OAuth2 response), where the session cookie is sent.
50
+ option :relay_form_post, true
51
+
52
+ RELAYED_PARAMS = %w[code state error error_description error_uri].freeze
53
+
54
+ uid { raw_info.fetch("sub").to_s }
55
+
56
+ info do
57
+ prune!(
58
+ "name" => full_name,
59
+ "email" => user_claims["email"],
60
+ "first_name" => user_claims["first_name"],
61
+ "last_name" => user_claims["last_name"],
62
+ "nickname" => user_claims["netID"],
63
+ "image" => user_claims["avatar_link"]
64
+ )
65
+ end
66
+
67
+ extra do
68
+ { "raw_info" => raw_info }
69
+ end
70
+
71
+ def raw_info
72
+ @raw_info ||= verified_claims(access_token.token)
73
+ end
74
+
75
+ # SSO2 only ever redirects to the URI registered for the app, and the token
76
+ # request must send that same URI. Set the `redirect_uri` option when the
77
+ # app's public URL differs from what Rack sees.
78
+ def callback_url
79
+ options.redirect_uri || (full_host + callback_path)
80
+ end
81
+
82
+ def callback_call
83
+ return relay_form_post if options.relay_form_post && request.post?
84
+
85
+ super
86
+ end
87
+
88
+ protected
89
+
90
+ def build_access_token
91
+ super.tap { |token| @raw_info = verified_claims(token.token) }
92
+ rescue ::JWT::DecodeError => e
93
+ raise CallbackError.new(:invalid_token, e.message)
94
+ end
95
+
96
+ private
97
+
98
+ def relay_form_post
99
+ query = URI.encode_www_form(request.POST.slice(*RELAYED_PARAMS))
100
+ location = "#{script_name}#{callback_path}"
101
+ location += "?#{query}" unless query.empty?
102
+
103
+ [
104
+ 303,
105
+ {
106
+ "location" => location,
107
+ "cache-control" => "no-store",
108
+ "referrer-policy" => "no-referrer",
109
+ "content-type" => "text/plain"
110
+ },
111
+ []
112
+ ]
113
+ end
114
+
115
+ def verified_claims(token)
116
+ keys = signing_keys
117
+ raise ::JWT::DecodeError, "No SSO2 signing key configured" if keys.empty?
118
+ raise ::JWT::DecodeError, "No SSO2 issuer configured" if expected_issuer.empty?
119
+
120
+ last_error = nil
121
+ keys.each do |key|
122
+ return ::JWT.decode(token, key, true, decode_options).first
123
+ rescue ::JWT::VerificationError => e
124
+ # Signature didn't match this key; try the next one.
125
+ last_error = e
126
+ end
127
+ raise last_error
128
+ end
129
+
130
+ def signing_keys
131
+ [*Array(options.jwt_secret), options.client_secret].compact.map(&:to_s).reject(&:empty?).uniq
132
+ end
133
+
134
+ def decode_options
135
+ {
136
+ algorithm: JWT_ALGORITHM,
137
+ iss: expected_issuer,
138
+ verify_iss: true,
139
+ aud: options.client_id.to_s,
140
+ verify_aud: true,
141
+ verify_expiration: true,
142
+ leeway: options.jwt_leeway.to_i,
143
+ required_claims: %w[sub iss aud exp]
144
+ }
145
+ end
146
+
147
+ def expected_issuer
148
+ (options.issuer || options.client_options.site).to_s.chomp("/")
149
+ end
150
+
151
+ def user_claims
152
+ claims = raw_info["user"]
153
+ claims.is_a?(Hash) ? claims : {}
154
+ end
155
+
156
+ def full_name
157
+ name = [user_claims["first_name"], user_claims["last_name"]].compact.map { |part| part.to_s.strip }
158
+ name = name.reject(&:empty?).join(" ")
159
+ name.empty? ? nil : name
160
+ end
161
+
162
+ def prune!(hash)
163
+ hash.delete_if { |_, value| value.nil? || (value.respond_to?(:empty?) && value.empty?) }
164
+ end
165
+ end
166
+ end
167
+ end
@@ -0,0 +1,7 @@
1
+ # frozen_string_literal: true
2
+
3
+ module OmniAuth
4
+ module TxsscSso2
5
+ VERSION = "0.1.0"
6
+ end
7
+ end
@@ -0,0 +1,19 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "uri"
4
+ require "omniauth/txssc_sso2/version"
5
+ require "omniauth/strategies/txssc_sso2"
6
+
7
+ module OmniAuth
8
+ module TxsscSso2
9
+ LOGOUT_PATH = "/users/saml/logout"
10
+
11
+ # URL that ends the user's SSO2 session. Clear the app's own session first,
12
+ # then redirect here. Passing client_id lets SSO2 show the app's name.
13
+ def self.logout_url(site:, client_id: nil)
14
+ uri = URI.join("#{site.to_s.chomp('/')}/", LOGOUT_PATH.delete_prefix("/"))
15
+ uri.query = URI.encode_www_form(client_id: client_id) if client_id
16
+ uri.to_s
17
+ end
18
+ end
19
+ end
@@ -0,0 +1,3 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "omniauth/txssc_sso2"
metadata ADDED
@@ -0,0 +1,96 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: omniauth-txssc-sso2
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0
5
+ platform: ruby
6
+ authors:
7
+ - Joshua Hawks
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: jwt
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - ">="
17
+ - !ruby/object:Gem::Version
18
+ version: '2.7'
19
+ - - "<"
20
+ - !ruby/object:Gem::Version
21
+ version: '4'
22
+ type: :runtime
23
+ prerelease: false
24
+ version_requirements: !ruby/object:Gem::Requirement
25
+ requirements:
26
+ - - ">="
27
+ - !ruby/object:Gem::Version
28
+ version: '2.7'
29
+ - - "<"
30
+ - !ruby/object:Gem::Version
31
+ version: '4'
32
+ - !ruby/object:Gem::Dependency
33
+ name: omniauth
34
+ requirement: !ruby/object:Gem::Requirement
35
+ requirements:
36
+ - - "~>"
37
+ - !ruby/object:Gem::Version
38
+ version: '2.2'
39
+ type: :runtime
40
+ prerelease: false
41
+ version_requirements: !ruby/object:Gem::Requirement
42
+ requirements:
43
+ - - "~>"
44
+ - !ruby/object:Gem::Version
45
+ version: '2.2'
46
+ - !ruby/object:Gem::Dependency
47
+ name: omniauth-oauth2
48
+ requirement: !ruby/object:Gem::Requirement
49
+ requirements:
50
+ - - "~>"
51
+ - !ruby/object:Gem::Version
52
+ version: '1.8'
53
+ type: :runtime
54
+ prerelease: false
55
+ version_requirements: !ruby/object:Gem::Requirement
56
+ requirements:
57
+ - - "~>"
58
+ - !ruby/object:Gem::Version
59
+ version: '1.8'
60
+ description: Signs users in to Rails apps through TxSSC SSO2. Built on omniauth-oauth2;
61
+ verifies the signed JWT SSO2 returns (signature, issuer, audience, expiry).
62
+ email:
63
+ - snl95@txstate.edu
64
+ executables: []
65
+ extensions: []
66
+ extra_rdoc_files: []
67
+ files:
68
+ - CHANGELOG.md
69
+ - LICENSE.txt
70
+ - README.md
71
+ - lib/omniauth-txssc-sso2.rb
72
+ - lib/omniauth/strategies/txssc_sso2.rb
73
+ - lib/omniauth/txssc_sso2.rb
74
+ - lib/omniauth/txssc_sso2/version.rb
75
+ licenses:
76
+ - MIT
77
+ metadata:
78
+ rubygems_mfa_required: 'true'
79
+ rdoc_options: []
80
+ require_paths:
81
+ - lib
82
+ required_ruby_version: !ruby/object:Gem::Requirement
83
+ requirements:
84
+ - - ">="
85
+ - !ruby/object:Gem::Version
86
+ version: '2.7'
87
+ required_rubygems_version: !ruby/object:Gem::Requirement
88
+ requirements:
89
+ - - ">="
90
+ - !ruby/object:Gem::Version
91
+ version: '0'
92
+ requirements: []
93
+ rubygems_version: 3.6.9
94
+ specification_version: 4
95
+ summary: OmniAuth strategy for the TxSSC SSO2 identity broker
96
+ test_files: []