Managing access to your API portal with Azure Active Directory - Cloud

EnrichVersion
Cloud
EnrichProdName
Talend Cloud
EnrichPlatform
Talend API Designer
task
Design and Development

Managing access to your API Portal with Azure Active Directory

Deploy your API Portal on Azure Static Web Apps and configure roles and access rights for consumers.

Azure Static Web Apps comes with a role management feature that allows you to use Azure Active Directory to manage authentication for your API Portal. You can easily define custom roles for your users and limit access to specific pages.

In the following example, the API Portal contains:
  • A custom landing page
  • A custom "Request access" page
  • The default API list with the published API documentation
  • The default "Getting started" page

The "Getting started" page and the API documentation should be available only to users with the api_developer role, and the landing page and "Request access" page should be visible by all authenticated users.

For more information about customizing the landing page and creating new pages, see Organizing and adding content.

Defining custom roles for Azure Static Web Apps

Create a file in your API Portal repository to define custom roles and their access rights.

Before you begin

You have generated an API Portal repository from Talend Cloud API Designer. For more information, see the Talend Cloud API Designer User Guide.

Procedure

  1. At the root of your API Portal repository, create a file named staticwebapp.config.json.
    This file defines routes and the user roles allowed to access them. For more information, see Routes in Azure Static Web Apps.
  2. Define your routes.
    In this example, you need to add five routes:
    • /login to allow users to log in with Azure Active Directory.
    • /logout to allow users to log out.
    • /me to display information about the user.
    • /apis/* to specify how to handle the list of APIs and the API documentation.
    • /getting-started to specify how to handle the "Getting started" page.
    • /* to specify how to handle any other page on the API Portal. This route should be the last one in the file.

    If needed, you can also use routes to block other authorization providers. For more information, see Block an authorization provider.

  3. Define a redirection in case users are not logged in.

    Azure Static Web Apps returns a status code 401 when a user who is not logged in tries to access a page available only to authenticated users. You can redirect users from the default error page to a login page using the responseOverrides element. For more information, see Response overrides.

    In this example, the staticwebapp.config.json file looks like this:
    {
        "routes": [
            {
                "route": "/login",
                "rewrite": "/.auth/login/aad"
            },
            {
                "route": "/logout",
                "redirect": "/.auth/logout"
            },
            {
                "route": "/me",
                "redirect": "/.auth/me"
            },
            {
                "route": "/apis/*",
                "allowedRoles": ["api_developer"]
            },
            {
                "route": "/getting-started",
                "allowedRoles": ["api_developer"]
            },
            {
                "route": "/*",
                "allowedRoles": ["authenticated"]
            }
        ],
        "responseOverrides": {
            "401": {
                "redirect": "/login",
                "statusCode": 302
            }
        }
    }
  4. Commit your changes.

Customizing your API Portal header

Customize the header on your API Portal to display user information and a Log out button.

About this task

You can customize the API Portal's HTML files to add custom elements if needed. The best practice is to copy folders and files from the themes/talend to the root of the repository. This way you can override the default files without editing them.
Warning: If you download an updated version of the theme after overriding theme files, you will have to manually update your custom files.

Procedure

  1. At the root of your API Portal repository, create a layouts folder, and inside it create a partials folder.
  2. Copy the file /themes/talend/layouts/partials/header.html in the /layouts/partials folder your created.
    You now have two header.html files in the repository. You should only edit the one in /layouts/partials.
  3. In your new header.html file, before the closing </ul> tag, add a new <li> element that contains a link to the logout page and the user information.

    Example

      <li style="margin-left: auto; margin-right: 1em">
        <a href="/logout">Log out</a>
        <span id="user"></span>
      </li>
  4. After the closing </ul> tag, add a <script> element to fetch user information from the /me route.

    Example

    <script>
      fetch('/me')
      .then(response => response.json())
      .then(me => document.getElementById('user').innerHTML = me.clientPrincipal.userDetails)
      .catch(e => document.getElementById('user').innerHTML = 'Anonymous');
    </script>
  5. Commit your changes.

Deploying your portal with Azure Static Web Apps

Deploy your portal by connecting your GitHub repository to Azure Static Web Apps. For more information, see the Azure Static Web Apps documentation.

Before you begin

  • You have the relevant rights on Microsoft Azure.
  • You have generated your API Portal repository.

Procedure

  1. Log in to your Azure account and open the Static Web Apps service.
  2. Click Add to create a new static web app.
  3. In the Project details section, select your subscription and resource group.
  4. In the Static Web App details, enter a name for your web app and select a region.
  5. Click Sign in with GitHub to link your GitHub account to your web app and click Authorize Azure-App-Service-Static-Web-Apps.
  6. Once your account is linked, select the organization, repository and branch to use to build your portal.
  7. In the Build Presets drop-down list, select Hugo, then enter the required location details.
    This parameter allows Azure Static Web Apps to automatically use the build configuration provided in the GitHub repository.
  8. Click Review + create.
  9. Make sure that your configuration is correct and click Create.

Results

Your portal is deploying and a GitHub Action automatically starts on your repository.
Once it is completed, you can click the URL provided on Azure Static Web Apps to access your portal.

Adding users to your API Portal

Invite users to access your API Portal and manage their roles.

Procedure

  1. In Azure Static Web Apps, open your API Portal app and go to Settings > Role management.
  2. Click the Invite button.
  3. Select Azure Active Directory in the Authentication provider field and enter the user's email address.
  4. Enter the name of the relevant custom role(s), as defined in staticwebapp.config.json.
    In this example, you have the api_developer custom role.
  5. Click Generate.
  6. Share the invite link provided with the corresponding user.

Results

Once the user uses the invite link, they will be able to log in and will be prompted to grant access to their email address and username. After that they will be able to see the pages accessible to them depending on their role.