Skip to main content

Authress Local

The Authress Local source code is available in the Authress Local GitHub repository.

      

info

The Authress Local APIs match the ones that are support by the Authress API. See the API documentation for in-depth details about the available endpoints.

Usage​

Authress Local is a container that can be run locally, so that you can add login, authentication, authorization, api keys, and additional security to the development of your service. When developing your service on your machine, you might have the need to:

  • Generate a JWT which your service requires to call the endpoints
  • Ensure that your endpoints are secured with RBAC, ABAC, policies, and other access control mechanisms
  • Generate client side API keys to make it easy to authenticate once you get to production.

The goal of Authress Local is to avoid the need to integrate set up complex configuration to get your service up and running locally. Additionally, since the Authress Local container mirrors the Authress Production APIs, you can integrate your local service with the Authress Local container and then be sure when running service in production it will work as tested.

Prerequisites​

To run Authress Local on your development machine you will only need to have a container orchestrator running. We recommend podman, but you can also use docker. You only need one of these:

Setup​

Next after having the necessary framework installed, you can pull and run the latest version of the authress-local container

Run Authress Local on your machine
# Download the package
podman pull ghcr.io/authress/authress-local:latest

# Run the package as a daemon (-d) on port 8888 (-p 8888:8888)
podman run -d -p 8888:8888 authress/authress-local:latest

If this works and you get back a long string of characters that represents the running container. Now you are ready to continue development with your service.

Generating Tokens for your API​

Most services require an access_token that enables your users to both identify themselves and also qualify which kinds of endpoints in your service they are allowed to utilize. Getting an access token for service usually requires a complex process of generating one yourself. That often unnecessarily complicated and makes it difficult to validate.

To solve this problem Authress Local provides an easy way to generate tokens as necessary.

To generate a valid JWT:

Adding Authorization​

By running the Authress Local container you can connect to the authorization api to secure your endpoints. When running your service you'll have a need to restrict which endpoints can be called by your users. Commonly you might have a roles or a permissions check. Using Authress Local you can delete these checks to running container. These checks will perform an API call to the running service to validate your user is logged in and the token your service gets is valid.

When using Authress in production, these calls will likely go to Authress instead of a local container, but when running locally you can just use the container to authorize your service endpoints. To actually authorize your users, you can directly call the Authress Local API by specifying the endpoint as http://localhost:8888 or even easier is to use one of the authorization SDKs available in almost any language:

In the situation when you are using the Javascript/Typescript SDK:

Add Authress Local authorization checks to your service
import AuthressClient from '@authress/sdk';

const authressClient = new AuthressClient();

// on api route to get resource
@route('/resources/<resourceId>')
async function getResource(resourceId) {

    // Get the user token and pass it to authress
    const authorizationToken = request.headers.get('authorization');
    authressClient.setToken(authorizationToken);

    // Check Authress to authorize the user, this call goes to your running Authress Local container
    try {
      await authressClient.userPermissions.authorizeUser(userId, `resources/${resourceId}`, 'READ');
    } catch (error) {
      // Will throw except if the user is not authorized to read the resource
      if (error.code === 'UnauthorizedError') {
        return 404;
      }

      return { resource: {}, statusCode: 503 };
    }

    // On success, continue with the route code to load resource and return it
    return { resource: {}, statusCode: 200 };
}

The full list, check out the available languages and frameworks.

FAQ​

My service requires a JWT to be used to authenticate with it, can I get one from Authress Local?​

Absolutely, hop over to the Authress Local JWT generator and you should be good to go.

The tokens generated by the Authress Local token generator look like this:

Authress Local generated JWT
{
    "iss": "https://authress.io/authress-local",
    "sub": "authress-local|user_001",
    "iat": 1690720928,
    "exp": 1690807328,
    "scope": "openid profile email",
    "azp": "authress-local"
}

These tokens can be used with your local development version of your service and with Authress Local for testing out your service without even needing login.

tip

Want to use Authress Local or the Authress API and not sure what to do or want a security consult on what you are building, just let our development team know.