{"id":15066832,"url":"https://github.com/cerner/cerner-oauth1a","last_synced_at":"2025-10-05T03:31:30.527Z","repository":{"id":49107598,"uuid":"78053516","full_name":"cerner/cerner-oauth1a","owner":"cerner","description":"Cerner OAuth 1.0a Library for Consumers and Service Providers","archived":true,"fork":false,"pushed_at":"2021-06-28T20:25:09.000Z","size":140,"stargazers_count":3,"open_issues_count":0,"forks_count":6,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-01-02T08:36:53.792Z","etag":null,"topics":["cerner","oauth1","oauth1a","ruby","rubygem"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cerner.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-04T21:15:45.000Z","updated_at":"2024-02-29T15:30:59.000Z","dependencies_parsed_at":"2022-09-24T02:50:44.045Z","dependency_job_id":null,"html_url":"https://github.com/cerner/cerner-oauth1a","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerner%2Fcerner-oauth1a","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerner%2Fcerner-oauth1a/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerner%2Fcerner-oauth1a/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerner%2Fcerner-oauth1a/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cerner","download_url":"https://codeload.github.com/cerner/cerner-oauth1a/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235360900,"owners_count":18977595,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cerner","oauth1","oauth1a","ruby","rubygem"],"created_at":"2024-09-25T01:12:50.984Z","updated_at":"2025-10-05T03:31:24.961Z","avatar_url":"https://github.com/cerner.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cerner OAuth 1.0a Consumer and Service Provider Library\n\n[![Build Status](https://api.travis-ci.com/cerner/cerner-oauth1a.svg)](https://travis-ci.com/cerner/cerner-oauth1a)\n[![Gem Version](http://img.shields.io/gem/v/cerner-oauth1a.svg)](https://rubygems.org/gems/cerner-oauth1a)\n[![AwesomeCode Status](https://awesomecode.io/projects/48ece237-ac9c-49c9-859a-3a825968339b/status)](https://awesomecode.io/repos/cerner/cerner-oauth1a)\n\nA minimal dependency library for interacting with a Cerner OAuth 1.0a Access Token Service for\ninvoking Cerner OAuth 1.0a protected services or implementing Cerner OAuth 1.0a authentication.\nCerner's OAuth 1.0a Access Token Service provides a means for facilitating two-legged (B2B)\nauthentication via a variant of OAuth 1.0a.\n\n# Usage\n\nThere are two use cases for working with this library: Consumer and Service Provider. The Consumer\nUse Case is for invoking services protected by Cerner OAuth 1.0a. The Service Provider Use Case is\nfor implementing a Ruby-based service.\n\n## Consumer Use Case\n\n    require 'cerner/oauth1a'\n    require 'net/http'\n\n    # Setup the AccessTokenAgent with an Access Token Service's URL, a Key and a Secret\n    agent = Cerner::OAuth1a::AccessTokenAgent.new(\n      access_token_url: 'https://oauth-api.cerner.com/oauth/access',\n      consumer_key: 'CONSUMER_KEY',\n      consumer_secret: 'CONSUMER_SECRET'\n    )\n\n    # Retrieve an AccessToken instance\n    access_token = agent.retrieve\n\n    # Setup the HTTP library to access the protected API you want to invoke\n    uri = URI('https://authz-demo-api.cerner.com/me')\n    http = Net::HTTP.new(uri.host, uri.port)\n    http.use_ssl = true if uri.scheme == 'https'\n\n    # Invoke the API's HTTP endpoint and use the AccessToken to generate an Authorization header\n    response = http.request_get(uri.path, Authorization: access_token.authorization_header)\n\n### Consumer HMAC-SHA1 Signature Method\n\nThe preferred and default signature method is PLAINTEXT, as all communication SHOULD be via TLS. However, if HMAC-SHA1 signatures are necessary, then this can be achieved by constructing AccessTokenAgent as follows:\n\n    agent = Cerner::OAuth1a::AccessTokenAgent.new(\n      access_token_url: 'https://oauth-api.cerner.com/oauth/access',\n      consumer_key: 'CONSUMER_KEY',\n      consumer_secret: 'CONSUMER_SECRET',\n      signature_method: 'HMAC-SHA1'\n    )\n\nTo use the AccessToken requires additional parameters to be passed when constructing the Authorization header. The HTTP method, the URL being invoked and all request parameters. The request parameters should include all parameters passed in the query string and those passed in the body if the Content-Type of the body is `application/x-www-form-urlencoded`. See the specification for more details.\n\n#### Consumer HMAC-SHA1 Signature Method Examples\n\nGET with no request parameters\n\n    uri = URI('https://authz-demo-api.cerner.com/me')\n    # ...\n    authz_header = access_token.authorization_header(fully_qualified_url: uri)\n\nGET with request parameters in URL\n\n    uri = URI('https://authz-demo-api.cerner.com/me?name=value')\n    # ...\n    authz_header = access_token.authorization_header(fully_qualified_url: uri)\n\nPOST with request parameters (form post)\n\n    authz_header = access_token.authorization_header(\n      http_method: 'POST'\n      fully_qualified_url: 'https://example/path',\n      request_params: {\n        sort: 'asc',\n        field: ['name', 'desc'] # sending the field multiple times\n      }\n    )\n\nPUT with no request parameters (entity body)\n\n    authz_header = access_token.authorization_header(\n      http_method: 'PUT'\n      fully_qualified_url: 'https://example/path'\n    )\n\n### Access Token Reuse\n\nGenerally, you'll want to use an Access Token more than once. Access Tokens can be reused, but\nthey do expire, so you'll need to acquire new tokens after one expires. All of the expiration\ninformation is contained in the AccessToken class and you can easily determine if a token is\nexpired or about to by using the AccessToken#expired? method. Below is an example of you might\nimplement that:\n\n    uri = URI('https://authz-demo-api.cerner.com/me')\n    http = Net::HTTP.new(uri.host, uri.port)\n    http.use_ssl = true if uri.scheme == 'https'\n\n    access_token = agent.retrieve if access_token.expired?\n\n    response = http.request_get(uri.path, Authorization: access_token.authorization_header)\n\n## Service Provider Use Case\n\n    # Acquire Authorization header value from HTTP server's request\n    authz_header = request['Authorization']\n\n    # Parse the header value\n    access_token = Cerner::OAuth1a::AccessToken.from_authorization_header(authz_header)\n\n    # Authenticate the Access Token\n    # Note: An AccessTokenAgent, configured with a System Account that has been granted privileges\n    # to Acquire Tokens and Process Tokens.\n    begin\n      results = access_token.authenticate(agent)\n    rescue OAuthError =\u003e e\n      # respond with a 401\n    end\n\n    # Use Consumer Key (i.e. the System Account) to do further authorization, as appropriate\n    system_account_id = access_token.consumer_key\n\n    # Optionally, extract additional parameters sent with the token, such as Consumer.Principal\n    # (xoauth_principal)\n    consumer_principal = access_token.consumer_principal\n\n### Service Provider HMAC-SHA1 Signature Method\n\nThe preferred and default signature method is PLAINTEXT, as all communication SHOULD be via TLS. However, if HMAC-SHA1 signatures are necessary, then this can be achieved by passing additional informational to the `authenticate` method.\n\n    begin\n      results = access_token.authenticate(\n        agent,\n        http_method: request.method,\n        fully_qualified_url: request.original_url,\n        request_params: request.parameters\n      )\n    rescue OAuthError =\u003e e\n      # respond with a 401\n    end\n\n## Caching\n\nThe AccessTokenAgent class provides built-in memory caching. AccessTokens and Keys are cached\nbehind their respective retrieve methods. The caching can be disabled via parameters passed to the\nconstructor. See the class-level documentation for details.\n\n### Caching in Rails\n\nWhen the gem is loaded within a Rails application, it will attach a Railtie for initializing the\ncache to use an implementation that stores the AccessTokens and Keys within Rails.cache.\n\n## References\n* https://wiki.ucern.com/display/public/reference/Cerner%27s+OAuth+Specification\n  * https://tools.ietf.org/html/rfc5849\n  * http://oauth.net/core/1.0a\n  * http://oauth.pbwiki.com/ProblemReporting\n* https://wiki.ucern.com/display/public/reference/Accessing+Cerner%27s+Web+Services+Using+OAuth+1.0a\n\n# Installing\nThis library can be installed using the `gem` command or added to a Gemfile for use with Bundler.\n\n## `gem` command\n\n    $ gem install cerner-oauth1a\n\n## Gemfile\n\n    gem 'cerner-oauth1a', '~\u003e 2.0'\n\n# Building\n\nThis project is built using Ruby 2.5+, Rake and Bundler. RSpec is used for unit tests and SimpleCov\nis utilized for test coverage. RuboCop is used to monitor the lint and style.\n\n## Setup\n\nTo setup the development workspace, run the following after checkout:\n\n    gem install bundler\n    bundle install\n\n## Tests\n\nTo run the RSpec tests, run the following:\n\n    bin/rspec\n\n## Lint\n\nTo analyze the project's style and lint, run the following:\n\n    bin/rubocop\n\n## Bundler Audit\n\nTo analyze the project's dependency vulnerabilities, run the following:\n\n    bin/bundle audit\n\n# Availability\n\nThis RubyGem will be available on https://rubygems.org/.\n\n# Communication\n\nAll questions, bugs, enhancements and pull requests can be submitted here, on GitHub via Issues.\n\n# Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n# LICENSE\n\nCopyright 2020 Cerner Innovation, Inc.\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerner%2Fcerner-oauth1a","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcerner%2Fcerner-oauth1a","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerner%2Fcerner-oauth1a/lists"}