Ruby: Authorization Code Grant Examples

Github repo: eg-03-ruby-auth-code-grant

Introduction

This repo is a Ruby on Rails application that demonstrates:

• Multiple workflow examples using the DocuSign SDK. See the Example Workflows list below.

• Authentication with DocuSign via the Authorization Code Grant flow. When the token expires, the user is asked to re-authenticate. The refresh token is not used in this example.

  The OmniAuth library is used for authentication. This example includes a DocuSign OAuth2 strategy for the OAuth package. The DocuSign strategy:

  • Uses the Authorization Code Grant flow to obtain an access token.
  • Calls the OAuth::getUser API method.
  • Processes the OAuth::getUser results to obtain the user's name, email, account id, account name, and base path.

  In this example, OmniAuth is called from session_controller.rb. OmniAuth is additionally configured and referenced in other files; search the project for "omni" for a complete list.

Example Workflows

This launcher includes code examples for the following workflows:

1. Embedded Signing Ceremony. Source. This example sends an envelope, and then uses an embedded signing ceremony for the first signer. With embedded signing, the DocuSign signing ceremony is initiated from your website.

2. Send an envelope with a remote (email) signer and cc recipient. Source. The envelope includes a pdf, Word, and HTML document. Anchor text (AutoPlace) is used to position the signing fields in the documents.

3. List envelopes in the user's account. Source. The envelopes' current status is included.

4. Get an envelope's basic information. Source. The example lists the basic information about an envelope, including its overall status.

5. List an envelope's recipients Source. Includes current recipient status.

6. List an envelope's documents. Source.

7. Download an envelope's documents. Source. The example can download individual documents, the documents concatenated together, or a zip file of the documents.

8. Programmatically create a template. Source.

9. Send an envelope using a template. Source.

10. Send an envelope and upload its documents with multpart binary transfer. Source. Binary transfer is 33% more efficient than using Base64 encoding.

11. Embedded sending. Source. Embeds the DocuSign web tool (NDSE) in your web app to finalize or update the envelope and documents before they are sent.

12. Embedded DocuSign web tool (NDSE). Source.

13. Embedded Signing Ceremony from a template with an added document. Source. This example sends an envelope based on a template. In addition to the template's document(s), the example adds an additional document to the envelope by using the Composite Templates feature.

14. Payments example: an order form, with online payment by credit card. Source.

15. Get the envelope tab data. Retrieve the tab (field) values for all of the envelope's recipients. Source.

16. Set envelope tab values. The example creates an envelope and sets the initial values for its tabs (fields). Some of the tabs are set to be read-only, others can be updated by the recipient. The example also stores metadata with the envelope. Source.

17. Set template tab values. The example creates an envelope using a template and sets the initial values for its tabs (fields). The example also stores metadata with the envelope. Source.

18. Get the envelope custom field data (metadata). The example retrieves the custom metadata (custom data fields) stored with the envelope. Source.

19. Requiring an Access Code for a Recipient Source. This example sends an envelope that requires an access-code for the purpose of multi-factor authentication.

20. Requiring SMS authentication for a recipient Source. This example sends an envelope that requires entering in a six digit code from an text message for the purpose of multi-factor authentication.

21. Requiring Phone authentication for a recipient Source. This example sends an envelope that requires entering in a voice-based response code for the purpose of multi-factor authentication.

22. Requiring Knowledge-Based Authentication (KBA) for a Recipient Source. This example sends an envelope that requires passing a Public records check to validate identity for the purpose of multi-factor authentication.

23. Requiring ID Verification (IDV) for a recipient Source. This example sends an envelope that requires the recipient to upload a government issued id.

Installation

Prerequisites

1. A DocuSign Developer Sandbox account (email and password) on demo.docusign.net. Create a free account.

2. A DocuSign Integration Key (a client ID) that is configured to use the OAuth Authorization Code flow. You will need the Integration Key itself, and its secret.

   The Integration key must include a Redirect URI of

   {base_url}/auth/docusign/callback

   Where {base_url} is the url for the web app.

   By default, the rails app starts on url http://localhost:3000

   So the default Redirect URI for your Integration Key is

   http://localhost:3000/auth/docusign/callback

3. Ruby version 2.5.3 or later. Or you can update the Gemfile to use other versions of Ruby.

4. A name and email for a signer, and a name and email for a cc recipient.

Installation steps

1. Download or clone this repository to your workstation to directory eg-03-ruby-auth-code-grant

2. cd eg-03-ruby-auth-code-grant

3. Install the needed gems listed in the Gemfile:

   Run bundler install

4. Update the file config/application.rb with the Integration Key and other settings. Note: The terms "client_id" and "Integration key" are synonyms. They refer to the same thing.

5. Update your Integration Key's settings to include a Redirect URI for your installation of the example. See Prerequisites item #2, above for more information.

Run the application

1. To start the development web server and application:

   Run rails s

2. Open a browser to the example's base url to view the index page.

Payments code example

To use the payments example, create a test payments gateway for your developer sandbox account.

See the PAYMENTS_INSTALLATION.md file for instructions.

Then add the payment gateway account id to the config/application.rb file.

Using the examples with other authentication flows

The examples in this repository can also be used with the JWT OAuth flow. See the Authentication guide for information on choosing the right authentication flow for your application.

License and additional information

License

This repository uses the MIT License. See the LICENSE file for more information.

Pull Requests

Pull requests are welcomed. Pull requests will only be considered if their content uses the MIT License.