auth0 3.6.1 → 4.0.0

data/doc_config/templates/default/layout/html/breadcrumb.erb

@@ -0,0 +1,11 @@
+<div id="menu">
+  <% if @contents || @file %>
+    <% if object != '_index.html' %><a href="<%= url_for_index.gsub! '_index.html', 'index.html' %>">Index</a> &raquo; <% end %>
+    <span class="title"><%= @breadcrumb_title %></span>
+  <% elsif object.is_a?(CodeObjects::Base) %>
+    <a href="<%= url_for_index.gsub! '_index.html', 'index.html' %>"><% if object.root? || object.type == :method %>Index<% else %>Index (<%= object.name.to_s[0,1] %>)<% end %></a> &raquo;
+    <%= @breadcrumb.map {|obj| "<span class='title'>" + linkify(obj, obj.name) + "</span>" }.join(" &raquo; ") %>
+    <%= @breadcrumb.size > 0 ? " &raquo; " : "" %>
+    <span class="title"><%= object.root? ? "Top Level Namespace" : object.name(true) %></span>
+  <% end %>
+</div>

data/doc_config/templates/default/layout/html/footer.erb

@@ -0,0 +1,115 @@
+<footer class="site-footer">
+  <div class="container">
+    <div class="logo">
+      <img src="https://cdn.auth0.com/styleguide/1.0.0/img/badge.png" width="30">
+    </div>
+    <div class="footer-grid">
+      <div class="column">
+        <div class="item">
+          <h6>Product</h6>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/pricing">Pricing</a>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/why-auth0">Why Auth0</a>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/how-it-works">How It Works</a>
+        </div>
+      </div>
+      <div class="column">
+        <div class="item">
+          <h6>Company</h6>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/about">About Us</a>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/blog">Blog</a>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/jobs">Jobs</a>
+        </div>
+      </div>
+      <div class="column">
+        <div class="item"><h6>Security</h6></div>
+        <div class="item">
+          <a href="https://auth0.com/availability-trust">Availability &amp; Trust</a>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/security">Security</a>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/whitehat">White Hat</a>
+        </div>
+      </div>
+      <div class="column">
+        <div class="item">
+          <h6>Learn</h6>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/support">Help &amp; Support</a>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/docs">Documentation</a>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/opensource">Open Source</a>
+        </div>
+      </div>
+      <div class="column">
+        <div class="item">
+          <h6>Extend</h6>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/lock">Lock</a>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/wordpress">WordPress</a>
+        </div>
+        <div class="item">
+          <a href="https://auth0.com/docs/apiv2">API Explorer</a>
+        </div>
+      </div>
+      <div class="contact">
+        <div class="column">
+          <div class="item">
+            <h6>Contact</h6>
+          </div>
+          <div class="item">
+            <a href="mailto:support@auth0.com">Email Us</a>
+          </div>
+          <div class="item item-text">10777 Main Street<br>Suite 204<br>Bellevue, WA   98004</div>
+        </div>
+          <div class="column no-heading">
+            <div class="item item-phone-label">Sales</div>
+            <div class="item"><a href="tel:+18882352699">+1 (888) 235-2699</a>
+              <a href="tel:+14253126521">+1 (425) 312-6521</a>
+            </div>
+            <div class="item item-phone-label">Support</div>
+            <div class="item"><a href="tel:+14255599554">+1 (425) 559-9554</a></div>
+          </div>
+        </div>
+      </div>
+      <div class="colophon">
+        <div class="column">
+          <div class="social">
+            <div class="twitter">
+              <iframe allowtransparency="true" frameborder="0" scrolling="no" src="https://platform.twitter.com/widgets/follow_button.html?screen_name=auth0" class="twitter"></iframe>
+            </div>
+            <div class="facebook">
+              <iframe src="http://www.facebook.com/plugins/like.php?href=https%3A%2F%2Ffacebook.com%2Fgetauth0&width&layout=button_count&action=like&show_faces=false&show_count=false&share=false&height=21&appId=507756515938786" scrolling="no" frameborder="0" allowtransparency="true" class="facebook"></iframe>
+            </div>
+          </div>
+        </div>
+        <div class="column">
+          <ul class="list-inline text-right">
+            <li><a href="https://auth0.com/privacy">Privacy Policy</a></li>
+            <li><a href="https://auth0.com/terms">Terms of Service</a></li>
+            <li><span>© 2013-2016 Auth0 Inc. All Rights Reserved.</span></li>
+          </ul>
+        </div>
+      </div>
+    </div>
+  </footer>

data/doc_config/templates/default/layout/html/headers.erb

@@ -0,0 +1,17 @@
+<meta http-equiv="Content-Type" content="text/html; charset=<%= charset %>" />
+<title>
+  <%= h @page_title %>
+  <% if options.title && @page_title != options.title %>
+    &mdash; <%= h options.title %>
+  <% end %>
+</title>
+<link href="https://cdn.auth0.com/styleguide/latest/index.css" rel="stylesheet" />
+<link href="https://cdn.auth0.com/web-header/latest/standalone.css" rel="stylesheet"/>
+<script type="text/javascript" src="https://cdn.auth0.com/web-header/latest/standalone.min.js"></script>
+<% stylesheets.each do |stylesheet| %>
+  <link rel="stylesheet" href="<%= url_for(stylesheet) %>" type="text/css" charset="utf-8" />
+<% end %>
+<%= erb :script_setup %>
+<% javascripts.each do |javascript| %>
+  <script type="text/javascript" charset="utf-8" src="<%= url_for(javascript) %>"></script>
+<% end %>

data/doc_config/templates/default/layout/html/layout.erb

@@ -0,0 +1,27 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <%= erb(:headers) %>
+  </head>
+  <body>
+    <header class="site-header clearfix"></header>
+    <script type="text/javascript">(function() {
+      var header = new WebHeader({ base_url: 'https://auth0.com' });
+      header.render('header.site-header');
+    })();
+    </script>
+
+    <div id="header">
+      <%= erb(:breadcrumb) %>
+      <%= erb(:search) %>
+      <div class="clear"></div>
+    </div>
+
+    <iframe id="search_frame"></iframe>
+
+    <div id="content"><%= yieldall %></div>
+
+    <%= erb(:footer) %>
+  </body>
+</html>

data/lib/auth0.rb

@@ -1,8 +1,8 @@
-require "auth0/version"
-require "auth0/mixins"
-require "auth0/exception"
-require "auth0/client"
-require "auth0_client"
+require 'auth0/version'
+require 'auth0/mixins'
+require 'auth0/exception'
+require 'auth0/client'
+require 'auth0_client'
 # Namespace for ruby-auth0 logic
 module Auth0
 end

data/lib/auth0/api/authentication_endpoints.rb

@@ -1,88 +1,306 @@
+# rubocop:disable Metrics/ModuleLength
 module Auth0
   module Api
     # {https://auth0.com/docs/auth-api}
-    # Describing functionality of auth0 authentication endpoints
+    # Methods to use the authentication endpoints
     module AuthenticationEndpoints
-      # {https://auth0.com/docs/auth-api#!#post--oauth-access_token}
-      def obtain_access_token
+      UP_AUTH = 'Username-Password-Authentication'
+      JWT_BEARER = 'urn:ietf:params:oauth:grant-type:jwt-bearer'
+
+      # Retrives an access token
+      # @see https://auth0.com/docs/auth-api#!#post--oauth-access_token
+      # @param access_token [string] Social provider's access_token
+      # @param connection [string] Currently, this endpoint only works for Facebook, Google, Twitter and Weibo
+      # @return [json] Returns the access token
+      def obtain_access_token(access_token = nil, connection = 'facebook', scope = 'openid')
+        if access_token
+          request_params = { client_id: @client_id, access_token: access_token, connection: connection, scope: scope }
+          post('/oauth/access_token', request_params)['access_token']
+        else
+          request_params = { client_id: @client_id, client_secret: @client_secret, grant_type: 'client_credentials' }
+          post('/oauth/token', request_params)['access_token']
+        end
+      end
+
+      # Logins using username/password
+      # @see https://auth0.com/docs/auth-api#!#post--oauth-ro
+      # @param username [string] Username
+      # @param password [string] User's password
+      # @param scope [string] Defaults to openid. Can be 'openid name email', 'openid offline_access'
+      # @param id_token [string] Token's id
+      # @param connection_name [string] Connection name. Works for database connections, passwordless connections,
+      # Active Directory/LDAP, Windows Azure AD and ADF
+      # @return [json] Returns the access token and id token
+      def login(username, password, id_token = nil, connection_name = UP_AUTH, options = {})
+        fail Auth0::InvalidParameter, 'Must supply a valid username' if username.to_s.empty?
+        fail Auth0::InvalidParameter, 'Must supply a valid password' if password.to_s.empty?
         request_params = {
-          client_id:      @client_id,
-          client_secret:  @client_secret,
-          grant_type:     'client_credentials'
+          client_id:  @client_id,
+          username:   username,
+          password:   password,
+          scope:      options.fetch(:scope, 'openid'),
+          connection: connection_name,
+          grant_type: options.fetch(:grant_type, password),
+          id_token:   id_token,
+          device:     options.fetch(:device, nil)
+        }
+        post('/oauth/ro', request_params)
+      end
+
+      # Signup using username/password
+      # @see https://auth0.com/docs/auth-api#!#post--dbconnections-signup
+      # @param email [string] User email
+      # @param password [string] User's password
+      # @param connection_name [string] Connection name. Works for database connections.
+      # @return [json] Returns the created user
+      def signup(email, password, connection_name = UP_AUTH)
+        fail Auth0::InvalidParameter, 'Must supply a valid email' if email.to_s.empty?
+        fail Auth0::InvalidParameter, 'Must supply a valid password' if password.to_s.empty?
+        request_params = {
+          client_id:  @client_id,
+          email:      email,
+          connection: connection_name,
+          password:   password
         }
-        post("/oauth/token", request_params)["access_token"]
+        post('/dbconnections/signup', request_params)
       end
 
-      # {https://auth0.com/docs/auth-api#!#post--delegation}
-      def delegation(id_token, target, scope = "openid", api_type = "app", extra_parameters = {})
+      # Asks to change a password for a given user.
+      # Send an email to the user.
+      # @see https://auth0.com/docs/auth-api#!#post--dbconnections-change_password
+      # @param email [string] User email
+      # @param password [string] User's new password
+      # @param connection_name [string] Connection name. Works for database connections.
+      def change_password(email, password, connection_name = UP_AUTH)
+        fail Auth0::InvalidParameter, 'Must supply a valid email' if email.to_s.empty?
         request_params = {
           client_id:  @client_id,
-          grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+          email:      email,
+          connection: connection_name,
+          password:   password
+        }
+        post('/dbconnections/change_password', request_params)
+      end
+
+      # Start passwordless workflow sending an email
+      # @see https://auth0.com/docs/auth-api#!#post--with_email
+      # @param email [string] User email
+      # @param send [string] Defaults to 'link'. Can be 'code'. You can then authenticate with this user opening the link
+      # @param auth_params [hash] Append/override parameters to the link (like scope, redirect_uri, protocol, etc.)
+      def start_passwordless_email_flow(email, send = 'link', auth_params = {})
+        fail Auth0::InvalidParameter, 'Must supply a valid email' if email.to_s.empty?
+        request_params = {
+          client_id:    @client_id,
+          email:        email,
+          send:         send,
+          auth_params:  auth_params
+        }
+        post('/passwordless/start', request_params)
+      end
+
+      # Start passwordless workflow sending a SMS message
+      # @see https://auth0.com/docs/auth-api#!#post--with_sms
+      # @param phone_number [string] User's phone number.
+      def start_passwordless_sms_flow(phone_number)
+        fail Auth0::InvalidParameter, 'Must supply a valid phone number' if phone_number.to_s.empty?
+        request_params = {
+          client_id:    @client_id,
+          connection:   'sms',
+          phone_number: phone_number
+        }
+        post('/passwordless/start', request_params)
+      end
+
+      # Logins using phone number/verification code.
+      # @see https://auth0.com/docs/auth-api#!#post--ro_with_sms
+      # @param phone_number [string] User's phone number.
+      # @param code [string] Verification code.
+      # @return [json] Returns the access token and id token
+      def phone_login(phone_number, code, scope = 'openid')
+        fail Auth0::InvalidParameter, 'Must supply a valid phone number' if phone_number.to_s.empty?
+        fail Auth0::InvalidParameter, 'Must supply a valid code' if code.to_s.empty?
+        request_params = {
+          client_id:  @client_id,
+          username:   phone_number,
+          password:   code,
+          scope:      scope,
+          connection: 'sms',
+          grant_type: 'password'
+        }
+        post('/oauth/ro', request_params)
+      end
+
+      # Retrives the SAML 2.0 metadata
+      # @see https://auth0.com/docs/auth-api#!#get--samlp--client_id-
+      # @param client_id [string] Client id
+      # @return [xml] SAML 2.0 metadata
+      def saml_metadata(client_id)
+        fail Auth0::InvalidParameter, 'Must supply a valid client_id' if client_id.to_s.empty?
+        get("/samlp/metadata/#{client_id}")
+      end
+
+      # Retrives the WS-Federation metadata
+      # @see https://auth0.com/docs/auth-api#!#get--wsfed--client_id-
+      # @return [xml] Federation Metadata
+      def wsfed_metadata
+        get('/wsfed/FederationMetadata/2007-06/FederationMetadata.xml')
+      end
+
+      # Validates a JSON Web Token (signature and expiration)
+      # @see https://auth0.com/docs/auth-api#!#post--tokeninfo
+      # @param id_token [string] Token's id.
+      # @return User information associated with the user id (sub property) of the token.
+      def token_info(id_token)
+        fail Auth0::InvalidParameter, 'Must supply a valid id_token' if id_token.to_s.empty?
+        request_params = { id_token: id_token }
+        post('/tokeninfo', request_params)
+      end
+
+      # Refreshes a delegation token
+      # @see https://auth0.com/docs/auth-api#!#post--delegation
+      # @param refresh_token [string] Token to refresh
+      # @param target [string] Target to sign the new token.
+      # @param scope [string] Defaults to openid. Can be 'openid name email'.
+      # @param api_type [string] Defaults to app. Can be aws, azure_sb, azure_blob, firebase, layer, salesforce_api,
+      #  salesforce_sandbox_api, sap_api or wams
+      # @param extra_parameters [hash] Extra parameters.
+      # @return [json] Returns the refreshed delegation token
+      def refresh_delegation(refresh_token, target, scope = 'openid', api_type = 'app', extra_parameters = {})
+        fail Auth0::InvalidParameter, 'Must supply a valid token to refresh' if refresh_token.to_s.empty?
+        request_params = {
+          client_id:      @client_id,
+          grant_type:     JWT_BEARER,
+          refresh_token:  refresh_token,
+          target:         target,
+          api_type:       api_type,
+          scope:          scope
+        }.merge(extra_parameters)
+        post('/delegation', request_params)
+      end
+
+      # Retrives a delegation token
+      # @see https://auth0.com/docs/auth-api#!#post--delegation
+      # @param id_token [string] Token's id.
+      # @param target [string] Target to sign the new token.
+      # @param scope [string] Defaults to openid. Can be 'openid name email'.
+      # @param api_type [string] Defaults to app. Can be aws, azure_sb, azure_blob, firebase, layer, salesforce_api,
+      #  salesforce_sandbox_api, sap_api or wams
+      # @param extra_parameters [hash] Extra parameters.
+      # @return [json] Returns the refreshed delegation token
+      def delegation(id_token, target, scope = 'openid', api_type = 'app', extra_parameters = {})
+        fail Auth0::InvalidParameter, 'Must supply a valid id_token' if id_token.to_s.empty?
+        request_params = {
+          client_id:  @client_id,
+          grant_type: JWT_BEARER,
           id_token:   id_token,
           target:     target,
           api_type:   api_type,
           scope:      scope
         }.merge(extra_parameters)
-        post("/delegation", request_params)
+        post('/delegation', request_params)
       end
 
-      # {https://auth0.com/docs/auth-api#!#post--users--user_id--impersonate}
+      # Retrives an impersonation URL to login as another user
+      # @see https://auth0.com/docs/auth-api#!#post--users--user_id--impersonate
+      # @param user_id [string] Impersonate user id
+      # @param app_client_id [string] Application client id
+      # @param impersonator_id [string] Impersonator user id id.
+      # @param options [string] Additional Parameters
+      # @return [string] Impersonation URL
       def impersonate(user_id, app_client_id, impersonator_id, options)
+        fail Auth0::InvalidParameter, 'Must supply a valid user_id' if user_id.to_s.empty?
         request_params = {
-          protocol:         options.fetch(:protocol, "oauth2"),
+          protocol:         options.fetch(:protocol, 'oauth2'),
           impersonator_id:  impersonator_id,
           client_id:        app_client_id,
-          ttl:              options.fetch(:ttl, 120),
           additionalParameters: {
-            response_type:  options.fetch(:response_type, "code"),
-            state:          options.fetch(:state, ""),
-            scope:          options.fetch(:scope, "openid"),
-            callback_url:   options.fetch(:callback_url, ""),
+            response_type:  options.fetch(:response_type, 'code'),
+            state:          options.fetch(:state, ''),
+            scope:          options.fetch(:scope, 'openid'),
+            callback_url:   options.fetch(:callback_url, '')
           }
         }
         post("/users/#{user_id}/impersonate", request_params)
       end
 
-      # {https://auth0.com/docs/auth-api#!#post--oauth-ro}
-      def login(username, password, scope = "openid", id_token=nil, connection_name="Username-Password-Authentication")
+      # Unlinks a User
+      # @see https://auth0.com/docs/auth-api#!#post--unlink
+      # @param access_token [string] Logged-in user access token
+      # @param user_id [string] User Id
+      def unlink_user(access_token, user_id)
+        fail Auth0::InvalidParameter, 'Must supply a valid access_token' if access_token.to_s.empty?
+        fail Auth0::InvalidParameter, 'Must supply a valid user_id' if user_id.to_s.empty?
         request_params = {
-          client_id:  @client_id,
-          username:   username,
-          password:   password,
-          scope:      scope,
-          connection: connection_name,
-          grant_type: "password",
-          id_token:   id_token
+          access_token:  access_token,
+          user_id: user_id
+        }
+        post('/unlink', request_params)
+      end
+
+      # Returns the user information based on the Auth0 access token.
+      # @see https://auth0.com/docs/auth-api#!#get--userinfo
+      # @return [json] User information based on the Auth0 access token
+      def user_info
+        get('/userinfo')
+      end
+
+      # Returns an authorization URL, triggers a redirect.
+      # @see https://auth0.com/docs/auth-api#!#get--authorize_social
+      # @param redirect_uri [string] Url to redirect after authorization
+      # @param options [hash] Can contain response_type, connection, state and additional_parameters.
+      # @return [url] Authorization URL.
+      def authorization_url(redirect_uri, options = {})
+        fail Auth0::InvalidParameter, 'Must supply a valid redirect_uri' if redirect_uri.to_s.empty?
+        request_params = {
+          client_id: @client_id,
+          response_type: options.fetch(:connection, 'code'),
+          connection: options.fetch(:connection, nil),
+          redirect_url: redirect_uri,
+          state: options.fetch(:state, nil)
+        }.merge(options.fetch(:additional_parameters, {}))
+
+        URI::HTTPS.build(host: @domain, path: '/authorize', query: to_query(request_params))
+      end
+
+      # Returns an logout  URL, triggers the logout flow.
+      # @see https://auth0.com/docs/auth-api#!#get--logout
+      # @param return_to [string] Url to redirect after authorization
+      # @return [url] Logout URL.
+      def logout_url(return_to)
+        request_params = {
+          returnTo: return_to
         }
-        post("/oauth/ro", request_params)
+
+        URI::HTTPS.build(host: @domain, path: '/logout', query: to_query(request_params))
       end
 
-      # {https://auth0.com/docs/auth-api#!#post--dbconnections-signup}
-      def signup(email, password, connection_name= "Username-Password-Authentication")
+      # Returns a samlp URL. The SAML Request AssertionConsumerServiceURL will be used to POST back the assertion
+      # and it has to match with the application callback URL.
+      # @see https://auth0.com/docs/auth-api#get--samlp--client_id-
+      # @param connection [string] to login with a specific provider.
+      # @return [url] samlp URL.
+      def samlp_url(connection = UP_AUTH)
         request_params = {
-          client_id:  @client_id,
-          email:      email,
-          connection: connection_name,
-          password:   password
+          connection: connection
         }
-        post("/dbconnections/signup", request_params)
+        URI::HTTPS.build(host: @domain, path: "/samlp/#{@client_id}", query: to_query(request_params))
       end
 
-      # {https://auth0.com/docs/auth-api#!#post--dbconnections-change_password}
-      def change_password(email, password, connection_name = "Username-Password-Authentication")
+      # Returns a wsfed URL.
+      # @see https://auth0.com/docs/auth-api#get--wsfed--client_id-
+      # @param connection [string] to login with a specific provider.
+      # @return [url] wsfed URL.
+      def wsfed_url(connection = UP_AUTH)
         request_params = {
-          client_id:  @client_id,
-          email:      email,
-          connection: connection_name,
-          password:   password
+          whr: connection
         }
-        post("/dbconnections/change_password", request_params)
+        URI::HTTPS.build(host: @domain, path: "/wsfed/#{@client_id}", query: to_query(request_params))
       end
 
-      # {https://auth0.com/docs/auth-api#!#post--tokeninfo}
-      def token_info(id_token)
-        request_params = { id_token: id_token}
-        post("/tokeninfo", request_params)
+      private
+
+      def to_query(hash)
+        hash.map { |k, v| "#{k}=#{URI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
       end
     end
   end