Skip to content

README.md

Latest commit

 

History

History
482 lines (334 loc) · 22.9 KB

README.md

File metadata and controls

482 lines (334 loc) · 22.9 KB
Raw

Configuration of ODM with PingFederate

Introduction

In the context of the Operational Decision Manager (ODM) on Certified Kubernetes offering, ODM for production can be configured with an external OpenID Connect server (OIDC provider), such as the PingFederate cloud service.

This tutorial shows how to integrate ODM with PingFederate to manage classic authentication and authorization.

What is PingFederate?

PingFederate is an enterprise identity and access management (IAM) software product made by Ping Identity. It is mainly used for federated authentication and single sign-on (SSO) across different systems and organizations.

About this task

You need to create a number of secrets before you can install an ODM instance with an external OIDC provider such as the PingFederate service, and use web application single sign-on (SSO). The following diagram shows the ODM services with an external OIDC provider after a successful installation.

ODM web application SSO

The following procedure describes how to manually configure ODM with a PingFederate service.

ODM OpenID flows

OpenID Connect is an authentication standard built on top of OAuth 2.0. It adds a token called an ID token.

Terminology:

  • The OpenID provider — The authorization server that issues the ID token. In this case, PingFederate is the OpenID provider.
  • The end user — The end user whose information is contained in the ID token.
  • The relying party — The client application that requests the ID token from PingFederate.
  • The ID token — The token that is issued by the OpenID provider and contains information about the end user in the form of claims.
  • A claim — A piece of information about the end user.

The Authorization Code flow is best used by server-side apps where the source code is not publicly exposed. The apps must be server-side because the request that exchanges the authorization code for a token requires a client secret, which has to be stored in your client. However, the server-side app requires an end user because it relies on interactions with the end user's web browser, which redirects the user and then receives the authorization code.

Authorization Code Flow

The Client Credentials flow is intended for server-side (AKA "confidential") client applications with no end user, which normally describes machine-to-machine communication. The application must be server-side because it must be trusted with the client secret, and since the credentials are hard-coded, it cannot be used by an actual end user. It involves a single, authenticated request to the token endpoint, which returns an access token.

Client Credentials Flow

Prerequisites

You need the following elements:

  • Helm v3
  • Kubectl
  • Access to an Operational Decision Manager product
  • Access to a CNCF Kubernetes cluster
  • A PingFederate Saas trial Instance

Install a PingFederate instance

This tutorial has been tested with a PingFederate Saas trial instance. You have to request it if you don't have one.

Configure a PingFederate instance for ODM (Part 1)

In this section, you will:

  • Log into the PingFederate Admin Console
  • Create some users and groups
  • Create an ODM Resource and dedicated scope
  • Create an ODM Application
  • Check the configuration

Log into the PingFederate Admin Console

When the trial is available, you have a link to the PingFederate Admin Console in the email you received. Use it to connect to the PingFederate Admin Console.

Create some users and groups

At the first connection, a predefined user that was used to log into the PingFederate Admin Console is already present in the Directory > Users tab. You can use the + button to add new users.

We will use the Directory>Groups tab to create a group named ODM-Admin and add the prefdefined user to it.

Select Directory > Groups and click the + button to create a new group.

  • Group Name: ODM-Admin
  • Description: ODM Admin Group
  • Click Save

Using the three dot button on the ODM-Admin group, you can add the predefined user to the group using the Add/remove Users menu.

Admin Group

Create an ODM Resource and dedicated scope

The resource is a way to create a dedicated scope that will be used in the client_credentials flow, as openid scope acconot be used.

Select Applications > Resources tab and click the + button to create a new resource.

  • Resource Name: ODM CC

  • Description: ODM Resource for Client Crededentials

  • Click Next

  • Click + Add Attributes button

  • Attribute Name: identity and PingOne Mappings Value #root.context.appConfig.clientId using the Advanced Expression button

  • Check Required checkbox

  • Click Next

Resource Attributes

  • Click + Add Scope button
  • Scope Name: odm_cc
  • Click Save

Resource Scope

Create an ODM Application

Select Applications > Applications tab and click the + button to create a new application.

  • Application Name: ODM Application
  • Application Type: OIDC Web App
  • Click Save

Select Configuration and edit using the Edit button.

  • Response Type: Code,Token and ID Token
  • Grant Type: Authorization Code, Implicit, Client Credentials
  • Token Endpoint Authentication Method: Client Secret Post
  • Click Save

Application Configuration

Select Resources and edit using the Edit button.

  • Add the odm_cc scope to the Selected Scopes list
  • Click Save

Application Resources

[Optional] Set MFA to login to ODM UI Select Policies and edit using the Edit button.

  • Check Multi_factor policy
  • Click Save

Application Policies

Select Attribute Mappings and edit using the Edit button. Add new attribute using the +Add button

  • Attribute Name: groups and PingOne Mappings Value Group Names
  • Attribute Name: identity and PingOne Mappings Value user.name.given + ' ' + user.name.family using the Advanced Expression button
  • Click Save

Application Attributes

Select Access and edit using the Edit button.

  • Select ODM-Admin group from the Groups dropdown
  • Click Save

Application Access

Check the configuration

Download the pingfederate-odm-script.zip file to your machine and unzip it in your working directory. This .zip file contains scripts and templates to verify and set up ODM.

You can request an access token using the Client-Credentials flow to verify the format of the token. This token is used for the deployment of rulesets from the Business Console:

./get-client-credential-token.sh -i $CLIENT_ID -x $CLIENT_SECRET -n $PING_FEDERATE_SERVER_URL

Where:

  • CLIENT_ID can be found in the overview of the ODM Application, section Applications / Applications
  • CLIENT_SECRET can be found in the overview of the ODM Application, section Applications / Applications
  • PING_FEDERATE_SERVER_URL is the issuer ID that can be retrieved in the Connection Details of the Overview tab of the ODM Application

If you decode the access_token value with a JWT decoder tool, you should get:

{
  ..
  "iss": "<PING_FEDERATE_SERVER_URL>",
....
  "identity": "<CLIENT_ID>",
  ...
}

Deploy ODM on a container configured with PingFederate (Part 2)

Prepare your environment for the ODM installation

Create a secret to use the Entitled Registry

  1. To get your entitlement key, log in to MyIBM Container Software Library with the IBMid and password that are associated with the entitled software.

    In the Container software library tile, verify your entitlement on the View library page, and then go to Get entitlement key to retrieve the key.

  2. Create a pull secret by running a kubectl create secret command.

    kubectl create secret docker-registry ibm-entitlement-key \
    --docker-server=cp.icr.io \
    --docker-username=cp \
    --docker-password="<API_KEY_GENERATED>"

    Where:

    • API_KEY_GENERATED is the entitlement key from the previous step. Make sure you enclose the key in double-quotes.

    Note:

    1. The cp.icr.io value for the docker-server parameter is the only registry domain name that contains the images. You MUST set the docker-username to cp to use an entitlement key as docker-password.
    2. The ibm-entitlement-key secret name will be used for the image.pullSecrets parameter when you run a Helm install of your containers. The image.repository parameter is also set by default to cp.icr.io/cp/cp4a/odm.

Create secrets to configure ODM with PingFederate

  1. Create a secret to configure ODM with PingFederate.

    If you have not done it yet, download the pingfederate-odm-script.zip file to your machine. This .zip file contains the script and the content of the templates directory. The script allows you to generate the necessary configuration files.

    Generate the files with the following command:

    ./generateTemplate.sh -i $CLIENT_ID -x $CLIENT_SECRET -n $PING_FEDERATE_SERVER_URL

    Where:

    • CLIENT_ID can be found in the overview of the ODM Application, section Applications / Applications
    • CLIENT_SECRET can be found in the overview of the ODM Application, section Applications / Applications
    • PING_FEDERATE_SERVER_URL can be found as the Issuer ID in the overview / Connection Details of the ODM Application, section Applications / Applications

    The following files are generated into the output directory:

    • webSecurity.xml contains the mapping between Liberty J2EE ODM roles and the PingFederate ODM-Admin group
    • openIdWebSecurity.xml contains two openIdConnectClient Liberty configurations:
      • the first for web access to Decision Center and Decision Server consoles with the Authorization Code flow
      • the second for the rest-api calls with the client-credentials flow
    • openIdParameters.properties configures several features like allowed domains, logout, and some internal ODM openid features

  2. Create the PingFederate authentication secret using webSecurity.xml, openIdWebSecurity.xml and openIdParameters.properties files.

    kubectl create secret generic pingfederate-auth-secret \
    --from-file=openIdParameters.properties=./output/openIdParameters.properties \
    --from-file=openIdWebSecurity.xml=./output/openIdWebSecurity.xml \
    --from-file=webSecurity.xml=./output/webSecurity.xml

Install your ODM Helm release

1. Add the public IBM Helm charts repository

helm repo add ibm-helm https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm
helm repo update

2. Check that you can access the ODM chart

helm search repo ibm-odm-prod

The output should look like:

NAME                      CHART VERSION  APP VERSION  DESCRIPTION
ibm-helm/ibm-odm-prod     26.0.0         9.6.0.0      IBM Operational Decision Manager

3. Run the helm install command

You can now install the product. We will use the PostgreSQL internal database and disable data persistence (internalDatabase.persistence.enabled=false) to avoid any platform complexity with persistent volume allocation.

Note:
The following command installs the latest available version of the chart.
If you want to install a specific version, add the --version option:

helm install my-odm-release ibm-helm/ibm-odm-prod --version <version> -f pingfederate-values.yaml

You can list all available versions using:

helm search repo ibm-helm/ibm-odm-prod -l

a. Installation on OpenShift using Routes

See the Preparing to install documentation for more information. Inspect pingfederate-values.yaml for the parameters that have been defined for this installation.

helm install my-odm-release ibm-helm/ibm-odm-prod -f pingfederate-values.yaml

b. Installation using Ingress

Refer to the following documentation to install an NGINX Ingress Controller on:

When the NGINX Ingress Controller is ready, you can install the ODM release using pingfederate-ingress-values.yaml. Take note of the service.ingress.annotations values that have been defined in this file.

helm install my-odm-release ibm-helm/ibm-odm-prod -f pingfederate-nginx-values.yaml

Complete post-deployment tasks

Register the ODM redirect URL

  1. Get the ODM endpoints. Refer to this documentation to retrieve the endpoints. For example, on OpenShift you can get the route names and hosts with:

    kubectl get routes --no-headers --output custom-columns=":metadata.name,:spec.host"

    You get the following hosts:

    my-odm-release-odm-dc-route           <DC_HOST>
my-odm-release-odm-dr-route           <DR_HOST>
my-odm-release-odm-ds-console-route   <DS_CONSOLE_HOST>
my-odm-release-odm-ds-runtime-route   <DS_RUNTIME_HOST>

    Using an Ingress, the endpoint is the address of the ODM ingress and is the same for all components. You can get it with:

    kubectl get ingress my-odm-release-odm-ingress

    You get the following ingress address:

    NAME                       CLASS    HOSTS   ADDRESS          PORTS   AGE
my-odm-release-odm-ingress <none>   *       <INGRESS_ADDRESS>   80    1d

  2. Register the redirect URIs into your PingFederate application.

    The redirect URIs are built in the following way:

    Using Routes:

    • Decision Center redirect URI: https://<DC_HOST>/decisioncenter/openid/redirect/odm
    • Decision Runner redirect URI: https://<DR_HOST>/DecisionRunner/openid/redirect/odm
    • Decision Server Console redirect URI: https://<DS_CONSOLE_HOST>/res/openid/redirect/odm
    • Decision Server Runtime redirect URI: https://<DS_RUNTIME_HOST>/DecisionService/openid/redirect/odm
    • Rule Designer redirect URI: https://127.0.0.1:9081/oidcCallback

    Using Ingress:

    • Decision Center redirect URI: https://<INGRESS_ADDRESS>/decisioncenter/openid/redirect/odm
    • Decision Runner redirect URI: https://<INGRESS_ADDRESS>/DecisionRunner/openid/redirect/odm
    • Decision Server Console redirect URI: https://<INGRESS_ADDRESS>/res/openid/redirect/odm
    • Decision Server Runtime redirect URI: https://<INGRESS_ADDRESS>/DecisionService/openid/redirect/odm
    • Rule Designer redirect URI: https://127.0.0.1:9081/oidcCallback

    From the PingFederate admin console, in Applications / Applications

    • Edit the ODM Application

    • In the tab Configuration

      • Add the redirect URIs in the Redirect URIs field for each component.

      For example, add the Decision Center redirect URI that you got earlier (https://<DC_HOST>/decisioncenter/openid/redirect/odm -- do not forget to replace <DC_HOST> with your actual host name!)

    • Click Save at the bottom of the page.

    Add URI

Access the ODM services

Well done! You can now connect to ODM using the endpoints you got earlier and log in as an ODM admin with your account.

Set up Rule Designer

First set up Rule Designer following these instructions.

To be able to securely connect your Rule Designer to the Decision Server and Decision Center services that are running in Certified Kubernetes, you need to establish a TLS connection through a security certificate in addition to the OpenID configuration.

  1. Get the following configuration files.

    • https://<DC_HOST>/decisioncenter/assets/truststore.jks
    • https://<DC_HOST>/decisioncenter/assets/OdmOidcProvidersRD.json where DC_HOST is the Decision Center endpoint.

  2. Copy the truststore.jks and OdmOidcProvidersRD.json files to your Rule Designer installation directory next to the eclipse.ini file.

  3. Edit your eclipse.ini file and add the following lines at the end.

    -Djavax.net.ssl.trustStore=<ECLIPSEINITDIR>/truststore.jks
-Djavax.net.ssl.trustStorePassword=changeme
-Dcom.ibm.rules.authentication.oidcconfig=<ECLIPSEINITDIR>/OdmOidcProvidersRD.json

    Where:

    • changeme is the fixed password to be used for the default truststore.jks file.
    • ECLIPSEINITDIR is the Rule Designer installation directory where the eclipse.ini file is.

  4. Restart Rule Designer.

For more information, refer to this documentation.

Getting Started with IBM Operational Decision Manager for Containers

Get hands-on experience with IBM Operational Decision Manager in a container environment by following this Getting started tutorial.

Calling the ODM Runtime Service

Log in the Business Console.

Import the Decision Service named Loan Validation Service if it is not already there.

Import project

Deploy the Loan Validation Service production_deployment ruleapp using the production deployment deployment configuration in the Deployments>Configurations tab.

Deploy project

You can retrieve the payload.json from the ODM Decision Server Console or use the provided payload.

As explained in the ODM on Certified Kubernetes documentation Configuring user access with OpenID, we advise you to use basic authentication for the ODM runtime call for better performance and to avoid token expiration and revocation.

You perform a basic authentication ODM runtime call in the following way:

curl -H "Content-Type: application/json" -k --data @payload.json \
      -H "Authorization: Basic b2RtQWRtaW46b2RtQWRtaW4=" \
     https://<DS_RUNTIME_HOST>/DecisionService/rest/production_deployment/1.0/loan_validation_production/1.0

Where b2RtQWRtaW46b2RtQWRtaW4= is the base64 encoding of the current username:password odmAdmin:odmAdmin

If you want to perform a bearer authentication ODM runtime call using the Client Credentials flow, you must get a bearer access token:

curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=${CLIENT_ID}&scope=odm_cc&client_secret=${CLIENT_SECRET}&grant_type=client_credentials" \
     "${PING_FEDERATE_SERVER_URL}/token"

And use the retrieved access token in the following way:

curl -H "Content-Type: application/json" -k --data @payload.json \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     https://<DS_RUNTIME_HOST>/DecisionService/rest/production_deployment/1.0/loan_validation_production/1.0

Troubleshooting

If you encounter any issue, have a look at the OpenID Connect troubleshooting Tips

License

Apache 2.0