Integrate the Token Handler with an API Gateway

After completing the First Configuration, the final deployment task is to provide token handler URLs that the SPA can call. These URLs must be in the same parent site as the SPA's web origin. An API gateway provides the token handler public URLs and SSL certificates. Once URLs are available the SPA can integrate with the token handler to enable the following end-to-end flow, where the SPA sends cookies to API gateway entry points that use the OAuth Proxy to process cookies.

Many organizations already have an API gateway and an infrastructure team that can create the token handler host name. Full details of provisioning an API gateway, connecting networking infrastructure and enabling external URLs is a major topic that is not covered here. Instead, the following sections summarize the main steps to integrate the OAuth Proxy and update the API gateway.

Create the Token Handler Host Name

In deployed environments, use a DNS solution to create the token handler host name. For example, use your cloud platform to create a new DNS A record as a subdomain of the SPA's existing domain. The API gateway can then use API routes that reference the token handler's host name.

Get the OAuth Proxy

The OAuth Proxy executes as an API gateway plugin for API routes that the SPA calls. Use the Curity Developer Portal to download a zip file for a particular API gateway, which contains the proxy files and detailed instructions on how to integrate the plugin with your gateway. Implementations are available for the following popular gateways:

• Kong
• OpenResty
• NGINX
• AWS API Gateway
• Azure API Management
• Google Apigee API Manegement

Deploy the OAuth Proxy

The main deployment task is integration of the OAuth Proxy plugin with the API gateway. You deploy the plugin files once and can then configure the plugin for multiple API routes. The exact deployment behavior varies depending on the particular gateway and how you administer it. For gateways that can run on a local computer you can see working deployments in the Token Handler Deployment Example.

services:
  kong:
    image: custom_kong:1.0.0
    ports:
      - 80:3001
    volumes:
      - ./kong.yml:/usr/local/kong/declarative/kong.yml
    environment:
      KONG_DATABASE: 'off'
      KONG_DECLARATIVE_CONFIG: '/usr/local/kong/declarative/kong.yml'
      KONG_PROXY_LISTEN: '0.0.0.0:3000'
      KONG_LOG_LEVEL: 'info'
      KONG_PLUGINS: 'bundled,cors,oauth-proxy'

Configure the OAuth Proxy

When the SPA calls an API, the browser sends a cookie containing an encrypted access token. Configure the OAuth Proxy so that each of the SPA's API routes decrypts cookies, and forwards access tokens to the API. The exact details of how to configure the OAuth Proxy depend upon the particular API gateway. The following content provides a summary of OAuth Proxy configuration for each supported API gateway, with links to further details.

- name: example-api
  url: http://api-internal:3001
  routes:
  - name: example-api-route
    hosts:
    - api.demoapp.example
    paths:
    - /api
  plugins:
  - name: cors
    config:
      origins:
      - https://www.demoapp.example
      credentials: true
      max_age: 86400
  - name: oauth-proxy
    config:
        -----BEGIN ENCRYPTED PRIVATE KEY-----
        MIH0MF8GCSqGSIb3DQEFDTBSMDEGCSqGSIb3DQEFDDAkBBA9BLL4kbxiN4dOlIZE
        nxxsAgIIADAMBggqhkiG9w0CCQUAMB0GCWCGSAFlAwQBKgQQ72a5HguvLkDUto5Q
        gLjuygSBkCOR6pSeXPp1ym5f+oPwYzT99EXbyxELUI43r01IcfY1i8Ib+rPbHB0K
        abRjKb/MnJXaRVS3iaQDYmTLK4SF6YcA3wRJtUZWTeCr79PbzkAootHyRjrYT6jN
        hOm/DLJHiRtNFyRTX+E9r9uMnYACmv6o0lsWScb0NrwPlyW3Ft14ayibtRvCnpEa
        CB3FgLlR9w==
        -----END ENCRYPTED PRIVATE KEY-----
      cookie_key_pass: Password1

Expose the OAuth Agent

The API gateway also provides the public URL for the OAuth Agent, at a path such as /apps/example within the token handler base URL. Create this route in the same way as API routes but do not configure any plugins, since the OAuth Agent implements its own cookie and CORS logic.

Deploy a Local Gateway

You can also run a token handler on a local computer, to learn about how it works before deploying to real environments. You can run a local deployment using Docker, and expose the OAuth Agent and OAuth Proxy to a local SPA using domain based URLs. First, enable a local computer DNS solution to resolve host names. For example, add the following line to the /etc/hosts file.

127.0.0.1 www.demoapp.example api.demoapp.example

Next, use Docker to deploy the token handler components. The following example shows a docker-compose.yml file that enables deployment of the Kong API gateway and the OAuth Agent. The curity-config.xml file would contain OAuth Agent configuration downloaded from the Admin UI, with a local development redirect URI such as http://www.demoapp.example:3000/callback. The kong.yml file would define development API routes and their use of the OAuth Prroxy and CORS plugins.

services:
  kong:
    image: custom_kong:1.0.0
    ports:
      - 80:3001
    volumes:
      - ./kong.yml:/usr/local/kong/declarative/kong.yml
    environment:
      KONG_DATABASE: 'off'
      KONG_DECLARATIVE_CONFIG: '/usr/local/kong/declarative/kong.yml'
      KONG_PROXY_LISTEN: '0.0.0.0:3000'
      KONG_LOG_LEVEL: 'info'
      KONG_PLUGINS: 'bundled,cors,oauth-proxy'

  oauth-agent:
    image: curity.azurecr.io/curity/idsvr:latest
    hostname: oauthagent
    ports:
      - 6749:6749
    volumes:
      - ./license.json:/opt/idsvr/etc/init/license/license.json
      - ./curity-config.xml:/opt/idsvr/etc/init/curity-config.xml
    environment:
      ADMIN: 'true'
      LOGGING_LEVEL: 'INFO'
      BASE_URL: 'http://api.demoapp.example'
      PASSWORD: 'zIf66A9Wz'

The Token Handler Deployment Example provides a reference deployment and it is possible to Adapt the Deployment in various ways. For example, you can upgrade to an HTTPS development setup using locally issued OpenSSL certificates, or run a same-origin deployment where the OAuth Agent and OAuth Proxy run on the web origin and might use base URLs of the following form:

• OAuth Agent Base URL: https://www.demoapp.example/apps/example
• OAuth Proxy Base URL: https://www.demoapp.example/api

Integrate the SPA

Once the API gateway work is complete, the SPA can call the token handler's external URLs. The final task is to Integrate the SPA so that it runs an OAuth flow and then calls APIs with secure cookies as credentials.