How To

• 1: Call Manhattan API
• 1.1: Authenticate to Manhattan API
• 1.2: Call Manhattan API from your code
• 1.3: Call Manhattan API using Postman
• 1.4: Manhattan 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
• 5: Configure Identity Providers
• 5.1: IDP Initiated Login with Okta and AccessManagement 2.0 via SAML 2.0
• 5.2: Configure Azure Entra ID SAML 2.0 IdP for JIT & Non JIT
• 5.3: Configure Okta SAML 2.0 IdP for JIT
• 5.4: Configure Okta OIDC IdP for JIT
• 5.5: Configure Azure Identity Providers
• 6: Clearing IDP Assocations for Users with Access Management 2.0 API
• 7: Configuring Proof Key for Code Exchange (PKCE) between AM 2.0 and Okta
• 8: Handling IdP Key Rotation in Access Management

1 - Call Manhattan API

Manhattan 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 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 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 ActivePlatform™ administrator for the following OAuth settings:

Authenticate from your code

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

Authenticate using Postman

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

What’s next

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

• Supply Chain Execution
• Unified Commerce and Enterprise Promise & Fulfill

1.2 - Call Manhattan 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 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 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 <Consult your Administrator to obtain one>
      client_secret (str): client password <Consult your Administrator to obtain one>
      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=<Custom_Client_Id_Created_By_Your_Administrator>

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 <Consult your Administrator to obtain the client_id> \
 -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 API using Postman

This guide will walk you through the steps for invoking an example REST API exposed by Manhattan. 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 v11.x or newer.
• You will need the following information from the administrator who manages the implementation of Manhattan 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. Your administrator will need to create a custom client_id (documented elsewhere already) to be used with Postman. The administrator can look up the value of the respective client_secret. We will refer the client_secret as <client_secret> as the value of client_secret for this document. Please use your own client_secret value exclusive for your use cases.
  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. These are not valid credentials at all. Please use valid credentials for your purposes.
• 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: <client_id> should be created by your Administrator
7. Client Secret: <client_secret> should be created by your Administrator
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 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 API Reference

To learn more about calling an individual Manhattan API, please see the API documentation in our solution sites:

• Supply Chain Execution
• Unified Commerce and Enterprise Promise & Fulfill
• ActivePlanning™
• ActivePlatform™

A complete reference for Manhattan API across all solutions is available in the following site:

• All API Reference

2 - Configure login modes

Objective

ActivePlatform™ 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 ActivePlatform™.

Before You Begin

You will need access to the ActivePlatform™ application, and a System Administrator role to configure security properties in the Auth Server user interface.

Manhattan Cloud standardizes authorization with OAuth2 for all inbound HTTP traffic. For identity provisioning and active directory integration, Manhattan 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 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 Cloud. In this mode, the user directory, and credentials (in the form of usernames and passwords) are maintained in Manhattan 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 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: Tech Lead, Application Security, ActivePlatform™, 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

ActivePlatform™ 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

ActivePlatform™ 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 ActivePlatform™ solution 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: Tech Lead, Application Security, ActivePlatform™, R&D.

4.2 - Access Management 2.0

Objective

ActivePlatform™ Access Management 2.0 (AM 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 ActivePlatform™ solution and a System:SystemAdministrator or System:KeycloakAdministrator role to be able to configure security properties in the AM 2.0.

To check your access in the administration UI, go to your AM 2.0 URL (https://<unique_id>-auth.<domain_name>/auth/admin/maactive/console/) and login. Administration UI will look something like this:

Note: The panel is accessible only to the users with the System:SystemAdministrator or System:KeycloakAdministrator 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 AM 2.0. The other type of client is the one that requests an access token so that it can invoke other services on behalf of the authenticated user.

Note: In case you have a custom client that you might have created in Access Management 1.0, then you will see that this client should already be migrated to Access Management 2.0. In this case, you will only need to perform client secret updation activity for the same client in the Access Management 2.0 portal. If you have the client’s secret handy, then you can go to the Credentials tab of this client and update the credentials.

If you do not have the secret value, you can create a custom client following the below steps.

Steps

There are two ways to create a new OpenID Connect client. First way is simpler one using the REST API. The second one is creating it using AM 2.0 admininstration UI.

I. Creating client using REST API

Creating a custom client using this approach is much easier and a recommended approach. It does the standard configuration of a client and creates Manhattan specific custom user attributes that will be populated in JWT token for this particular client. In case you have additional configuration requirements in a custom client, please use this approach to create a new client and then login to the administration UI and edit the configurations further.
Below is an example of a REST API that will create a custom client with password and auth-code grant.

Request

POST https://<stack-name>-auth.<domain-name>/clients

Header Parameter

Basic Auth header

Content-Type: application/json

{
    "client_id": "testclient",
    "client_secret": "xxxxxx",
    "scope": ["openid", "testscope"],
    "authorized_grant_types": ["password", "authorization_code"],
    "redirect_uri": "https://www.getpostman.com/oauth2/callback",
    "access_token_validity": 1800
}

Note: access_token_validity is a number field indicating token expiry in seconds. i.e. a value of 1800 represents 30 minutes. Max allowed value is 24 hrs (1 Day).

Example Responses

🟢 Success:

HTTP Status: 200

Response Text: Client (testclient) created successfully under maactive realm.

🔴 Error:

HTTP Status: 401: Authentication Failure. Make a request using valid token in authorisation header.

HTTP Status: 403: Authorization Failure. Access token being used in Authorisation header should belong to a user having SystemAdministrator or KeycloakAdministrator role in Org DB.

HTTP Status: 400: Bad request/Validation error

HTTP Status: 500: Internal Server Error

Response Text: Client (testclient) creation failed.

II. Creating client using the AM 2.0 admininstration UI

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 an Access Token.
    Select OFF if the client-side clients perform browser logins where secrets cannot be kept safe.

   

9. Select Authentication flow as needed. Hover over the question mark ? icon to show a tooltip text that describes which AM 2.0 Authentication Flow Maps to which OAuth2 Grant Type.

10. Click on Next.

11. Enter the Valid redirect URIs as needed.
    This is the place where the browser redirects after a successful login.
    NOTE: If you want to use Postman to get an access token using this client for Authorization Code Grant, configure this URL in the Valid redirect URI field - https://www.getpostman.com/oauth2/callback

    

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

    

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

    

14. The next step is to add claims that will be sent as part of the access token, or to be returned during the user info endpoint call. Go to the Client scopes tab. A dedicated scope will be automatically created for this client. Click on this scope.

    

15. This scope will initially be empty. Here is where we need to add the user attributes. Click on Configure a new mapper.

    

16. From this list of mappings, select the User Attribute mapper.

    

17. In this example, we will see how to configure the “sub” attribute.
    Enter Name as sub.
    Enter User Attribute as sub.
    Enter Token Name Claim as sub.
    Select Claim JSON Type as String.
    Toggle ON Add to access token.
    Hit Save.

    

    We can see that the sub claim is now added to this client’s dedicated scope.

    

18. Similarly, you can add other claims as per application requirements. To add another claim, click the Add Mapper dropdown and select the By configuration option.

    

19. Repeat the same steps from 16-18 to map all the attributes (similar to sub attribute) as listed in the table below.

    User Attribute	Token Claim Name	Claim Type	Present in Access Token	Present in ID Token	Multivalued
    sub	sub	String	TRUE	FALSE	FALSE
    organization	organization	String	TRUE	FALSE	FALSE
    userOrgs	userOrgs	String	TRUE	FALSE	TRUE
    bulkOrganizationAccess	bulkOrganizationAccess	boolean	TRUE	FALSE	FALSE
    userBusinessUnits	userBusinessUnits	String	TRUE	FALSE	TRUE
    excludedUserBusinessUnits	excludedUserBusinessUnits	String	TRUE	FALSE	TRUE
    bulkBusinessUnitAccess	bulkBusinessUnitAccess	boolean	TRUE	FALSE	FALSE
    userDefaults	userDefaults	JSON	TRUE	FALSE	TRUE
    userLocations	userLocations	JSON	TRUE	FALSE	TRUE
    largeStoreAccess	largeStoreAccess	boolean	TRUE	FALSE	FALSE
    locale	locale	String	TRUE	TRUE	FALSE
    edge	edge	String	TRUE	FALSE	FALSE
    tenantId	tenantId	String	TRUE	FALSE	FALSE
    userTimeZone	userTimeZone	String	TRUE	FALSE	FALSE
    authorities	authorities	String	TRUE	FALSE	TRUE
    reporting_roles	reporting_roles	String	TRUE	FALSE	TRUE
    user_name	user_name	String	TRUE	FALSE	FALSE

20. Navigate to Scope tab of this dedicated scope and toggle OFF the Full scope allowed option.

Learn More

• Concept Guides
• Quick Starts

Author

Shipra Choudhary: Tech Lead, Security, ActivePlatform™, R&D.

5 - Configure Identity Providers

Objective

ActivePlatform™ Access Management has administrative screens that manage various security aspects, including authentication, login modes, OAuth client setup, and Identity Provider Configuration. Documents that describe various flavors of Identity Provider Setup for external integration are based on the type of Identity Provider Integration Sought. There are two available:

• Azure Ad
• Okta.

Introduction

As a premier SaaS provider in the market, Manhattan prioritizes the security of its ActivePlatform™ software. In alignment with this commitment, we are pleased to announce the release of an enhanced version of the Manhattan Identity & Access Management (IAM) system, named Access Management 2.0. This updated version not only delivers enhanced security features but also offers improved integration capabilities with customer-owned identity platforms such as Azure and Okta. Previously, the ActivePlatform™ supported Just In Time (JIT) user provisioning exclusively for the SAML 2.0 protocol. With Access Management 2.0, JIT support has been extended to include the OpenID Connect (OIDC) protocol as well. The subsequent sections provide comprehensive guidance, including illustrative screen captures, on configuring Access Management 2.0 alongside Azure and Okta as external Identity Providers (IdPs) for both JIT and non-JIT use cases within the OIDC protocol.

Assumptions

• The configuration screens shown for both Azure and Okta could change with time.
• This document will be kept in alignment when that happens.
• If further assistance is needed during configuring Access Management 2.0 for OIDC JIT/Non-JIT, please reach out to your Manhattan Services Representatives to seek help and report any issues with this document.

Special Note

• Access Management 2.0 creates a Local User for every external Identity Provider (IdP) User.
• After creation in the JIT Flow, such external Users are also created in the Organization Database.
• If, subsequently, the same user is deleted and recreated through the JIT process, to remove roles/orgs/locations, such deletion is:
  • First, not needed
  • Second, it blocks the same user from logging in because Access Management 2.0 cannot find the Id of the internal user
• To proceed, usually add and remove roles/org/location, and the JIT process will update the same user in the Organization DB.
• If such users must be deleted, please reach out to Manhattan Operations for a subsequent cleanup in the Access Management 2.0 DB.

5.1 - IDP Initiated Login with Okta and AccessManagement 2.0 via SAML 2.0

Introduction

In AccessManagement 2.0, an IDP-initiated login enables users to begin the authentication process directly from an Identity Provider (IDP), like Okta, instead of a Service Provider (SP) or application. In this flow, the IDP sends a SAML authentication response to AccessManagement 2.0, which verifies the response and grants the user access to the target application. Common in SAML-based single sign-on (SSO) configurations, this approach allows users to log in from a central IDP-managed portal, streamlining access across applications and improving user experience with a single, centralized login point. Here, we will detail how to set up an IDP-initiated login between Okta and AccessManagement 2.0 via SAML 2.0. The section is segregated into two parts: the first section is related to changes on AccessManagement 2.0’s side, and the second section is related to changes on Okta’s side. As a pre-requisite, please have the SAML 2.0 IDP created. To create an OKTA SAML2.0 IDP, please follow the steps mentioned here if needed.

Section 1: Changes on AccessManagement 2.0’s side

Step 1

AccessManagement 2.0 needs to understand how to handle SAML assertions from Okta, which is accomplished by exporting and importing the correct metadata and establishing a Client. Log in to the admin console. Go to your already created IDP and click on the SAML 2.0 Service Provider Metadata link. Copy and save the contents from the metadata link in a .xml file.

Figure: Sample content of SAML 2.0 service provider metadata

Step 2

Go to the Clients section of the maactive realm and click Import client. On the next page, click Browse and import the .xml file exported in Step 1. Then, scroll down and click Save.

Step 3

Go to the IDP-Initiated SSO URL name on the same page and give a name to your app.

Step 4

Go to IDP Initiated SSO Relay State and enter the stack URL.

Step 5

Ensure that Force POST binding is On. Scroll down and disable Front channel logout. Once done, click Save.

Step 6

Scroll to the top and click the Advanced section. Scroll down and add the stack URL in the Assertion Consumer Service POST Binding URL.

Step 7

Remove content from Assertion Consumer Service Redirect Binding URL

Step 8

Remove the content of the Logout Service POST Binding URL.

Step 9

Scroll down and select Browser Flow as MA first broker login from the dropdown. Click Save. This concludes all changes at AccessManagement 2.0’s end.

Section 2: Changes on IDP’s (Okta) end

Step 1

Log in to Okta, go to your application, and click on the General tab. Scroll down and click on Edit in the SAML settings section.

Step 2

Click Next in the General Settings of the Edit SAML Integration section.

Step 3

Compose the Single Sign On URL by entering the AssertionConsumerService (ACS) URL, followed by /clients/<name of your app>. The ACS URL can be obtained from the XML file imported in Step 2 of Section 1, and the app name is the name given in Step 3 of Section 1. This is the endpoint in AccessManagement 2.0 where the IDP sends the SAML assertion (authentication response) after a user has successfully authenticated.

Step 4

Ensure that the value of Audience URI (SP Entity ID) is the entityID. The entityID can be obtained from the XML file imported in Step 2 of Section 1. Also, enter the value of Default RelayState as the stack URL.

Step 5

On the same page, click the Show Advanced Settings section and scroll down. Look for Other Requestable SSO URLs and enter the AssertionConsumerService (ACS) URL. The ACS URL can be obtained from the XML file imported in Step 2 of Section 1. This step is necessary if the same IDP has to work for SP-initiated flow as well. This concludes all changes needed on IDP’s(Okta) end.

Authors

• Mustaque Rashid, Technical Lead, R&D-Cloud platform.
• Kaveen Jagadeesan, Technical Director - Software Engineering, R&D-Cloud platform.
• Binit Datta, Technical Director - Software Engineering, R&D-Cloud platform.

5.2 - Configure Azure Entra ID SAML 2.0 IdP for JIT & Non JIT

Objective

This page describes the Microsoft Entra ID SAML 2.0 setup with JIT and Non JIT flows.
It has a detailed step-by-step guide for registering an enterprise SAML 2.0 application in Microsoft Entra ID as an Identity Provider and configuring Access Management 2.0 as a Service Provider (SP) to enable SAML-based identity federation.

Introduction

Configuring Microsoft Entra ID as Identity Provider (IdP) with Access Management 2.0 (AM 2.0) as Service Provider (SP) using SAML 2.0 protocol.

This documentation provides a comprehensive guide to setting up and configuring Microsoft Entra ID (formerly Azure Active Directory) as the IdP and Access Management 2.0 as the SP using SAML 2.0 protocol. This setup enables secure single sign-on (SSO) capabilities for enterprise applications while leveraging the robust identity and access management features of Microsoft Entra ID and the flexibility of AM 2.0.

Additionally, this guide covers the implementation of Just-In-Time (JIT) provisioning, which automatically creates user accounts in Access Management 2.0 as they log in, streamlining user management and enhancing operational efficiency.

Before You Begin

You will need access to the ActivePlatform™ solution and a System:SystemAdministrator or System:KeycloakAdministrator role to be able to configure security properties in the AM 2.0.

To check your access in the administration UI, go to your AM 2.0 URL (https://<unique_id>-auth.<domain_name>/auth/admin/maactive/console/) and login. Administration UI will look something like this:

Note: The panel is accessible only to the users with System:SystemAdministrator or System:KeycloakAdministrator role.

Steps to achieve AM 2.0 integration with Microsoft Azure

There are 2 ways to achieve this integration. First way is simpler one using the REST API for making the configurations on AM 2.0 side. The second one is manually creating it using AM 2.0 admininstration UI. In both scenaios, configuration on Azure is still to be done manually.

Step 1: Create a New Enterprise Application in the Azure portal

1. Navigate to the Azure Portal.

2. Sign in using an account with administrative permissions for Microsoft Entra ID.

3. Click on the Enterprise Application icon.

   

4. Click on New Application.

   

5. Click on Create your own application.

   

6. Give a name to your application.

   

7. Select Integrate any other application you don’t find in the gallery (Non-gallery application) radio button.

8. Click Create. This creates a basic SAML application in the Azure portal and now you will land on its overview page.

   

9. After the application is created, click on Set up single sign-on tile.

   

10. Select SAML as the single sign-on method.

11. In the SAML Certificates tile, you will be able to see the App Federation Metadata URL field which has IDP metadata. Keep this URL handy for step 2.

Step 2: Create an IDP config in the AM 2.0 portal

There are 2 ways to create this config on AM 2.0 side. First way is much easier and a recommended approach using the REST API. The second one is manually creating it using AM 2.0 admininstration UI.

I. Creating IDP config using REST API

In case of taking this approach, the REST API will take care of all the configuration that is needed on AM 2.0 side, obviously except for any customisations that might be needed. You can skip steps 4, 6, 8 while using this approach.

Request

  POST https://<stack-name>-auth.<domain-name>/idps/saml
  Authorization: Bearer {access-token}
  Content-Type: application/json
  {
    "idpAlias": "testsaml",
    "displayName": "SAML IDP Test",
    "metadataUrl": "https://dev-58965664.okta.com/app/exk91wj32ekQdnvc55d7/sso/saml/metadata",
    "entityId": "https://localdocker:10191/auth/realms/maactive"
  }

Note: idpAlias is a unique value on AM 2.0 side. This alias forms a part of the redirect URL. entityId is SP entity ID.

Example Responses

🟢 Success:

• 200: Success

Response Text: Identity provider created successfully under maactive realm!

🔴 Error:

• 401: Authentication Failure — valid token required
• 403: Authorization Failure — token must have SystemAdministrator or KeycloakAdministrator role in Org DB
• 500: Internal Server Error

Response Text: Identity provider (testsaml) creation failed.

II. Creating IDP config using AM 2.0 UI

This is a slightly longer procedure and is not the recommended approach, owing to chances of manual errors.

1. Login to AM 2.0 Admin Console. Select the maactive realm.
   

   Note: In case you have Restricted Admin Access on AM 2.0, then use this URL:

   https://<stack_name>-auth.<domain_name>/auth/admin/maactive/console/
   

2. Click on the Identity Providers option from the left panel and select SAML v2.0 from the drop-down.

   

3. Enter the Alias. This will be the default display name on the login page.
   Please note that the Alias forms a part of the redirect URL. In case it does not reflect, you can create the Redirect URI yourself and keep the URL handy.
   Eg. if Alias is set as - samlazure
   Redirect URI - https://localdocker:8443/auth/realms/sample/broker/samlazure/endpoint

   

4. Optionally, enter Display Name. This is the name that will be displayed in case you need it to be different from the alias.

5. Take note of the Service provider entity ID value from the same page.

6. In the Service entity descriptor field, paste the URL you copied from step 2.9. If the URL is correct, you will see a green tick on the right.

7. Click on Add. This will create a basic SP configuration on AM 2.0 for this Azure application.

8. Scroll down and set the Want AuthnRequests signed option to be On.

   

9. Now scroll to the bottom of AM 2.0’s provider configuration page and select First Login Flow and Post Login Flow, if not already pre-selected.

   

10. Click on Save.

Step 3: Configure AM 2.0 details in Azure IDP

1. In the Single sign-on tab, edit the Basic SAML Configuration and fill in the Entity ID from step 2.5 in case you have created the config manually on AM 2.0. And in case you have created it using REST API, then you can simply open the configuration in console and fetch the values.

   

2. Copy the redirect URI from step 2.3 and paste it into the Add reply URL.

   

3. Hit the Save button on the top. You will see a confirmation message after doing so.

   

Step 4: Configure User.UserId Mapper on AM 2.0

Perform this step only if you have created IDP config on AM 2.0 manually. You can skip this step if you have created using REST API, as it already takes care of this config.

1. To add mappers in AM 2.0, click the Mappers tab on the same SP configuration page. Click on the Add mapper button.

   

2. Configure User.UserId mapper by filling in the fields as shown in the image below.

   

   Click on Save.

Step 5: Configure User.UserId Mapper on Azure

1. Now to add this attribute on the Azure IDP side, go to the Single sign-on tab and edit the Attributes & Claims tile.

   

2. Click on Add new claim and then add User.UserId as an attribute as shown below.

   

   

Step 6: Configure Mapping for JIT on AM 2.0 (this step is mandatory only if you would like to enable SAML JIT)

Perform this step only if you have created IDP config on AM 2.0 manually. You can skip this step if you have created using REST API, as it already takes care of this config.

1. To add mappers in AM 2.0, click the Mappers tab on the same SP configuration page. Click on the Add mapper button.

   

2. Similarly, configure the User.LocaleId mapper by filling in the fields as shown in the image below.

   

   Click on Save.

3. Similarly, configure User.PrimaryOrgId mapper by filling in the fields as shown in the image below.

   

   Click on Save.

4. Similarly, configure User.Roles mapper by filling in the fields as shown in the image below.

   

   Click on Save.

Step 7: Configure Mapping for JIT on Azure (this step is mandatory only if you would like to enable SAML JIT)

1. To add attributes on the Azure IDP side, go to the Single sign-on tab and edit the Attributes & Claims tile.

   

2. Click on Add new claim, then add the User.LocaleId, User.PrimaryOrgId, and User.Roles attributes individually.

   

Step 8: Additional attributes configuration

Perform this step only if you have created IDP config on AM 2.0 manually. You can skip this step if you have created using REST API, as it already takes care of this config.

In case additional attributes are needed, they can be configured as well. Below is a list of attributes that can be configured.\

You will have to pass these exact attribute names from Azure to receive on AM 2.0.

Attributes shown below can be configured on IDP, as well as SP.

Author

Shipra Choudhary: Tech Lead, Application Security, ActivePlatform™, R&D.

5.3 - Configure Okta SAML 2.0 IdP for JIT

Objective

This page describes the Okta SAML 2.0 setup with JIT and Non JIT flows.

Integrating Access Management 2.0 with Okta SAML 2.0

This section shows how to integrate Access Management 2.0 (AM 2.0) with Okta, where Okta will serve as the Identity Provider (IdP). The protocol used for authentication is SAML 2.0. Steps involve exchanging the IdP Metadata (URL generating XML) and the Service Provider Metadata URL between the IdP and the AM 2.0 SP.

Step 1: Identity provider in AM 2.0.

• Login to AM 2.0 Admin Console. Select the maactive realm.
  

  Note: In case you have Restricted Admin Access on AM 2.0, then use the URL:

  https://<stack_name>-auth.<domain_name>/auth/admin/maactive/console/
  

  Click on the Identity Providers option from the left panel and select SAML v2.0 from the list of providers.

  

• Enter the Alias. This will be the default display name on the login page.
  Please note that the Alias forms a part of the redirect URL. In case it does not reflect, you can create the Redirect URI yourself and keep the URL handy.
  Eg. if Alias is set as - samlokta
  Redirect URI - https://localdocker:8443/auth/realms/sample/broker/samlokta/endpoint

  

• Optionally enter Display Name. This is the name that will be displayed, in case you need it to be different from the alias.

• Take note of the Service provider entity ID value from the same page.

Step 2: SAML 2.0 App Registration in Okta

• Next, we need to create an IDP in Okta. In the Okta admin page, go to Applications → Click Create App Integration.

  

• Select the SAML 2.0 radio button, and click Next.

  

• Provide the application name under the App name, and click Next.

  

• Copy Redirect URI from AM 2.0’s provider page, from Step 1. Configure this URL in the Single sign on URL field.

  

• Copy the Service Provider Entity ID from AM 2.0’s provider page, from Step 1 and configure this URL in the Audience URI field.

• Leave other fields to default values. Hit Next. Select the fields as indicated below and select Finish.

  

Step 3: Get the IdP Metadata URL From Okta

• Now in the same Okta application configuration page, click on the Sign On tab. You will find the metadata URL here. Please copy this URL and we will configure this in AM 2.0

  

Step 4: Configure AM 2.0 With IdP Metadata

• Paste the metadata link from Okta in the SAML entity descriptor field on AM 2.0’s provider page. If the URL is correct, you will see a green tick on the right.

  

• Click on Add. This will create a basic SP configuration on AM 2.0 for this Okta application.

Step 5: Configure other fields on AM 2.0

• Scroll down and set the Want AuthnRequests signed option to be On.

  

• Now scroll to the bottom of AM 2.0’s provider configuration page and select First Login Flow and Post Login Flow, if not already pre-selected.

  

• Click on Save.

Step 6: Configure Mapping for JIT (this step is mandatory only if you would like to enable SAML JIT)

• In case a customer requires SAML JIT need to be enabled, we need to add 4 mandatory mappers on both sides - AM 2.0 as well as Okta. In case SAML JIT is not required, please skip this step entirely.

• To add mappers in AM 2.0, click the Mappers tab on the same SP configuration page. Click on the Add mapper button.

  

• Configure User.UserId mapper by filling in the fields as shown in the image below.

  

  Click on Save.

• Similarly, configure User.LocaleId mapper by filling in the fields as shown in the image below.

  

  Click on Save.

• Similarly, configure User.PrimaryOrgId mapper by filling in the fields as shown in the image below.

  

  Click on Save.

• Similarly, configure User.Roles mapper by filling in the fields as shown in the image below.

  

  Click on Save.

• To add mappers on the Okta side to support SAML JIT, go to the General settings tab and click on the Edit button in SAML Settings.

  

  Navigate to the SAML Tab by clicking on the Configure SAML button. Go to the Configure SAML tab and add the 4 attributes as shown below.

  

  Note: the values shown in the above image in the Okta side mapper configuration are only for example. Please enter values as per your requirements.

  Click on Next and then click on Finish. You are now done with the SAML JIT configuration.

Step 7: Configure logout

To configure logout, a Signing certificate needs to be extracted from AM 2.0 and saved on the Okta side.

• To extract this Signing certificate from AM 2.0, go to Realm settings → Keys → Certificate.

  

  The certificate will look like below:

  

• Follow the template shown below to create a new certificate file.

  —–BEGIN CERTIFICATE—–
  <PASTE THE CERT HERE!>
  —–END CERTIFICATE—–
  

  Replace the text “<PASTE THE CERT HERE!>” with the copied certificate data from above. It should look like this after the replace:

  

• This file needs to be saved on the Okta side. Now on the Okta side, go to the General settings tab and click the Edit button in SAML Settings. Click on Show Advanced Settings.

  

  The certificate saved goes in the Signature Certificate field.

  

• Get the Single Logout URL from the AM 2.0 metadata URL of this realm. The metadata link can be found on the IDP configuration page, as shown below.

  

  The metadata will look like below:

  

  Extract this URL and save it in the Single Logout URL field.

• The SP issuer will be the same as the SP Entity ID, which we saw in Step 1.

• After saving all of these changes, go to the Sign On tab in Okta and get the metadata URL.

  

• Okta metadata will now have a SingleLogoutService field populated to reflect the Logout URL.

  

  Use this URL to configure the logout on the AM 2.0 side. Save the change.

Step 8: Additional attributes configuration

• In case additional attributes are needed, they can be configured as well. Below is a list of attributes can be configured. You will have to pass the attribute from the IDP side to receive on SP side.

5.4 - Configure Okta OIDC IdP for JIT

Objective

This page describes the Okta OIDC setup with JIT and Non JIT flows.

Integrating Access Management 2.0 with OKTA OIDC

This section shows how to integrate Access Management 2.0 with OKTA, where OKTA will behave as the Identity Provider (IdP). The protocol used for authentication is OIDC. Steps involve creating an OIDC client on both sides.

Step 1: Identity provider in Access Management 2.0.

• Login to the Access Management 2.0 admin console. Select the correct realm, here it’s maactive.

https://xxxxxx-auth.sce.manh.com/auth/

If you only have Restricted Admin Access, then use the URL:

https://<stack_short_name>-auth.<domain_name>/auth/admin/maactive/console/

• Verify the Realm.

• Click Identity Providers → Add providers and select OpenID Connect provider from the list of providers.

• Enter the Alias and the Display name.

Alias also forms part of Redirect URL. For example, if the Alias is scoeoidc, then the Redirect URI is:

https://xxxxxx-auth.sce.manh.com/auth/realms/maactive/broker/scoeoidc/endpoint

Copy this redirect URI to register the application In OKTA.

Step 2: App Registration in OKTA

The instructions described below can be used to integrate the ActivePlatform™ with OKTA Login

• Login to your OKTA Account → Go to Applications → Click Create App Integration.

• Select OIDC - OpenID connect radio button and then Web/Native Application radio button on the Application Type Panel, and click Next.

Provide the name of the application and paste that Redirect URI from step1-C to Okta Sign-in redirect URIs

The below screen will be displayed after Save Operation on Okta.

• Follow the below steps to create a client_secret key.

Edit and select client secret → save. As soon as you hit Save, you see Client Secret. Copy this for further configuration. Unselect Proof Key for Code Exchange (PKCE)

• Copy the Client ID, Client Secret from the above screen, and Metadata Well known URI as below to register it in Access Management 2.0.

• There is a concept in OIDC Application called the Metadata Well Known URI.

The general format (in Okta) is https://host:<port>/oauth2/default/.well-known/openid-configuration. In our case:

https://dev-95801423.okta.com/oauth2/default/.well-known/openid-configuration

• Assign users to the application in OKTA.

Step 3: Integrating Access Management 2.0 with OKTA OIDC

• Go to Access Management 2.0 Admin and paste the OpenID connect metadata URI in the Discovery endpoint as shown below (click on show metadata to see the rest of the endpoints).

• Select Client Authentication as Client secret sent as basic auth, paste the client ID and client secret value, and then hit add.

• Next, click on advanced to add the default scopes as shown below.

• Next, choose the First Login Flow as MA first Broker login if not already configured. Once done, choose the MA post login flow as the Post Login Flow drop down. This is an important step, and it is needed for the IDP login to work fine.

  

• Manually add users to the application with appropriate roles. This completes the integration of Access Management 2.0 and OKTA using the OIDC protocol.

• Click on the application URL and use the icon in the UI to log in through OKTA-ODIC. In our case it is scoeoidc

  

Step 4: Enabling JWT-OIDC-JIT – OKTA

Creating/adding mappers in Access Management 2.0:

• To add mappers in Access Management 2.0, go to Access Management 2.0’s provider configuration page, Select the identity providers (Scoeoidc) and click on the Mappers tab.

  

• Click on Add mapper and create the below mappers by filling in the fields as shown in the below screenshots.

  • User.UserId:

  

  • User.FirstName:

  

  • User.LastName:

  

  • User.PrimaryOrgId:

  

  • User.Roles:

  

  • User.LocaleId :

  

Step 5: Adding Custom claims in OKTA:

Login to OKTA portal https://okta-devok12.okta.com/

• Login to your OKTA Account → Go to Directory → Click Profile Editor → select User (default).

  

• Next, click on Add Attribute to add the required customer user attributes.

  

  • primary_org_id:

  

  • preferred_roles:

  

  • LocaleId:

  

Save and Next:

Once the attributes are added to the profile-editor, custom attributes fields will be displayed for the user under the profile.

• → Go to Directory → Click People → select User(ltadimarri@manh.com) → profile → Edit.

Define the values for custom attributes.

• Next is Add claims, go to Security tab on the left-hand side, and select the API option.

  

• Under the Authorization Servers tab, select the default authorization server.

  

• Under the claims header, click on the Add Claim button.

  

• Create a new claim called “primary_org_id” as shown below. Click save.

  

• Create a new claim called “preferred_roles” as shown below. Click save.

  

• Create a new claim called “LocaleId” as shown below. Click save.

  

Follow the above steps to add attributes based on customer requirements.

• Next, assign users to this application in OKTA.

Step 6: Viewing Claims and Attributes in Okta’s Token Preview

Okta provides a way to view the custom claims or attributes passed under the token preview in the authorization server.

• In the Okta admin console, navigate to Security > API > Authorization Servers, select default authorization server, and then go to the Token Preview.

Select the properties for your token request to preview a token payload (ClientID, Grant type, user, and scopes).

• Once properties are selected, click on the token preview to view the attributes and claims.

  

Note: By default, the claims for preferred_username, first name (given_name), and last name (family_name) will be available in the Okta token.

Step 7: JWT-OIDC-JIT Required claims in OKTA.

Note: Please take special care to make sure values mapped to your Identity Provider do not have any unwanted spaces, commas, or other invalid characters before or after the values.

Attributes Shown Below can be configured on IDP as well as SP.

5.5 - Configure Azure Identity Providers

Objective

This page describes Azure Ad OIDC Setup with JIT and Non JIT Flows.

Integrating Access Management 2.0 with Azure OIDC

This section shows how to integrate Access Management 2.0 with Azure AD, where Azure will behave as an Identity Provider (IdP). The protocol used for authentication is OpenID Connect (OIDC). Steps involve creating an OIDC client on both sides.

Step 1: Identity provider in Access Management 2.0.

• Login to the Access Management 2.0 Admin console and select the correct realm, here it’s maactive.

https://xxxxxx-auth.sce.manh.com/auth/

If you only have Restricted Admin Access, then use the URL.

https://<stack_short_name>-auth.<domain_name>/auth/admin/maactive/console/

• Verify the Realm.

• Click Identity Providers → Add providers and select OpenID Connect provider from the list of providers.

• Enter the Alias and the Display name.

Alias also forms part of the Redirect URL. For example, if Alias is scoeoidcazure, then the redirect URI is:

https://xxxxxx-auth.sce.manh.com/auth/realms/maactive/broker/scoeoidcazure/endpoint

Copy this redirect URI to register the application In Azure.

Step 2: OIDC App Registration in Microsoft Azure AD

The instructions described below can be used to integrate ActivePlatform™ with Microsoft Azure AD Login:

• Login to https://portal.azure.com/#home as an Administrator or Co-Administrator to create a new Application.
• Select App Registration from the homepage or search for the same from the search bar.

• Select New Registration to create an OIDC application.

• Set the application name, select web application from the drop-down, and paste the redirect URI that has been copied from Access Management 2.0:

https://xxxxxx-auth.sce.manh.com/auth/realms/maactive/broker/scoeoidcazure/endpoint

Once the redirect URI is pasted, register the application.

This creates the new application (client) in Azure Portal. Note down the client ID, which is also the application ID.

• Creation of client secret Key.
  • Select the application (scoeoidc) → select certificate and secrets to create a new secret key.
  • Select New client secret. Describe this secret. Hit Add.

Note: Write down the Client secret value, and make sure you register the key “Value”.

This will be the only chance to capture the key. Never send the secrets over emails.

• Enable permission for this application
  • Select API permissions.
  • Click on Grant admin consent. Confirm in yes.

• Copy Endpoints for this client to configure in Access Management 2.0. These endpoints can be captured by clicking on Endpoints, as shown below.

Copy the OpenID Connect metadata document (also known as the OIDC Well Known URL across the Security Industry, like SAML IdP Metadata) to configure it in Access Management 2.0.

https://login.microsoftonline.com/c38aa44d-4165-427e-94a7-62d15e922c35/v2.0/.well-known/openid-configuration

Configure the OpenID Connect application using OpenID Connect Application Endpoints in Access Management 2.0.

• Assign the users or groups to this application in Azure.

Step 3: Integrating Access Management 2.0 with Azure OIDC

• Go to Access Management 2.0 Admin Console and paste the OpenID connect metadata in the Discovery endpoint as shown below (click on show metadata to see the rest of the endpoints).

• Select Client Authentication as Client secret sent as basic auth, paste the client ID and Client secret value, then hit Add.

• Next, click on Advanced to add the default scopes as shown below.

• Next, choose the First login flow as MA first Broker login if not yet configured.

Also, choose Post login flow as MA post login flow if not configured already. This is an important step, and it is needed for the IDP login to work fine.

• Ensure users were added to the application with appropriate roles.

This completes the integration of Access Management 2.0 and Azure using the OIDC protocol.

• Click on the application URL and use the icon in the UI to log in through Azure-ODIC. A better-looking screen is expected soon. The number of IdP Login buttons/Options will depend on how many IdPs the user has configured within Access Management 2.0. In our case, it is scoeazure-oidc.

Step 4: Enabling JWT-OIDC-JIT - Azure

In case Just In Time (JIT) User Provisioning is not needed, please skip this step 4.

If JIT needs to be enabled, we need to add six mandatory mappers on each side in Access Management 2.0, as well as Azure.

• To add mappers in Access Management 2.0, go to the Access Management 2.0 provider configuration page, select the identity providers (Scoeazure-oidc), and click on the Mappers tab.

• Click on Add mapper and create the below mappers by filling in the fields as shown in the screenshots below.

  • User.UserId:

  

  • User.FirstName:

  

  • User.LastName:

  

  • User.PrimaryOrgId:

  

  • User.Roles:

  

  • User.LocaleId:

  

Step 5: Adding Custom claims in Azure AD

Login to Azure portal https://portal.azure.com/#home

We have multiple options in Azure AD to pass the required claims in the response token.

Steps for Enabling Optional claim for OIDC in Azure:

• In AZURE AD, go to Token Configuration → Add optional claim ID → select preferred_username and add available required claims as well.

• If we do not have options to pass the required attributes/claims in token configuration, we can pass it through managed claims.

• Go to Enterprise applications → Single Sign-on → Attributes and claims.

• Go to Enterprise applications and search for the application (in our case: scoeoidc)

• Select the application and click on the Single sign-on Tab.

• Edit the attributes & Claims. Click on Add new claim. Provide the Claim Name and the Source attribute value:

  • primary_org_id

  

Similarly, add other attributes as well.

• To make these changes work and send the attributes in the ID token, we need to update the acceptMappedClaims to true in the application manifest.

Go to App registrations → <application name(scoeoidc)> → manifest.

Next, assign users to this application.

Once the above steps are performed, the user will be created in the application.

• JWT Token response using Postman.

We can check the sent claims/attributes in the JWT token response using Postman. Use the token endpoint, client ID, and client secret key to get the token response ID of the user in Postman.

POST Request:

A successful request would get HTTP 200 OK responses having an ID token and access token, as shown below.

• Go to https://jwt.io/ and paste the ID token in the debugger to know what response is sent from the token.

Step 6: JWT-OIDC-JIT Required claims in Azure.

Note: Please take special care to make sure values mapped to your Identity Provider do not have any unwanted spaces, commas, or other invalid characters before or after the values.

The attributes in the table below can be configured on both IDP and SP by following the steps above.

6 - Clearing IDP Assocations for Users with Access Management 2.0 API

Clearing Identity Provider Associations in Keycloak

In identity federation scenarios, users in Keycloak may be linked to external Identity Providers (IdPs) through two specific user attributes:

• BROKER_LINK: Stores the federation link between a Keycloak user and an external identity provider, capturing the IdP alias, the user’s external identity, and the associated realm details.
• FEDERATED_USER: Stores the reference to a user managed by an external storage provider, linking the user ID to its storage provider and realm.

When Is This Needed?

These associations may need to be removed for a user for a number of reasons including -

• Allow users to re-register with a different Identity Provider
• Remove obsolete or broken identity links
• Support migration between Identity Providers

API Specification: Clear Federated User Associations

This secure API endpoint may be used to clear both BROKER_LINK and FEDERATED_USER attributes for a given user, effectively removing thier federation association.

Endpoint

POST {{authurl}}/user/clearCachedUser?userId={{userId}}

Method

POST

Description

Clears the following identity federation attributes for the specified user:

• BROKER_LINK
• FEDERATED_USER

Example Auth URL:

https://abcds-auth.sce.manh.com

Note: This endpoint must use the authentication (auth) URL, not the regular application URL.

Clear Cached User API – Expected Responses

This section describes typical response scenarios for the {{auth_url}}/user/clearCachedUser API, including success and edge cases.

Scenario 1: Successful Attribute Clearance

Scenario 2: Specified User Not Found

Scenario 3: Missing or Invalid userId Parameter

Scenario 4: Bulk Clearance Completed

Scenario 5: Access Token Validation Failed

Scenario 6: Successful Authentication

Note

Only users with one of the following roles are authorized to access this API:

• admin-maactive (SystemAdministrator / KeycloakAdministrator) — Restricted Admin
• admin — Super Admin
  Any requests made with tokens that do not include one of these roles will receive an Access Denied (403 Forbidden) response.

7 - Configuring Proof Key for Code Exchange (PKCE) between AM 2.0 and Okta

Objective

In today’s security-conscious digital landscape, safeguarding user authentication flows against interception and unauthorized token exchange is critical, especially when integrating with public or external Identity Providers. Proof Key for Code Exchange (PKCE) is an extension to the OAuth 2.0 Authorization Code Flow that adds a layer of security to mitigate the risk of code interception attacks.

This document provides a structured overview of PKCE: its definition, purpose, and practical value and follows with a comprehensive, step-by-step guide to:

• ✅ Understand how PKCE strengthens the OAuth2/OIDC flow,
• ✅ Configure Access Management 2.0 as an Identity Broker that delegates authentication to an external Identity Provider, and
• ✅ Integrate Okta as a secure and standards-compliant OIDC Identity Provider using PKCE.

This guide is intended for architects, developers, and system administrators seeking to enable secure OIDC federation between Access Management 2.0 and Okta in environments where PKCE is required.

Whether you’re developing public web clients, mobile applications, or federated authentication systems, implementing PKCE ensures that your Authorization Code Flow adheres to best practices in secure identity delegation.

Purpose of PKCE (Proof Key for Code Exchange)

Originally designed for mobile/native clients, PKCE (RFC 7636) prevents authorization code interception attacks in OAuth2/OIDC Authorization Code Flow.

Why is it needed?

In the traditional Authorization Code Grant, the client app receives the authorization code in a browser redirect, which could be intercepted by malicious apps (especially in public clients like SPA or mobile apps).

PKCE ensures that:

• The authorization code is bound to the client application through a challenge
• Even if an attacker steals the code, they cannot exchange it for a token without the original code verifier

PKCE Definitions

code_verifier

• Definition: A high-entropy cryptographic random string used to bind the authorization request to the token request.

• Format Requirements (from RFC 7636):

  • Minimum length: 43 characters
  • Maximum length: 128 characters
  • Characters: [A-Z], [a-z], [0-9], -, ., _, ~

• Purpose: Sent only in the token request. It proves that the token requester is the same party who initiated the authorization request.

code_challenge

• Definition: A hashed and base64-url-encoded version of the code_verifier, which is sent in the initial authorization request.

• Generation:

  code_challenge = BASE64URL-ENCODE(SHA256(code_verifier))
  code_challenge_method = "S256"
  

  (Alternatively, the method can be "plain" but "S256" is recommended for security.)

• Purpose: Sent in the authorization request to the authorization server, so the server can later verify that the code_verifier in the token request matches the previously submitted code_challenge.

Which One is Generated First?

✅ code_verifier is generated first

• It is the original, client-generated secret.
• The code_challenge is derived from the code_verifier using a transformation algorithm (usually SHA-256 and base64url encoding).

Sequence

1. Generate code_verifier (random 43–128 character string)
2. Derive code_challenge from the code_verifier
3. Send code_challenge in the /authorize request
4. Later, send code_verifier in the /token request to prove the client’s identity

Example

code_verifier:  dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
code_challenge: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
code_challenge_method: S256

PKCE Flow: Step-by-Step

Step 1: Client creates a code verifier

code_verifier = base64url(32-96 random bytes)

Step 2: Client derives a code challenge

code_challenge = BASE64URL-ENCODE(SHA256(code_verifier))
method = S256

Step 3: Client initiates authorization request

GET /authorize?
  response_type=code
  client_id=CLIENT_ID
  redirect_uri=REDIRECT_URI
  code_challenge=CODE_CHALLENGE
  code_challenge_method=S256

Step 4: Authorization server authenticates user and issues code

Step 5: Client sends token request with the code_verifier

POST /token
  grant_type=authorization_code
  code=AUTH_CODE
  redirect_uri=REDIRECT_URI
  client_id=CLIENT_ID
  code_verifier=CODE_VERIFIER

Step 6: Server validates:

SHA256(code_verifier) == code_challenge ?

If yes → returns access_token, id_token, and optionally refresh_token.

Okta OIDC App Configuration with PKCE

Prerequisite

• You must use Authorization Code Flow with PKCE
• Do not require a client_secret (suitable for public clients)

Okta App Configuration Steps

1. Login to Okta Admin Console

2. Go to Applications → Create App Integration

3. Choose:

   • Sign-in method: OIDC – OpenID Connect
   • Application type: Native Application (or Web if backend app)

4. Click Next

5. Fill in:

   • App name
   • Sign-in redirect URIs: You application callback URI (eg https://www.getpostman.com/oauth2/callback)
   • Sign-out redirect URIs (optional)

6. Click Save

Settings Behind the Scenes

• Grant type: authorization_code

• PKCE is enabled automatically for native apps

• No client secret required (for public/native apps)

• Okta’s .well-known/openid-configuration will contain:

  "code_challenge_methods_supported": ["S256"]
  

Configure Access Management to Use Okta as OIDC Identity Provider with PKCE

To configure Access Management as a Relying Party (Client) and Okta as an OIDC Identity Provider, follow these steps:

Step 1: In Access Management Admin Console

• Go to the Realm where you want to add the external IdP
• Navigate to Identity Providers → Add Provider → OpenID Connect

Step 2: Configure OIDC IdP (Okta)

Required fields:

Enable PKCE

• Access Management currently does not explicitly require a checkbox to “enable PKCE” when it’s an OIDC client to another IdP

• However, if the remote IdP (Okta) requires PKCE, Access Management must:

  • Use the Authorization Code Flow
  • Support the code_challenge parameter in the /authorize request

As of recent versions, Access Management acts as a confidential client (with client_secret) for brokered OIDC IdPs. If you’re using PKCE with Okta, configure Okta to allow PKCE for confidential clients, or:

• Configure the IdP as a public client
• Add custom code_challenge logic if necessary via SPI or reverse proxy

Summary Table

Visual Flow

References

• PKCE spec: RFC 7636
• Okta PKCE: https://developer.okta.com/docs/guides/implement-auth-code-pkce/
• Access Management Docs: [https://www.Access Management.org/docs/latest/server_admin/#openid-connect](https://www.Access Management.org/docs/latest/server_admin/#openid-connect)

Author

• Jim Knupp:Director, Application Security, ActivePlatform™, R&D._

8 - Handling IdP Key Rotation in Access Management

Objective

A signing certificate is a crucial component in securing SAML communications, it is used to ensure authentication requests and responses are trusted. For security reasons, a signing certificate is periodically rotated before its expiration. A single key for the Signing Certificate of an IDP is used by Access Management 2.0, so when the IDP begins using a new certificate, access will be denied until the new key is updated in Access Management.

This document describes how to change this key in Access Management.

Purpose

Following is a structured explanation of SAML Signing Certificates/Keys and how to update Keycloak’s SAML Identity Provider (IdP) configuration when Okta rotates its SAML signing certificate.

SAML Signing Certificates / Keys – Concept

1. Why This is Important

In a SAML 2.0 authentication flow:

• The Identity Provider (IdP) (e.g., Okta) digitally signs the SAML assertions using a private key.
• The Service Provider (SP) (e.g., Keycloak as a SAML IdP for another application) verifies this signature using the corresponding public certificate.
• This prevents tampering, ensures message authenticity, and verifies the identity of the sender.

2. Key Concepts

Why Rotation Happens

• Okta periodically rotates signing certificates to comply with security best practices.
• After rotation:
  • Old cert is deprecated (or valid temporarily).
  • New cert must be trusted by Keycloak; otherwise, signature verification will fail and SAML login will break.

Different Rotation Scenarios -

1 - IDPs that do no support more than one Key

• Create the new Signing Certificate and Key in your IDP (logins start failing in Manhattan Solutions)
• Login to the Access Management to update the Key (logins succeed again)

2 - IDPs that support multiple Keys

• Generate the new Signing Certificate and Key in your IDP (but do not activate it)
• Configure the new Signing Key in Access Management (active key in IDP is old - logins start failing)
• activate the new Key in your IDP (now Keycloak allows login again)

Before you begin

You will need access to the AM 2.0 Admin Console using the System Management account (a non IDP based super user provided with your subscription.)

Steps

Follow these steps below to rotate a SAML signing key with your IdP -

1. Log in to the AM 2.0 Admin Console. Select the maactive realm.

   Note: If you have Restricted Admin Access on AM 2.0, then use the URL:

   https://<stack_name>-auth.<domain_name>/auth/admin/maactive/console/
   

   The Admin Console will appear as shown below:

   

2. Click on the Identity providers tab on the left panel and select the IdP provider whose signing certificate is to be changed.

   

3. Scroll down and toggle IdP configurations For the SP to be able to validate the signatures, the Want Assertions Signed and Validate Signatures toggle fields must be switched ON.

   

4. Update the IdP certificate on the SP side. Clear out the certificate that is already present on AM 2.0 from the field Validating X509 certificates. Paste the new X509 certificate to use it with the IdP.

   

5. Hit the Save button at the bottom.

You should be able to successfully set a new IdP signing certificate on the SP side.

Author

Shipra Choudhary: Tech Lead, Application Security, ActivePlatform™, R&D. e;, R&D._