How To

• 1: Call Manhattan Active® API
• 1.1: Authenticate to Manhattan Active® API
• 1.2: Call Manhattan Active® API from your code
• 1.3: Call Manhattan Active® API using Postman
• 1.4: Manhattan Active® API Reference
• 2: Configure login modes
• 3: Configure Data Stream for Google PubSub
• 4: Configure OAuth Clients
• 4.1: Access Management 1.0
• 4.2: Access Management 2.0

1 - Call Manhattan Active® API

Manhattan Active® API follows the REST architectural style. Our API has predictable resource-oriented URLs, accepts and returns JSON, and uses standard HTTP response codes, authentication, and verbs.

What’s next

1.1 - Authenticate to Manhattan Active® API

Before you begin

Before authenticating to an API, it is necessary to have an authorized user (OAuth resource owner) and an OAuth client.

Authentication information

Manhattan Active® API supports the following OAuth 2.0 authorization grants (OAuth flows):

• Authorization Code Grant (web server flow)
• Resource Owner Password Credentials Grant (password flow)

Please contact your organization’s Manhattan Active® Platform administrator for the following OAuth settings:

Authenticate from your code

For access to Manhattan Active® API from your software, please see Call from your code

Authenticate using Postman

For access to Manhattan Active® API from Postman, please see Call using Postman

What’s next

To learn more about calling an individual Manhattan Active® API, please see the REST API documentation in our product sites:

• Manhattan Active® Omni
• Manhattan Active® Supply Chain

1.2 - Call Manhattan Active® API from your code

This how-to guide will walk you through a very simple Python command line utility (CLI). The utility will obtain an access token for Manhattan Active® API using the OAuth 2.0 Resource Owner Password Credentials Grant. That token will then be used to call the following to get information for the authenticated user:

GET /api/organization/user/allDetails/userId/

Before you begin

Before beginning, please assemble the authentication information.

Obtain an access token

The OAuth 2.0 Resource Owner Password Credentials Grant (direct access) may be used to obtain an API access token. The token endpoint may be called as follows:

def access_token(client_id, client_secret, token_url, username, password):
    """Return access token for Manhattan Active® API using the resource owner password credentials grant

    Conforms to https://datatracker.ietf.org/doc/html/rfc6749#section-4.3

    Must authenticate to token endpoint with client credentials:
    https://datatracker.ietf.org/doc/html/rfc6749#section-3.2.1

    Args:
      client_id (str): client identifier
      client_secret (str): client password
      token_url (str): endpoint to obtain access token
      username (str): the resource owner username
      password (str): the resource owner password

    Returns:
      string: access token

    Raises
       HTTPError:  http error
    """

    # Access Token Request:  https://datatracker.ietf.org/doc/html/rfc6749#section-4.3.2
    response = requests.post(token_url, data={
        "grant_type": "password",
        "username": username, "password": password},
        auth=(client_id, client_secret))
    response.raise_for_status()
    return response.json()["access_token"]

Call an API

To call the API, obtain an access token above and place it in the Authorization header as a Bearer token:

url = api + "/organization/api/organization/user/allDetails/userId/" + username

response = requests.request(
    "GET", url, headers={'Authorization': 'Bearer ' + token}, data={})
response.raise_for_status()

print(json.dumps(response.json(), indent=2))

Run the code

Download the source code

Download the user.py python source code.

Install requests module

python3 -m pip install requests==2.27.1 

Set environment variables

Environment variables may be used to store common information:

For example:

export ACTIVE_USERNAME=user@example.com
export ACTIVE_CLIENT_ID=omnicomponent.1.0.0

Run CLI

Run the user.py script to obtain information for the authenticated user.

# See help for getting user info
python3 user.py -h

# Sample call (assumes ACTIVE_PASSWORD and ACTIVE_CLIENT_SECRET environment variables set)
python3 user.py \
 -c omnicomponent.1.0.0 \
 -t https://<environment>-auth.omni.manh.com/oauth/token \
 -u user@system.com \
 -a https://<environment>.omni.manh.com

Troubleshooting

If you receive a 400 Client Error: for url: https://...-auth.omni.manh.com/oauth/token, then your username and password are invalid for the authorization server.

1.3 - Call Manhattan Active® API using Postman

This guide will walk you through the steps for invoke an example REST API exposed by Manhattan Active®. The steps below will also assist you in establishing the authorization using OAuth v2.0 for invoking the API.

Before You Begin

• Download and install Postman or an equivalent tool of your choice. If you already have Postman installed, update it to v9.0.9 or newer.
• You will need the following information from the administrator who manages the implementation of Manhattan Active® applications for you:
  1. Application URL such as https://<unique_id>.omni.manh.com or https://<unique_id>.sce.manh.com or https://<unique_id>.scp.manh.com. We will use https://example.omni.manh.com for this document.
  2. Authorization Server URL such as https://<unique_id>-auth.omni.manh.com or https://<unique_id>-auth.sce.manh.com or https://<unique_id>-auth.scp.manh.com. We will use https://example-auth.omni.manh.com for this document.
  3. Values of client_id and client_secret parameters as configured by your administrator. A default client_id for Postman is automatically created with value postman.1.0.0. The administrator can look up the value of the respective client_secret. We will use aQsuVkh24SAp8MYr as the value of client_secret for this document.
  4. A valid username and password for you to authenticate yourself. We will use jerrythomas@example.com and p455w0rd respectively as the username and password for this document.
• As a sample REST API, we will use the endpoint that returns the details of your user. You may replace it with any other REST API that you have access to.

Steps

The step-by-step instructions below include the steps to obtain the authorization token for invoking the target REST API, followed by the invocation of the API.

Obtaining the Authorization Token

1. Open Postman and click on “New”

2. In the pop-up dialog, select “HTTP Request”

3. Click on the “Authorization” tab in the request section under “Untitled Request”

4. Click on the “Type” drop-down and select “OAuth v2.0”.

5. In the right-hand section, scroll down to the sub-section titled “Configure New Token”, and enter the values as shown below:

1. Token Name: my-first-auth-token
2. Grant Type: Authorization Code
3. Callback URL: https://www.getpostman.com/oauth2/callback
4. Auth URL: https://example-auth.omni.manh.com/oauth/authorize
5. Access Token URL: https://example-auth.omni.manh.com/oauth/token
6. Client ID: postman.1.0.0
7. Client Secret: aQsuVkh24SAp8MYr
8. Scope: leave empty
9. State: leave empty
10. Client Authentication: Send as Basic Auth header

Click the “Get New Access Token” button to fetch the token.

6. Sign in with your username and password in the pop-up dialog. The pop-up may look different from the screenshot shown below depending on the Manhattan Active® application you are using.

7. Upon a successful login, Postman will display the access token in the UI, and give you an option to use it.

8. In the “Current Token” section of your REST API request, select my-first-auth-token from the list to make use of the token you obtained.

Invoking the REST API call

1. To invoke the API to get the details of your username, set the URL to the value shown below:

http://example.omni.manh.com/organization/api/organization/user/allDetails/userId/jerrythomas@example.com

Set the HTTP method to GET. The inputs will look like this:

Verify that the “Access Token” is set to my-first-auth-token in the “Current Token” section.

Click on the “Send” Button.

2. The API response in JSON format will be displayed in the section on the bottom

You can inspect the response content and headers by switching the response tabs.

Pro Tip

With the access token, you can also invoke the API using curl as a command line option instead of Postman:

curl -L -X GET  -H 'Authorization: Bearer eyJhbGciOiJSUzI1Ni...' 'http://example.omni.manh.com/organization/api/organization/user/allDetails/userId/jerrythomas@example.com'

Learn More

• Concept Guides
• Quick Starts

1.4 - Manhattan Active® API Reference

2 - Configure login modes

Objective

Manhattan Active® Platform Auth Server has administrative user interface to configure or modify several aspects of security such as the authentication and login modes and OAuth client setup. This document describes how you can configure the login modes for authenticating to Manhattan Active® Platform.

Before You Begin

You will need access to the Manhattan Active® Platform application, and a System Administrator role to configure security properties in the Auth Server user interface.

Manhattan Active® Cloud standardizes authorization with OAuth2 for all inbound HTTP traffic. For identity provisioning and active directory integration, Manhattan Active® Cloud supports a variety of authentication modes with Open ID and SAML:

• External Authentication Mode with Open ID is a login configuration where the user is exclusively authenticated via an external Identity Provider using Open ID as the identity protocol. In this mode, all users are maintained by the external Identity Provider.
• External Authentication Mode with SAML is a login configuration where the user is exclusively authenticated via an external Identity Provider using SAML as the identity protocol. In this mode, all users are maintained by the external Identity Provider.
• Mixed Authentication Mode with User Discovery is a login configuration where the user identity is managed either in the Native authentication source by Manhattan Active® Cloud, or by an External Identity Provider with Open ID or SAML. The determination for the authentication mode for the actual user is made in real-time when the user attempts to log in, based on the user’s username. In this mode, the user is first prompted to enter their username, and the UI then redirects to the authentication mode configured for that user.
• Native Authentication Mode is a login configuration where the user is exclusively authenticated by Manhattan Active® Cloud. In this mode, the user directory, and credentials (in the form of usernames and passwords) are maintained in Manhattan Active® Cloud database. Users that are maintained with the native authentication mode are referred to as native users to distinguish them from the users that are maintained in the corporate directory. If no other authentication mode is configured, Native Authentication Mode is the default configuration.

Manhattan supports known Open ID and SAML Identity Providers for configuring as the External Authentication Mode. Integration with the IDPs listed below has been tested and supported:

• Microsoft Azure AD: Open ID & SAML
• ADFS: Open ID & SAML
• Okta: Open ID & SAML
• CA SiteMinder: Open ID
• Ping Identity: Open ID
• MITREid: Open ID
• KeyCloak: Open ID & SAML
• IBM Security Access Manager: SAML

Do note, that IDPs may have their nuances - not all IDPs support the full Open ID and/or SAML standards or may support additional features that are not part of the standards. In such cases, Manhattan offers technical support and consulting to accommodate the testing and validation necessary for a specific IDP to fully integrate with Manhattan Active® Cloud.

To access the administration UI, go to your Auth Server URL (https://<stack_name>-auth.<domain_name>). After you log in, you should see the Administration option as a button that you can use to navigation to the administration UI:

The admin panel is accessible only to the users with the System Administrator role.

There are two main concepts that are important to understand:

Authorization providers

An authorization provider is a configuration for an external identity provider. For example, you could have the following authorization providers stored in the Auth Server configuration:

• OpenID with Okta
• Backup OpenID with Okta
• OpenID with Azure
• SAML external IDP

One of these providers could be used when setting the identity type to external or mixed.

Login mode

The login mode defines how your users will authenticate in the Auth Server.

• Active login mode will be loaded on the Auth Server startup and defines how the users authenticate.
• Pending login mode will be marked when setting a new login mode. If there is a pending login mode when the Auth Server starts it will be marked as Active and the previous Active login mode will be marked as Inactive.

Steps

1. Click on Configure Login Mode

2. Select the identity type between database, external or mixed and click Next

3. If you choose external or mixed in Step 2, it will show the list of available providers. You can also add new ones. Click on Add Authentication Provider to add a new one and select the protocol.

4. You can also click Show Templates to see predefined providers

5. Select a template

6. This will copy the pre-configured parameters, you will have to provide a unique Name that cannot be edited later. Click on Save button

7. This will create a provider. You can view it under Authentication Providers tab

8. The new login mode will be Pending until the next restart of the Auth Server.

Global Properties

There are other properties that are not exclusive of either OpenId or SAML. In the Global properties tab you can edit these properties.

Note that these properties will only be loaded when manh.security.dbmode=true and a proper login mode is configured. Properties can be of three types: string, number or boolean.

Learn More

• Concept Guides
• Quick Starts

Author

• Shipra Choudhary: Senior Software Engineer, Security, Manhattan Active® Platform, R&D.

3 - Configure Data Stream for Google PubSub

Objective

This guide will walk you through the steps for enabling the Data Streaming from Manhattan Active® to Google Cloud Pub/Sub endpoint owned and managed by the customer. The below steps also guides authorization and network access required to post events to this Pub/Sub endpoint.

Gravina is Manhattan Active® Platform’s data replication solution to provide most real-time data streaming service to target systems. It provides set of distributed services that capture row-level changes in databases so that applications can see and respond to those changes. DataStream utilizes JSON for exchanging data between internal & external components.

Google Cloud Pub/Sub provides messaging between applications. Cloud Pub/Sub is designed to provide reliable, many-to-many, asynchronous messaging between applications. Publisher applications can send messages to a “topic” and other applications can subscribe to that topic to receive the messages.

Before You Begin

• Deployment model:

  • The current scope of this document considers the target Google Cloud Pub/Sub, is owned and managed by Customer. To meet customer business and preferences, we continue to extend our ability to support multiple deployment models.

• Target Google Cloud Pub/Sub configuration:

  • Google Project: Customer owned Google project.
  • Region/Location: Google Cloud Pub/Sub is Global Service. but, we prefer to have both producer and subscriber in the same region.
  • Pub/Sub topic name ( Optional ): Any preferred topic name to use. By default, Manhattan Active® uses the default gravina_cdc_stream_<customer

• Network Connectivity & whitelist:

  • Pub/Sub Targets: At present we support Google Cloud Pub/Sub.
  • Network Traffic: Since both Source and targets are managed in GCP, traffic is routed through Google backbone interface.
  • Access whitelist : If Customer Google Cloud Pub/Sub endpoint is allowed to connect only from the trusted IP sources, then Manhattan Active® Platform NAT range needs to whitelist in Customer network.

• Data inclusion list for DataStreaming

  • By default, Gravina ignores all tables for DataStreaming unless we define to include in replicator configuration.
  • Get the list of database schemas and tables required to enable for DataStream to target system.

• Subscription Strategy:

  • By default, gravina creates the default subscription which can be used by Customer Application to process the data stream events from Pub/Sub
  • Customer owns the configuration of target application subscription(s) and attach to Pub/Sub topic and processing of messages.

Steps

• Generate service-account & Key:

  • Login to Google Cloud Console –> Go to Google Cloud Project –> IAM & Admin
    • Service Accounts
    • Create Service Account : Ex: gravina-pubsub-sa
    • Go to “Keys”
    • ADD KEY –> Create New Key –> Select Key Type : JSON –> Create –> The JSON Key file gets downloaded.
    • Provide the JSON Key file to Manhattan CLoud Ops Team in secured way.

• Grant Pub/Sub Editor permissions to service-account:

  • Login to Google Cloud Console –> Go to Google Cloud Project –> IAM & Admin
    • IAM
    • Click on “ADD”
    • Give the gravina-pubsub-sa as principle & Role as “Pub/Sub Editor”
    • Save

• Provide the configuration details to Manhattan Cloud team for replicator configuration.

  • Send the Service account “JSON Key file” which have the following details
    • project_id
    • service-account-id
    • Key & secret
  • Pub/Sub Topic Name ( If any explicitly needs to configure )
  • Inclusion Table List ( If only required specific tables )

• Configure Network Access Whitelist in Customer Google Cloud project:

  • If the Customer Google project is restricted access, then Manhattan team provide the NAT IP range from which the traffic will be initiated to Pub/Sub endpoint.
  • Customer needs to whitelist the NAT IP range in Google Cloud Project to allow the access.

• Target Pub/Sub topic Subscription:

  • The configuration of subscription to topic and processing of messages are completely managed by Customer based on customer business needs.
  • By default, gravina creates the subscription which can be configured and used by Customer Application to process the data stream events from Pub/Sub topic.

• Monitoring & Alerts:

  • Google Cloud Console provides the default monitoring statistics & metrics.
    • Publish message request count.
    • Average message size.
    • Unacked message count.
    • Oldest unacked message age.
  • Customer responsible to configure the required monitoring and Alerting based on the business needs.

Learn More

• Concept Guides
• Quick Starts

Authors

• Srinivasa Rao Jammula: Director, Manhattan Active® Platform, R&D.

4 - Configure OAuth Clients

Objective

Manhattan Active® Platform Access Management has administrative screens that manage various aspects of security, including authentication, login modes, and OAuth client setup. Documents that describe OAuth client setup for external integration are based on the version of Access Management.

Identifying Access Management Version

You can identify the version of Access Management based on its URL.

When you enter the environment hostname or the Access Management hostname as the address in your browser, you will be redirected to the login page of the Access Management server.

• https://<unique_id>.<domain_name> (environment hostname)
• https://<unique_id>-auth.<domain_name> (Access Management hostname)

The URL of the login page may be used to identify the version of Access Management -

4.1 - Access Management 1.0

Objective

Manhattan Active® Platform Auth Server has an administrative user interface to configure or modify several security aspects, such as the authentication and login modes and OAuth client setup. This document describes how to set up OAuth clients for external integration and calling the REST API.

Before You Begin

You will need access to the Manhattan Active® Platform application and a System Administrator role to configure security properties in the Auth Server user interface.

To access the administration UI, go to your Auth Server URL (https://<unique_id>-auth.<domain_name>). After you log in, you should see the Administration option as a button that you can use to navigate to the administration UI:

The admin panel is accessible only to the users with the System Administrator role.

Clicking on the “OAuth Clients” option in the menu will take you to the UI to manage the configuration for OAuth Clients.

The UI has two sections in it:

• Custom clients: includes the clients that are created by users. These clients can be edited and deleted.
• Default clients: pre-configured clients. These cannot be edited but cloned.

Steps

1. Go to Custom clients tab and click on the Add button
2. Add client details like Client Id and Client secret. The value of the Client secret will be encoded and stored. Optionally, you can set the value of Access token validity and Refresh token validity. Select appropriate Scopes and Grants for this client. For each Scope selected, you have the option if you’d like to auto-approve the requests. You can add one or more Redirect URIs and Resource Ids to this client.
3. Hit the Save button, and this creates a new client.

Learn More

• Concept Guides
• Quick Starts

Author

• Shipra Choudhary: Senior Software Engineer, Security, Manhattan Active® Platform, R&D.

4.2 - Access Management 2.0

Objective

Manhattan Active® Platform Access Management 2.0 has an administrative user interface to configure or modify several security aspects, such as the authentication and OAuth client setup. This document describes how you can set up OAuth 2.0 clients for external integration and for calling the REST API.

Before You Begin

You will need access to the Manhattan Active® Platform application and a Maactive System Administrator role to configure security properties in the Access Management 2.0 administration user interface.

To access the administration UI, go to your Access Management 2.0 URL (https://<unique_id>-auth.<domain_name>/auth/admin/maactive/console/). After you log in, administration UI will look something like this:

The panel is accessible only to the users with the Maactive System Administrator role.

Managing OpenID Connect clients
Clients are entities that request authentication on behalf of a user. Clients come in two forms. The first type of client is an application that wants to participate in a Single Sign On. These clients are only looking for security from Access Management 2.0. The other type of client is one that requests an access token so that it can invoke other services on behalf of the authenticated user.

Steps

Let’s see how you can create a new OpenID Connect client.

1. Under the Manage menu, click on Clients.

   

2. Click on Create client.

3. Under General Settings, leave the Client type set to OpenID Connect

   

4. Enter a Client ID
   This is an alphanumeric string that specifies ID reference in URI and tokens.

5. Enter a Name for this client.
   Specify the display name of this client.

6. You can optionally give a description of this client in the Description field.

7. Click on Save. This action will create a client for you.

8. Next, under Capability config, we have a toggle button to enable/disable Client authentication. This setting depends on the type of OIDC you would like to create.
     Select ON if - the server-side clients perform browser logins and require client secrets when requesting for Access Token.
     Select OFF if - the client-side clients perform browser logins where secrets cannot be kept safe.

   

9. Enable/Disable the Authorization button for fine-grained authorization for clients.

10. Select Authentication flow as needed. Default ones are already enabled.

11. Click on Next.

12. Enter the Valid redirect URIs as needed.
    This is the place where the browser redirects after a successful login.

    

13. You will be redirected to the basic client configuration page. You can review or modify any other details needed on this page.

    

14. In case the Client Authentication was set to true in step 8, you will see a Credentials tab. Click on it. Make note of the Client Secret to be used during the authentication of this created client against Access Management 2.0.

    

Learn More

• Concept Guides
• Quick Starts

Author

• Shipra Choudhary: Senior Software Engineer, Security, Manhattan Active® Platform, R&D.