<commit_before># Tokens

## Token Overview

This document is designed to clarify and disambiguate the numerous types of tokens referenced in Auth0 documentation, what each is used for and how to use it.  

First there are a couple different categories of tokens 

* JSON Web Tokens (JWT) - These are tokens that conform to the JSON Web Token standard and contain information about an identity.  They are self-contained in that it is not necessary for the recipient to call a server to validate the token.
* Opaque tokens - Opaque tokens are tokens in a proprietary format that typically contain some identifier to information in a server’s persistent storage.  To validate an opaque token, the recipient of the token needs to call the server that issued the token.

There are six primary tokens used in Auth0's token based authentication scenarios and referenced in Auth0 documentation.

* The Auth0 id_token
* The Auth0 access_token (Auth0 APIv1 token)
* Identity Provider access tokens from other providers
* The Auth0 refresh token
* A Delegation token 
* The Auth0 APIv2 Token 


(Editing question: In the logs file, (authN via SAML connection) there is an entry for “exchange” and it says exchange of “authorization code for access token” - Is the “authorization code” that is referenced there yet another “token” that should be documented here?)

### id_token (JWT)

The Auth0 `id_token` is a token in JSON Web Token (JWT) format, which provides a mechanism for transferring claims about a user from Identity Providers, who are authoritative sources of such information, to other relying parties, such as websites or web services, also known as service providers, who need such information.  The claims included in a JWT can be basic profile attributes such as a name or email address as well as security information such as a group membership or the support plan a user is entitled to use.

### Auth0 access token
The Auth0 access token is a random, opaque string and was used to call portions of the Auth0 Management API ( APIv1) and the /userinfo endpoint within the Auth0 Authentication API.  

### Identity Provider access tokens 
When a user authenticates via Auth0 with another social provider's authentication service, such as Facebook or LinkedIn, the social provider will return an access token that can be used by the client program to call that social provider's API.

### Refresh tokens
The Refresh token is a long-lived token that is used to obtain a new id_token after a previous one has expired.  This is useful for applications running on mobile devices that call remote APIs and do not want to require the user to log in everytime the user uses the mobile app.  

### Delegation tokens
The Auth0 `id_token` can be exchanged for another token, called a Delegation token, that can be used to call either other application APIs registered as clients in the same Auth0 tenant or APIs represented by some types of application Addons registered in the same Auth0 tenant.  

### Auth0 APIv2 token
The Auth0 APIv2 token is used to call v2 of the Auth0 Management API.  This allows a specific tenant in Auth0 to call Auth0 APIv2.  This APIv2 token is a JWT, and contains various scopes, such as “read users” or “update clients”, and is signed with a client API key and secret for the entire tenant. 

The following sections will discuss each token in greater detail and provide information on how to use each.

##`id_token`

The `id_token` is referred to by several names, including `id_token`, the JSON Web Token or abbreviated as the JWT.  It conforms to an industry standard (IETF RFC 7519) and contains three parts: A header, a body and a signature. The header contains the type of token and the hash algorithm used on the contents of the token.  The body, also called the payload, contains identity claims about a user.  There are some non-mandatory claims with registered names, for things like the issuer of the token, the subject of the token (who the claims are about), and the time of issuance.  Any number of additional claims with other names can be added, though care must be taken to keep the JWT within the browser size limitations for URLs.  The third part of the JWT is the signature which is used by the recipient of a JWT to validate the integrity of the information conveyed in the JWT.

### How to get the `id_token`
The `id_token` is returned when calling any of the Auth0 functions which invoke authentication.  This includes calls to the Lock widget, to the auth0.js library, or the libraries for other languages.  In our code samples for Lock and auth0.js for example, there is a variable called `id_token` in the callback function passed to Lock and auth0.js which receives the `id_token`.

Lock libraries:
https://auth0.com/docs/libraries/lock
https://auth0.com/docs/libraries/lock-ios
https://auth0.com/docs/libraries/lock-android

Auth0.js
https://auth0.com/docs/libraries/auth0js
https://github.com/auth0/auth0.js

Tutorials showing libraries for other languages
https://auth0.com/docs/tutorials

###How to control contents of `id_token`
The contents of the `id_token`, specifically the claims contained within it, are controlled by the use of a parameter called `scope` which is passed to the authentication functions mentioned above.  For example, the call to the Lock widget’s `.show` function can specify optional authentication parameters as follows:

```
lock.show({
   responseType: ‘token’,
   authParams: {
      scope: ‘openid name email’
    }
 });
```
The above sample, specifying `openid name email` will result in a JWT with claims for the name and email attributes within the user profile.  The responseType should be `token` for client-side authentication flows and `code` for server-side authentication flows as described for the /authorize endpoint here:
https://auth0.com/docs/auth-api

Additional information on the `id_token` is at:
https://auth0.com/docs/jwt

A valid JWT can be pasted into the following website to view the contents of the JWT.
https://jwt.io

A blog entry on JWT - with an explanation of why it is getting to be more popular
https://auth0.com/blog/2015/07/21/jwt-json-webtoken-logo/

Additional samples using the auth0.js library are at:
https://github.com/auth0/auth0.js


###Validity
The `id_token` is valid for 10 hours (36000 seconds) by default.  The expiration of this token can be set in the `Apps/APIs` -> Settings screen using the `JWT expiration` field.

###Renewing the token

A new `id_token` can be obtained using an existing, unexpired `id_token` or by using a refresh token and the `/delegation` endpoint.  

To use an existing, unexpired `id_token` to obtain a new one, use the `renewIdToken` function within auth0.js library as shown at:
https://github.com/auth0/auth0.js#refresh-token

To get a new `id_token` when the existing `id_token` has expired, use a refresh token to get a new `id token`, as explained in the Refresh Token section below and also at:
https://auth0.com/docs/refresh-token

The auth0.js library can also be used to refresh an `id token` as shown at:
https://github.com/auth0/auth0.js#refresh-token

###Termination of tokens
Once issued, tokens can not be revoked in the same fashion as cookies with session id’s for server-side sessions.  As a result, tokens should be issued for relatively short periods, and then renewed periodically if the user remains active.  See the above section on renewing id tokens.


###Uses
The `id_token` is designed to be used to pass information about a user between websites,  web programs and APIs in an industry standard, URL-friendly fashion.  One advantage of using an `id_token` for this purpose is that the recipient can validate the token without having to make a call back to the issuer of the token.  The token is also designed to enable being passed from one web property to another, via an untrusted client, such that the client cannot alter the token without such tampering being evident to the recipient.

The `id_token` can be used to call the /tokeninfo endpoint within the Auth0 authentication API to retrieve the user’s complete profile.
https://auth0.com/docs/auth-api#user-profile

The `id_token` can also be used to call the /delegation endpoint within the Auth0 authentication API to obtain another token for another API.<commit_msg>Update tokens.md<commit_after># Tokens

## Token Overview

This document is designed to clarify and disambiguate the numerous types of tokens referenced in Auth0 documentation, what each is used for and how to use it.  

First there are a couple different categories of tokens 

* JSON Web Tokens (JWT) - These are tokens that conform to the JSON Web Token standard and contain information about an identity.  They are self-contained in that it is not necessary for the recipient to call a server to validate the token.
* Opaque tokens - Opaque tokens are tokens in a proprietary format that typically contain some identifier to information in a server’s persistent storage.  To validate an opaque token, the recipient of the token needs to call the server that issued the token.

There are six primary tokens used in Auth0's token based authentication scenarios and referenced in Auth0 documentation.

* The Auth0 id_token
* The Auth0 access_token (Auth0 APIv1 token)
* Identity Provider access tokens from other providers
* The Auth0 refresh token
* A Delegation token 
* The Auth0 APIv2 Token 


(Editing question: In the logs file, (authN via SAML connection) there is an entry for “exchange” and it says exchange of “authorization code for access token” - Is the “authorization code” that is referenced there yet another “token” that should be documented here?)

### id_token (JWT)

The Auth0 `id_token` is a token in JSON Web Token (JWT) format, which provides a mechanism for transferring claims about a user from Identity Providers, who are authoritative sources of such information, to other relying parties, such as websites or web services, also known as service providers, who need such information.  The claims included in a JWT can be basic profile attributes such as a name or email address as well as security information such as a group membership or the support plan a user is entitled to use.

### Auth0 access token
The Auth0 access token is a random, opaque string and was used to call portions of the Auth0 Management API ( APIv1) and the /userinfo endpoint within the Auth0 Authentication API.  

### Identity Provider access tokens 
When a user authenticates via Auth0 with another social provider's authentication service, such as Facebook or LinkedIn, the social provider will return an access token that can be used by the client program to call that social provider's API.

### Refresh tokens
The Refresh token is a long-lived token that is used to obtain a new id_token after a previous one has expired.  This is useful for applications running on mobile devices that call remote APIs and do not want to require the user to log in everytime the user uses the mobile app.  

### Delegation tokens
The Auth0 `id_token` can be exchanged for another token, called a Delegation token, that can be used to call either other application APIs registered as clients in the same Auth0 tenant or APIs represented by some types of application Addons registered in the same Auth0 tenant.  

### Auth0 APIv2 token
The Auth0 APIv2 token is used to call v2 of the Auth0 Management API.  This allows a specific tenant in Auth0 to call Auth0 APIv2.  This APIv2 token is a JWT, and contains various scopes, such as “read users” or “update clients”, and is signed with a client API key and secret for the entire tenant. 

The following sections will discuss each token in greater detail and provide information on how to use each.

##`id_token`

The `id_token` is referred to by several names, including `id_token`, the JSON Web Token or abbreviated as the JWT.  It conforms to an industry standard (IETF RFC 7519) and contains three parts: A header, a body and a signature. The header contains the type of token and the hash algorithm used on the contents of the token.  The body, also called the payload, contains identity claims about a user.  There are some non-mandatory claims with registered names, for things like the issuer of the token, the subject of the token (who the claims are about), and the time of issuance.  Any number of additional claims with other names can be added, though care must be taken to keep the JWT within the browser size limitations for URLs.  The third part of the JWT is the signature which is used by the recipient of a JWT to validate the integrity of the information conveyed in the JWT.

### How to get the `id_token`
The `id_token` is returned when calling any of the Auth0 functions which invoke authentication.  This includes calls to the Lock widget, to the auth0.js library, or the libraries for other languages.  In our code samples for Lock and auth0.js for example, there is a variable called `id_token` in the callback function passed to Lock and auth0.js which receives the `id_token`.

Lock libraries:
https://auth0.com/docs/libraries/lock
https://auth0.com/docs/libraries/lock-ios
https://auth0.com/docs/libraries/lock-android

Auth0.js
https://auth0.com/docs/libraries/auth0js
https://github.com/auth0/auth0.js

Tutorials showing libraries for other languages
https://auth0.com/docs/tutorials

###How to control contents of `id_token`
The contents of the `id_token`, specifically the claims contained within it, are controlled by the use of a parameter called `scope` which is passed to the authentication functions mentioned above.  For example, the call to the Lock widget’s `.show` function can specify optional authentication parameters as follows:

```
lock.show({
   responseType: ‘token’,
   authParams: {
      scope: ‘openid name email’
    }
 });
```
The above sample, specifying `openid name email` will result in a JWT with claims for the name and email attributes within the user profile.  The responseType should be `token` for client-side authentication flows and `code` for server-side authentication flows as described for the /authorize endpoint here:
https://auth0.com/docs/auth-api

The scope of the id_token JWT can also be altered via Rules, through the context.jwtConfiguration.scopes object as documented at:
https://github.com/auth0/docs/blob/32033877180affa26233b8f65cb28bd532514eab/articles/rules/index.md#context

There is also a sample for altering scopes in a Rule at:
https://github.com/auth0/rules/blob/dff2a3e72f01d33af3086414be7cf115b19eea0c/rules/custom-scopes.md

Additional information on the `id_token` is at:
https://auth0.com/docs/jwt

A valid JWT can be pasted into the following website to view the contents of the JWT.
https://jwt.io

A blog entry on JWT - with an explanation of why it is getting to be more popular
https://auth0.com/blog/2015/07/21/jwt-json-webtoken-logo/

Additional samples using the auth0.js library are at:
https://github.com/auth0/auth0.js


###Validity
The `id_token` is valid for 10 hours (36000 seconds) by default.  The expiration of this token can be set in the `Apps/APIs` -> Settings screen using the `JWT expiration` field.

The validity period of the token can be altered via Auth0 Rules using the context.jwtConfiguration.lifetimeInSeconds object as documented at:
https://github.com/auth0/docs/blob/32033877180affa26233b8f65cb28bd532514eab/articles/rules/index.md#context

For example, the following code in a Rule would set the id_token JWT expiration to 1 hour.
```
context.jwtConfiguration.lifetimeInSeconds = 3600;
```

###Renewing the token

A new `id_token` can be obtained using an existing, unexpired `id_token` or by using a refresh token and the `/delegation` endpoint.  

To use an existing, unexpired `id_token` to obtain a new one, use the `renewIdToken` function within auth0.js library as shown at:
https://github.com/auth0/auth0.js#refresh-token

To get a new `id_token` when the existing `id_token` has expired, use a refresh token to get a new `id token`, as explained in the Refresh Token section below and also at:
https://auth0.com/docs/refresh-token

The auth0.js library can also be used to refresh an `id token` as shown at:
https://github.com/auth0/auth0.js#refresh-token

###Termination of tokens
Once issued, tokens can not be revoked in the same fashion as cookies with session id’s for server-side sessions.  As a result, tokens should be issued for relatively short periods, and then renewed periodically if the user remains active.  See the above section on renewing id tokens.


###Uses
The `id_token` is designed to be used to pass information about a user between websites,  web programs and APIs in an industry standard, URL-friendly fashion.  One advantage of using an `id_token` for this purpose is that the recipient can validate the token without having to make a call back to the issuer of the token.  The token is also designed to enable being passed from one web property to another, via an untrusted client, such that the client cannot alter the token without such tampering being evident to the recipient.

The `id_token` can be used to call the /tokeninfo endpoint within the Auth0 authentication API to retrieve the user’s complete profile.
https://auth0.com/docs/auth-api#user-profile

The `id_token` can also be used to call the /delegation endpoint within the Auth0 authentication API to obtain another token for another API.
{'fraction_non_alphanumeric': 0.0512393848978655, 'fraction_numerical': 0.013828322240073444, 'mean_word_length': 4.422837585563161, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 33, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2925388', 'n_tokens_mistral': 4596, 'n_tokens_neox': 4408, 'n_words': 2600}