Clean up jwt, id token, jwks, some guides, claims

Author: rkhoriander

articles/_includes/_api-auth-customize-tokens.md

@@ -15,5 +15,5 @@ function(user, context, callback) {
 ```
 
 ::: panel-warning Namespacing Custom Claims
-Auth0 returns profile information in a [structured claim format as defined by the OpenID Connect (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that in order to add custom claims to ID Tokens or Access Tokens, they must [conform to a namespaced format](/api-auth/tutorials/adoption/scope-custom-claims) to avoid possible collisions with standard OIDC claims. For example, if you choose the namespace `https://foo.com/` and you want to add a custom claim named `myclaim`, you would name the claim `https://foo.com/myclaim`, instead of `myclaim`. You can [add namespaced claims using Rules](#optional-customize-the-tokens).
+Auth0 returns profile information in a [structured claim format as defined by the OpenID Connect (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that in order to add custom claims to ID Tokens or Access Tokens, they must [conform to a namespaced format](/tokens/concepts/claims-namespacing) to avoid possible collisions with standard OIDC claims. You can [add namespaced claims using Rules](#optional-customize-the-tokens).
 :::

articles/_includes/_enforce-claim-namespacing.md

@@ -0,0 +1,5 @@
+::: warning
+By default, Auth0 always enforces namespacing; any custom claims with non-namespaced identifiers will be silently excluded from tokens.
+
+We do allow non-OIDC claims without a namespace for legacy tenants using a non-OIDC-conformant pipeline with the **Legacy User Profile** enabled, but we strongly recommend that legacy tenants migrate to an OIDC-conformant flow.
+:::

articles/_includes/_new_api.html

@@ -1,5 +1,5 @@
 <% if (account.userName) { %>
-  <p>In the APIs section in <a href="${manage_url}/#/">dashboard</a>, click the <strong>Create API</strong> button. Provide a <strong>Name</strong> and <strong>Identifier</strong> for your API. You must choose the RS256 signing algorithm. Once it is created, navigate to the <strong>Scopes</strong> tab and create the applicable scopes for your API.</p>
+  <p>In the APIs section in <a href="${manage_url}/#/">dashboard</a>, click the <strong>Create API</strong> button. Provide a <strong>Name</strong> and <strong>Identifier</strong> for your API. You must choose the RS256 <a href="/tokens/concepts/signing-algorithms">signing algorithm</a>. Once it is created, navigate to the <strong>Scopes</strong> tab and create the applicable scopes for your API.</p>
 <% } else { %>
-  <p>Create an <a href="${manage_url}/login">Auth0 account</a> (or login) navigate to the APIs section in <a href="${manage_url}/#/">Dashboard</a>. Click the <strong>Create API</strong> button and provide a <strong>Name</strong> and <strong>Identifier</strong> for your API. You must choose the RS256 signing algorithm. Once it is created, navigate to the <strong>Scopes</strong> tab and create the applicable scopes for your API.</p>
+  <p>Create an <a href="${manage_url}/login">Auth0 account</a> (or login) navigate to the APIs section in <a href="${manage_url}/#/">Dashboard</a>. Click the <strong>Create API</strong> button and provide a <strong>Name</strong> and <strong>Identifier</strong> for your API. You must choose the RS256 <a href="/tokens/concepts/signing-algorithms">signing algorithm</a>. Once it is created, navigate to the <strong>Scopes</strong> tab and create the applicable scopes for your API.</p>
 <% } %>

articles/api-auth/apis.md

@@ -47,7 +47,7 @@ You need to provide the following information for your API:
 
 - **Identifier**: a unique identifier for the API. Auth0 recommends using a URL. Auth0 does differentiate between URLs that include the last forward slash. For example, https://example.com and https://example.com/ are two different identifiers. The URL does not have to be a publicly available URL. Auth0 will not call your API. This value **cannot** be modified afterwards. 
 
-- **Signing Algorithm**: the algorithm to sign the tokens with. The available values are `HS256` and `RS256`. When selecting `RS256` the token will be signed with the tenant's private key. For more details on the signing algorithms go to the [Signing Algorithms paragraph](#signing-algorithms).
+- **Signing Algorithm**: the algorithm to sign the tokens with. The available values are `HS256` and `RS256`. When selecting `RS256` the token will be signed with the tenant's private key. To learn more about signing algorithms, see [Signing Algorithms paragraph](/tokens/concepts/signing-algorithms).
 
 Fill in the required information and click the **Create** button.
 
@@ -82,41 +82,7 @@ Click on the *Settings* tab of your [API](${manage_url}/#/apis) to review the av
 
 - **Allow Offline Access**: If this setting is enabled, Auth0 will allow applications to ask for Refresh Tokens for this API.
 
-- **Signing Algorithm**: The algorithm to sign the tokens with. The available values are `HS256` and `RS256`. When selecting `RS256` (recommended) the token will be signed with the tenant's private key. This value is set upon API creation and cannot be modified afterwards. For more details on the signing algorithms see the [Signing Algorithms paragraph](#signing-algorithms) below.
-
-### Signing Algorithms
-
-When you create an API you have to select the algorithm your tokens will be signed with. The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.
-
-::: note
-The signature is part of a JWT. If you are not familiar with the JWT structure, please see [JSON Web Tokens (JWTs) in Auth0](/jwt#what-is-the-json-web-token-structure-).
-:::
-
-To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that. That algorithm, which is part of the JWT header, is the one you select for your API: `HS256` or `RS256`.
-
-- **RS256** is an [asymmetric algorithm](https://en.wikipedia.org/wiki/Public-key_cryptography) which means that there are two keys: one public and one private (secret). Auth0 has the secret key, which is used to generate the signature, and the consumer of the JWT has the public key, which is used to validate the signature.
-
-- **HS256** is a [symmetric algorithm](https://en.wikipedia.org/wiki/Symmetric-key_algorithm) which means that there is only one secret key, shared between the two parties. The same key is used both to generate the signature and to validate it. Special care should be taken in order for the key to remain confidential.
-
-The most secure practice, and our recommendation, is to use **RS256**. Some of the reasons are:
-
-- With RS256 you are sure that only the holder of the private key (Auth0) can sign tokens, while anyone can check if the token is valid using the public key.
-
-- Under HS256, if the secret key is compromised (e.g. by the application) you would have to re-deploy the API with the new secret.
-
-- With RS256 you can request a token that is valid for multiple <dfn data-key="audience">audiences</dfn>.
-
-- With RS256 you can implement key rotation without having to re-deploy the API with the new secret.
-
-::: panel Verify an RS256 signed token
-Go to [Dashboard > Applications](${manage_url}/#/applications). Open the **Settings** of your applications, scroll down and open **Advanced Settings**. Open the **Certificates** tab and you will find the Public Key in the **Signing Certificate** field.
-
-If you want to use the Public Key to verify a JWT signature on [JWT.io](https://jwt.io/), you can copy the Public Key and paste it in the **Public Key or Certificate** field under the **Verify Signature** section on the [JWT.io](https://jwt.io/) website.
-
-If you want to verify the signature of a token from one of your applications, we recommend that you get the Public Key from your tenant's [JSON Web Key Set (JWKS)](/jwks). Your tenant's JWKS is `https://${account.namespace}/.well-known/jwks.json`.
-:::
-
-For a more detailed overview of the JWT signing algorithms, see [JSON Web Token (JWT) Signing Algorithms Overview](https://auth0.com/blog/json-web-token-signing-algorithms-overview/).
+- **Signing Algorithm**: The algorithm to sign the tokens with. The available values are `HS256` and `RS256`. When selecting `RS256` (recommended) the token will be signed with the tenant's private key. This value is set upon API creation and cannot be modified afterwards. To learn more about signing algorithms, see [Signing Algorithms](/tokens/concepts/signing-algorithms).
 
 ## Keep Reading
 

articles/api-auth/index.md

@@ -146,7 +146,7 @@ In this page you can find a list of resources that can help you secure your APIs
     </p>
   </li>
   <li>
-    <i class="icon icon-budicon-715"></i><a href="/api-auth/tutorials/verify-access-token">Verify Access Tokens</a>
+    <i class="icon icon-budicon-715"></i><a href="/tokens/guides/access-token/validate-access-token">Validate an Access Token</a>
     <p>
       Learn what an API has to do in order to verify a Bearer Access Token.
     </p>

articles/api-auth/intro.md

@@ -74,7 +74,7 @@ For more information, refer to [Calling your APIs with Auth0 tokens](/api-auth/t
 
 Historically, you were able to define and request arbitrary application-specific claims. From now on, your application can request any of the [standard OpenID Connect (OIDC) scopes](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims), as [defined by the OIDC Specification](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims), or any <dfn data-key="scope">scopes</dfn> supported by your [API](/apis).
 
-In order to add custom claims to ID Tokens or Access Tokens, they must [conform to a namespaced format](/api-auth/tutorials/adoption/scope-custom-claims) to avoid possible collisions with standard OIDC claims.
+In order to add custom claims to ID Tokens or Access Tokens, they must [conform to a namespaced format](/tokens/concepts/claims-namespacing) to avoid possible collisions with standard OIDC claims.
 
 To customize the tokens, use Hooks for the Client Credentials Flow, and Rules for the rest of the flows:
 - __Client Credentials Flow__: [Customize Tokens using Hooks](/flows/guides/client-credentials/call-api-client-credentials#customize-tokens)
@@ -251,7 +251,7 @@ To use the `audience` parameter instead, configure your app to send it when init
     <tr>
       <th><strong>Add arbitrary claims in Tokens</strong></th>
       <td>Supported</td>
-      <td>Supported. The namespaced format has to be used.</td>
+      <td>Supported. The <a href="/tokens/concepts/claims-namespacing">namespaced format</a> has to be used.</td>
     </tr>
     <tr>
       <th><strong>SSO</strong></th>

articles/api-auth/tutorials/adoption/api-tokens.md

@@ -83,7 +83,7 @@ The Access Token is meant to **authorize** the user to the **API (resource serve
 
 The token does not contain any information about the user except for the user ID (located in the **sub** claim). The token only contains authorization information about the actions that application is allowed to perform at the API (such permissions are referred to as **scopes**).
 
-In many cases, you may find it useful to retrieve additional user information. You can do this by calling the [/userinfo API endpoint](/api/authentication#get-user-info) with the Access Token. Be sure that the API for which the Access Token is issued uses the **RS256** signing algorithm.
+In many cases, you may find it useful to retrieve additional user information. You can do this by calling the [/userinfo API endpoint](/api/authentication#get-user-info) with the Access Token. Be sure that the API for which the Access Token is issued uses the **RS256** [signing algorithm](/tokens/concepts/signing-algorithms).
 
 ## Scopes
 

articles/api-auth/tutorials/adoption/authorization-code.md

@@ -147,7 +147,7 @@ Pragma: no-cache
     "id_token": "eyJ..."
 }</code></pre>
         <ul>
-            <li>The returned Access Token is valid for optionally calling the API specified in the <code>audience</code> parameter and the <a href="/api/authentication#get-user-info">/userinfo endpoint</a> (provided that the API uses <code>RS256</code> as the signing algorithm and <code>openid</code> is used as a <code>scope</code> parameter). If you are not implementing your own Resource Server (API), then you can use <code>https://{$account.namespace}/userinfo</code> as the <code>audience</code> parameter, which will return an opaque Access Token.</li>
+            <li>The returned Access Token is valid for optionally calling the API specified in the <code>audience</code> parameter and the <a href="/api/authentication#get-user-info">/userinfo endpoint</a> (provided that the API uses <code>RS256</code> as the <a href="/tokens/concepts/signing-algorithms">signing algorithm</a> and <code>openid</code> is used as a <code>scope</code> parameter). If you are not implementing your own Resource Server (API), then you can use <code>https://{$account.namespace}/userinfo</code> as the <code>audience</code> parameter, which will return an opaque Access Token.</li>
             <li>A Refresh Token will be returned only if the <code>offline_access</code> scope was granted.</li>
         </ul>
     </div>
@@ -188,7 +188,7 @@ Pragma: no-cache
     "https://app.example.com/favorite_color": "blue"
 }</code></pre>
         <ul>
-            <li>The <code>favorite_color</code> claim must be namespaced and added through a rule.</li>
+            <li>The <code>favorite_color</code> claim must be <a href="/tokens/concepts/claims-namespacing">namespaced</a> and added through a rule.</li>
         </ul>
     </div>
   </div>
@@ -224,7 +224,7 @@ Pragma: no-cache
     "scope": "openid email"
 }</code></pre>
         <ul>
-            <li>The returned Access Token is valid for optionally calling the API specified in the <code>audience</code> parameter and the <a href="/api/authentication#get-user-info">/userinfo endpoint</a> (provided that the API uses <code>RS256</code> as the signing algorithm and <code>openid</code> is used as a <code>scope</code> parameter). If you are not implementing your own Resource Server (API), then you can use <code>https://{$account.namespace}/userinfo</code> as the <code>audience</code> parameter, which will return an opaque Access Token.</li>
+            <li>The returned Access Token is valid for optionally calling the API specified in the <code>audience</code> parameter and the <a href="/api/authentication#get-user-info">/userinfo endpoint</a> (provided that the API uses <code>RS256</code> as the <a href="/tokens/concepts/signing-algorithms">signing algorithm</a> and <code>openid</code> is used as a <code>scope</code> parameter). If you are not implementing your own Resource Server (API), then you can use <code>https://{$account.namespace}/userinfo</code> as the <code>audience</code> parameter, which will return an opaque Access Token.</li>
         </ul>
     </div>
   </div>

articles/api-auth/tutorials/adoption/implicit.md

@@ -92,7 +92,7 @@ Location: https://app.example.com/#
     &id_token=eyJ...
     &token_type=Bearer</code></pre>
     <ul>
-        <li>The returned Access Token is valid for calling the <a href="/api/authentication#get-user-info">/userinfo endpoint</a> (provided that the API specified by the <code>audience</code> param uses <code>RS256</code> as signing algorithm) and optionally the resource server specified by the <code>audience</code> parameter.</li>
+        <li>The returned Access Token is valid for calling the <a href="/api/authentication#get-user-info">/userinfo endpoint</a> (provided that the API specified by the <code>audience</code> param uses <code>RS256</code> as <a href="/tokens/concepts/signing-algorithms">signing algorithm</a>) and optionally the resource server specified by the <code>audience</code> parameter.</li>
         <li>If using <code>response_type=id_token</code>, Auth0 will only return an ID Token.</li>
         <li>Refresh Tokens are not allowed in the implicit grant. <a href="/api-auth/tutorials/silent-authentication">Use <code>prompt=none</code> instead</a>.</li>
     </ul>
@@ -136,7 +136,7 @@ Location: https://app.example.com/#
     "nonce": "jxdlsjfi0fa"
 }</code></pre>
         <ul>
-            <li>The <code>favorite_color</code> claim must be namespaced and added through a rule.</li>
+            <li>The <code>favorite_color</code> claim must be <a href="/tokens/concepts/claims-namespacing">namespaced</a> and added through a rule.</li>
             <li>After validating the ID Token, the application must <a href="/api-auth/tutorials/nonce">validate the nonce to mitigate replay attacks</a>.</li>
         </ul>
     </div>
@@ -173,7 +173,7 @@ Location: https://app.example.com/#
     "scope": "openid email"
 }</code></pre>
         <ul>
-            <li>The returned Access Token is a JWT valid for calling the <a href="/api/authentication#get-user-info">/userinfo endpoint</a>(provided that the API specified by the <code>audience</code> param uses <code>RS256</code> as signing algorithm) as well as the resource server specified by the <code>audience</code> parameter.</li>
+            <li>The returned Access Token is a JWT valid for calling the <a href="/api/authentication#get-user-info">/userinfo endpoint</a>(provided that the API specified by the <code>audience</code> param uses <code>RS256</code> as <a href="/tokens/concepts/signing-algorithms">signing algorithm</a>) as well as the resource server specified by the <code>audience</code> parameter.</li>
             <li>Note that an opaque Access Token could still be returned if /userinfo is the only specified audience.</li>
         </ul>
     </div>

articles/api-auth/tutorials/adoption/oidc-conformant.md

@@ -37,7 +37,7 @@ Enabling this flag on an application will have the following effects:
 * The [/oauth/access_token endpoint](/api/authentication#post-oauth-access_token), used for social authentication from native mobile applications, is disabled.
   An OIDC-conformant alternative will be added in future releases.
 * The [`scope` parameter of authentication requests](/api-auth/tutorials/adoption/scope-custom-claims) will comply to the OIDC specification:
-    - Custom claims must be namespaced and added to ID Tokens or Access Tokens via rules.
+    - Custom claims must be [namespaced](/tokens/concepts/claims-namespacing) and added to ID Tokens or Access Tokens via rules.
     - The namespace identifiers for custom claims must be **HTTP** or **HTTPS** URIs.
     - Custom <dfn data-key="scope">scope</dfn> values can be defined by a [resource server (API)](/api-auth/tutorials/adoption/api-tokens).
 * OIDC-conformant applications cannot be the source or target application of a [delegation request](/api-auth/tutorials/adoption/delegation).