Org idtoken validation guidance [SDK-2457] (#267)

* Org idtoken validation guidance

* Update README.md

* Update README.md

README.md

@@ -192,6 +192,7 @@ The method takes the following optional keyword parameters:
 | `max_age`     | Integer        | The `max_age` value you sent in the call to `/authorize`, if any.  | `nil`  |
 | `issuer`      | String         | By default the `iss` claim will be checked against the URL of your **Auth0 Domain**. Use this parameter to override that. | `nil`  |
 | `audience`    | String         | By default the `aud` claim will be compared to your **Auth0 Client ID**. Use this parameter to override that.  | `nil`  |
+| `organization`| String         | By default the `org_id` claim will be compared to your **Organization ID**. Use this parameter to override that.  | `nil`  |
 
 You can check the signing algorithm value under **Advanced Settings > OAuth > JsonWebToken Signature Algorithm** in your Auth0 application settings panel. [We recommend](https://auth0.com/docs/tokens/concepts/signing-algorithms#our-recommendation) that you make use of asymmetric signing algorithms like `RS256` instead of symmetric ones like `HS256`.
 
@@ -213,6 +214,29 @@ rescue Auth0::InvalidIdToken => e
 end
 ```
 
+### Organization ID Token Validation
+
+If an org_id claim is present in the Access Token, then the claim should be validated by the API to ensure that the value received is expected or known.
+
+In particular:
+
+* The issuer (iss) claim should be checked to ensure the token was issued by Auth0
+
+* the org_id claim should be checked to ensure it is a value that is already known to the application. This could be validated against a known list of organization IDs, or perhaps checked in conjunction with the current request URL. e.g. the sub-domain may hint at what organization should be used to validate the Access Token.
+
+Normally, validating the issuer would be enough to ensure that the token was issued by Auth0. In the case of organizations, additional checks should be made so that the organization within an Auth0 tenant is expected.
+
+If the claim cannot be validated, then the application should deem the token invalid.
+
+```ruby
+begin
+  @auth0_client.validate_id_token 'YOUR_ID_TOKEN', organization: '{Expected org_id}'
+rescue Auth0::InvalidIdToken => e
+  # In this case the ID Token contents should not be trusted
+end
+
+For more information, please read [Work with Tokens and Organizations](https://auth0.com/docs/organizations/using-tokens) on Auth0 Docs.
+
 ## Development
 
 In order to set up the local environment you'd have to have Ruby installed and a few global gems used to run and record the unit tests. A working Ruby version can be taken from the [CI script](/.circleci/config.yml). At the moment of this writting we're using Ruby `2.5.7`.