Build an authentication application using Identity Pools APIs

Inside the routes folder lets look at the index.js file. It contains our handlers and the code for obtaining the consent request, getting an authorization token, and accepting or denying the consent request.

First, we get our environment variables. The System workspace needs to obtain an access token so that it can fetch the scopes and related metadata. To do that, we will need the following:

const tenant_id = process.env.TENANT_ID;
const issuer_url = process.env.AUTHORIZATION_SERVER_URL;
const client_id = process.env.CLIENT_ID;
const client_secret = process.env.CLIENT_SECRET;

We will use the CLIENT_ID and CLIENT_SECRET to create the "Bearer" token credentials to access SecureAuth APIs.

const auth_token = Buffer.from(`${client_id}:${client_secret}`, 'utf-8').toString('base64');

Next, add a route for checking that our application is running and responding to requests.

router.get('/', function (req, res, next) {
  res.render('health');
});

Let's add a route to handle requests directed to the consent application at /consent since we defined the consent app at http://localhost:4000/consent. This is the consent application URI that SecureAuth platform redirect users to after they authenticate, in a case when the consent flow is required. The process for handling the custom consent page callback is found at Integrating the custom consent page. SecureAuth provides login ID and login state parameters during the redirect to consent application. If they are missing, an error is displayed and returned. Using the login ID retrieved from the query parameter, we can retrieve more details about the requested scope using the getScopeGrants function that we create below.

router.get('/consent', (req, res) => {
  const login_id = req.query.login_id;
  const state = req.query.login_state;
  if (state == null || login_id == null) {
    res.render('error', { msg: 'missing state and/or login id' });
    return;
  }

  appState.id = login_id
  appState.state = state

  getScopeGrants(res);
});

getScopeGrants fetches an access token from SecureAuth to call the APIs to get the consent details. The scope grant request is then performed.

const getScopeGrants = async (res) => {
  // An access token is required for making a scope grant request.
  appState.access_token = await getAccessToken(res);
  if (appState.access_token == null) {
    return;
  }

  // Once we have an access token we make an API call for a scope grant request.
  getScopeGrantRequest(res);
}

We make a request to the token endpoint for our access token using the Token Endpoint API.

const getAccessToken = async (res) => {
  let CLOUDENTITY_TOKEN_FETCH_API = getTokenURL();

  try {
    const data = qs.stringify({ grant_type: 'client_credentials', scope: 'manage_scope_grants', state: appState.access_token });

    const options = {
      method: 'POST',
      url: CLOUDENTITY_TOKEN_FETCH_API,
      rejectUnauthorized: false,
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        Authorization: 'Basic ' + auth_token
      },
      data: data
    };

    const response = await axiosInstance(options);
    return response.data.access_token;
  } catch (error) {
    console.log(error);
    res.render('error', { msg: 'error getting access token: ' + error });
  }
}

function getTokenURL() {
  return origin + '/' + tenant_id + '/system/oauth2/token';
}

Once we obtain an access token we make the scope grant request using the Consent Request API.

const getScopeGrantRequest = async (res) => {
  let CLOUDENTITY_SCOPE_GRANT_FETCH_API = getScopeGrantURL();

  const options = {
    url: CLOUDENTITY_SCOPE_GRANT_FETCH_API,
    method: "GET",
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': 'Bearer ' + appState.access_token,
    }
  }

  try {
    const response = await axiosInstance(options);
    appState.redirectURI = response.data.request_query_params.redirect_uri[0];
    res.render('consent', { scopes: response.data.requested_scopes });
  } catch (error) {
    console.log(error);
    res.render('error', { msg: 'error getting scope grants: ' + error });
  }
}

function getScopeGrantURL() {
  return origin + '/api/system/' + tenant_id + '/scope-grants/' + appState.id + '?login_state=' + appState.state;
}

The response from the scope grant request includes the requested scopes. We then display the requested scopes to the user. The HTML templates are stored in the views folder. In the case of the application repository the template for showing the user that requested scopes is located in views/consent.hbs. The user can then choose which, if any, scopes they will allow or they can reject the request altogether. For each scope we display the display_name of the scope and the description.

<!doctype html>
<html lang="en">

<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet"
    integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">

  <title>Custom Consent</title>
</head>

<body style="background-color: #f8f5f3;">
  <div class="d-flex flex-column min-vh-100 justify-content-center align-items-center mx-auto" style="width: 600px;">
    <div class="card">
      <div class="card-body">
        <h5 class="card-title">Scopes</h5>
        <form id="scopeForm" action="/accept" method="post">
          {{#each scopes}}
          <div class="form-check">
            <input type="checkbox" class="form-check-input" id="{{this.name}}" name="{{this.name}}" checked>
            <label class="form-check-label" for="{{this.name}}">{{this.display_name}} -
              {{this.description}}</label>
          </div>
          {{/each}}
          <div class="row">
            <div class="col">
              <button type="button" class="text-center btn btn-primary mt-3 float-end"
                onclick="accept()">Accept</button>
            </div>
            <div class="col">
              <button type="button" class="text-center btn btn-danger mt-3"
                onclick="reject()">Reject</button>
            </div>
          </div>
        </form>
      </div>
    </div>
  </div>

  <script>
    function accept() {
      document.getElementById('scopeForm').submit();
    }

    function reject() {
      window.location = '/reject';
    }
  </script>

  <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js"
    integrity="sha384-ka7Sk0Gln4gmtz2MlQnikT1wXgYsOg+OMhuP+IlRH9sENBO0LRn5q+8nbTov4+1p"
    crossorigin="anonymous"></script>
</body>

</html>

If the user rejects the request, we need to notify the SecureAuth authorization platform using the Reject Login Request API.

router.get('/reject', function (req, res, next) {
  const data = JSON.stringify({ id: appState.id, login_state: appState.state });
  submitConsentAndRedirect(res, 'reject', data);
});

If the user accepts some or all of the scopes, we collect the scopes the user has accepted and notify the SecureAuth platform using the Accept Login Request API.

router.post('/accept', function (req, res, next) {
  let scopes = [];
  for (const val in req.body) {
    scopes.push(val);
  }
  const data = JSON.stringify({ granted_scopes: scopes, id: appState.id, login_state: appState.state });
  submitConsentAndRedirect(res, 'accept', data);
});

Finally, we notify the SecureAuth platform of the acceptance or rejection of the requested scopes. The response from the SecureAuth platform includes a body with a redirect_to field. We then redirect the user to the provided redirect URI which sends the user agent back to the SecureAuth platform.

const submitConsentAndRedirect = async (res, consent, data) => {
  let CLOUDENTITY_CONSENT_API = getConsentURL(consent);

  const options = {
    url: CLOUDENTITY_CONSENT_API,
    method: "POST",
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': 'Bearer ' + appState.access_token,
    },
    data: data
  }

  try {
    let acceptRes = await axiosInstance(options)
    res.redirect(acceptRes.data.redirect_to);
  } catch (error) {
    console.log(error);
    res.render('error', { msg: 'failed to submit consent acceptance: ' + error });
  }
}

function getConsentURL(consent) {
  return origin + '/api/system/' + tenant_id + '/scope-grants/' + appState.id + '/' + consent;
}

When we enabled a custom consent page in our SecureAuth platform client, an application was created for us in the System workspace. This application should have grant type client credentials and Client Secret Basic as the Token Endpoint Authentication Method (if your system workspace has different settings then change them to the previous values).

Additionally, under the Scopes tab of your client application settings, ensure that the manage_consents and manage_scope_grants scopes are selected.

From the OAuth tab of the system workspace application, copy the CLIENT ID and CLIENT SECRET. Also, make note of your Tenant ID in the top right. Then, in your client application in the new workspace that we created, on the left navigation menu choose OAuth > Authorization Server and from the General tab copy the Authorization Server URL (this is your issuer URL and can also be found in the .well-known endpoint). Add these values to the environment variables in the .env file.