OAuth/userinfo CORS support
Good news: the oauth/userinfo API method now supports CORS! This new feature is available now in the developer system (demo) and will be available with the May release on the production platforms. The May release is scheduled for approximately May 10, 2021.
What’s CORS?
CORS, Cross-Origin Resource Sharing is a standard web protocol that enables a browser-based application to make API calls to a resource that is hosted by a server on a different domain.
For example, suppose your browser-based application is loaded from hr-app.example.com. When it wants to make an API call to api1.apis-are-us.net, the API call will be blocked by the browser, because the application’s origin of hr-app.example.com does not match the API’s origin of api1.apis-are-us.net. However, if the api1.apis-are-us.net server supports CORS, then the API call will succeed.
CORS only applies to browser-based applications. CORS is never needed when a server-based application calls an API service. CORS is also not needed when a mobile application or a downloaded application makes an API call.
What’s the new OAuth/userinfo CORS feature?
With the new CORS support, browser-based applications can now directly call the oauth/userinfo API to obtain the authenticated user’s name, email, account, and organization information.
After using the oauth/userinfo API, browser-based applications’ next step is to make API calls to the account-specific DocuSign platform (na2.docusign.net, eu.docusign.net, etc). Those systems do not yet support CORS. If your company would like DocuSign to implement CORS sooner, ask your DocuSign Sales or Customer Service contact to add your organization’s information to the internal ticket PORTFOLIO-1100.
Private CORS proxy server
Meanwhile, the workaround is a private CORS proxy server for your application. See this post, which discusses how to configure the Apache server to be a CORS proxy. In addition, I’ve written and tested a CORS proxy configuration file for the popular Nginx web server.
Do I need to enable CORS for my application?
No, the oauth/userinfo API method enables any browser-based application to make CORS requests to it. No setup, configuration, or other steps are required.
Do OAuth grant flows require CORS?
The standard OAuth Authorization Code and Implicit grant flows do not require CORS. They use the HTTP redirect protocol instead of requiring applications to make direct API requests to the Identity Provider (IdP) system. Redirects do not need CORS. Direct API requests from browser-based applications to cross-origin servers do require CORS.
Any code examples?
Yes, see the React blog posts for a code example that calls the oauth/UserInfo API method via CORS.
Summary
With the new CORS support for the oauth/userinfo API method, DocuSign has made an important step forward to enable browser-based applications, including Single Page Applications, to work with the DocuSign platform.
