omniauth-wecom 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20123a046b4db04e1a3afcf76aa4bf7593114df4bc7c67e06dfef9506418658d
+  data.tar.gz: ccba1c2ed792ec30ec7349d5aa9523b8c9795ca6a552b89d3def12b4ad1bbfa9
+SHA512:
+  metadata.gz: dbaade7da462cbba6f25234be688fde4712b469af3867819a932040529f39d0b5324a56d9e8b5e56178e48f256714e9da50ddccce4d8563b14b278811834dfb1
+  data.tar.gz: a6790a76cc51c440bdc1c606582530cdf58966ef5f3730de1b3e2d1e6f5d7c09c83dfb615f92838c70c198e6464f20f5fc69684cbbc99b5b9acaf310b3e5ce0c

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 1.0.0 (2026-09-08)
+
+- Extract the WeCom CorpApp OmniAuth strategy from the JiHu GitLab monolith into a standalone gem.
+- Add standalone tests, linting, gem packaging, and contributor documentation.
+
+The extraction is tracked in [work item 5299](https://jihulab.com/gitlab-cn/gitlab/-/work_items/5299) and is based on [MR 3776](https://jihulab.com/gitlab-cn/gitlab/-/merge_requests/3776).

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 JiHu (Shanghai) Information Technology Co., Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,77 @@
+# omniauth-wecom
+
+`omniauth-wecom` is an [OmniAuth](https://github.com/omniauth/omniauth) strategy for signing in through a WeCom (WeChat Work) custom, corp-internal application. It supports the desktop CorpApp QR-code flow. Third-party service-provider applications and the WeCom in-app WebView flow are outside its scope.
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem 'omniauth-wecom', '~> 1.0.0'
+```
+
+Then run `bundle install`.
+
+The gem supports Ruby 3.2 or later and OmniAuth 2.
+
+## Usage
+
+```ruby
+use OmniAuth::Builder do
+  provider :wecom,
+    ENV.fetch('WECOM_CORP_ID'),
+    ENV.fetch('WECOM_CORP_SECRET'),
+    agent_id: ENV.fetch('WECOM_AGENT_ID')
+end
+```
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `client_id` (first argument) | Yes | WeCom CorpID |
+| `client_secret` (second argument) | Yes | Secret of the custom application |
+| `agent_id` | Yes | AgentID of the custom application |
+| `fetch_user_detail` | No | Fetch the member's name and email from the address book; defaults to `false` and requires the relevant permission |
+| `authorize_url` | No | Override the QR-code authorization endpoint for development or a private host |
+| `client_options[:site]` | No | Override the API host for development or a private host |
+
+The host application must follow OmniAuth 2's integration requirements: start authentication with `POST`, preserve the session from the request phase through the callback, and keep request validation and CSRF protection enabled. The strategy stores an OmniAuth `state` value in the session and relies on `omniauth-oauth2` to reject a missing or mismatched value at callback time.
+
+Host overrides are available for private endpoints and local stubs. Their presence does not imply official support for any particular private WeCom deployment.
+
+## Authentication flow
+
+The access token belongs to the application, not the member. The strategy:
+
+1. Redirects the browser to WeCom's `CorpApp` QR-code endpoint.
+2. Exchanges the CorpID and application secret for a corp-level access token.
+3. Uses that token and the callback code to resolve the member's UserId.
+4. Optionally reads the member's name and email when `fetch_user_detail` is enabled.
+
+Only corp members can sign in. Responses without a `userid`, including external contacts, are rejected. If WeCom rejects an access token, the strategy invalidates it and retries the identity lookup once. When the optional address-book lookup returns a WeCom API error, such as missing permission or a rejected token, the strategy falls back to the UserId instead of failing sign-in. Other network or HTTP failures are not covered by this fallback.
+
+## Identity and auth hash
+
+The auth hash uses `"<CorpID>:<UserId>"` as `uid`, because a UserId is unique only within one corp. `info` always includes the UserId as `nickname`; it uses the UserId as `name` unless member details are available.
+
+The corp-level token can grant broad application access, and the member response can contain a long-lived ticket. To keep both out of sessions and logs:
+
+- `credentials` is empty.
+- `extra` contains only `corp_id`.
+
+## Extension hooks and token storage
+
+The strategy exposes five protected hooks for host applications:
+
+- `parse_json(raw)` parses WeCom response bodies.
+- `request_user_info` performs the member identity request.
+- `request_user_detail` performs the optional address-book request.
+- `corp_access_token` obtains the application token and returns `[token, expires_in]`.
+- `invalidate_access_token` invalidates token storage after WeCom rejects a token.
+
+The standalone defaults fetch a token directly from WeCom and do not provide shared token caching. GitLab-specific HTTP adapters, hardened JSON parsing, and `Gitlab::Wecom::AccessToken` caching remain in the GitLab monolith and are not part of this gem.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). This project is licensed under the MIT License; see [LICENSE](LICENSE).
+
+The extraction was tracked in [work item 5299](https://jihulab.com/gitlab-cn/gitlab/-/work_items/5299), following the implementation merged in [MR 3776](https://jihulab.com/gitlab-cn/gitlab/-/merge_requests/3776).

data/lib/omniauth/strategies/wecom.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+require 'omniauth-oauth2'
+
+module OmniAuth
+  module Strategies
+    # Sign-in with a WeCom (WeChat Work) custom, corp-internal application.
+    #
+    # This is not plain OAuth 2.0. The access token is issued to the *app*, not
+    # to the user: it comes from corpid plus corpsecret and has nothing to do
+    # with the authorization code. The code is presented at the last step,
+    # alongside that token, purely to resolve who signed in. That is why
+    # `build_access_token` is replaced wholesale.
+    #
+    # Only corp members can sign in. External contacts and WeChat users outside
+    # the corp come back without a userid and are rejected.
+    class Wecom < OmniAuth::Strategies::OAuth2
+      # Scan-the-QR-code entry point, for a normal desktop browser. Authorizing
+      # inside the WeCom client's own WebView uses a different endpoint and is
+      # not supported yet.
+      AUTHORIZE_URL = 'https://login.work.weixin.qq.com/wwlogin/sso/login'
+
+      API_SITE = 'https://qyapi.weixin.qq.com'
+      TOKEN_PATH = '/cgi-bin/gettoken'
+      USER_INFO_PATH = '/cgi-bin/auth/getuserinfo'
+      USER_DETAIL_PATH = '/cgi-bin/user/get'
+
+      # How extern_uid is encoded: CorpID and UserId joined by a colon.
+      #
+      # A UserId is only unique inside one corp, so it means nothing on its own.
+      # Carrying the CorpID means that after the instance switches corps, old
+      # bindings stop matching instead of quietly resolving to whoever happens
+      # to share that UserId in the new corp.
+      #
+      # WeCom UserIds allow letters, digits and `-_@.`, so a colon separates
+      # them unambiguously.
+      UID_SEPARATOR = ':'
+
+      # Raised when the provider is wired up without the settings CorpApp
+      # sign-in needs. Surfaced at request time rather than at boot so that one
+      # bad provider entry cannot stop the whole application from starting.
+      ConfigurationError = Class.new(StandardError)
+
+      # Raised when WeCom refuses the corp token, so it can be refreshed once.
+      TokenRejected = Class.new(StandardError)
+
+      option :name, 'wecom'
+
+      # AgentID of the custom app. Required: CorpApp scan-code sign-in is
+      # scoped to a single app and WeCom rejects the request without it.
+      option :agent_id, nil
+
+      # Reading a member's name and email needs the address book permission,
+      # which many customers will not grant, so it is off by default. Without
+      # it `info` carries only the userid and GitLab generates a placeholder
+      # email.
+      option :fetch_user_detail, false
+
+      # Overridable so the strategy can point at a WeCom private deployment,
+      # or at a local stub while developing.
+      option :authorize_url, AUTHORIZE_URL
+
+      # A rejected or expired token comes back as one of these; the caller
+      # refreshes once rather than failing the sign-in.
+      TOKEN_REJECTED_CODES = [40014, 41001, 42001].freeze
+
+      option :client_options, {
+        site: API_SITE,
+        connection_opts: { request: { timeout: 20, open_timeout: 10 } }
+      }
+
+      uid { "#{corp_id}#{UID_SEPARATOR}#{raw_user_info['userid']}" }
+
+      info do
+        {
+          name: user_detail['name'] || raw_user_info['userid'],
+          nickname: raw_user_info['userid'],
+          email: user_detail['email']
+        }
+      end
+
+      # `credentials` and `extra` are overridden as methods rather than as DSL
+      # blocks: OmniAuth merges the whole ancestor stack, so an empty block here
+      # would still let the OAuth2 base contribute its own keys.
+
+      # The token is corp-level: it can send messages and read the address book
+      # for the whole company. Sign-in needs none of it, so keep it out of the
+      # auth hash, which is stored in the session and shows up in logs.
+      def credentials
+        {}
+      end
+
+      # Deliberately not the raw payload: it also returns a member ticket, a
+      # credential that stays valid for weeks. Only the corp id is needed here.
+      def extra
+        { corp_id: corp_id }
+      end
+
+      def request_phase
+        if options.agent_id.nil? || options.agent_id.to_s.empty?
+          raise ConfigurationError, 'WeCom provider requires `agent_id` to be configured'
+        end
+
+        redirect authorize_url
+      end
+
+      # WeCom matches the trusted domain against the URL without its query
+      # string, so the callback must not carry one.
+      def callback_url
+        full_host + callback_path
+      end
+
+      def authorize_url
+        # Take the state from authorize_params: it also writes the value into
+        # the session, which is what callback_phase compares against. Rolling
+        # our own state here would silently disable the CSRF check.
+        state = authorize_params[:state]
+
+        query = {
+          login_type: 'CorpApp',
+          appid: corp_id,
+          agentid: options.agent_id,
+          redirect_uri: callback_url,
+          state: state
+        }.reject { |_, value| value.nil? || value.to_s.empty? }
+
+        "#{options.authorize_url}?#{URI.encode_www_form(query)}"
+      end
+
+      protected
+
+      def build_access_token
+        token, expires_in = corp_access_token
+
+        ::OAuth2::AccessToken.new(
+          client, token,
+          expires_in: expires_in,
+          # WeCom reads the token from the query string; it has no Bearer support
+          mode: :query,
+          param_name: 'access_token'
+        )
+      end
+
+      # Fetches the corp-level token straight from WeCom.
+      #
+      # Overridden inside GitLab to go through a shared cache: WeCom hands out
+      # one token per app, and asking for a new one can invalidate the token
+      # another part of the app is still using.
+      #
+      # @return [Array(String, Integer)] the token and its lifetime in seconds
+      def corp_access_token
+        body = parse_response(
+          client.request(:get, TOKEN_PATH, params: { corpid: corp_id, corpsecret: client.secret })
+        )
+
+        [body['access_token'], body['expires_in']]
+      end
+
+      # Overridden inside GitLab so the call goes through the instance's
+      # controlled HTTP client instead of the gem's own connection.
+      def request_user_info
+        access_token.get(USER_INFO_PATH, params: { code: request.params['code'] })
+      end
+
+      # Same reason as `request_user_info`: kept as a hook so GitLab can route
+      # it through the controlled HTTP client too.
+      def request_user_detail
+        access_token.get(USER_DETAIL_PATH, params: { userid: raw_user_info['userid'] })
+      end
+
+      # Overridden inside GitLab to evict the shared token cache.
+      def invalidate_access_token; end
+
+      # Overridden inside GitLab to use a hardened parser.
+      def parse_json(raw)
+        ::JSON.parse(raw)
+      end
+
+      def corp_id
+        client.id
+      end
+
+      private
+
+      def raw_user_info
+        @raw_user_info ||= fetch_user_info
+      end
+
+      def fetch_user_info
+        member_info
+      rescue TokenRejected
+        # The cached token was retired early. Drop it, get a new one, try once.
+        invalidate_access_token
+        self.access_token = build_access_token
+
+        begin
+          member_info
+        rescue TokenRejected => e
+          raise CallbackError.new(:invalid_credentials, e.message)
+        end
+      end
+
+      def member_info
+        info = parse_response(request_user_info)
+
+        if info['userid'].nil? || info['userid'].to_s.empty?
+          raise CallbackError.new(:invalid_credentials,
+            'WeCom did not return a userid: the account is not a member of this corp')
+        end
+
+        info
+      end
+
+      def user_detail
+        return {} unless options.fetch_user_detail
+
+        @user_detail ||= begin
+          parse_response(request_user_detail)
+        rescue CallbackError, TokenRejected
+          # Details are optional. Whether the address book permission is missing
+          # or the token was retired between the two calls, fall back to the
+          # userid alone rather than failing the sign-in.
+          {}
+        end
+      end
+
+      # WeCom answers 200 even for failures and puts the real status in
+      # `errcode`, so the body is what decides success.
+      def parse_response(response)
+        body = parse_json(response.body)
+        errcode = body['errcode']
+
+        return body if errcode.nil? || errcode.to_i == 0
+
+        if TOKEN_REJECTED_CODES.include?(errcode.to_i)
+          raise TokenRejected, "WeCom rejected the access token: #{errcode} #{body['errmsg']}"
+        end
+
+        raise CallbackError.new(:invalid_credentials,
+          "WeCom API error #{errcode}: #{body['errmsg']}")
+      rescue ::JSON::ParserError
+        raise CallbackError.new(:invalid_credentials, 'WeCom returned a malformed response')
+      end
+    end
+  end
+end
+
+OmniAuth.config.add_camelization 'wecom', 'Wecom'

data/lib/omniauth/wecom/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module OmniAuth
+  module Wecom
+    VERSION = '1.0.0'
+  end
+end

data/lib/omniauth/wecom.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'omniauth/wecom/version'
+require 'omniauth/strategies/wecom'

data/lib/omniauth-wecom.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'omniauth/wecom'

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: omniauth-wecom
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- JiHu GitLab
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: omniauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: omniauth-oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: OmniAuth strategy for signing in with a WeCom custom (internal) application.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/omniauth-wecom.rb
+- lib/omniauth/strategies/wecom.rb
+- lib/omniauth/wecom.rb
+- lib/omniauth/wecom/version.rb
+homepage: https://gitlab.com/gitlab-jh/jh-team/omniauth-wecom
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://gitlab.com/gitlab-jh/jh-team/omniauth-wecom
+  bug_tracker_uri: https://gitlab.com/gitlab-jh/jh-team/omniauth-wecom/-/issues
+  changelog_uri: https://gitlab.com/gitlab-jh/jh-team/omniauth-wecom/-/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.13
+specification_version: 4
+summary: WeCom (WeChat Work) strategy for OmniAuth
+test_files: []