Protecting Application Endpoints

Your application may access a resource server with endpoints that are protected and restrict to privileged users. Use Access Tokens to protect your endpoints that require specific permissions.

Configuring Resource Audience

By default, your application will only be able to request access tokens for IDaaS and use it to retrieve user information. A common use case in OAuth is to enable access to an API with protected resources using IDaaS as the authorizer along with an API Gateway (e.g. an AWS API Gateway). In this scenario, you will need to configure a resource server in IDaaS that represents the API you are trying to protect. When requesting an access token, the audience associated with the resource server must be requested.

Follow these steps to configure API Authorization in your IDaaS account using Resource Servers.

1. Navigate to the Security > Resource Servers page
2. Under API/URL, select + to define a new resource server (audience) that your access token will be valid for.
3. Configure the following fields:

Field	Description
Enabled	Should be set to true.
Name	A friendly name for this resource when shown in the IDaaS API/URL list.
Value	The resource that you are trying to protect. This will be the same as the AUDIENCE value that that is associated with the access token and expected by the resource server.
Supported OIDC/OAuth Applications	The OIDC applications generating the access tokens to access this resource. Select your configured OIDC application.
Refresh Token	Whether to allow refresh token requests (i.e., use of the offline_access scope).

info

Additional configuration can be applied, but these are the required fields.

Scope Configuration

Your endpoints will likely have different purposes, for example you may have an endpoint to fetch a user's transaction history, and another one to create a new transaction. You can configure scopes under the Scope Configuration header.

1. Click Add in the scope configuration table
2. Set the name of the scope (If you enable consent, this will be the label shown to the user)
3. Set the value. Common use cases use an operation:entity style, e.g., read:tests and write:profile, but you may have other values for your app.

note

Scopes must be unique across all resource servers.

Sending Requests to Protected Endpoints

tip

In the examples below, the access token is sent to the resource server in the Authorization header but your app may be different.

In order to access a protected endpoint you can retrieve a user's previously acquired access token and pass it to your resource server endpoint. If they have the required scopes and claims the endpoint will return the requested resource. See Protecting AWS API Gateway for an example of how to enforce Authorization in your API.

JavaScript

Retrieve the user's access token and include it in the API request

<button id="access-resource">Click to Access Resource</button>

document
  .getElementById("access-resource")
  .addEventListener("click", async () => {
    const token = idaasClient.getAccessToken();
    const response = await fetch(`https://resource.com`, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });
    const data = await response.json();
    console.log(data);
  });

Requesting a New Access Token

You can request a new access token use login method described in Protecting your Single Page Application. This includes if the user needs a more recent authenticate or needs to request different scopes or a different audience.

Verify Type of Authentication

You are able to specify the level of authentication that must be used when authenticating the user to receive the token. This enables you to define what level of authentication to use for step-up authentication.

JavaScript

<button id="authenticate">Authenticate</button>

document
  .getElementById("authenticate")
  .addEventListener("click", async () => {
    const token = idaasClient.getAccessToken({
      // Retrieve a token with <SCOPE> and <AUDIENCE> that was authenticated recently via a `possession` (something you have) or `inherence` (something you are) method of authentication.
      audience: "<AUDIENCE>",
      scope: "<SCOPE>",
      acrValues: ["possession", "inherence"]
      // If the token is not found, login via an authentication method that falls under the 
      // `possession` or `inherence` method of authentication to receive this token.
    });
    const response = await fetch(`https://resource.com`, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });
    const data = await response.json();
    console.log(data);
  });

If an existing access token matching the requirements does not exist, a new authentication request needs to be made.