Protecting Application Endpoints

Your app may have endpoints that you want to protect 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. A common use case for OIDC is to enable access to an API with protected resources using IDaaS as the authorizer (e.g. an AWS API Gateway).

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

1. Navigate to the Security > Authorization page
2. Under API/URL, select + to define a new domain (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 you are passing in from the client when authenticating.
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 (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 are read and write, but you may have other values for your app.

Sending Requests to Protected Endpoints

tip

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

In order to access a protected endpoint you can retrieve the user's access token and pass it to your resource endpoint. If they have the required 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);
  });

React

Retrieve an access token to pass along in the Authorization header using getAccessToken:

import { useIdaas } from "@entrustcorp/idaas-auth-react";
...
const { getAccessToken } = useIdaas();

const handleOnClick = async () => {
  const token = await getAccessToken();
  const response = await fetch(`https://resource.com`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${token}`,
    },
  });

  const data = await response.json();
  console.log(data);
};
...
<button onClick={handleOnClick}>Protected Resource</button>;

Requesting a New Access Token

You can request a new access token using the getAccessToken method.

JavaScript

Request an access token that is not already stored by supplying fallbackAuthorizationOptions to getAccessToken. Doing so will initiate an access token request from IDaaS.

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

document
  .getElementById("access-resource")
  .addEventListener("click", async () => {
    const token = idaasClient.getAccessToken({
      fallbackAuthorizationOptions: {
        popup: true,
      },
    });

    const response = await fetch(`https://resource.com`, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });
    const data = await response.json();
    console.log(data);
  });

React

Request an access token that is not already stored by supplying fallbackAuthorizationOptions to getAccessToken. Doing so will initiate an access token request from IDaaS.

import { useIdaas } from "@entrustcorp/idaas-auth-react";
...
  const { getAccessToken } = useIdaas();

  const handleOnClick = async () => {
    const token = await getAccessToken({
      fallbackAuthorizationOptions: {
        popup: true
      },
    });
    const response = await fetch(`https://resource.com`, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });

    const data = await response.json();
    console.log(data);
  };
...
<button onClick={handleOnClick}>Protected Resource</button>;

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 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.
      fallbackAuthorizationOptions: {
        popup: true,
      },
    });

    const response = await fetch(`https://resource.com`, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });
    const data = await response.json();
    console.log(data);

  });

React

import { useIdaas } from "@entrustcorp/idaas-auth-react";
... const { getAccessToken } = useIdaas();

          const handleOnClick = async () => {
          const token = await getAccessToken({
            // Retrieve a token with <SCOPE> and <AUDIENCE> that was authenticated via a `possession` (something you have) or `inherence` (something you are) method of authentication.
            audience: "<YOUR_AUDIENCE>",
            scope: "<YOUR_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.
            fallbackAuthorizationOptions,
          });
          const response = await fetch(`https://resource.com`, {
            method: "GET",
            headers: {
              Authorization: `Bearer ${token}`,
            },
          });

          const data = await response.json();
          console.log(data);
        };
        ...
          <button onClick={handleOnClick}>
            Authenticate Inherence or Possession
          </button>;