fix(OAuth2 options): added locale and state parameters for browser ba…

…sed OAuth2

AFFECTS PACKAGES:
@esri/arcgis-rest-auth

use clientId for state by default

.gitignore

@@ -80,4 +80,6 @@ packages/*/debug/
 /packages/*/.rpt2_cache
 
 # packages in development
-packages/arcgis-rest-portal/
+packages/arcgis-rest-portal/
+
+test.html

demos/oauth2-browser/authenticate.html

@@ -10,13 +10,14 @@
     <script src="node_modules/@esri/arcgis-rest-request/dist/umd/arcgis-rest-request.umd.js"></script>
     <script src="node_modules/@esri/arcgis-rest-auth/dist/umd/arcgis-rest-auth.umd.js"></script>
     <script>
-      // in a production app, clientID would be hardcoded. we're uusing a regex so that developers can pass one in at runtime.
+      // in a production app, clientID would be hardcoded. we're using a regex so that developers can pass one in at runtime.
+      debugger;
       const match = window.location.href.match(
-        /clientID=(.+)#/
+        /&state=(.+)/
       );
       const clientId = match[1];
       let session;
-      function processAuthentication() {        
+      function processAuthentication() {
         window.location.href = '/';
         session = arcgisRest.UserSession.completeOAuth2({
           clientId,

demos/oauth2-browser/config.js.template

@@ -3,4 +3,4 @@ You can generate your own clientid by creating an application on the ArcGIS for
 
 once you have a clientid of your own, copy/paste it here and rename this file 'config.js'
 */
-const clientId = "abc123"
+let clientId = "abc123"

demos/oauth2-browser/index.html

@@ -114,7 +114,7 @@ <h2>
 
       // Function to check that a client id is present.
       function requireClientId() {
-        // Pull out the client id. 
+        // Pull out the client id.
         if (document.getElementById('clientId').value !== "") {
           clientId = document.getElementById('clientId').value
         }
@@ -160,8 +160,8 @@ <h2>
           // Begin an OAuth2 login using a popup.
           arcgisRest.UserSession.beginOAuth2({
             clientId,
-            redirectUri: `${redirect_uri}authenticate.html?clientID=${clientId}`,
-            popup: true,
+            redirectUri: `${redirect_uri}authenticate.html`,
+            popup: true
           }).then((newSession) => {
             // Upon a successful login, update the session with the new session.
             session = newSession;

packages/arcgis-rest-auth/src/UserSession.ts

@@ -65,7 +65,7 @@ export interface IOauth2Options {
   duration?: number;
 
   /**
-   * Determines wether to open the authorization window in a new tab/window or in the current window.
+   * Determines whether to open the authorization window in a new tab/window or in the current window.
    *
    * @browserOnly
    */
@@ -77,6 +77,20 @@ export interface IOauth2Options {
    * @nodeOnly
    */
   refreshTokenTTL?: number;
+
+  /**
+   * The locale assumed to render the login page.
+   *
+   * @browserOnly
+   */
+  locale?: string;
+
+  /**
+   * Applications can specify an opaque value for this parameter to correlate the authorization request sent with the received response. By default, clientId is used.
+   *
+   * @browserOnly
+   */
+  state?: string;
 }
 
 /**
@@ -140,6 +154,16 @@ export interface IUserSessionOptions {
    * Duration (in minutes) that a refresh token will be valid.
    */
   refreshTokenTTL?: number;
+
+  /**
+   * The locale assumed to render the login page.
+   */
+  locale?: string;
+
+  /**
+   * Applications can specify an opaque value for this parameter to correlate the authorization request sent with the received response. By default, clientId is used.
+   */
+  state?: string;
 }
 
 /**
@@ -263,18 +287,28 @@ export class UserSession implements IAuthenticationManager {
     options: IOauth2Options,
     /* istanbul ignore next */ win: any = window
   ) {
-    const { portal, clientId, duration, redirectUri, popup }: IOauth2Options = {
+    const {
+      portal,
+      clientId,
+      duration,
+      redirectUri,
+      popup,
+      state,
+      locale
+    }: IOauth2Options = {
       ...{
         portal: "https://arcgis.com/sharing/rest",
         duration: 20160,
-        popup: true
+        popup: true,
+        state: options.clientId,
+        locale: ""
       },
       ...options
     };
 
     const url = `${portal}/oauth2/authorize?client_id=${clientId}&response_type=token&expiration=${duration}&redirect_uri=${encodeURIComponent(
       redirectUri
-    )}`;
+    )}&state=${state}&locale=${locale}`;
 
     if (!popup) {
       win.location.href = url;

packages/arcgis-rest-auth/test/UserSession.test.ts

@@ -406,8 +406,9 @@ describe("UserSession", () => {
 
       UserSession.beginOAuth2(
         {
-          clientId: "clientId",
-          redirectUri: "http://example-app.com/redirect"
+          clientId: "clientId123",
+          redirectUri: "http://example-app.com/redirect",
+          state: "abc123"
         },
         MockWindow
       )
@@ -422,12 +423,12 @@ describe("UserSession", () => {
         });
 
       expect(MockWindow.open).toHaveBeenCalledWith(
-        "https://arcgis.com/sharing/rest/oauth2/authorize?client_id=clientId&response_type=token&expiration=20160&redirect_uri=http%3A%2F%2Fexample-app.com%2Fredirect",
+        "https://arcgis.com/sharing/rest/oauth2/authorize?client_id=clientId123&response_type=token&expiration=20160&redirect_uri=http%3A%2F%2Fexample-app.com%2Fredirect&state=abc123&locale=",
         "oauth-window",
         "height=400,width=600,menubar=no,location=yes,resizable=yes,scrollbars=yes,status=yes"
       );
 
-      MockWindow.__ESRI_REST_AUTH_HANDLER_clientId(null, {
+      MockWindow.__ESRI_REST_AUTH_HANDLER_clientId123(null, {
         token: "token",
         expires: TOMORROW,
         username: "c@sey"
@@ -441,21 +442,22 @@ describe("UserSession", () => {
 
       UserSession.beginOAuth2(
         {
-          clientId: "clientId",
-          redirectUri: "http://example-app.com/redirect"
+          clientId: "clientId123",
+          redirectUri: "http://example-app.com/redirect",
+          locale: "fr"
         },
         MockWindow
       ).catch(e => {
         done();
       });
 
       expect(MockWindow.open).toHaveBeenCalledWith(
-        "https://arcgis.com/sharing/rest/oauth2/authorize?client_id=clientId&response_type=token&expiration=20160&redirect_uri=http%3A%2F%2Fexample-app.com%2Fredirect",
+        "https://arcgis.com/sharing/rest/oauth2/authorize?client_id=clientId123&response_type=token&expiration=20160&redirect_uri=http%3A%2F%2Fexample-app.com%2Fredirect&state=clientId123&locale=fr",
         "oauth-window",
         "height=400,width=600,menubar=no,location=yes,resizable=yes,scrollbars=yes,status=yes"
       );
 
-      MockWindow.__ESRI_REST_AUTH_HANDLER_clientId(
+      MockWindow.__ESRI_REST_AUTH_HANDLER_clientId123(
         new ArcGISRequestError("unable to sign in", "SIGN_IN_FAILED")
       );
     });
@@ -470,15 +472,15 @@ describe("UserSession", () => {
       // https://github.com/palantir/tslint/issues/3056
       void UserSession.beginOAuth2(
         {
-          clientId: "clientId",
+          clientId: "clientId123",
           redirectUri: "http://example-app.com/redirect",
           popup: false
         },
         MockWindow
       );
 
       expect(MockWindow.location.href).toBe(
-        "https://arcgis.com/sharing/rest/oauth2/authorize?client_id=clientId&response_type=token&expiration=20160&redirect_uri=http%3A%2F%2Fexample-app.com%2Fredirect"
+        "https://arcgis.com/sharing/rest/oauth2/authorize?client_id=clientId123&response_type=token&expiration=20160&redirect_uri=http%3A%2F%2Fexample-app.com%2Fredirect&state=clientId123&locale="
       );
     });
   });