Improvements for Auth0 documentation. (#350)

Update for Auth0 integration with the OIDC flow using APIs

auth.rst

@@ -204,42 +204,25 @@ JWT from Auth0
 
 An external service like `Auth0 <https://auth0.com/>`_ can do the hard work transforming OAuth from Github, Twitter, Google etc into a JWT suitable for PostgREST. Auth0 can also handle email signup and password reset flows.
 
-To use Auth0, copy its client secret into your PostgREST configuration file as the :code:`jwt-secret`. (Old-style Auth0 secrets are Base64 encoded. For these secrets set :code:`secret-is-base64` to :code:`true`, or just refresh the Auth0 secret.) You can find the secret in the client settings of the Auth0 management console.
+To use Auth0, create `an application <https://auth0.com/docs/applications>`_ for your app and `an API <https://auth0.com/docs/authorization/apis>`_ for your PostgREST server. Auth0 supports both HS256 and RS256 scheme for the issued tokens for APIs. For simplicity, you may first try HS256 scheme while creating your API on Auth0. Your application should use your PostgREST API's `API identifier <https://auth0.com/docs/get-started/dashboard/api-settings>`_ by setting it with the `audience parameter <https://auth0.com/docs/tokens/access-tokens/get-access-tokens#control-access-token-audience>`_  during the authorization request. This will ensure that Auth0 will issue an access token for your PostgREST API. For PostgREST to verify the access token, you will need to set ``jwt-secret`` on PostgREST config file with your API's signing secret.
 
 .. note::
 
-  Make sure OIDC-conformant is toggled off.
-
-  A recent Auth0 change sets it on by default. Turn it `off` here:
-
-  Clients > `Your App` > Settings > Show Advanced Settings > OAuth > OIDC Conformant
-
-  Ensure also that your client application does not pass in any `audience` configuration.
-
-Our code requires a database role in the JWT. To add it you need to save the database role in Auth0 `app metadata <https://auth0.com/docs/rules/metadata-in-rules>`_. Then, you will need to write a rule that will extract the role from the user metadata and include a :code:`role` claim in the payload of our user object. Afterwards, in your Auth0Lock code, include the :code:`role` claim in your `scope param <https://auth0.com/docs/libraries/lock/v10/sending-authentication-parameters#scope-string->`_.
+Our code requires a database role in the JWT. To add it you need to save the database role in Auth0 `app metadata <https://auth0.com/docs/rules/metadata-in-rules>`_. Then, you will need to write `a rule <https://auth0.com/docs/rules>`_ that will extract the role from the user's app_metadata and set it as a `custom claim <https://auth0.com/docs/scopes/sample-use-cases-scopes-and-claims#add-custom-claims-to-a-token>`_ in the access token. Note that, you may use Auth0's `core authorization feature <https://auth0.com/docs/authorization/rbac>`_ for more complex use cases. Metadata solution is mentioned here for simplicity. 
 
 .. code:: javascript
 
-  // Example Auth0 rule
   function (user, context, callback) {
+
+    // Follow the documentations at http://postgrest.org/en/v7.0.0/configuration.html#role-claim-key
+    // to set a custom role claim on PostgREST and use it as custom claim attribute in this rule
+    const myRoleClaim = 'https://myapp.com/role'; 
+    
     user.app_metadata = user.app_metadata || {};
-    user.role = user.app_metadata.role;
+    context.accessToken[myRoleClaim] = user.app_metadata.role;
     callback(null, user, context);
   }
 
-
-.. code:: javascript
-
-  // Example using Auth0Lock with role claim in scope
-  new Auth0Lock ( AUTH0_CLIENTID, AUTH0_DOMAIN, {
-    container: 'lock-container',
-    auth: {
-      params: { scope: 'openid role' },
-      redirectUrl: FQDN + '/login', // Replace with your redirect url
-      responseType: 'token'
-    }
-  })
-
 .. _asym_keys:
 
 Asymmetric Keys