When developing Single Page Applications (SPAs) that interact with APIs, ensuring secure authentication and authorization is paramount. By default, many platforms, including Auth0, might treat your client application as a first-party application if explicit configurations are not made. While this might seem convenient initially, it’s crucial to understand the implications and adopt best practices for robust security, especially when your SPA and API are designed as independent entities.

For applications where your SPA frontend and backend API are distinct services, it is highly recommended to configure them as such within your identity provider. In platforms like Auth0, this translates to explicitly defining two separate records: one representing your SPA client application and another representing your API as a resource server.

This separation offers several advantages in terms of security and maintainability. Treating your SPA and API as distinct entities allows for granular control over access policies and permissions. For instance, you can define specific scopes and audiences for your API, ensuring that only authorized applications with the correct credentials can access it.

To establish this secure connection, your SPA should initiate authentication requests that explicitly target your API. This is achieved by including the audience parameter in your authentication request. The audience parameter essentially tells the authorization server (like Auth0) which API the SPA intends to access.

Consider the following code snippet, demonstrating how to configure the audience parameter when using the auth0-js library in your SPA:

this.auth0 = new auth0.WebAuth({
  clientID: 'YOUR_CLIENT_ID',
  domain: 'YOUR_AUTH0_DOMAIN.auth0.com',
  redirectUri: 'YOUR_SPA_REDIRECT_URI',
  responseType: 'token',
  audience: 'https://your-api.example.com'
});

In this configuration, https://your-api.example.com is the identifier of your API resource server, as configured in your identity provider. By including this audience parameter, the SPA signals its intent to access this specific API, and the authorization server will issue an access token specifically for this purpose. This access token, often a JWT (JSON Web Token), is then used by the SPA to authenticate subsequent requests to the API, typically included in the Authorization header as a bearer token.

Beyond API access, SPAs often require information about the currently logged-in user to personalize the user experience. Displaying user-specific information or customizing the UI based on user roles are common requirements. To achieve this securely and in accordance with OpenID Connect (OIDC) standards, you should request an id_token in addition to the access_token.

The id_token is another type of JWT that contains claims about the authenticated user, such as their name, email, and other profile information. To request an id_token, you need to include id_token in the responseType and also include the openid scope in your authentication request. The openid scope is mandatory when requesting an id_token as per the OIDC specification.

Here’s how you would modify the auth0-js configuration to request both an access_token and an id_token:

this.auth0 = new auth0.WebAuth({
  clientID: 'YOUR_CLIENT_ID',
  domain: 'YOUR_AUTH0_DOMAIN.auth0.com',
  redirectUri: 'YOUR_SPA_REDIRECT_URI',
  responseType: 'id_token token',
  audience: 'https://your-api.example.com',
  scope: 'openid'
});

By setting responseType to id_token token and including scope: 'openid', your SPA will receive both an access_token (for API authentication) and an id_token (for user information) upon successful authentication. You can further expand the requested user information by adding more scopes, such as email or profile, to the scope parameter, for example: scope: 'openid email profile'. You can also request scopes specific to your API to obtain more granular permissions.

It’s important to note that when using the audience parameter or explicitly enabling OIDC conformance, the claims included in the id_token are restricted to the standard claims defined in the OIDC specifications. This ensures interoperability and security best practices.

However, there are scenarios where you might need to include additional custom claims in either the access_token or the id_token. For example, you might want to include user roles, application-specific permissions, or other relevant metadata. Identity platforms like Auth0 provide mechanisms to achieve this through rules or hooks.

Rules (in Auth0) are customizable functions that execute during the authentication process. They allow you to modify the contents of tokens by adding custom claims based on user attributes, application context, or other factors. For instance, the following rule snippet demonstrates how to add a custom claim named https://my.example.com/ref to the access_token, based on a user’s app_metadata:

function (user, context, callback) {
  if(context.accessToken) {
    context.accessToken["https://my.example.com/ref"] = user.app_metadata.reference;
  }
  callback(null, user, context);
}

This rule checks if an access_token is being generated and then adds a custom claim to it. Crucially, custom claim types should be namespaced (like https://my.example.com/ref in this example) to avoid potential conflicts with standard claims or claims from other applications. If you needed to add custom claims to the id_token instead, you would use context.idToken within the rule.

By strategically using the audience parameter, requesting id_tokens with the openid scope, and leveraging rules for custom claims, you can build secure and flexible SPA applications that effectively authenticate with APIs and manage user information, adhering to security best practices and industry standards like OIDC.