API Connect

API Connect

Join this online group to communicate across IBM product users and experts by sharing advice and best practices with peers and staying up to date regarding product enhancements.

 View Only

IBM API Connect - Configure OIDC User Registry using Azure AD

By Kok Sing Khong posted Tue April 25, 2023 09:46 AM

  

This article shows the steps on how to configure OIDC User Registry in IBM API Connect using Azure AD. OIDC stands for OpenID Connect, an authentication protocol built on top of the OAuth 2.0 framework. OIDC provides a standardized way for applications to authenticate users using third-party identity providers (IdP) such as Google, Microsoft, or Facebook.

In an OIDC flow, the user's identity and authentication state is maintained by an external IdP. When a user logs in to an application or API that uses OIDC, the application redirects the user to the IdP's login page, where the user enters their credentials. Once the user is authenticated, the IdP sends an ID token to the application, which the application can use to validate the user's identity and access the user's profile information.


Prerequisites
List of prerequisites required to configure OIDC User Registry using Azure AD in IBM API Connect. 

  1. An Azure login account.
  2. API Connect instance on Cloud Pak for Integration (because the scripts are written for CP4I)
  3. API Connect CLI setup 
  4. Basic knowledge of API Connect
  5. Basic knowledge of OIDC

Procedures

  1. Before you begin, you should know that Azure AD should have a Default Directory already created. Note that Azure AD is free to use at the moment. Add more users in this Default Directory. You should also take note of the Tenant ID of the Directory (this will be used in API Connect configuration, AZURE_TENANT_ID).
  2. Add an Enterprise Application by clicking Add > Enterprise application. Then click on Create your own application button.

  3. Fill up the name of your application (IBM API Connect) and select Register an application to integrate with Azure AD (App you're developing) and click Create button.
  4. When registering your application, select Accounts in this organizational directory only (Default Directory only -Single tenant) and click the Register button. Leave the Redirect URI empty for now - this value can be obtained after you have created the OIDC User Registry in API Connect.
  5. After the application is registered, go to the App Registrations page. Note down the Application (client) ID (this will be used in API Connect configuration, AZURE_AD_CLIENT_ID). Then on the same page, click on App a certificate or secret to create Client credentials.
  6. Click the New client secret button. Give a Description and set the Expires value (for testing I set it to a longer 730 days). Click on the Add button. Note down the Value of the secret because it will only be shown once (this will be used in APIC configuration, AZURE_AD_CLIENT_SECRET).
  7. Use this script to create an OIDC user registry in API Connect. Before you do, clone or fork the git repository and cd to the folder.
    % git clone https://github.com/khongks/apic-scripts-public.git
% cd apic-scripts-public
  8. Create an environment variable file (e.g. oidc-azure-ad.vars). You need to get the values for these fields AZURE_TENANT_ID, AZURE_AD_CLIENT_ID
    ##
## Azure OIDC User registry configurations
## 
USER_REGISTRY_NAME="Azure OIDC"
AZURE_TENANT_ID="replaceme"
AZURE_AD_CLIENT_ID="replaceme"
AZURE_AD_CLIENT_SECRET="replaceme"
DEF_TLS_CLIENT_PROFILE_NAME="tls-client-profile-default"
DEF_TLS_CLIENT_PROFILE_VERSION="1.0.0"
  9. Create your script file (e.g. create-oidc-user-registry.sh). Change the mode to x. This script does 3 things (a) login to API Connect cloud admin UI, (b) create an OIDC user registry and (c) add the user registry in API Connect organization.
    #!/bin/bash

##
## Set your environment variables
##
. ./env.vars
. ./oidc-azure-ad.vars

##
## Login to cloud admin
##
./login-cmc.sh

##
## Create OIDC user registry
##
USER_REGISTRY_NAME_SLUGIFIED=$(echo ${USER_REGISTRY_NAME} | slugify)
./user-registries/get.sh "${USER_REGISTRY_NAME_SLUGIFIED}" "${ADMIN_ORG_NAME}" "${CLOUD_ADMIN_SERVER}" > /dev/null 2>&1
if [ $? -eq 0 ]; then
        echo "User registry ${USER_REGISTRY_NAME_SLUGIFIED} already exist."
else
        echo "Create user registry ${USER_REGISTRY_NAME_SLUGIFIED}."
        ./user-registries/create-azure-ad-oidc.sh \
                "${USER_REGISTRY_NAME_SLUGIFIED}" \
                "${AZURE_TENANT_ID}" \
                "${AZURE_AD_CLIENT_ID}" \
                "${AZURE_AD_CLIENT_SECRET}" \
                "${DEF_TLS_CLIENT_PROFILE_NAME}" \
                "${DEF_TLS_CLIENT_PROFILE_VERSION}" \
                "${ADMIN_ORG_NAME}" \
                "${CLOUD_ADMIN_SERVER}"
fi

##
## Add User Registry to Organization default
## 
./user-registry-settings/add-user-registry-to-org.sh "${USER_REGISTRY_NAME_SLUGIFIED}" "${ADMIN_ORG_NAME}"
  10. Run the script (create-oidc-user-registry.sh), and if it is successful, you will find the following output that shows the User Registry called azure-oidc is created.
    % ./create-oidc-user-registry.sh
apic login -r admin/default-idp-1 -s https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic -u admin -p ***************
Warning: Using default toolkit credentials.
Logged into cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud successfully
Create user registry azure-oidc.
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1753  100  1753    0     0   2317      0 --:--:-- --:--:-- --:--:--  2328
{
  "name": "azure-oidc",
  "title": "azure-oidc",
  "visibility": {
    "type": "public"
  },
  "case_sensitive": false,
  "email_required": false,
  "email_unique_if_exist": true,
  "configuration": {
    "provider_type": "standard",
    "authorization_endpoint": "https://login.microsoftonline.com/83100458-a9da-4cf4-bf20-a39f85680132/oauth2/v2.0/authorize",
    "token_endpoint": {
      "endpoint": "https://login.microsoftonline.com/83100458-a9da-4cf4-bf20-a39f85680132/oauth2/v2.0/token",
      "tls_client_profile_url": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/orgs/0e5bc3ae-e943-4626-825c-5287650247f8/tls-client-profiles/359edadf-1905-48d2-b169-08705f8f296f"
    },
    "userinfo_endpoint": {
      "endpoint": "https://graph.microsoft.com/oidc/userinfo",
      "tls_client_profile_url": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/orgs/0e5bc3ae-e943-4626-825c-5287650247f8/tls-client-profiles/359edadf-1905-48d2-b169-08705f8f296f"
    },
    "jwks_uri": {
      "endpoint": "https://login.microsoftonline.com/83100458-a9da-4cf4-bf20-a39f85680132/discovery/v2.0/keys",
      "tls_client_profile_url": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/orgs/0e5bc3ae-e943-4626-825c-5287650247f8/tls-client-profiles/359edadf-1905-48d2-b169-08705f8f296f"
    },
    "logout_endpoint": "https://login.microsoftonline.com/83100458-a9da-4cf4-bf20-a39f85680132/oauth2/v2.0/logout",
    "client_id": "******* masked out *******",
    "client_secret": "******* masked out *******",
    "response_type": "code",
    "scope": "openid email",
    "credential_location": "auth_header",
    "features": [
      "auto_onboard",
      "userinfo"
    ],
    "field_mapping": {
      "email": "email",
      "username": "name",
      "first_name": "given_name",
      "last_name": "family_name"
    }
  },
  "registry_type": "oidc",
  "org_url": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/orgs/0e5bc3ae-e943-4626-825c-5287650247f8",
  "integration_url": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/cloud/integrations/user-registry/a2872422-95c1-4ebd-84ce-6907e78811a9"
}
{
    "type": "user_registry",
    "api_version": "2.0.0",
    "id": "62fc9261-3393-4aa6-a273-14e0b2cf705a",
    "name": "azure-oidc",
    "title": "azure-oidc",
    "visibility": {
        "type": "public"
    },
    "case_sensitive": false,
    "email_required": false,
    "email_unique_if_exist": true,
    "configuration": {
        "provider_type": "standard",
        "authorization_endpoint": "https://login.microsoftonline.com/83100458-a9da-4cf4-bf20-a39f85680132/oauth2/v2.0/authorize",
        "token_endpoint": {
            "endpoint": "https://login.microsoftonline.com/83100458-a9da-4cf4-bf20-a39f85680132/oauth2/v2.0/token",
            "tls_client_profile_url": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/orgs/0e5bc3ae-e943-4626-825c-5287650247f8/tls-client-profiles/359edadf-1905-48d2-b169-08705f8f296f"
        },
        "userinfo_endpoint": {
            "endpoint": "https://graph.microsoft.com/oidc/userinfo",
            "tls_client_profile_url": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/orgs/0e5bc3ae-e943-4626-825c-5287650247f8/tls-client-profiles/359edadf-1905-48d2-b169-08705f8f296f"
        },
        "jwks_uri": {
            "endpoint": "https://login.microsoftonline.com/83100458-a9da-4cf4-bf20-a39f85680132/discovery/v2.0/keys",
            "tls_client_profile_url": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/orgs/0e5bc3ae-e943-4626-825c-5287650247f8/tls-client-profiles/359edadf-1905-48d2-b169-08705f8f296f"
        },
        "logout_endpoint": "https://login.microsoftonline.com/83100458-a9da-4cf4-bf20-a39f85680132/oauth2/v2.0/logout",
        "client_id": "ed85e538-01d7-4659-88ee-de96e7ffdb49",
        "client_secret": "********",
        "response_type": "code",
        "scope": "openid email",
        "credential_location": "auth_header",
        "features": [
            "auto_onboard",
            "userinfo"
        ],
        "field_mapping": {
            "email": "email",
            "username": "name",
            "first_name": "given_name",
            "last_name": "family_name"
        },
        "request_endpoint": {},
        "email_endpoint": {},
        "state_ttl": "1200",
        "redirect_uris": {
            "provider": {
                "redirect_uri": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/manager/uia/oauth2/redirect",
                "redirect_uri_implicit": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/manager/oauth2/redirect",
                "oidc_redirect_uri": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/oauth2/redirect"
            },
            "admin": {
                "redirect_uri": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/admin/uia/oauth2/redirect",
                "redirect_uri_implicit": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/admin/oauth2/redirect",
                "oidc_redirect_uri": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/oauth2/redirect"
            },
            "consumer": {
                "redirect_uri": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/consumer-api/ibm_apim/oauth2/redirect",
                "oidc_redirect_uri": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/consumer-api/oauth2/redirect"
            }
        }
    },
    "registry_type": "oidc",
    "integration_url": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/cloud/integrations/user-registry/a2872422-95c1-4ebd-84ce-6907e78811a9",
    "owned": true,
    "external_group_mapping_enabled": false,
    "identity_providers": [
        {
            "name": "azure-oidc",
            "title": "azure-oidc"
        }
    ],
    "user_managed": false,
    "user_registry_managed": false,
    "created_at": "2023-04-25T12:51:50.365Z",
    "updated_at": "2023-04-25T12:51:50.365Z",
    "org_url": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/orgs/0e5bc3ae-e943-4626-825c-5287650247f8",
    "url": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/user-registries/0e5bc3ae-e943-4626-825c-5287650247f8/62fc9261-3393-4aa6-a273-14e0b2cf705a"
}
{
	"admin_user_registry_urls": [ "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/user-registries/0e5bc3ae-e943-4626-825c-5287650247f8/32b3ef9c-1500-4d3d-86d8-0aed44569daa","https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/user-registries/0e5bc3ae-e943-4626-825c-5287650247f8/42d3121a-9d31-47b5-a15b-b27ab2dd25de","https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/user-registries/0e5bc3ae-e943-4626-825c-5287650247f8/62fc9261-3393-4aa6-a273-14e0b2cf705a" ],
	"admin_user_registry_default_url": https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/user-registries/0e5bc3ae-e943-4626-825c-5287650247f8/62fc9261-3393-4aa6-a273-14e0b2cf705a,
    "provider_user_registry_urls": [ "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/user-registries/0e5bc3ae-e943-4626-825c-5287650247f8/5b9aeec7-dac5-4d8b-bde3-e9d5acc04d76","https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/user-registries/0e5bc3ae-e943-4626-825c-5287650247f8/42d3121a-9d31-47b5-a15b-b27ab2dd25de","https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/user-registries/0e5bc3ae-e943-4626-825c-5287650247f8/62fc9261-3393-4aa6-a273-14e0b2cf705a" ],
    "provider_user_registry_default_url": "https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/user-registries/0e5bc3ae-e943-4626-825c-5287650247f8/62fc9261-3393-4aa6-a273-14e0b2cf705a"
}
user-registry-setting   https://cpd-cp4i.itzroks-3100015379-c5zltg-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/integration/apis/apic/myapic/api/cloud/settings/user-registries
    Let's inspect some key points about the script (create-azure-ad-oidc.sh).
    • Obtain endpoints of the OIDC provider (authorization, token, userinfo, jwks_uri, logout) from Azure AD link (https://login.microsoftonline.com/${AZURE_TENANT_ID}/v2.0/.well-known/openid-configuration) 
    • Scopes:
      • openid - openid token is returned
      • email - email field is returned
    • Features:
      • auto_onboard - new users can automatically be onboard in API Connect
      • userinfo - userinfo endpoint can be used to retrieve information about the user
    • Field mapping
      • email (APIC) is mapped to email (Azure AD)
      • username (APIC) is mapped to name (Azure AD)
      • first_name (APIC) is mapped to given_name (Azure AD)
      • last_name (APIC) is mapped to family_name (Azure AD)
  11. After the OIDC User Registry is created, you need to note down the Redirect URI - and because we are using this for Cloud Admin user registry, we will use admin > oidc_redirect_uri.
  12. Return to the App Registrations page in Azure, and click on Add a Redirect URI link. Then click on Add a platform > Web. Enter the Redirect URI you have copied in previous step and check the boxes for Access Tokens and ID Tokens. Click Configure button.
  13. Now you are ready to test. Open a browser to the API Connect cloud manager UI. You will find there is a new azure-oidc button you have just configured. Click on this button.
  14. You will be redirected to the Azure AD page to select a user account you want to use for login. I will use cloudadmin.
  15. Then you will be prompt to enter your password. Enter your password.
  16. If login is successful, you will be login to the API Connect Cloud Manager landing page. However, you will find that this new user does not have administrator rights, therefore not able to do any administrator work.
  17. You need to assign this user to a role (in the Cloud Manager)
  18. Now the cloudadmin user is added as a member with Administrator rights.
  19. To test, re-login again using cloudadmin user. You will see, now the user has Administrator rights.








































1 comment
63 views

Permalink

https://community.ibm.com/community/user/blogs/kok-sing-khong/2023/04/25/apic-oidc-azuread

Comments

Abu Davis
Wed August 21, 2024 06:08 AM

Could you please make the GIT link public? 

https://github.com/khongks/apic-scripts-public.git