minty 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7c4937d043506771b524e4ca14acfcf5fa30bcd141b2a0e6bb6cbb16840bd845
+  data.tar.gz: 4da3f2a001aa8633abe790d90669e159642245cb42b199855836cdf8e7e00851
+SHA512:
+  metadata.gz: 600c76679a2131f77221338fcfe3e54d9a4a335ddbb9ec7cb0d2bbf4fbafff5c051c67d3e067444f9cf7bee31edb621ae724077475d349d6602b7edd4932a691
+  data.tar.gz: 00c0acd3dd87c681ba0af9abc7248b53d80c0afb5f0cc6e7171d3fe4eba84acc3762c596a447b2b3ea526c0a410debd25ea342ce49c0c47e3069fc23058e4f65

data/.bundle/config

@@ -0,0 +1,4 @@
+---
+BUNDLE_JOBS: "3"
+BUNDLE_BIN: "bin"
+BUNDLE_RETRY: "3"

data/.devcontainer/Dockerfile

@@ -0,0 +1,19 @@
+# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.245.2/containers/ruby/.devcontainer/base.Dockerfile
+
+# [Choice] Ruby version (use -bullseye variants on local arm64/Apple Silicon): 3, 3.1, 3.0, 2, 2.7, 3-bullseye, 3.1-bullseye, 3.0-bullseye, 2-bullseye, 2.7-bullseye, 3-buster, 3.1-buster, 3.0-buster, 2-buster, 2.7-buster
+ARG VARIANT="3.1-bullseye"
+FROM mcr.microsoft.com/vscode/devcontainers/ruby:0-${VARIANT}
+
+# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10
+ARG NODE_VERSION="none"
+RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi
+
+# [Optional] Uncomment this section to install additional OS packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#     && apt-get -y install --no-install-recommends <your-package-list-here>
+
+# [Optional] Uncomment this line to install additional gems.
+# RUN gem install <your-gem-names-here>
+
+# [Optional] Uncomment this line to install global node packages.
+# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

data/.devcontainer/devcontainer.json

@@ -0,0 +1,37 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.245.2/containers/ruby
+{
+	"name": "Ruby",
+	"build": {
+		"dockerfile": "Dockerfile",
+		"args": { 
+			// Update 'VARIANT' to pick a Ruby version: 3, 3.1, 3.0, 2, 2.7
+			// Append -bullseye or -buster to pin to an OS version.
+			// Use -bullseye variants on local on arm64/Apple Silicon.
+			"VARIANT": "3.1",
+			// Options
+			"NODE_VERSION": "lts/*"
+		}
+	},
+
+	// Configure tool-specific properties.
+	"customizations": {
+		// Configure properties specific to VS Code.
+		"vscode": {
+			// Add the IDs of extensions you want installed when the container is created.
+			"extensions": [
+				"rebornix.Ruby"
+			]
+		}
+	},
+	
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "ruby --version",
+
+	// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	"remoteUser": "vscode"
+
+}

data/.env.example

@@ -0,0 +1,2 @@
+DOMAIN=
+CLIENT_ID=

data/.gemrelease

@@ -0,0 +1,2 @@
+bump:
+  tag: true

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+### Changes
+
+Please describe both what is changing and why this is important. Include:
+
+- Endpoints added, deleted, deprecated, or changed
+- Classes and methods added, deleted, deprecated, or changed
+- Screenshots of new or changed UI, if applicable
+- A summary of usage if this is a new feature or change to a public API (this should also be added to relevant documentation once released)
+
+### References
+
+Please include relevant links supporting this change such as a:
+
+- support ticket
+- community post
+- StackOverflow post
+- support forum thread
+
+Please note any links that are not publicly accessible.
+
+### Testing
+
+Please describe how this can be tested by reviewers. Be specific about anything not tested and reasons why. If this library has unit and/or integration testing, tests should be added for new functionality and existing tests should complete without errors.
+
+* [ ] This change adds unit test coverage
+* [ ] This change adds integration test coverage
+* [ ] This change has been tested on the latest version of Ruby
+
+### Checklist
+
+* [ ] All existing and new tests complete without errors
+* [ ] Rubocop passes on all added/modified files
+* [ ] All active GitHub checks have passed

data/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+
+  - package-ecosystem: "bundler" 
+    directory: "/" 
+    schedule:
+      interval: "daily"
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]

data/.github/stale.yml

@@ -0,0 +1,20 @@
+# Configuration for probot-stale - https://github.com/probot/stale
+
+# Number of days of inactivity before an Issue or Pull Request becomes stale
+daysUntilStale: 90
+
+# Number of days of inactivity before an Issue or Pull Request with the stale label is closed.
+daysUntilClose: 7
+
+# Issues or Pull Requests with these labels will never be considered stale. Set to `[]` to disable
+exemptLabels: []
+
+# Set to true to ignore issues with an assignee (defaults to false)
+exemptAssignees: true
+
+# Label to use when marking as stale
+staleLabel: closed:stale
+
+# Comment to post when marking as stale. Set to `false` to disable
+markComment: >
+  This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you have not received a response for our team (apologies for the delay) and this is still a blocker, please reply with additional information or just a ping. Thank you for your contribution! 🙇‍♂️

data/.gitignore

@@ -0,0 +1,18 @@
+bin/
+!examples/ruby-on-rails-api/bin/
+vendor/
+doc/
+.DS_Store
+.ruby-version
+coverage
+*.gem
+.ruby-gemset
+*.swp
+*.swo
+spec/minty.yml
+.env
+/.yardoc/checksums
+/.yardoc/complete
+/.yardoc/object_types
+/.yardoc/objects/root.dat
+/.yardoc/proxy_types

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format Fuubar
+--color

data/.rubocop.yml

@@ -0,0 +1,9 @@
+require:
+  - rubocop-rails
+Rails:
+  Enabled: true
+AllCops:
+ Exclude:
+   - bin/**/*
+   - vendor/**/*
+   - minty.gemspec

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,3 @@
+# Code of Conduct
+
+Please see [Minty's code of conduct guidelines](https://github.com/minty/open-source-template/blob/master/CODE-OF-CONDUCT.md) for information on contributing to this repo.

data/DEPLOYMENT.md

@@ -0,0 +1,61 @@
+# Releasing the gem
+
+## Credentials set up
+
+Make sure you have access in https://rubygems.org/gems/minty/ and that your Ruby Gems tokens are set in `~/.gem/credentials`.
+
+In order to generate the required changelog entry, define an environment variable `GITHUB_READ_TOKEN` with a Github API token that has READ access to `repo:public_repo`. You can generate a Github API Token [here](https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token).
+
+Create a new Github Milestone with the version name prefixed with `v`. i.e. `v4.10.2`. Assign every Issue and Pull Request to be included on this release to that Milestone, and tag them with the `CH:xxxxxx` labels, depending on the type of change fixed or introduced there.
+
+Finally, follow the next steps:
+
+```bash
+# Install gems for exec commands
+bundle install
+
+# Run all tests
+bundle exec rake test
+
+# Create a release branch
+git checkout master
+git pull
+git checkout -b release-X.X.X
+git push --set-upstream origin release-X.X.X
+
+# Update the version number
+# This will create a commit with the new version
+bundle exec gem bump --version X.X.X
+
+# Make sure the Gemfile.lock is up-to-date
+bundle update
+git commit -am "Update gems"
+
+# Generate the changelog
+github_changelog_generator -t $GITHUB_READ_TOKEN
+# ... or similar.
+# Review the changelog
+# Remove "unreleased" section
+# Make sure the tags are ordered
+
+# Commit, push, and create a PR for this release
+git commit -am "Update CHANGELOG.md"
+git push
+
+# Add related milestone
+# Create PR on GitHub and assign for review
+# Merge/rebase and delete branch once approved
+
+# Create and add a tag
+git checkout master
+git pull
+bundle exec gem tag
+git push origin vX.X.X
+# Create a new release from this tag on GitHub using markdown from the changelog
+
+# Make sure you are an author for this gem here https://rubygems.org/gems/minty/
+# Rubygems token can be updated in ~/.gem/credentials
+bundle exec gem release
+```
+
+The steps above were tested with Ruby `v2.5.7`.

data/DEVELOPMENT.md

@@ -0,0 +1,35 @@
+# Development
+
+In order to set up the local environment you'd have to have Ruby installed and a few global gems used to run and record the unit tests. A working Ruby version can be taken from the [CI script](/.circleci/config.yml). At the moment of this writting we're using Ruby `2.5.7`.
+
+> It is expected that every Pull Request introducing a fix, change or feature contains enough test coverage to assert the new behavior.
+
+## Running the tests
+
+Install the gems required for this project.
+
+```bash
+bundle install
+```
+
+Finally, run the tests.
+
+```bash
+bundle exec rake test
+```
+
+### Running only unit tests
+
+You can run only the unit tests and ignore the integration tests by running the following:
+
+```bash
+bundle exec rake spec
+```
+
+### Running only integration tests
+
+You can run only the unit tests and ignore the integration tests by running the following:
+
+```bash
+bundle exec rake integration
+```

data/Dockerfile

@@ -0,0 +1,5 @@
+FROM ruby:2.5
+
+WORKDIR /home/app
+
+COPY . /home/app

data/EXAMPLES.md

@@ -0,0 +1,195 @@
+# Examples using ruby
+
+## Build a URL to Universal Login Page
+
+```ruby
+require 'minty'
+
+client = MintyClient.new(
+  client_id: ENV['AUTH0_RUBY_CLIENT_ID'],
+  client_secret: ENV['AUTH0_RUBY_CLIENT_SECRET'],
+  domain: ENV['AUTH0_RUBY_DOMAIN'],
+)
+
+client.authorize_url 'http://localhost:3000'
+
+> => #<URI::HTTPS https://YOUR_DOMAIN/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A3000>
+
+```
+
+## Management API Client
+
+As a simple example of how to get started with the management API, we'll create an admin route to point to a list of all users from Minty:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # ...
+  get 'admin/users', to: 'all_users#index'
+  # ...
+end
+```
+
+... and a Controller to handle that route:
+
+```ruby
+# app/controllers/all_users_controller.rb
+require 'minty'
+
+class AllUsersController < ApplicationController
+  # Get all users from Minty with "minty" in their email.
+  def index
+    @params = {
+      q: "email:*minty*",
+      fields: 'email,user_id,name',
+      include_fields: true,
+      page: 0,
+      per_page: 50
+    }
+    @users = minty_client.users @params
+  end
+
+  private
+
+  # Setup the Minty API connection.
+  def minty_client
+    @minty_client ||= MintyClient.new(
+      client_id: ENV['AUTH0_RUBY_CLIENT_ID'],
+      client_secret: ENV['AUTH0_RUBY_CLIENT_SECRET'],
+      domain: ENV['AUTH0_RUBY_DOMAIN'],
+      api_version: 2,
+      timeout: 15 # optional, defaults to 10
+    )
+  end
+end
+```
+
+In this example, we're using environment variables to store the values needed to connect to Minty and authorize. The `token` used above is an API token for the Management API with the scopes required to perform a specific action (in this case `read:users`). These tokens can be [generated manually](https://minty.page/docs/api/management/v2/tokens#get-a-token-manually) using a test Application or with the [Application](https://manage.minty.page/#/applications) being used for your project.
+
+Finally, we'll add a view to display the results:
+
+```ruby
+# app/views/all_users/index.html.erb
+<h1>Users</h1>
+<%= debug @params %>
+<%= debug @users %>
+```
+
+This should show the parameters passed to the `users` method and a list of users that matched the query (or an empty array if none).
+
+## Organizations
+
+[Organizations](https://minty.page/docs/organizations) is a set of features that provide better support for developers who build and maintain SaaS and Business-to-Business (B2B) applications.
+
+Note that Organizations is currently only available to customers on our Enterprise and Startup subscription plans.
+
+### Logging in with an Organization
+
+Configure the Authentication API client and pass your Organization ID to the authorize url:
+
+```ruby
+require 'minty'
+
+@minty_client ||= MintyClient.new(
+  client_id: '{YOUR_APPLICATION_CLIENT_ID}',
+  client_secret: '{YOUR_APPLICATION_CLIENT_SECRET}',
+  domain: '{YOUR_TENANT}.minty.page',
+  organization: "{YOUR_ORGANIZATION_ID}"
+)
+
+universal_login_url = @minty_client.authorization_url("https://{YOUR_APPLICATION_CALLBACK_URL}")
+
+# redirect_to universal_login_url
+```
+
+### Accepting user invitations
+
+Minty Organizations allow users to be invited using emailed links, which will direct a user back to your application. The URL the user will arrive at is based on your configured `Application Login URI`, which you can change from your Application's settings inside the Minty dashboard. When they arrive at this URL, a `invitation` and `organization` query parameters will be provided
+
+```ruby
+require 'minty'
+
+@minty_client ||= MintyClient.new(
+  client_id: '{YOUR_APPLICATION_CLIENT_ID}',
+  client_secret: '{YOUR_APPLICATION_CLIENT_ID}',
+  domain: '{YOUR_TENANT}.minty.page',
+  organization: "{YOUR_ORGANIZATION_ID}"
+)
+
+universal_login_url = @minty_client.authorization_url("https://{YOUR_APPLICATION_CALLBACK_URL}", {
+  organization: "{ORGANIZATION_QUERY_PARAM}", # You can override organization if needed
+  invitation: "{INVITATION_QUERY_PARAM}"
+})
+
+# redirect_to universal_login_url
+```
+
+## ID Token Validation
+
+An ID token may be present in the credentials received after authentication. This token contains information associated with the user that has just logged in, provided the scope used contained `openid`. You can [read more about ID tokens here](https://minty.page/docs/tokens/concepts/id-tokens).
+
+Before accessing its contents, you must first validate the ID token to ensure it has not been tampered with and that it is meant for your application to consume. Use the `validate_id_token` method to do so:
+
+```ruby
+begin
+  @minty_client.validate_id_token 'YOUR_ID_TOKEN'
+rescue Minty::InvalidIdToken => e
+  # In this case the ID Token contents should not be trusted
+end
+```
+
+The method takes the following optional keyword parameters:
+
+| Parameter      | Type           | Description                                                                                                               | Default value                                                                                                          |
+| -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `algorithm`    | `JWTAlgorithm` | The [signing algorithm](https://minty.page/docs/tokens/concepts/signing-algorithms) used by your Minty application.        | `Minty::Algorithm::RS256` (using the [JWKS URL](https://minty.page/docs/tokens/concepts/jwks) of your **Minty Domain**) |
+| `leeway`       | Integer        | Number of seconds to account for clock skew when validating the `exp`, `iat` and `azp` claims.                            | `60`                                                                                                                   |
+| `nonce`        | String         | The `nonce` value you sent in the call to `/authorize`, if any.                                                           | `nil`                                                                                                                  |
+| `max_age`      | Integer        | The `max_age` value you sent in the call to `/authorize`, if any.                                                         | `nil`                                                                                                                  |
+| `issuer`       | String         | By default the `iss` claim will be checked against the URL of your **Minty Domain**. Use this parameter to override that. | `nil`                                                                                                                  |
+| `audience`     | String         | By default the `aud` claim will be compared to your **Minty Client ID**. Use this parameter to override that.             | `nil`                                                                                                                  |
+| `organization` | String         | By default the `org_id` claim will be compared to your **Organization ID**. Use this parameter to override that.          | `nil`                                                                                                                  |
+
+You can check the signing algorithm value under **Advanced Settings > OAuth > JsonWebToken Signature Algorithm** in your Minty application settings panel. [We recommend](https://minty.page/docs/tokens/concepts/signing-algorithms#our-recommendation) that you make use of asymmetric signing algorithms like `RS256` instead of symmetric ones like `HS256`.
+
+```ruby
+# HS256
+
+begin
+  @minty_client.validate_id_token 'YOUR_ID_TOKEN', algorithm: Minty::Algorithm::HS256.secret('YOUR_SECRET')
+rescue Minty::InvalidIdToken => e
+  # Handle error
+end
+
+# RS256 with a custom JWKS URL
+
+begin
+  @minty_client.validate_id_token 'YOUR_ID_TOKEN', algorithm: Minty::Algorithm::RS256.jwks_url('YOUR_URL')
+rescue Minty::InvalidIdToken => e
+  # Handle error
+end
+```
+
+### Organization ID Token Validation
+
+If an org_id claim is present in the Access Token, then the claim should be validated by the API to ensure that the value received is expected or known.
+
+In particular:
+
+- The issuer (iss) claim should be checked to ensure the token was issued by Minty
+
+- the org_id claim should be checked to ensure it is a value that is already known to the application. This could be validated against a known list of organization IDs, or perhaps checked in conjunction with the current request URL. e.g. the sub-domain may hint at what organization should be used to validate the Access Token.
+
+Normally, validating the issuer would be enough to ensure that the token was issued by Minty. In the case of organizations, additional checks should be made so that the organization within an Minty tenant is expected.
+
+If the claim cannot be validated, then the application should deem the token invalid.
+
+```ruby
+begin
+  @minty_client.validate_id_token 'YOUR_ID_TOKEN', organization: '{Expected org_id}'
+rescue Minty::InvalidIdToken => e
+  # In this case the ID Token contents should not be trusted
+end
+```
+
+For more information, please read [Work with Tokens and Organizations](https://minty.page/docs/organizations/using-tokens) on Minty Docs.

data/Gemfile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'coveralls', require: false
+  gem 'irb', require: false
+  gem 'rubocop', require: false
+  gem 'rubocop-rails', require: false
+  gem 'terminal-notifier-guard', require: false unless ENV['CIRCLECI']
+end
+
+group :test do
+  gem 'pp'
+  gem 'simplecov-cobertura'
+  gem 'timecop', require: false
+  gem 'vcr', require: false
+  gem 'webmock', require: false
+end