Identity Gateway 2023.11

Gateway guide

This guide shows you how to set up examples that use IG. It is for access management designers and administrators who develop, build, deploy, and maintain IG for their organizations.

This guide assumes familiarity with the following topics:

  • Hypertext Transfer Protocol (HTTP), including how clients and servers exchange messages, and the role that a reverse proxy (gateway) plays

  • JavaScript Object Notation (JSON), which is the format for IG configuration files

  • Managing services on operating systems and application servers

  • Configuring network connections on operating systems

  • Managing Public Key Infrastructure (PKI) used to establish HTTPS connections

  • Access management for web applications

Depending on the features you use, you should also have basic familiarity with the following topics:

  • Lightweight Directory Access Protocol (LDAP) if you use IG with LDAP directory services

  • Structured Query Language (SQL) if you use IG with relational databases

  • Configuring AM if you use password capture and replay, or if you plan to follow the OAuth 2.0 or SAML 2.0 tutorials

  • The Groovy programming language if you plan to extend IG with scripts

  • The Java programming language if you plan to extend IG with plugins, and Apache Maven for building plugins

Example installation for this guide

Unless otherwise stated, the examples in this guide assume the following installation:

  • IG accessible on http://ig.example.com:8080 and https://ig.example.com:8443, as described in Quick install.

  • Sample application installed on http://app.example.com:8081, as described in Use the sample application.

  • AM installed on http://am.example.com:8088/openam, with the default configuration.

If you use a different configuration, substitute in the procedures accordingly.

Set up AM

This documentation contains procedures for setting up items in AM that you can use with IG. For more information about setting up AM, refer to the Access Management docs.

Authenticate an IG agent to AM

From AM 7.3

When AM 7.3 is installed with a default configuration, as described in Evaluation, IG is automatically authenticated to AM by an authentication tree. Otherwise, IG is authenticated to AM by an AM authentication module.

Authentication chains and modules were deprecated in AM 7. When they are removed in a future release of AM, it will be necessary to configure an appropriate authentication tree when you are not using the default configuration.

For more information, refer to AM’s Authentication Nodes and Trees.

This section describes how to create an authentication tree to authenticate an IG agent to AM. The tree has the following requirements:

  • It must be called Agent

  • Its nodes must pass the agent credentials to the Agent Data Store Decision node.

When you define a tree in AM, that same tree is used for all instances of IG, Java agent, and Web agent. Consider this point if you change the tree configuration.

  1. On the Realms page of the AM admin UI, choose the realm in which to create the authentication tree.

  2. On the Realm Overview page, click Authentication > Trees > Create tree.

  3. Create a tree named Agent.

    The authentication tree designer is displayed, with the Start entry point connected to the Failure exit point, and a Success node.

    The authentication tree designer provides the following features on the toolbar:

    Button Usage
    Trees auto layout

    Lay out and align nodes according to the order they are connected.
    Trees full screen

    Toggle the designer window between normal and full-screen layout.
    Trees delete node

    Remove the selected node. Note that the Start entry point cannot be deleted.

  4. Using the Filter bar, find and then drag the following nodes from the Components panel into the designer area:

    • Zero Page Login Collector node to check whether the agent credentials are provided in the incoming authentication request, and use their values in the following nodes.

      This node is required for compatibility with Java agent and Web agent.

    • Page node to collect the agent credentials if they are not provided in the incoming authentication request, and use their values in the following nodes.

    • Agent Data Store Decision node to verify the agent credentials match the registered IG agent profile.

    Many nodes can be configured in the panel on the right side of the page. Unless otherwise stated, do not configure the nodes and use only the default values.

  5. Drag the following nodes from the Components panel into the Page node:

    • Username Collector node to prompt the user to enter their username.

    • Password Collector node to prompt the user to enter their password.

  6. Connect the nodes as follows and save the tree:

    A tree that can be used to authenticate an agent to AM.

Register an IG agent in AM 7 and later

In AM 7 and later versions, follow these steps to register an agent that acts on behalf of IG.

  1. In the AM admin UI, select the top-level realm, and then select Applications > Agents > Identity Gateway.

  2. Add an agent with the following configuration, leaving other options blank or with the default value:

    • For SSO

    • For CDSSO

    • Agent ID : ig_agent

    • Password : password

    • Agent ID : ig_agent

    • Password : password

    • Redirect URL for CDSSO : https://ig.ext.com:8443/home/cdsso/redirect

    • Login URL Template for CDSSO: Configure this property to direct login to a custom URL instead of the default AM login page.

Register an IG agent in AM 6.5 and earlier

In AM 6.5 and earlier versions, follow these steps to register an agent that acts on behalf of IG.

  1. In the AM admin UI, select the top-level realm, and then select Applications > Agents > Java (or J2EE ).

  2. Add an agent with the following configuration, leaving other options blank or with the default value:

    • For SSO

    • For CDSSO

    • Agent ID : ig_agent

    • Agent URL : http://ig.example.com:8080/agentapp

    • Server URL : http://am.example.com:8088/openam

    • Password : password

    • Agent ID : ig_agent_cdsso

    • Agent URL : http://ig.ext.com:8080/agentapp

    • Server URL : http://am.example.com:8088/openam

    • Password : password

    • Login URL Template for CDSSO: Configure this property to direct login to a custom URL instead of the default AM login page.

  3. On the Global tab, deselect Agent Configuration Change Notification.

    This option stops IG from being notified about agent configuration changes in AM. IG doesn’t need these notifications.

  4. (For CDSSO) On the SSO tab, select the following values:

    • Cross Domain SSO : Deselect this option

    • CDSSO Redirect URI : /home/cdsso/redirect

  5. (For CDSSO and policy enforcement) On the SSO tab, select the following values:

    • Cross Domain SSO : Deselect this option

    • CDSSO Redirect URI : /home/pep-cdsso/redirect

Set up a demo user in AM

AM is provided with a demo user in the top-level realm, with the following credentials:

  • ID/username: demo

  • Last name: user

  • Password: Ch4ng31t

  • Email address: demo@example.com

  • Employee number: 123

For information about how to manage identities in AM, refer to AM’s Identity stores.

In routes that use AmService, IG retrieves AM’s SSO cookie name from the ssoTokenHeader property or from AM’s /serverinfo/* endpoint.

In other circumstances where you need to find the SSO cookie name, access http://am-base-url/serverinfo/*. For example, access the AM endpoint with curl:

$ curl http://am.example.com:8088/openam/json/serverinfo/*

External tools used in this guide

The examples in this guide use some of the following third-party tools: