### Install Project Dependencies

Source: https://github.com/auth0/ruby-auth0/blob/master/DEVELOPMENT.md

Run this command to install all the gems required for the project. Ensure you have Bundler installed.

```bash
bundle install
```

--------------------------------

### Install Ruby Auth0 Gem

Source: https://github.com/auth0/ruby-auth0/blob/master/README.md

Install the auth0 gem using the gem command. This is a straightforward installation method.

```bash
$ gem install auth0
```

--------------------------------

### Install Auth0 Ruby Gem (Pre-release)

Source: https://github.com/auth0/ruby-auth0/blob/master/README.md

Install the pre-release version of the Auth0 Ruby gem to access the latest features and improvements. This command is useful for testing beta versions.

```bash
gem install auth0 --pre
```

--------------------------------

### Run Ruby on Rails API

Source: https://github.com/auth0/ruby-auth0/blob/master/examples/ruby-on-rails-api/README.md

After setting environment variables and installing dependencies, run the Rails server using the `rails s` command. You can then access the API endpoints.

```bash
bundle install
rails s
```

--------------------------------

### Install Ruby Auth0 Gem with Bundler

Source: https://github.com/auth0/ruby-auth0/blob/master/README.md

Add the auth0 gem to your project's Gemfile using Bundler. This ensures dependency management.

```bash
bundle add auth0
```

--------------------------------

### Rails Route for All Users

Source: https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md

Defines a GET route in a Rails application to fetch all users from Auth0. This is part of a larger example for displaying users.

```ruby
# config/routes.rb
Rails.application.routes.draw do
  # ...
  get 'admin/users', to: 'all_users#index'
  # ...
end
```

--------------------------------

### Gem Release Workflow Commands

Source: https://github.com/auth0/ruby-auth0/blob/master/DEPLOYMENT.md

Execute these commands to manage the gem release process, including installing dependencies, running tests, creating branches, updating versions, generating changelogs, and publishing the gem.

```bash
bundle install
```

```bash
bundle exec rake test
```

```bash
git checkout master
git pull
git checkout -b release-X.X.X
git push --set-upstream origin release-X.X.X
```

```bash
# Update the version number
# This will create a commit with the new version
bundle exec gem bump --version X.X.X
```

```bash
# Make sure the Gemfile.lock is up-to-date
bundle update
git commit -am "Update gems"
```

```bash
# Generate the changelog
github_changelog_generator -t $GITHUB_READ_TOKEN
```

```bash
# ... or similar.
# Review the changelog
# Remove "unreleased" section
# Make sure the tags are ordered
```

```bash
# Commit, push, and create a PR for this release
git commit -am "Update CHANGELOG.md"
git push
```

```bash
# Add related milestone
# Create PR on GitHub and assign for review
# Merge/rebase and delete branch once approved
```

```bash
# Create and add a tag
git checkout master
git pull
bundle exec gem tag
git push origin vX.X.X
```

```bash
# Create a new release from this tag on GitHub using markdown from the changelog
```

```bash
# Make sure you are an author for this gem here https://rubygems.org/gems/auth0/
# Rubygems token can be updated in ~/.gem/credentials
bundle exec gem release
```

--------------------------------

### Initialize Auth0Client

Source: https://github.com/auth0/ruby-auth0/blob/master/README.md

Create an instance of Auth0Client to interact with Auth0 APIs. Provide your client ID, secret, and domain. The SDK can automatically fetch a Management API token if client credentials are provided and the application is configured for the Client Credentials grant.

```ruby
require 'auth0'

client = Auth0Client.new(
  client_id: ENV['AUTH0_RUBY_CLIENT_ID'],
  client_secret: ENV['AUTH0_RUBY_CLIENT_SECRET'],
  domain: ENV['AUTH0_RUBY_DOMAIN'],
  # If you pass in a client_secret value, the SDK will automatically try to get a
  # Management API token for this application. Make sure your Application can make a
  # Client Credentials grant (Application settings in Auth0 > Advanced > Grant Types
  # tab) and that the Application is authorized for the Management API:
  # https://auth0.com/docs/api-auth/config/using-the-auth0-dashboard
  #
  # Otherwise, you can pass in a Management API token directly for testing or temporary
  # access using the key below.
  # token: ENV['AUTH0_RUBY_API_TOKEN'],
  #
  # When passing a token, you can also specify when the token expires in seconds from epoch. Otherwise, expiry is set
  # by default to an hour from now.
  # token_expires_at: Time.now.to_i + 86400
)
```

--------------------------------

### Build and Publish Ruby Gem using Docker

Source: https://github.com/auth0/ruby-auth0/blob/master/RUBYGEM.md

Use these Docker commands to build the image and then run the container to publish the gem. Ensure RUBYGEMS_EMAIL and RUBYGEMS_PASSWORD environment variables are set.

```bash
docker build -t auth0-publish-rubygem .
docker run --rm -e RUBYGEMS_EMAIL="$RUBYGEMS_EMAIL" -e RUBYGEMS_PASSWORD="$RUBYGEMS_PASSWORD" -it auth0-publish-rubygem /bin/sh publish_rubygem.sh
```

--------------------------------

### Set Environment Variables for Auth0

Source: https://github.com/auth0/ruby-auth0/blob/master/examples/ruby-api/README.md

Configure your Auth0 Client Secret and Client ID by creating a .env file in the project directory. This is required for the application to authenticate correctly.

```bash
# .env file
AUTH0_CLIENT_SECRET=myCoolSecret
AUTH0_CLIENT_ID=myCoolClientId
```

--------------------------------

### Accept User Invitations with Organization

Source: https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md

Generates a Universal Login URL that includes organization and invitation parameters, used when accepting user invitations. Replace placeholders with actual query parameters.

```ruby
require 'auth0'

@auth0_client ||= Auth0Client.new(
  client_id: '{YOUR_APPLICATION_CLIENT_ID}',
  client_secret: '{YOUR_APPLICATION_CLIENT_ID}',
  domain: '{YOUR_TENANT}.auth0.com',
  organization: "{YOUR_ORGANIZATION_ID_OR_NAME}"
)

universal_login_url = @auth0_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
```

--------------------------------

### Run All Tests

Source: https://github.com/auth0/ruby-auth0/blob/master/DEVELOPMENT.md

Execute this command to run all tests, including unit and integration tests. This is the primary command for verifying code changes.

```bash
bundle exec rake test
```

--------------------------------

### Build Universal Login URL with ruby-auth0

Source: https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md

Use this to generate a URL that redirects users to Auth0's Universal Login page. Ensure your Auth0 client credentials and domain are set as environment variables.

```ruby
require 'auth0'

client = Auth0Client.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>
```

--------------------------------

### Run Only Unit Tests

Source: https://github.com/auth0/ruby-auth0/blob/master/DEVELOPMENT.md

Use this command to run only the unit tests, excluding integration tests. This is useful for faster feedback cycles during development.

```bash
bundle exec rake spec
```

--------------------------------

### Authenticate with Auth0 using a Private Key

Source: https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md

Configure the Auth0 client to use a private key for authentication instead of a client secret. Ensure the corresponding public key is uploaded to your Auth0 tenant. The `client_assertion_signing_alg` defaults to `RS256` if omitted, and only `RS256`, `RS384`, and `PS256` are supported.

```ruby
key_string = File.read 'key.pem'
key = OpenSSL::PKey::RSA.new key_string

client = Auth0Client.new(
  domain: 'AUTH0_DOMAIN',
  client_id: 'AUTH0_CLIENT_ID',
  client_assertion_signing_key: key,
  client_assertion_signing_alg: 'RS256')

```

--------------------------------

### Login with Organization using ruby-auth0

Source: https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md

Configures the Auth0 client to include an organization ID or name for logging in users within a specific organization. Ensure placeholders are replaced with actual values.

```ruby
require 'auth0'

@auth0_client ||= Auth0Client.new(
  client_id: '{YOUR_APPLICATION_CLIENT_ID}',
  client_secret: '{YOUR_APPLICATION_CLIENT_SECRET}',
  domain: '{YOUR_TENANT}.auth0.com',
  organization: "{YOUR_ORGANIZATION_ID_OR_NAME}"
)

universal_login_url = @auth0_client.authorization_url("https://{YOUR_APPLICATION_CALLBACK_URL}")

# redirect_to universal_login_url
```

--------------------------------

### Run Only Integration Tests

Source: https://github.com/auth0/ruby-auth0/blob/master/DEVELOPMENT.md

Execute this command to run only the integration tests, excluding unit tests. This is helpful for testing end-to-end functionality.

```bash
bundle exec rake integration
```

--------------------------------

### Rails Controller to Fetch Auth0 Users

Source: https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md

A Rails controller action that uses the Auth0 Management API to retrieve users matching a specific query. Requires Auth0 client configuration.

```ruby
# app/controllers/all_users_controller.rb
require 'auth0'

class AllUsersController < ApplicationController
  # Get all users from Auth0 with "auth0" in their email.
  def index
    @params = {
      q: "email:*auth0*",
      fields: 'email,user_id,name',
      include_fields: true,
      page: 0,
      per_page: 50
    }
    @users = auth0_client.users @params
  end

  private

  # Setup the Auth0 API connection.
  def auth0_client
    @auth0_client ||= Auth0Client.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
```

--------------------------------

### Rails View to Display Auth0 Users

Source: https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md

A simple ERB view template for a Rails application to display the parameters used for fetching users and the list of users retrieved from Auth0.

```erb
# app/views/all_users/index.html.erb
<h1>Users</h1>
<%= debug @params %>
<%= debug @users %>
```

--------------------------------

### Test Secured API Endpoint

Source: https://github.com/auth0/ruby-auth0/blob/master/examples/ruby-on-rails-api/README.md

Access the /secured/ping endpoint to test authentication. This endpoint requires a JWT in the header; otherwise, it will return an error.

```http
http://localhost:3000/secured/ping
```

--------------------------------

### Validate ID Token with Default Settings

Source: https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md

Use this snippet to validate an ID token with the default algorithm (RS256) and JWKS URL. Ensure you handle potential `Auth0::InvalidIdToken` exceptions.

```ruby
begin
  @auth0_client.validate_id_token 'YOUR_ID_TOKEN'
rescue Auth0::InvalidIdToken => e
  # In this case the ID Token contents should not be trusted
end
```

--------------------------------

### Validate ID Token with HS256 Algorithm

Source: https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md

When using the HS256 symmetric signing algorithm, you must provide the shared secret. This method is not recommended for production environments.

```ruby
begin
  @auth0_client.validate_id_token 'YOUR_ID_TOKEN', algorithm: Auth0::Algorithm::HS256.secret('YOUR_SECRET')
rescue Auth0::InvalidIdToken => e
  # Handle error
end
```

--------------------------------

### Test Unsecured API Endpoint

Source: https://github.com/auth0/ruby-auth0/blob/master/examples/ruby-on-rails-api/README.md

Access the /ping endpoint to test the basic API functionality. This endpoint does not require authentication.

```http
http://localhost:3000/ping
```

--------------------------------

### Validate ID Token with RS256 and Custom JWKS URL

Source: https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md

For RS256 asymmetric signing, you can specify a custom JWKS URL if it differs from your Auth0 domain's default. This is the recommended signing algorithm.

```ruby
begin
  @auth0_client.validate_id_token 'YOUR_ID_TOKEN', algorithm: Auth0::Algorithm::RS256.jwks_url('YOUR_URL')
rescue Auth0::InvalidIdToken => e
  # Handle error
end
```

--------------------------------

### Validate Organization Claim in ID Token

Source: https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md

Use this snippet to validate the `org_id` or `org_name` claim within an ID token. Ensure the token was issued by Auth0 and the organization value is known to your application. Handle `Auth0::InvalidIdToken` exceptions if validation fails.

```ruby
begin
  @auth0_client.validate_id_token 'YOUR_ID_TOKEN', organization: '{Expected org_id or org_name}'
rescue Auth0::InvalidIdToken => e
  # In this case the ID Token contents should not be trusted
end
```

--------------------------------

### validate_id_token

Source: https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md

Validates an ID token to ensure it has not been tampered with and is intended for your application. It can accept optional parameters to customize the validation process.

```APIDOC
## validate_id_token

### Description
Validates an ID token to ensure it has not been tampered with and is intended for your application. It can accept optional parameters to customize the validation process.

### Method
```ruby
@auth0_client.validate_id_token 'YOUR_ID_TOKEN'
```

### Parameters
#### Optional Keyword Parameters
- **algorithm** (`JWTAlgorithm`) - The signing algorithm used by your Auth0 application. Defaults to `Auth0::Algorithm::RS256` using the JWKS URL of your Auth0 Domain.
- **leeway** (`Integer`) - Number of seconds to account for clock skew when validating the `exp`, `iat` and `azp` claims. Defaults to `60`.
- **nonce** (`String`) - The `nonce` value sent in the call to `/authorize`, if any. Defaults to `nil`.
- **max_age** (`Integer`) - The `max_age` value sent in the call to `/authorize`, if any. Defaults to `nil`.
- **issuer** (`String`) - Overrides the default check of the `iss` claim against your Auth0 Domain URL. Defaults to `nil`.
- **audience** (`String`) - Overrides the default comparison of the `aud` claim to your Auth0 Client ID. Defaults to `nil`.
- **organization** (`String`) - Overrides the default comparison of the `org_id` or `org_name` claims to the `organization` value specified at client creation. Defaults to `nil`.

### Request Example
```ruby
begin
  @auth0_client.validate_id_token 'YOUR_ID_TOKEN'
rescue Auth0::InvalidIdToken => e
  # Handle error
end
```

### Response
#### Success Response
- The method returns successfully if the token is valid.

#### Error Response
- `Auth0::InvalidIdToken`: Raised if the ID token is invalid.

### Examples
#### Using HS256 algorithm
```ruby
begin
  @auth0_client.validate_id_token 'YOUR_ID_TOKEN', algorithm: Auth0::Algorithm::HS256.secret('YOUR_SECRET')
rescue Auth0::InvalidIdToken => e
  # Handle error
end
```

#### Using RS256 with a custom JWKS URL
```ruby
begin
  @auth0_client.validate_id_token 'YOUR_ID_TOKEN', algorithm: Auth0::Algorithm::RS256.jwks_url('YOUR_URL')
rescue Auth0::InvalidIdToken => e
  # Handle error
end
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.