Programming/Auth0

What is Auth0?

"Auth0 is an easy to implement, adaptable authentication and authorization platform."

Auth0 can be used for user logins as well as machine-to-machine permission management.

Terms and Setup Suggestions

General

Tenant

- "At Auth0, a logically-isolated group of users who share common access with specific privileges to a single software instance. No tenant can access the data of another tenant, even though multiple tenants might be running on the same machine. Tenant, in general, is a term borrowed from software multitenant architecture."

• Tenants cannot be renamed.
• You can restrict API access via scopes (more on those later), so I generally recommend one tenant per stage per website.

Application

- "Your software that relies on Auth0 for authentication and identity management. Auth0 supports single-page, regular web, native, and machine-to-machine applications."

• You will only need one application per website.

API

- (No formal definition given)

• APIs are your backend services.
• Since I recommend a micro-service architecture, I recommend one API per backend micro-service.

Scope

- "A mechanism that defines the specific actions applications can be allowed to do or information that they can request on a user’s behalf. Often, applications will want to make use of the information that has already been created in an online resource. To do so, the application must ask for authorization to access this information on a user’s behalf. When an app requests permission to access a resource through an authorization server, it uses the Scope parameter to specify what access it needs, and the authorization server uses the Scope parameter to respond with the access that was actually granted."

• Basically, this allows you to limit access to APIs. For example, you might have a "read" scope to allow reads from the database and a "write" scope for writing. A customer-facing website might only have the "read" scope for an API, whereas an internal website might have both "read" and "write" scopes for the same API.
• More on scopes here.

API Identifier

- (No formal definition given)

• API Identifiers are unique, developer-defined, human-readable strings used to identify APIs in JWT tokens (more on those later).

Token

Audience

- "The unique identifier of the audience for an issued token, identified within a JSON Web Token as the `aud` claim. The audience value is either the application (`Client ID`) for an ID Token or the API that is being called (`API Identifier`) for an Access Token. At Auth0, the Audience value sent in a request for an Access Token dictates whether that token is returned in an opaque or JWT format."

Sample Machine to Machine Token

For this example, I've generated a token from a Application to an API.

The response to an authorization request looks like this:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjhuMmtQVTB0M1JSRzlPRTlhUTRKSSJ9.eyJpc3MiOiJodHRwczovL2V0LWFscGhhLnVzLmF1dGgwLmNvbS8iLCJzdWIiOiJKUFhmZjJGRkQ4elZxUnFvbEZOdTRUR2x6Q3I4WXJneUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9ldC1hbHBoYS1maXJzdC1hcGkvIiwiaWF0IjoxNjIzMjQ2MTAxLCJleHAiOjE2MjMzMzI1MDEsImF6cCI6IkpQWGZmMkZGRDh6VnFScW9sRk51NFRHbHpDcjhZcmd5IiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.K9zTQ7-fFT4ENsALlXEIrrJCN3dByaFB9IKkrCps39S--pnWJgCApTMtM3V4JBIJfuyKwTs-HZt-uEnN-w4KF-0Uikqn5gRzKGgIDcUm2VzWYpJ9jxDkco7mwgigB6o0eHXgAxjMdwDpJx1kADVPCELDS4Qt-Sa-SsQpUWDVAORxTy4zF8DnmqlFa9uxHAKAK038fxMldflcuqSs5zbVsbXs1wx4x7f8QW8DilrNoRgi-iXPFc4Rd4-rBwHHvJcfqb6b8v_8q2rvzMQX-RRXWIv87kuGKudB-H_va2_TmstyftSGpjf6w2tPOgBwHTZhEJS6SUx4jhSK3ipiQcR5GA

The token is split into three parts (delineated by periods): header, payload, and signature. We can use jwt.io to break apart this token into human-readable parts.

Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "8n2kPU0t3RRG9OE9aQ4JI"
}

This gives us data about the encryption algorithm (alg), token type (typ), and the key ID (kid). alg and typ will never change and kid is autogenerated.

Payload

{
  "iss": "https://et-alpha.us.auth0.com/",
  "sub": "JPXff2FFD8zVqRqolFNu4TGlzCr8Yrgy@clients",
  "aud": "https://et-alpha-first-api/",
  "iat": 1623246101,
  "exp": 1623332501,
  "azp": "JPXff2FFD8zVqRqolFNu4TGlzCr8Yrgy",
  "gty": "client-credentials"
}

This section gives us the most data about our token.

iss

- This is our issuer. The format is "https://<tenant>.<region>.auth0.com/".

sub

- This is our subject, to whom the token refers. The format is "<Client ID>@clients". In this example, this is the Client ID for my Application.

aud

- This is the audience, for whom the token is intended. This is the API Identifier of the API.

iat

- This is the timestamp at the token was issued.

exp

- This is the timestamp at which the token expires.

azp

- This is the authorized party, to whom the token was issued. Again, this is the Client ID for my Application.

gty

- This is the grant type. The value will be "client-credentials" for machine to machine and "password" for user logins.

Most of the keys are registered claims, meaning they are universal. However, gty is a custom claim specific to Auth0.

Signature

RSASHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret
)

This is the signature of the token. This ensures that no one can modify the token (for example, extend the expiration date).

Appendix

• Auth0 Glossary