Localauth0 is a project that aims to be a helper while developing authentications inspired by localstack. Most of the time people tend to mock authentication in order to not be forced to create complex mocks. With localauth0 you can fake your auth0 tenant and test it offline for "real".

• Installation
• APIs
  • Web page
  • Jwt
  • Jwks
• Configuration
  • Local development
  • Integrate Localauth0 in an existing docker compose project
• Healthchecks

In order to run localauth0 docker image execute the following:

docker run -d -p 3000:3000 public.ecr.aws/primaassicurazioni/localauth0:0.8.1

By default, the container exposes an http server on the port 3000 and an https one on port 3001.

Note: The latest version is the same version written in the Cargo.toml file.

After having run the localauth0 machine a web interface is available at http://localhost:3000/. Here it's possible to:

• get a fresh new JWT with given audience.
• add/remove permissions for a given audience.

• POST http://localhost:3000/oauth/token: used to get a freshly new JWT. Body should be:

  {
    "client_id": "client_id",
    "client_secret": "client_secret",
    "audience": "{{your-audience}}",
    "grant_type": "client_credentials"
  }

  for the client credentials grant and

  {
    "client_id": "client_id",
    "client_secret": "client_secret",
    "grant_type": "authorization_code",
    "code": "{{your-auth-code}}"
  }

  for the authorization code grant.

• GET http://localhost:3000/permissions: used to get a the list of all audiences with their associated permissions.

• POST http://localhost:3000/permissions: used to set a list of permissions for given audience. Everytime a new JWT is requested for that audience those permissions will be injected in the JWT payload. Body should be:

  {
    "audience": "{{your-audience}}",
    "permissions": ["your-permission-1", "your-permission-2", ".."]
  }

• GET http://localhost:3000/permissions/{audience}: used to get the list of all permissions for the given audience.

• GET http://localhost:3000/oauth/token/custom_claims: used to get the list of custom claims that will be injected in the JWT payload.

• POST http://localhost:3000/oauth/token/custom_claims: used to add or update one or more custom claim fields. Body should be:

  {
    "custom_claims": [{
      "name": "custom_claim_field_name",
      "value": "custom claim field value. Can be a string or a list of strings"      
    }]
  }

• GET http://localhost:3000/oauth/token/user_info: used to get the user info.

• POST http://localhost:3000/oauth/token/user_info: used to update the user info. Body should be:

  {
    "subject": "optional field",
    "name": "optional field",
    "given_name": "optional field",
    "family_name": "optional field",
    "nickname": "optional field",
    "locale": "optional field",
    "gender": "optional field",
    "birthdate": "optional field",
    "email": "optional field",
    "email_verified": "optional field",
    "picture": "optional field",
    "updated_at": "optional field",
    "custom_fields": "optional field"
  }

• GET http://localhost:3000/.well-known/jwks.json: it's possible to fetch running instance jwks. Those jwks are randomly created starting from random certificates. Note that every generated JWT will be signed using one of those JWKS.

• GET http://localhost:3000/rotate: discard the last JWK of the JWKS list and prepend a freshly new JWK.

• GET http://localhost:3000/revoke: discard all the JWKs in the JWKS list and replace them with 3 freshly new JWKs.

Localauth0 could behave like Google SSO page. In order to achieve this your web page should navigate to http://localhost:3000/authorize providing these query params:

• redirect_uri: your web app callback page
• audience: the audience you want to use to generate the token
• response_type (optional): could be token or code. Use token to perform an implicit grant flow and retrieve an access token directly and use code to perform an authorization code flow and recieve an authorization code. If auth is succesful, the requested redirect is performed with the code or token contained in the query params.
• state (optional): An opaque value, used for security purposes. If this request parameter is set in the request, then it is returned to the application as part of the redirect_uri.
• bypass (optional): this is a dev feature. If set to true directly redirect to redirect_uri.

After redirection the redirect_url will contain these http fragments:

• access_token: the JWT token.
• token_type: always set to Bearer.
• expires_in: when will the jwt expires.
• state: present if set in authorize url; contains the same value.

For example navigating to:

http://localhost:3000/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A3000%2F&audience=audience1&client_id=client_id&connection=whatever&response_type=token&scope=whatever&state=test-state&bypass=true

The page will automatically redirect to:

http://localhost:3000/#access_token=eyJ..RrQ&token_type=Bearer&expires_in=3600&state=test-state

Localauth0 can be configured using a localauth0.toml file (see localauth0.toml as an example) or using the LOCALAUTH0_CONFIG environment variable.

Take a look here to see how to configure your docker compose cluster.

To build and run localauth0 locally run the following commands:

docker build -f Dockerfile -t localauth0 . && \
docker run -it -p 3000:3000 -v .:/code localauth0 bash

Keep in mind that installing trunk will take some time.

Get into docker-compose container with:

docker-compose run --service-ports web bash

Build the artifact, the web dist and run the http server with:

# Build the web dist with trunk. Then run the server
cargo make run

Now website is available at http://localhost:3000.

As mandatory step it's needed to create the artifact and the web dist. In order to achieve this run cargo make build or cargo make run commands from within the docker-compose container (alternatively from host machine if cargo and trunk are installed).

For someone this error could occur on host machine

error[E0463]: can't find crate for `core`
  |
  = note: the `wasm32-unknown-unknown` target may not be installed
  = help: consider downloading the target with `rustup target add wasm32-unknown-unknown`

error[E0463]: can't find crate for `compiler_builtins`

In order to fix it run

rustup target add wasm32-unknown-unknown --toolchain nightly

Then run:

docker build -f Dockerfile -t localauth0 . && \
docker run -d -p 3000:3000 localauth0

Add this snippet to your docker-compose.yml file and reference it in your app depends_on section.

auth0:
  image: public.ecr.aws/primaassicurazioni/localauth0:0.8.1
  healthcheck:
    test: ["CMD", "/localauth0", "healthcheck"]
  ports:
    - "3000:3000"

It is possible to add the LOCALAUTH0_CONFIG environment variable with an inline configuration to let Localauth0 load the configuration at startup. For example:

auth0:
  image: public.ecr.aws/primaassicurazioni/localauth0:0.8.0
  healthcheck:
    test: ["CMD", "/localauth0", "healthcheck"]
  ports:
    - "3000:3000"
  environment:
    LOCALAUTH0_CONFIG: |
issuer = "https://prima.localauth0.com/"
[user_info]
given_name = "Locie"

Another way to configure Localauth0 is to mount a configuration file in the container. For example, create a localauth0.toml file with the following:

issuer = "https://prima.localauth0.com/"

[user_info]
given_name = "Locie"

Then mount the file in the container using the following snippet in your docker-compose.yml file:

auth0:
  image: public.ecr.aws/primaassicurazioni/localauth0:0.8.0
  healthcheck:
    test: ["CMD", "/localauth0", "healthcheck"]
  environment:
    LOCALAUTH0_CONFIG_PATH: /etc/localauth0.toml
  volumes:
    - ./localauth0.toml:/etc/localauth0.toml:ro
  ports:
    - "3000:3000"

The localauth0 binary can perform a healthcheck on the running localauth0 service. Simply run localauth0 healtcheck