Gatsby RSS feed

In-Memory API Deployer

Fri, 18 Mar 2022 00:00:00 GMT

WSO2 API Manager & Auth0 OIDC SSO

Mon, 21 Feb 2022 00:00:00 GMT

Greetings Everyone!!! 👋

In this medium, we will be walking through how to configure OIDC SSO between WSO2 API Manager and Auth0.

We will be using the WSO2 API Manager v4.0.0 for this demo

Let’s break in…

🔐 Auth0

Before continuing with the SSO configurations in the WSO2 API Manager, there are a few configurations and rules that need to be added to the Auth0 platform to experience the expected outcome.

If you already have an Auth0 account, you can move on to the next steps, if you are not, then navigate to Auth0 (https://auth0.com) and register for a trial account to continue with this demo.

✋ OIDC Client Registration

Let’s start by creating and configuring an Application in Auth0.

Once you have successfully logged in to the Auth0 dashboard, expand the Applications menu from the side-bar and click on Applications, and Create Application. Fill the following

Name: WSO2APIM
Choose an application type: Regular Web Applications

and Create.

On the next page, move to Settings tab view, and provide the following inputs

Allowed Callback URLs: https://localhost:9443/commonauth

and Save Changes.

Next, expand the Advanced Settings, and move to Endpoints tab to gather all OIDC related endpoints of the Auth0 application to configure with the WSO2 API Manager.

✋ User Registration

We have now, successfully configured an application in Auth0 for our OIDC SSO flow. Next, we’ll register a demo user and a role in the Auth0 platform.

Expand the User Management menu from the sidebar and click on Users > Create User. Create a user with the following details

Email: demouser@auth0.com
Connection: Username-Password-Authentication

and click on Create.

On the next view, edit the Name field and provide Demo User as the value.

Next, expand the User Management from the side navigation bar and click on Roles to create a role in the Auth0 platform. Click on Create Role and add the following

Name: subscriber
Description: Subscriber Role to Login to the Devportal

and Create.

Navigate to the Users tab, and click on Add Users. Select the user that we registered previously and click on Assign to assign the subscriber role to our user.

✋ Rules to add Roles

As the next step, we are going to create a Rule in the Auth0 to include the Role details of the User in the ID token. To perform this, navigate to Auth Pipeline section and click on Rules.

Click on Create and select Empty Rule and provide the following as inputs

Name: Add Roles to User ID Token

Script

function addRoles(user, context, callback) {
    const namespace = 'http://sample.net';
    const assignedRoles = (context.authorization || {}).roles;
    
    let idTokenClaims = context.idToken || {};
    let accessTokenClaims = context.accessToken || {};
    
    idTokenClaims[`${namespace}/roles`] = assignedRoles;
    accessTokenClaims[`${namespace}/roles`] = assignedRoles;
    
    context.idToken = idTokenClaims;
    context.accessToken = accessTokenClaims;
    
    callback(null, user, context);
}

and Save changes.

The rule will get applied to all necessary flows and applications in the Auth0 platform. With this, we have now completed configuring the Auth0 platform to perform OIDC SSO. Now, let’s start configuring the other end, WSO2 API Manager.

🌐 WSO2 API Manager

Let’s start running a WSO2 API Manager v4.0.0 pack locally and then configure the SSO with Auth0 for the Devportal.

If you haven’t already run a WSO2 API Manager in your environment, download the distribution from here and start the server by executing sh api-manager.sh command from the <apim_home>/bin directory.

Once the server is started, navigate to https://localhost:9443/devportal and click on Sign-in to auto-create the Service Provider entries.

✋ Identity Provider

First, let’s register an Identity Provider in the API Manager server to represent the Auth0.

Open up your favourite browser, go to the Carbon Management console of the API Manager server by hitting to https://localhost:9443/carbon and logging in with the admin credentials.

Once logged in, click on Add under the Identity Providers section. Create an IDP with the following

Identity Provider Name: Auth0
Display Name: Auth0
Identity Provider’s JWKS Endpoint: Enter the JSON Web Key Set URL of the Application, we created in Auth0 (ex: https://dev-.....auth0.com/.well-known/jwks.json)

Expand the Claim Configuration > Basic Claim Configuration and add a Claim Mapping for the roles. Select Define Custom Claim Dialect and add the following claim mappings by clicking on Add Claim Mapping

http://sample.net/roles : http://wso2.org/claims/role

Next, expand the Role Configuration > Add Role Mapping and add the following

subscriber : Internal/subscriber

And choose the Role Claim URI as http://sample.net/roles.

Then, expand the Federated Authenticators > OAuth2/OpenID Connect Configuration and perform the following

Enable OAuth2/OpenIDConnect: true
Default: true
Client ID: Enter the Client ID of the WSO2APIM Application
Client Secret: Enter the Client Secret of the WSO2APIM Application
Authorization Endpoint URL: Enter the OAuth Authorization URL captured from Auth0
Token Endpoint URL: Enter the OAuth Token URL captured from Auth0
Userinfo Endpoint URL: Enter the OAuth User Info URL captured from Auth0
Additional Query Parameters: scope=openid profile email

Next, expand the Just-in-Time Provisioning section and perform the following

Always provision to User Store Domain: PRIMARY
Provision silently: true

and Register.

Attached below is the IDP configurations of Auth0 configured in the WSO2 API Manager server.

✋ Devportal Service Provider

Now, let’s open up the auto-created Devportal Service Provider by going to Service Providers > List > apim_devportal > Edit.

Expand the Local & Outbound Authentication Configuration and perform the following

Authentication Type: Federated Authentication : Auth0
Assert Identity using mapped local subject identifier: true

and click on Update.

🎉 Voila!!! 🎉

We have successfully configured OIDC SSO between WSO2 API Manager and Auth0. As the final step, let’s perform a few testing and verify the flow

Open up your favourite browser and navigate to https://localhost:9443/devportal. Click on Sign-in, this will direct you to the Auth0’s login page to log in with the user that we have created for this demo, demouser@auth0.com. Provide the credentials and proceed with the sign-in flow.

Once the login flow is successful, you will be redirected back to the Devportal’s page and will be signed in with the user that we have registered in the Auth0, along with the same user provisioned in the WSO2 API Manager side.

Happy Stacking!!! ✌️

SAML Bearer Grant with WSO2 API Manager

Fri, 04 Feb 2022 00:00:00 GMT

Greetings Everyone !!! 👋

In this medium, I will be walking through how to configure and generate an access token in WSO2 API Manager using SAML Bearer Grant flow.

As to demonstrate the flow and configurations, we will be using WSO2 API Manager v3.2.0 & WSO2 Identity Server v5.10.0

As out-of-the-box, the WSO2 API Manager v3.2.0 supports SAML Bearer grant flow to generate access tokens by providing a valid SAML Assertion to the system.

So, let’s dive in and start configuring our WSO2 API Manager & Identity Server to perform the SAML Bearer grant …

🌐 WSO2 API Manager

Let’s start with configuring the WSO2 API Manager.

As of the first step, we need a Service Provider configured in the API Manager environment to generate access tokens. We can either log in to the Devportal and create an Application to generate tokens or, we can log in to the Carbon Management console of the API Manager server and create a new Service Provider.

For this demonstration, I will be focusing on creating a Service Provider from the Carbon Management console of the API Manager server.

✋ Service Provider

Let’s log in to the Carbon Management console of the API Manager server by firing up your favourite browser and navigating to https://localhost:9443/carbon

Sign in to the console with the admin credentials. Once logged in, navigate to the Service Providers section and click on Add.

Configure the Service Provider with the following information

Service Provider Name: saml-bearer-sp

and click on Register.

On the next screen, expand the Inbound Authentication Configuration > OAuth/OpenID Connect Configuration and click on Configure. Make sure, that you have selected the SAML2 grant type in the Allowed Grant Types and add a Callback URL if you have enabled either Code or Implicit grant type. Once done, scroll down and click on Add

Make a note of the generated OAuth Client Key and OAuth Client Secret of the Service Provider, as we will be using these credentials when invoking the Token endpoint with SAML Bearer Token grant.

Click on Update to save the Service Provider configurations.

Next, we need to configure an Identity Provider in the API Manager server to validate the signature of the SAML Assertion that we are passing.

✋ Identity Provider

Navigate to the Identity Providers section and click on Add to add a new Identity Provider in the API Manager server.

Configure the Identity Provider with the following inputs

Identity Provider Name: wso2is
Display Name: WSO2 IS

Expand the Federated Authenticators > SAML2 Web SSO Configuration and perform the following

Enable SAML2 Web SSO: true
Service Provider Entity ID: wso2apim (enter the Service Provider Entity ID that you have registered in the IS server)
Identity Provider Entity ID: wso2is (enter the Identity Provider Entity ID of your IS Server)
SSO URL: https://localhost:9444/samlsso (assuming that the Identity Server is running on a port offset of 1)

click on Register

In addition to the above configurations, we also need to export the public certificate of the WSO2 Identity Server and import it under the created Identity Provider in the API Manager. This is because, we will be using the WSO2 Identity Server as our SAML provider, therefore the SAML Assertion is going to be signed with the private key of the Identity Server. Hence, in order to verify the signature of the assertion, we need to export and import the public certificate of the WSO2 Identity Server into API Manager.

If you are planning to use any other SAML providers than WSO2 Identity Server, then it is required to import the public certificate of the respective provider in the created Identity Provider

Execute the following command to export the public certificate from the WSO2 Identity Server. Run the commands from <WSO2_IS_HOME>/repository/resources/security directory

Provide the WSO2 Carbon JKS Keystore password when prompted

keytool -export -keystore wso2carbon.jks -alias wso2carbon -file wso2carbon.crt

Now, we have exported the public certificate as .crt format. Execute the following openssl command to convert the .crt to .pem format to upload certificate via the UI

openssl x509 -inform der -in wso2carbon.crt -out wso2carbon.pem

Now, that we have exported the public certificate of the WSO2 Identity Server as .pem format, let’s upload it via the Carbon Management console. Navigate to the Identity Providers section in the Carbon Management console of the WSO2 API Manager > List > and click on the Edit of our newly created Identity Provider.

Under Choose IDP certificate type, select Upload IDP certificate and choose the exported public certificate. And click on Update to save the configurations.

and Done!!! 🎉 🎉 🎉

We have now configured our WSO2 API Manager to successfully validate the SAML Assertion and to generate an access token using SAML Bearer grant flow.

🔍 Test & Verify

To try out and verify the SAML Bearer grant flow, let’s configure our existing API Manager to perform a federated authentication with the Identity Server using SAML SSO.

This is an extra part of the configuration to acquire a valid SAML Response and Assertion from the WSO2 Identity Server to try out our SAML Bearer grant flow. If you have already acquired a SAML Assertion from the Identity Server using any App integration, then this section is not required for you to follow 😃

If you haven’t already started a WSO2 Identity Server, start one with a port offset of any desired (I will be using a port offset of 1 for this demonstration).

Let’s start configuring the WSO2 Identity Server for our SAML SSO

🔐 WSO2 Identity Server

✋ Service Provider for SAML SSO

Open up your favourite browser and navigate to https://localhost:9444/carbon and sign in to the Carbon Management console of the Identity Server using the admin credentials.

Go to the Service Providers section and click on Add. Create a Service Provider named wso2apim and click on Register.

On the next screen, expand the Inbound Authentication Configuration > SAML2 Web SSO Configuration and click on Configure.

Fill the form with the following

Issuer: wso2apim
Assertion Consumer URLs: https://localhost:9443/commonauth (and click on Add to add the URL)
Enable Response Signing: true
Enable Signature Validation in Authentication Requests and Logout Requests: true
Enable Single Logout: true
Enable Attribute Profile: true
Include Attributes in the Response Always: true
Enable Audience Restriction: https://localhost:9443/oauth2/token
Enable Recipient Validation: https://localhost:9443/oauth2/token
Enable Assertion Query Request Profile: true
Idp Entity ID Alias: wso2is

and click on Register

Since we have enabled the Signature validation in authentication requests and log out requests, we have to upload the WSO2 API Manager’s public certificate to the Service Provider that we have registered.

Execute the following commands from <WSO2_APIM_HOME>/repository/resources/security directory

Provide the WSO2 Carbon JKS Keystore password when prompted

keytool -export -keystore wso2carbon.jks -alias wso2carbon -file wso2carbon.crt

Now, we have exported the public certificate as .crt format. Execute the following openssl command to convert the .crt to .pem format to upload certificate via the UI

openssl x509 -inform der -in wso2carbon.crt -out wso2carbon.pem

Navigate to the Service Provider that we have registered, and under Basic Information section, select the Upload SP certificate and upload the .pem certificate under Application Certificate. Once uploaded, click on Update to update the configurations.

Now, let’s move to WSO2 API Manager and configure the API Manager to initiate and perform the SAML2 Web SSO with WSO2 Identity Server from the Devportal.

🌐 WSO2 API Manager

As we have already registered an IDP in the API Manager server providing the URLs of the WSO2 IS, let’s open the same and make a few more adjustments for our SAML Web SSO requirement.

✋ Identity Provider: wso2is

Log in to the Carbon Management console of the API Manager server and navigate to Identity Providers > List > Edit the registered wso2is IDP.

Expand the Federated Authenticators > SAML2 Web SSO Configuration and perform the following

Enable Authentication Request Signing: true
Enable Assertion Signing: true
Enable Logout Request Signing: true
Enable Authentication Response Signing: true
Signature Algorithm: RSA with SHA1
Digest Algorithm: MD5

click on Update.

Next, we’ll configure the Devportal’s Service Provider to perform a Federated Authentication with WSO2 Identity Server.

✋ Service Provider

Navigate to Service Providers > List. Select and Edit the Service Provider that is registered for the Devportal, apim_devportal.

Expand the Local & Outbound Authentication Configuration and tick the Federated Authentication and select the registered IDP from the list, wso2is. Click on Update and save the configurations.

Let’s make the configurations work!!
Open up the browser, and install the SAML Tracer extension to capture the SAML Responses while performing the SAML SSO. After installing the extension, hit https://localhost:9443/devportal to go to Devportal. Click on the SIGN-IN button at the top-right corner.

Please make sure that the SAML Tracer extension is started and listening to the SAML transactions made in the browser.

This will take you to the WSO2 Identity Server’s login page, as you will be able to see and confirm the behaviour by inspecting the URLs in the browser. Sign in with your user’s credential and capture the successful SAML Response using the SAML Tracer.

Given below is a screenshot of the SAML Tracer and the SAML Response captured

Next, copy the raw SAML Response from the SAML Tracer extension (from Parameters tab and not SAML tab) and Base64 decode it.

Do not perform any prettifying or beautifying process on the XML response. If the XML response is prettified, you might encounter unmarshalling errors and unexpected behaviours when trying to generate the Access Token

Extract the saml2:Assertion content (including the opening and closing tags: <saml2:Assertion ...>, </saml2:Assertion>) from the decoded content and Base64 URL encode it. As of final step, let’s prepare the Token request with the required inputs

CLIENT_ID: The OAuth Client Key copied from the saml-bearer-sp
CLIENT_SECRET: The OAuth Client Secret copied from the saml-bearer-sp
ENCODED_SAML_ASSERTION: The SAML Assertion section that is extracted from the SAML Response and Base64 URL encoded

curl -u <CLIENT_ID>:<CLIENT_SECRET> \ 
-X POST https://localhost:8243/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer' \
--data-urlencode 'assertion=<ENCODED_SAML_ASSERTION>' \
-k

and HIT!!! (make sure you hit the request prior to the expiration of the SAML Assertion, else, you will get an error indicating that the assertion is not valid).

Voila!!! 🎉

We have now successfully configured our environments and performed the SAML Bearer Grant and generated an Access Token from the API Manager using the SAML Assertion acquired from the WSO2 Identity Server.

Happy Stacking!!! 😃 ✌️

Preview Deck | Troubleshoot Guide

Tue, 18 May 2021 00:00:00 GMT

👋 Preview Deck

—h—

Troubleshoot Throttling

This reveal deck contains the fundamental steps and instructions to troubleshoot few well-known issues in API Throttling of WSO2 API Manager.

This deck is drafted based on API Manager v3.2.0, however, this can referenced for v3.1.0, and v3.0.0 versions

Move across the deck using either arrow key on the keyboard, of by clicking the arrow icons in the bottom-right corner

Let’s get started!!!

reveal-note:

Use the arrow keys (up,right, down, and left) on the keyboard to navigate through the deck

Press `o` to show an overview of the deck

Press `f` for full-screen mode

—h—

Are you having any issues while publishing a (custom) policy from the Admin portal?

If yes, go through the below-given steps to verify the configurations in your environment. If no, move to the right.

—v—

A probable cause for this behavior can be a misconfiguration of the Service URL of the Policy Deployer. Open the <publisher>/repository/conf/deployment.toml and validate the following

[apim.throttling]
service_url = "https://tm-lb-hostname:9443/services/"

The service_url must point to the Traffic Manager’s services endpoint. This is used to publish and deploy the execution policies in Traffic Manager. If the endpoint is not reachable or misconfigured, there will be errors logged in the Publisher.

—v—

Further, if you are using different user credentials (username and password) for each node, please perform the following configurations in the Publisher’s deployment.toml to authenticate with the Traffic Manager without any failures.

[apim.throttling.policy_deploy]
username = "traffic-manager-admin-username"
password = "traffic-manager-admin-password"

—h—

We assume that you don’t have any issues with creating or publishing (custom) policies from the Admin portal. But, experiencing inconsistent behavior during the runtime.

If you are experiencing errors in the Gateway node during runtime, scroll down. If not, move to the right.

reveal-note:

Advanced Throttling enables an async communication between Gateway and Traffic Manager. During runtime, the Gateway collects and sends events to the Traffic Manager to process decisions.

If the API resource is unsecured, a default Unauthenticated subscription policy will be used to evaluate the subscription level throttling nevertheless the assigned.

—v—

Are you seeing any of the following error-traces in the Gateway node?

ERROR - DataEndpointConnectionWorker Error while trying to connect to the endpoint. Cannot borrow client for ssl://traffic-manager-host:9711
org.wso2.carbon.databridge.agent.exception.DataEndpointAuthenticationException: Cannot borrow client for ssl://traffic-manager-host:9711
    ...
Caused by: org.wso2.carbon.databridge.agent.exception.DataEndpointException: Error while opening socket to traffic-manager-host:9711. Connection refused (Connection refused)
    ...
Caused by: java.net.ConnectException: Connection refused (Connection refused)

Yes? proceed down.

—v—

The mentioned errors are logged due to connectivity issues between Gateway and Traffic Manager. Gateway establishes a Binary transport communication link with Traffic Manager to publish throttle data events.

Check whether all required ports related to Binary communication (9711 and 9611) are opened and not blocked by any firewall. You can use the following telnet from Gateway instance to check the connectivity between Traffic Manager.

telnet traffic-manager-host 9611

—h—

Happy Stacking!!! 👌👌👌

Preserve Authorization Header in WSO2 API Manager

Sat, 03 Apr 2021 00:00:00 GMT

Greetings Everyone!!! 👋

In this medium, I will be walking-through a solution to preserve and send the Authorization Header to the Backend service at the (per) API level.

APIs that are published through the WSO2 API Manager is protected by either OAuth2, Basic, or API Key tokens. As out-of-the-box, the API Manager server removes the incoming Authorization Header during the token validation process, so that the Backend services will never know the actual Access Token used to invoke the API in the API Manager.

The API Manager has a global configuration to enable and disable the removal of the Authorization Header. The configuration can be found under the api-manager.xml of the API Manager server.

<RemoveOAuthHeadersFromOutMessage>true</RemoveOAuthHeadersFromOutMessage>

and the respective TOML configuration will be as following

[apim.oauth_config]
enable_outbound_auth_header = false

But, let’s say, we have a requirement, where we only need to pass the Authorization Header presented for a specific API and not for others. In such scenarios, as out-of-the-box, there is no direct solution to achieve this requirement. So, let’s see how we can achieve this requirement with minimal customizations.

To make it easy, I have already developed a custom handler to extract and preserve the Authorization header in the message context. Given below is the custom handler implementation to preserve the Authorization header in the message context and then to pass it to the Backend service with the help of a mediation sequence.

Let’s get more understanding on how they work…

✋ How does it work?

The custom handler is implemented to engage and extract the Authorization header during an API invocation through the WSO2 API Manager Gateway. The handler extracts the Authorization header from the Transport Headers and saves it to the Message Context with a custom Key-Value pair.

Then, a global-in-mediation-sequence is added to the Gateway node, to check whether the custom Key-Value pair exists in the context. If exists, the value is retrieved from the context and set back as an Authorization header, and sent to the Backend service.

You can find a sample global-in mediation sequence under the example directory of the above-shared repository Global Sequence. 👌

✋ Configure API Manager

Let’s go through how to configure the WSO2 API Manager to engage this handler and perform the trick.

First, clone the shared repository, and build the project using the following command

The repository contains the source and dependencies supported to WSO2 API Manager v3.1.0

mvn clean package

Once, the build is done successfully, copy the built JAR artifact from the <project>/target directory and place it inside <apim>/repository/components/lib directory.

Next, we have to configure the velocity_template.xml of the API Manager to engage the handler when the API is published to the Gateway nodes. To do so, we need to alter the existing <apim>/repository/resources/api_templates/velocity_template.xml with the following segment.

...
<handlers xmlns="http://ws.apache.org/ns/synapse">
#foreach($handler in $handlers)
  #if($handler.className == 'org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler')      
    #if($apiObj.additionalProperties.get('PreserveAuthHeader') == true)
    <handler class="com.sample.handlers.PreserveAuthHeaderHandler">            
    #if($handler.hasProperties())
    #set ($tempMap = $handler.getProperties() )
      #foreach($property in $tempMap.entrySet())
        #if($property.key == 'AuthorizationHeader')
        <property name="$!property.key" value="$!property.value" />                
        #end
      #end
    #end
    </handler>
    #end
  #end
...

The above-segment introduces a condition to check whether an API Custom Property has been introduced with the name of PreserveAuthHeader. If yes, then the custom handler will be engaged and listed under the handlers section along with the default shipped handlers.

Next, we have to add a global-in mediation sequence to read the custom key-value pair property from the context and to set the Authorization header back. Given below is a sample global-in mediation sequence and you can find the exact sequence inside the example directory of the shared repository.

<sequence xmlns="http://ws.apache.org/ns/synapse" name="WSO2AM--Ext--In">
  <!-- a custom log to print the header content -->
  <log level="custom">
    <property name="Extracted Auth Header" 
expression="get-property('PRESERVE_AUTH_HEADER_HANDLER_TOKEN')" />
  </log>
  <!-- setting back the Auth header if property exists-->
  <filter 
    xpath="get-property('PRESERVE_AUTH_HEADER_HANDLER_TOKEN')">
    <property name="Authorization" scope="transport" expression="get-property('PRESERVE_AUTH_HEADER_HANDLER_TOKEN')" />     
  </filter>
</sequence>

Once the configurations are done, start the API Manager server and perform the following

Log-in to the Publisher portal
Create a new API or edit an existing API that needs to pass the Authorization header to the Backend
Navigate to the Properties menu of the respective API and add the following custom property
- PreserveAuthHeader : true
And save the API

With the above-made configurations, now we will be able to see that our custom handler getting engaged with the respective API.

We can verify this by navigating to the <apim>/repository/deployment/server/syanpse-configs/default/api directory and opening up the respective API Synapse artifact. There, under the handlers section, our custom PreserveAuthHandler will be engaged prior to the default APIAuthenticationHandler.

Voila!!! 🎉 🎊 🎉

We have now successfully configured the API Manager server to preserve and send the Authorization header to the Backend service (per) API level.

Happy Stacking!!! 😎

Log4j2 Appenders

Sat, 13 Mar 2021 00:00:00 GMT

Stratagem

WSO2 API Manager now supports (from v3.0.0 onwards) Log4j2 to manage logs and appenders. In this cheat, we will be looking at how to configure a custom appender for a simple requirement.

The requirement is to log the Synapse Wire logs in a seperate log file. So, first, lets enable the Synapse Wire DEBUG logs in the API Manager server.

The following configurations and steps are verified in API Manager v3.0.0, v3.1.0, and v3.2.0 environments

logger.synapse-wire.name = org.apache.synapse.transport.http.wire
logger.synapse-wire.level = DEBUG
# add to the loggers
loggers = synapse-wire, ...

To enable the Synapse Wire logs in API Manager server, navigate to <apim>/repository/conf directory and open the log4j2.properties. Then, add the mentioned properties (if not already exist) and set the DEBUG level.

Then, add the synapse-wire keyword to the loggers as mentioned. Refer to Enable Gateway Wire Logs for more info.

appender.WIRE_LOG.type = RollingFile
appender.WIRE_LOG.name = WIRE_LOG
appender.WIRE_LOG.fileName 
    = ${sys:carbon.home}/repository/logs/wire.log
appender.WIRE_LOG.filePattern 
    = ${sys:carbon.home}/repository/logs/wire-%d{MM-dd-yyyy}.log
appender.WIRE_LOG.layout.type = PatternLayout
appender.WIRE_LOG.layout.pattern 
    = TID: [%tenantId] [%appName] [%d] %5p {%c} - %m%ex%n
appender.WIRE_LOG.policies.type = Policies
appender.WIRE_LOG.policies.time.type = TimeBasedTriggeringPolicy
appender.WIRE_LOG.policies.time.interval = 1
appender.WIRE_LOG.policies.time.modulate = true
appender.WIRE_LOG.policies.size.type = SizeBasedTriggeringPolicy
appender.WIRE_LOG.policies.size.size = 10MB
# add to the appenders
appenders = WIRE_LOG, ...

Now, let’s introduce a Log4j2 appender to log the Synapse Wire to a separate log file.

Given is a sample Log4j2 Appender configuration with RollingFile. The presented configuration contains the basic set of patterns and layouts to print logs. You can further enhance the configurations according to your need.

Once the appender is configured, the Appender name needs to be added to the appenders property in the log4j2.properties.

logger.synapse-wire.name = org.apache.synapse.transport.http.wire
logger.synapse-wire.level = DEBUG
# configure with the appender
logger.synapse-wire.appenderRef.WIRE_LOG.ref = WIRE_LOG
logger.synapse-wire.additivity = false

At last, configure the synapse-wire logger configuration with the created WIRE_LOG appender as given.

Once the configurations are saved, we will see a new log file created with the name wire.log inside the <apim>/repository/logs directory containing the Wire logs.

We have now successfully configured a Log4j2 Appender to create and log the Synapse Wire DEBUG logs in a separate file named wire.

The complete set of log4j2 configurations that we introduced and used in this cheat is given below.

# appender declaration
appenders = WIRE_LOG, ...
# custom appender
appender.WIRE_LOG.type = RollingFile
appender.WIRE_LOG.name = WIRE_LOG
appender.WIRE_LOG.fileName = ${sys:carbon.home}/repository/logs/wire.log
appender.WIRE_LOG.filePattern = ${sys:carbon.home}/repository/logs/wire-%d{MM-dd-yyyy}.log
appender.WIRE_LOG.layout.type = PatternLayout
appender.WIRE_LOG.layout.pattern = TID: [%tenantId] [%appName] [%d] %5p {%c} - %m%ex%n
appender.WIRE_LOG.policies.type = Policies
appender.WIRE_LOG.policies.time.type = TimeBasedTriggeringPolicy
appender.WIRE_LOG.policies.time.interval = 1
appender.WIRE_LOG.policies.time.modulate = true
appender.WIRE_LOG.policies.size.type = SizeBasedTriggeringPolicy
appender.WIRE_LOG.policies.size.size = 10MB
# engaging the synapse-wire logger
loggers = synapse-wire, ...
# enabling Synapse Wire DEBUG
logger.synapse-wire.name = org.apache.synapse.transport.http.wire
logger.synapse-wire.level = DEBUG
# configuring the logger with the appender
logger.synapse-wire.appenderRef.WIRE_LOG.ref = WIRE_LOG
logger.synapse-wire.additivity = false

Key & Subscription Validation

Tue, 02 Mar 2021 00:00:00 GMT

Token Revocation: WSO2 API Manager & Keycloak KM

Wed, 18 Nov 2020 00:00:00 GMT

Greetings Everyone!!! 👋

In this blog, I will be presenting a custom implementation to achieve the Immediate Token (cache) Revocation in WSO2 API Manager v3.2.0 with Keycloak configured as Key Manager.

As you all may aware, WSO2 API Manager v3.2.0 got released!!! 🎉🎊🎉
and it is packed with a lot of new features and functionalities to support various use-cases and requirements. One of the praised features is the immediate Token (cache) revocation.

The API Manager v3.2.0 now also supports configuring third-party Key Managers with less hassle through the Admin portal. You can learn more about the out-of-the-box key-manager connectors and the respective instructions below.

As out-of-the-box, the Token cache revocation is supported by the WSO2 API Manager when using the in-built Resident Key Manager or when using the WSO2 Identity Server as Key Manager. But, this feature was made as an extension to other supported Key Managers to achieve the requirement if required.

You can learn more about the default Token (cache) Revocation flow the WSO2 API Manager v3.2.0 at Token Revocation

Hence, in this writing, we will be going through a sample implementation on achieving the Token (cache) revocation feature with Keycloak & WSO2 API Manager.

Let’s get started …

✋ Implementation & Execution Flow

First, let me brief you on the presented implementation and the requirement around it and then will explain how it works.

The custom implementation is an extension for the Keycloak server to introduce and expose a custom Token Revocation endpoint. The extension implements the RealmResourceProvider to expose the custom revocation endpoint per Realm basis.

You may wonder why a custom revocation endpoint is needed in the Keycloak server; Well, Keycloak’s default Revocation endpoint only supports revoking the Refresh tokens and not the JWT Access Tokens.

The above-statement is made considering the Keycloak v11 as the latest version in the community while delivering this blog 😃

The best-practice and security measure followed by the Keycloak community is to generate JWT Access Tokens with smaller validity.

But let’s assume that we have a requirement and we need to generate tokens with an hour validity. Further, the JWT tokens can be revoked by the client, and once the token is revoked the API Manager Gateway nodes needs to be aware of these in order to block the API requests that are associated with them.

Hence, to achieve the above requirement, I have come up with an extension introducing a custom revoke endpoint to verify the JWT and to send the notifications to the API Manager servers.

If you are eager to try out the solution, the complete source and instructions on applying those are available in the following Git repository 👏 👏 👌

Let’s get some more insights into the execution flow and the data flow of our custom implementation to understand the complete picture of the solution.

Given below is the HTTP definition of our custom Token Revocation endpoint in the Keycloak.

The {realm-name} needs to be replaced with the realm name of the Keycloak that you are using to generate the JWT Tokens. Basically the Realm of the Keycloak clietns presented

POST /auth/realms/{realm-name}/revoke-token
Authorization: Basic (base64<consumerkey:consumersecret>)
Content-Type: application/x-www-form-urlencoded
token=<JWTToken>

As soon our custom revocation endpoint receives a request with an active JWT token, the endpoint (implementation) verifies the passed JWT token’s signature, and validity.

If the token is found active and not expired, the following data are extracted from the presented JWT token to send the notification to the API Manager

JTI: JWT Token Identifier
Expiry Time of the token
Consumer Key

👉 Once the required data are extracted, those are composed and passed to the Event Sender to publish them to the Traffic Manager node. The data publishing is handled asynchronously and it is done by invoking the newly introduced Notification endpoint of Internal API of the Traffic Manager node.

Please find the HTTP definition of the Notification endpoint of the Traffic Manager node which is called from our custom extension

POST /internal/data/v1/notify
Host: traffic-manager:9443
Authorization: Basic (base64<username:password>)
Content-Type: application/json
{
  "accessToken": <JTI>,
  "expiryTime": <expiry time>,
  "user": <username>,
  "tokenType": "JWT",
  "timeStamp": <current timestamp>,
  "type": "token_revocation",
  "tenantId": -1234,
  "tenantDomain": "carbon.super",
  "consumerKey": <consumer key>,
  "eventId": <random UUID>
}

Once the Traffic Manager receives the request, the data is sent to the Token Revocation JMS Event Publisher through a set of pre-defined Event Streams deployed in the Traffic Manager server. And from the Event Publisher, a Token Revocation message is pushed to all subscribed Gateway nodes to mark the specific JTI (JWT) as revoked.

The Gateway node processes the received JMS message and persists the JTI record along with the Token expiry value in a temporary map named RevokedJWTDataHolder and clears the respective token entries from all other Token caches of the Gateway. This process ensures that the Gateway to not allow API requests if any of the revoked JWT tokens are used.

I know that it is hard to visualize the flow that I have explained above in my own words 😕 😟 …
But, I believe you all may be familiar with the following saying

"A Picture Speaks a Thousand Words"

Therefore, I have created a high-level diagram plotting the communications and data flows between the servers and components for an easier understanding …👌 👏

🎉 Voila!!! 🎉

Hope this blog presented you with a little bit of information and insight on the Token Revocation feature of the WSO2 API Manager and how possible it is to make an extension and to achieve them through other supported Key Managers. 👌

Clone the source > build > deploy and test the scenarios and share your experience
As this is a custom implementation, there can be bugs. Warmly welcome your contributions to the Repo if you find anything that needs to be fixed or improved. Issues and PRs are welcome 😃

Happy Stacking !!!! 🤘 ✌️

Token Revocation

Sun, 25 Oct 2020 00:00:00 GMT

Blocking Conditions

Mon, 12 Oct 2020 00:00:00 GMT

Throttling Execution Flow

Sun, 11 Oct 2020 00:00:00 GMT

Retrieve (Custom) API Properties

Sat, 26 Sep 2020 00:00:00 GMT

Stratagem

As out-of-the-box, the WSO2 API Manager supports adding and creating custom API properties. You can learn more about managing custom API properties from here. In this cheat, we will be looking at how to access these custom API properties from mediation sequences.

For demo, we have introduced a custom property named transparent-token in one of our published API, and we have a requirement to log this property in the logs whenever this API is invoked.

Quick Note
The following illustrations are developed considering an All-In-One deployment environment of the API Manager server. In a distributed environment, the Gateway component will not have access to the registry space of the Publisher component unless it is shared and configured under the master-datasources.xml and registry.xml.

<sequence name="custom-sequence" 
  xmlns="http://ws.apache.org/ns/synapse">
  <log level="custom">
      <property 
        name="prop" 
        value="value-to-be-printed" 
      />
  </log>
</sequence>

All introduced custom API properties are stored and persisted inside the local registry of the API Manager. We are going to implement a mediation sequence to retrieve our transparent-token custom property from the local registry space of the API Manager.

Since, our requirement is to only log the property, we are going to start implementing a custom mediation sequence with a simple log mediator.

<sequence name="custom-sequence" 
  xmlns="http://ws.apache.org/ns/synapse">
  <log level="custom">
      <property 
        name="prop" 
        expression="get-property('registry')" 
      />
  </log>
</sequence>

Change the log mediator to use expression in order to use the get-property() method to retrieve our custom API property. As the introduced custom property is available in the registry space, we are going to specify the scope of our get-property() with the registry scope.

fn:concat(
  'gov:/apimgt/applicationdata/provider/',
  $ctx:api.ut.apiPublisher, '/',
  $ctx:api.ut.api, '/',
  $ctx:api.ut.version, '/',
  'api@api_meta.transparent-token'
)

Now let’s construct the registry path to access our transparent-token custom property. The registry path is constructed with the use of existing context properties. The fn:concat function is used to join the strings and the properties to build a complete registry path.

Following are the usages of the specified context properties

$ctx:api.ut.apiPublisher: Publisher of the API
$ctx:api.ut.api: API name
$ctx:api.ut.version: API version

<sequence name="custom-sequence" 
  xmlns="http://ws.apache.org/ns/synapse">
  <log level="custom">
      <property 
        name="prop" 
        expression="get-property('registry', 
          fn:concat(
            'gov:/apimgt/applicationdata/provider/',
            $ctx:api.ut.apiPublisher, '/',
            $ctx:api.ut.api, '/',
            $ctx:api.ut.version, '/',
            'api@api_meta.transparent-token'
          ))"
      />
  </log>
</sequence>

We have now successfully developed a custom mediation sequence to retrieve our custom API property from the registry space and to print the value in the logs.

Upload the sequence as an in-mediation sequence to the API from the Publisher portal and, Save and Publish, Invoke and check the logs.

Given below is the complete Synapse sequence (in-sequence), we developed to access our custom property named transparent-token from the local registry space of the API Manager.

<sequence name="custom-sequence" xmlns="http://ws.apache.org/ns/synapse">
  <log level="custom">
      <property 
        name="prop"
        expression="get-property('registry', 
          fn:concat(
            'gov:/apimgt/applicationdata/provider/',
            $ctx:api.ut.apiPublisher, '/',
            $ctx:api.ut.api, '/',
            $ctx:api.ut.version, '/',
            'api@api_meta.transparent-token'
          ))" />
  </log>
</sequence>

WSO2 API Manager & Azure AD (OIDC) SSO

Mon, 27 Apr 2020 00:00:00 GMT

Greetings Everyone !!! 👋

In this medium, I will be running over on how to configure Federated OpenID Connect SSO flow between WSO2 API Manager and Azure AD service.

I will be using the WSO2 API Manager 3.1 to illustrate the configurations and the flows.
You can refer to one of my OIDC SSO mediums along with this to configure older versions of WSO2 API Manager.
OIDC SSO flow with Gluu
OIDC SSO with Keycloak
OIDC SSO with Okta

I hope you’ll find this one useful and illustrative enough to go through the configurations … 👐

Azure

✋ App Registration

I hope you have an active Azure account to continue with the demo. If not, click here and register for a trial account to continue with the demonstrations.

Once, you are done with the registration, direct to the Azure portal and log-in with your credentials. After a successful login, you will find a similar screen as prompted below

If you can’t find the Azure Active Directory, search for it using the search bar presented at the top

Select the Azure Active Directory. Then, click on Create Directory in the top-bar to create a Directory.

This is because we don’t have any registered Active Directory to continue with our demo. Hence, we will be creating a new Directory.

On the following form, select the Azure Active Directory and click on Next.

Enter the following

Organization Name: Demo OIDC Organization
Initial Domain Name: demooidcorg
Country/Region: United States (you choose any)

and Review + Create, then select Create. It will take a moment to create an Active Directory in your environment. After successful creation, you will receive a notification. Click on the link to direct to the created Active Directory.

On the left navigation panel, select the App Registration to register an OpenID Connect client.

The following screen can be different to you, if you have any registered Apps

Click on the New Registration and input the following

Name: WSO2APIM
Supported Account Types: Personal Microsoft Accounts Only (I have chosen this as per demo purposes)
Redirect URI: Web & https://localhost:9443/commonauth (change the hostname according to your environment)

and Register.

After successful creation, you will be directed to a general info page of the registered application. On the following screen copy and save the Client ID as we will be in need to configure the WSO2 API Manager.

Then, click on the Certificates & Secrets section in the left-sidebar, and select the New Client Secret to generate a secret for our WSO2APIM app

Enter the following in the prompted modal

Description: WSO2APIM OIDC Secret
Expires: Never

and Add.

Copy and save the generated Client Secret.

After making the note, click on the API Permissions section in the left navigation panel to configure the OpenID and Profile scope permissions to our App.

You will see a similar screen as follows after clicking on the API Permissions

Select the Add a Permission button arranged in the top to add new permissions to the existing tree. Once you click on the Add a Permission button, you will see a side-window popped-up with the following options

choose the Microsoft Graph. On the following screen, select the following permissions

email
openid
profile

and Add Permission (leave the existing permissions as it is). You will end up in a similar screen as below with all the configured API Permissions

✋ Group Registration

Since we are using a trial account to experiment and configure the SSO flow with Azure AD, we will be creating a Security Group named Subscriber to represent the Subscriber role in the Azure service.

If you have an active paid subscription, then you can follow on creating Roles in the Azure service and assign them to the Users. In addition, you can also create Groups in the Azure AD and assign it to your Users

Go to our Demo OIDC Organization and click on the Groups. You will find a similar window

Click on the New Group placed in the top and fill the following on the prompted window

Group Type: Security
Group Name: Subscriber
Group Description: Group for Subscriber

Then click on the No owners selected. On the prompted side-window, select our Azure account and Add Owner. Then click on the No members selected and perform the same as described above and click on Create to create the Subscriber Group.

Select our Subscriber group from the list and make a note of the Object ID value.

This is to map the Groups with the API Manager’s internal roles. As of the demo (for simplicity), we will be using the Object IDs of the groups to map the roles in the API Manager

👉 Add Groups Claim

Now we have to configure our Azure app to populate the Groups claim in the ID Token. Go to our Azure app WSO2APIM and click on Token Configurations.

Click on the Add Groups Claim and tick the Security Groups. Then, expand the ID section and choose the Group ID and enable Emit groups as role claims.

and Add.

Now we are all set with the Azure configurations. But before moving forward, we’ll make a note on the Authorization and Token endpoint of our Azure application. We will need these endpoints when configuring an Identity Provider in the API Manager.

Go to the Overview page of our Azure App and click on the Endpoints button. This will pop a side-window with all the necessary endpoints of our application. Make a note on the Authorization v2 and Token v2 endpoints. In addition to the above-set, also make a note on the OpenID Connect metadata document endpoint.

If you go to the endpoint URL mentioned in the OpenID Connect metadata document, you will find a set of metadata to configure an Identity Provider in the API Manager.

WSO2 API Manager

✋ Configure Email Username

Before starting our configurations with the Identity Provider creation and Service Provider registrations, we will be enabling a property called EnableEmailUsername in the API Manager server.

This is because of the preferred_username claims in the Azure ID Tokens are represented with the email usernames. Hence, as for this demo, we will be enabling email username in our API Manager server to provision and log-in to the Store nodes.
Without preferred_username, we can also make use of the sub claim presented in the Azure ID Token, which will be a unique ID value. If you are planning to use the sub claim as the User ID in the API Manager, then you may have to increase the number of characters of the Username Regex Pattern in the user-mgt.xml (you scroll to the very bottom for the full configurations)

Navigate to <apim>/repository/conf and open and add the following configurations in the deployment.toml file

[tenant_mgt]
enable_email_domain = true

After making the change, fire-up the server to configure the required Identity Provider and the Service Provider to demo our OIDC SSO.

✋ Identity Provider Configurations

Direct to the Carbon Management console, and log-in with the admin credentials. Select the Add under the Identity Providers and input the following

Identity Provider Name: AzureADIDP
Display Name: Azure AD IDP
Choose IDP Certificate Type: Use IDP JWKS Endpoint
Identity Provider’s JWKS Endpoint: the JWKS URI found in the OpenID Connect metadata document

Next, expand the Claim Configurations > Define Custom Claim Dialect > Add Claim Mapping and add the following mappings

preferred_username : http://wso2.org/claims/displayName
roles : http://wso2.org/claims/role

and

User ID Claim URI: preferred_username
Role Claim URI: roles

Expand the Role configurations and click on the Add Role Mapping. Paste the Object ID acquired from the Subscriber group in the Azure service and map it with our internal subscriber role

The Object ID of Subscriber Group : Internal/subscriber

Given below is a sample Role mapping configuration …

Then, expand the Federated Authenticators > OAuth2/OpenID Connect Configurations and perform the following

Enable OAuth2 / OpenID Connect: true
Default: true
Client ID: the Client ID of our WSO2APIM Azure app
Client Secret: the generated secret of our WSO2APIM Azure app
Authorization Endpoint URL: the authorization_endpoint in the OpenID Connect metadata document
Token Endpoint URL: the token_endpoint in the OpenID Connect metadata document
Userinfo Endpoint URL: the userinfo_endpoint in the OpenID Connect metadata document
Additional Query Parameters: scope=openid%20profile%20email

And finally, expand the Just-In-Time Provisioning accordion and configure as follows

and Register.

Given below is a complete snap of the AzureADIDP Identity Provider’s configuration in the API Manager server

✋ Service Provider Configurations

From API Manager 3.x onwards, both Publisher and Devportal (A.K.A Store) nodes are configured with OIDC SSO flows as default.

Hence, go to both Publisher and Devportal nodes and click on the Sign-in button to automatically create and register a Service Provider for the OIDC SSO flow. You don’t have to log-in to the portals, the above-mentioned process is to create the respective Service Providers in the API Manager.

Navigate to the Carbon Management console and sign-in with the Admin credentials.

Click on List under Service Providers section to list the automatically created Service Providers respective to Publisher apim_publisher and Devportal apim_devportal.

Click the Edit of the apim_devportal and expand the Claim Configurations and make the following changes

preferred_username : http://wso2.org/claims/displayName : Requested

Next, expand the Local & Outbound Authentication Configuration and select the AzureADIDP as the Federated Authentication and make the following changes

and Update.

🎉 Voila!!! 🎉

We have now successfully configured OpenID Connect Federated Authentication between Azure AD and Single Sign-On with OpenID Connect with API Devportal (Store).

👏 👏 👏

I hope you find this one useful to try-out and configure Federated Authentication & SSO between WSO2 API Manager and Azure Server.

Next, we’ll do a small test…

Test Drive

Direct to the Store portal using https://localhost:9443/devportal/ and click on Sign-In.

You will be redirected to the Microsoft’s login page to enter the credentials. Enter the credentials of our Microsoft User and then allow the attributes on the consent screen to continue with the federation and provision of the Gluu users to the WSO2 API Manager.

Login to the Carbon Management console of WSO2 API Manager and list the Users. If the Federation is successful and JIT Provisioned performed without any errors, you will be able to see our user in the prompted list.

Happy Stacking !!!! 🤘 ✌️

Troubleshooting

Username Regex

If you are planning to use the default sub claim value as the Username in the API Manager then, it is required to change the regex pattern of the Username in the user-mgt.xml.

API Manager 3.x series follows a new configuration model; a deployment.toml file to configure the entire server. Following are the TOML configurations related to the Regex patterns in the user-mgt.xml.

In the following, I have increased the length from 30 to 50. if the value recieved via sub claim is less than 30 characters, you don’t have to perform the following changes

# deployment.toml configurations
[user_store.properties]
UsernameJavaRegEx = "^[\\S]{3,50}$"

JIT Provisioning & Authentication Framework

If you want to enable the debug logs for the JIT Provisioning flow and the Federated authentication flows, then open and add the following property in the <server>/repository/conf/log4j2.properties

# to enable DEBUG logs in the authentication framework
logger.authentication_framework.name=org.wso2.carbon.identity.application.authentication.framework
logger.authentication_framework.level=DEBUG

And specify the authentication_framework name in the loggers property as follows (you mention the logger anywhere in the loggers property)

loggers = authentication_framework, AUDIT_LOG, ...

It is not required to restart the server after making the changes in the log4j2.properties. It is hot-applied 😍

WSO2 API Manager & Gluu SSO (OIDC)

Sun, 19 Apr 2020 00:00:00 GMT

Greetings Everyone!!! 👋

In this medium, I will be 🚶 ‍walking through on how to Federate and configure OpenID Connect SSO flow between the WSO2 API Manager and the Gluu Identity Server.

I will be using WSO2 API Manager v2.6 with WSO2 Identity Server as Key Manager v5.7 and Gluu Server v3.1.7 and performing SSO to the API Store node

I hope you enjoy it and find it useful 🙌

Gluu Identity Server

Quick Installation & Start

Let’s start the demo with the Gluu Identity Server installation. You can refer here for quick installation on the Google Cloud Platform.

Following are the commands executed to install and configure the Gluu server in the above-given reference …

# add the sources
echo "deb https://repo.gluu.org/ubuntu/ xenial main" > /etc/apt/sources.list.d/gluu-repo.list
# download key
curl https://repo.gluu.org/ubuntu/gluu-apt.key | apt-key add -
# udpate the existing packages
apt-get update
# install gluu-server 3.1.7
apt-get install gluu-server-3.1.7
# start the gluu-server
service gluu-server-3.1.7 start
# login to the gluu-server
service gluu-server-3.1.7 login
# execute the following to setup the gluu-server
cd /install/community-edition-setup/
./setup.py

✋ OpenID Connect Configurations & Metadata

Once the installation is done and the server is up and running as expected, log-in to the Gluu’s management console using the Admin credentials.

Click on the Configuration section in the navigation panel and select the JSON Configurations to list all required configurations and metadata of the Gluu Server.

In the following screen, move to the oxAuth Configuration tab and scroll down to the bottom or search for legacyIdTokenClaims. Change the configuration to true. This is to enable the Gluu Identity Server to pass the requested claims and information via the ID Tokens.

Scroll to the top and make a note on the following endpoints. We need the following endpoint URIs when configuring the WSO2 servers

authorizationEndpoint : will look like <host>/oxauth/restv1/authorize
tokenEndpoint : will look like <host>/oxauth/restv1/token
userInfoEndpoint : will look like <host>/oxauth/restv1/userinfo

After taking the notes, click on Certificates listed under the Configurations section and download the IDP Signing certificate and store it.

✋ OpenID Connect Client Registration

Next, we will be configuring an OpenID Connect client in the Gluu Identity Server to communicate and perform SSO flow with the WSO2 servers.

Expand the OpenID Connect section in the left navigation panel and select the Clients to list and create new clients.

Click on the Add Client, and on the next screen input the following

Client Secret: Click on the Generate Client Secret to generate one
Client Name: WSO2ISKM
Redirect Login URIs: https://localhost:9444/commonauth
Scopes: openid & profile
Response Types: code token & id_token
Grant Types: authorization_code & password

and Add.

Next, move to the Advanced Settings tab of our OpenID Connect client and enable the Include Claims In Id Token option by selecting true from the dropdown selection.

Please note that you have to enable the legacyIdTokenClaims in the JSON Configuration of the Gluu Server to make changes in the Include Claims In Id Token property in the Advanced Settings

and Update

Click on the Client Config Summary on the top and copy and save the Client ID and the Secret of our WSO2ISKM OpenID Connect client.

✋ User Registration

Next, click on the Users section and Add person to register a new User for this demo.

Add the following

Username: gluuuser
First Name: Gluu
Display Name: UserGluu
Last Name: User
Email: user@gluu.org
Password: any preferred passwords for your user 😃
User Status: Active

select and include the Preferred Username and Organization fields from the list displayed in the left-side

Preferred Username: gluuuser (same as Username)
Organization: Subscriber (to demo SSO with the API Manager Store node)

and Add.

✋ Scope & Claim Configurations

We are almost done configuring the Gluu server. As final steps in the Gluu Server, go to the OpenID Connect and select the Scopes.

Open the profile scope and click on Add Claim and include the following claims along with the existing

Preferred Username
Organization

For demo purposes, I have configured and included all required claims to the available scopes. As a best practice, try creating a new scope and including all additionally required claims into it. If so, then we have to include the newly created scope in our OpenID Connect client in the Gluu Server to serve the tokens.

WSO2 Identity Server as Key Manager

We are done with the Gluu configurations. Our next stop is on the WSO2 Identity Server as Key Manager.

I will be using WSO2 API Manager 2.6 and WSO2 Identity Server as Key Manager 5.7 on this demo. You can refer here to configure IS-KM in your environment.
As a bonus bonanza, you can use the Hydrogen (deprecated version can be found here) to configure the environment within minutes

✋ Identity Provider Configurations

Let’s start the journey 🚀 by configuring an Identity Provider to Federate with the Gluu Server.

Start the IS-KM server and sign-in to the Carbon Management console. Select the Add under the Identity Providers section to register an Identity Provider.

On the following screen, add the followings

Identity Provider Name: GluuIDP
Display Name: Gluu Identity Provider
Identity Provider Public Certificat: upload the certificate we downloaded from the Gluu Server IDP Signing Cert

Next, expand the Claim Configuration and the Basic Claim Configuration and click on the Define Custom Claim Dialect and make the following

preferred_username : http://wso2.org/claims/displayName
o : http://wso2.org/claims/role

The organization claim from the Gluu Server is passed as o in the ID Token

Next, expand the Role Configuration section and map the Subscriber organization retrieved from the Gluu Server with our Internal/subscriber role as follows

Expand the Federated Authenticators > OAuth2/OpenID Connect Configuration and make the following changes

Enable OAuth2 / OpenIDConnect: true
Default: true
Client ID: the Client ID of the WSO2ISKM
Client Secret: the Client Secret of the WSO2ISKM
Authorization Endpoint URL: the authorizationEndpoint from the configurations
Token Endpoint URL: the tokenEndpoint from the configurations
Userinfo Endpoint URL: the userInfoEndpoint from the configurations
OpenID Connect User ID Location: User ID found among claims
Additional Query Parameters: scope=openid profile

if you have introduced a new scope to include the preferred_username and organization claims, then append that scope as well

Enable HTTP Basic Auth for Client Authentication: true (as default Gluu server expects Basic auth header for authentication)

Expand the Just-In-Time Provisioning and select the PRIMARY as the provisioning User Store Domain

and Register.

Attached is a complete-snap of our GluuIDP configurations in the Identity Server as Key Manager server 👌👌

✋ Service Provider Configurations

Next, we need a Service Provider to communicate with the API Store node. Click on Add under the Service Providers and do the following

and Register.

On the next screen, expand the Claim Configurations and select the Define Custom Claim Dialect to and define the following to pass the preferred_username claim to the Store node

preferred_username : http://wso2.org/claims/displayName : Requested

Next, expand the OAuth2/OpenID Connect Configuration under the Inbound Authentication Configuration and click on Configure. On the following screen add

Callback URL: https://localhost:9443/store/jagg/jaggery_oidc_acs.jag

and Add.

Finally, expand the Local & Outbound Authentication Configuration and select the GluuIDP as the Federated Authentication

and Update.

As always, a complete-snip of the API_STORE Service Provider configuration is given below👌 🤓

👉 Before moving to the next part, make a note or copy the client_id and the client_secret which are generated in our Service Provider as we need ’em when configuring the site.json.

WSO2 API Manager

We are almost done with our configurations. As of the final steps, we have to configure the site.json which is related to the API Manager’s Store node to initiate the SSO flow.

✋ Store: Site.json

Open-up the WSO2 API Manager’s directory and move to <apim>/repository/deployment/server/jaggeryapps/store/site/conf and open the site.json to configure the OIDC

Given below is a complete segment of the OpenID Connect configuration model in the site.json. You can refer to the following to configure your site.json in your environment.

Replace the Client ID and Client Secret with the credentials acquired from the API_STORE Service Provider

"oidcConfiguration" : {
    "enabled": "true",
    "issuer": "API_STORE",
    "identityProviderURI": "https://localhost:9444/oauth2/token",
    "authorizationEndpointURI": "https://localhost:9444/oauth2/authorize",
    "tokenEndpointURI": "https://localhost:9444/oauth2/token",
    "userInfoURI": "https://localhost:9444/oauth2/userinfo",
    "jwksURI": "https://localhost:9444/oauth2/jwks",
    "logoutEndpointURI": "https://localhost:9444/oidc/logout",
    "authHttpMethod": "POST",
    "clientConfiguration" : {
        "clientId" : "Client ID",
        "clientSecret" : "Client Secret",
        "responseType" : "code",
        "authorizationType" : "authorization_code",
        "scope" : "phone email address openid profile",
        "redirectURI" : "https://localhost:9443/store/jagg/jaggery_oidc_acs.jag",
        "postLogoutRedirectURI" : "https://localhost:9443/store/",
        "clientAlgorithm" : "RS256"
    }
}

🎉 Voila!!! 🎉

We have now successfully configured OpenID Connect Federated Authentication between Gluu and Single Sign-On with OpenID Connect with API Store.

👏 👏 👏

I hope you find this one useful to try-out and configure Federated Authentication & SSO between WSO2 API Manager and Gluu Server.

Next, a small (alpha) test drive…

Test Drive

Direct to the Store portal using https://localhost:9443/store/ and click on Sign-In.

You will be redirected to the Gluu’s login page to enter the credentials. Enter the credentials of our Gluu User and then allow the attributes on the consent screen to continue with the federation and provision of the Gluu users to the WSO2 API Manager.

Login to the Carbon Management console of WSO2 API Manager and list the Users. If the Federation is successful and JIT Provisioned performed without any errors, you will be able to see our Gluu User in the prompted list.

Happy Stacking !!!! 🤘 ✌️

Troubleshooting

SSL Handshake | PKIX

If you encounter any SSL Handshake related issues or more precisely any PKIX Exceptions, then download the Public Certificate of the Gluu Server’s domain and add it to the WSO2 Identity Server as Key Manager’s trust-store.

You can download the Public certificate of the Gluu Server’s domain from the Browser. For example in Chrome, you can click on the padlock 🔒 icon near the URL and can download the certificate.

After successfully acquiring the certificate execute the following keytool command against the trust-store inside the <iskm>/repository/resources/security directory

# execute the following command and wso2carbon for the password
keytool -import -alias gluu -file <path-of-the-cert> -storetype JKS -keystore client-truststore.jks

After a successful import, try the SSO flow again in a new window.

JIT Provisioning & Authentication Framework

If you want to enable the debug logs for the JIT Provisioning flow and the Federated authentication flows, then open and add the following property in the <server>/repository/conf/log4j.properties

# to enable DEBUG logs in the authentication framework
log4j.logger.org.wso2.carbon.identity.application.authentication.framework = DEBUG

And the JIT Provisioning is handled by org.wso2.carbon.identity.application.authentication.framework.handler.request.impl.JITProvisionningPostAuthenticationHandler.

WSO2 API Manager & Keycloak SAML SSO

Sun, 12 Apr 2020 00:00:00 GMT

Greetings Everyone !!! 👋

In this medium, I will be 🚶walking through on how to configure SAML Federated Authentication & SSO flow between WSO2 API Manager and Keycloak including JIT (User) Provisioning.

In my previous mediums, I have used WSO2 API Manager 2.6 & WSO2 Identity Server as Key Manager 5.7 to achieve the SAML2 SSO Federated authentication flows.
Today, I will be using only the API Manager 2.6 pack and the Out-Of-The-Box features to achieve the requirement

As out-of-the-box, the WSO2 API Manager 2.6 provides a platform to configure SAML2 Federation.

But, please note that it is advised (best-practice) to use WSO2 Identity Server as Key Manager to perform Federated Authentication with External Identity Providers in Production grade environments.

Let’s break-in…

🔐 Keycloak

Let’s start our configurations from the External Identity Provider.

I hope you already have an active Keycloak server up and running. If not please follow the below section to download and start a Keycloak server in your environment.

Starting-Up Keycloak

Click Here to download the Keycloak standalone distribution to your environment. Extract the archive and navigate to the <keycloak>/bin directory and execute the following command to start the Keycloak server …

# move to bin directory and execute the following
# unix
sh standalone.sh
# windows
standalone.bat

Then, fire-up your favorite browser and go to http://localhost:8080/auth. In the prompted page, register an admin user for our Keycloak server.

& Done … simple as that 👏 👏

👉 You can follow up on the following Doc to get started with the Keycloak server …

✋ SAML 2.0 Metadata

After a successful log-in to the Keycloak server with our admin user, you will be looking into a similar UI as follows

Click on the SAML 2.0 Identity Provider Metadata to get the required configurations metadata.

Save the metadata as we will be using that in the following sections to configure Federated Identity Provider.

✋ SAML2 Client Registration

Click on the Clients under Configure to list all the existing registered clients of Keycloak Server. You will be looking into a similar screen as follows

We will be using the existing Master realm to create required Clients, Users, and Roles in the Keycloak server

Select the Create button to add a new client. Set the following

Client ID: wso2apim-saml
Client Protocol: saml

and Save.

In the next screen, add the following to configure our wso2apim-saml client in the Keycloak

Name: WSO2 APIM SAML Client
Enabled: true
Client Protocol: saml
Include AuthnStatement: true
Sign Documents: true
Signature Algorithm: RSA_SHA1
SAML Signature Key Name: NONE
Canonicalization Method: EXCLUSIVE
Force POST Binding: true
Front Channel Logout: true
Force Name ID Format: true
Name ID Format: username
Valid Redirect URIs: https://localhost:9443/commonauth
Master SAML Processing URL: https://localhost:9443/commonauth

and under Fine Grain SAML Endpoint Configuration

Assertion Consumer Service POST Binding URL: https://localhost:9443/commonauth
Assertion Consumer Service Redirect Binding URL: https://localhost:9443/commonauth

and Save.

Next, click on the Roles tab to create a role in Keycloak server representing the Subscriber role in the WSO2 API Manager

Click on Add Role to create a new Role and fill the following …

Role Name: subscriber

and Save

User Registration

We have now successfully configured our APIM SAML Client wso2apim-saml in the Keycloak Server. Next, we will be creating a new user to do our test runs.

Select the Users under the Manage section in the Left Navigation Panel and you will find a similar screen as follows

Smash the Add User button and feed the following

Username: keycloakuser
Email: key@cloak.com
First Name: Keycloak
Last Name: User
User Enabled: true
Email Verified: true

and Save.

Move to the Credentials tab and enter a password for the created user. Disable the Temporary Password and click on the Set Password.

Then, move to the Role Mappings tab to map our Subscriber role with the newly created User.

Select the wso2apim-saml client in the Client Roles dropdown and then select the subscriber roles under the Available Roles section and click on the Add Selected to assign it.

Now, we have successfully created a temp user to perform our test runs. Next, we want to configure the scopes which are related to SAML in the Keycloak server to send all assigned Roles.

SAML Scope for Roles

Select the Client Scopes listed under Configure section and Edit the role_list scope.

Go to the Mappers section and click on Edit to edit the default configured Mapper to send the Roles which are assigned to the User and the application as SAML Response

Make the Single Role Attribute to true and Save.

This is because, as default Keycloak server will send back the SAML Response with multiple Role attributes.
If we enable the Single Role Attribute, a single attribute named Role will be passed along with the associated roles as its child element.

and as one last step in the Keycloak server, we need to get the public certificate of the Keycloak server.

🔒 Keycloak Cert

Go to the Realm Settings under Configure and select the Keys tab. Click on the Certificate of the RS256 Algorithm and copy the cert value to a text editor.

Add the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- to the copied value respectively at the beginning and at the end and save it as keycloak.cert

Following is the default Keycloak server’s Public Cert

👏 👏 👏 one domain is done.

Next, we will be moving to the WSO2 API Manager to configure an Identity Provider and a Service Provider to perform Federated SAML2 SSO.

WSO2 API Manager

✋ Identity Provider for Keycloak

Fire-up the WSO2 API Manager server and navigate to the Carbon Management console and login with your admin credentials.

Click on Add under Identity Providers section and feed the following Basic Information

Identity Provider Name: KeycloakSAMLIDP
Display Name: Keycloak SAML IDP

Select the IDP Certificate as Upload IDP Certificate and upload the keycloak.cert that we have created in the previous steps.

Next, expand the Claim Configurations and map our Role claim with the Internal Role claim.

Select the Define Custom Claim Dialect and click on Add Claim Mapping and enter the following

Role : http://wso2.org/claims/role

Select the Role in the Role Claim URI dropdown as well

Then, expand the Role Configuration accordion and enter the following to map the subscriber role of the Keycloak with the Internal/subscriber role of the API Manager

subscriber : Internal/subscriber

Next, click and expand the Federated Authenticators section and SAML SSO to configure the Federated authentication with our Keycloak Server

Put the following in the respective fields

Enable SAML2 Web SSO: true
Service Provider Entity ID: wso2apim-saml (our client name in the Keycloak Server)
NameID Format: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
Identity Provider Entity ID: http://localhost:8080/auth/realms/master (Entity ID can be found in the SAML Metadata of the Keycloak)
SSO URL: http://localhost:8080/auth/realms/master/protocol/saml (SSO URL can be found in the SAML Metadata of the Keycloak)

Finally, expand the Just-In-Time Provisioning and select the Always Provision to User Store Domain to PRIMARY and Provision Silently

and Save.

Attached is a full-snap of the configurations 😍 👌

✋ Service Provider

We are done with the Identity Provider configurations. Now, we have to create and register a Service Provider to SSO with the API Store node.

Log-in to the Carbon Management console and click on the Add under the Service Providers section and enter the following in the following screen

Service Provider Name: API_STORE

and Register.

On the following screen, expand the Inbound Authentication Configuration and select the OAuth/OpenID Connect Configuration to configure an OAuth app.

As default the WSO2 API Manager doesn’t support the SAML2 Web SSO Configurations in Service Provider. Hence, we are configuring an OAuth service provider to perform SSO with the API Store

On the prompted screen add the following

Callback URL: https://localhost:9443/store/jagg/jaggery_oidc_acs.jag

and Save.

Next, expand the Local & Outbound Authentication Configuration and select our KeycloakSAMLIDP as the Federated Authentication and Register (Save).

As always, I have attached the full-snap of the Service Provider configuration below 🤓

👉 Before moving to the next part, make a note or copy the client_id and the client_secret which are generated in our Service Provider as we need ’em when configuring the site.json.

✋ Store: Site.json

We are in the latter part of our demo flow.

As the last part, now we have to configure the site.json related to the Store node to communicate with our Service Provider.

The Store will start to communicate with our Service Provider and it will start to communicate with our Identity Provider and finally, our Identity Provider Federates with the Keycloak Server

Phew …. 🤓😅😅

Open-up the WSO2 API Manager’s directory and move to <apim>/repository/deployment/server/jaggeryapps/store/site/conf and open the site.json to configure the OIDC

Given below is a complete segment of the OpenID Connect configuration model in the site.json. You can refer to the following to configure your site.json in your environment.

Replace the Client ID and Client Secret with the credentials acquired from the API_STORE Service Provider
Also, if you notice, I have used usernameClaim property in the OIDC Configuration to look for the sub claim to acquire the username for our Store node. As default it will be referred to the preferred_username field. In SAML2 SSO Federation the preferred_username field is not guaranteed when provisioning the Users. Hence, it is required to configure the usernameClaim property in the OIDC configuration

"oidcConfiguration" : {
    "enabled": "true",
    "issuer": "API_STORE",
    "identityProviderURI": "https://localhost:9443/oauth2/token",
    "authorizationEndpointURI": "https://localhost:9443/oauth2/authorize",
    "tokenEndpointURI": "https://localhost:9443/oauth2/token",
    "userInfoURI": "https://localhost:9443/oauth2/userinfo",
    "jwksURI": "https://localhost:9443/oauth2/jwks",
    "logoutEndpointURI": "https://localhost:9443/oidc/logout",
    "authHttpMethod": "POST",
    "usernameClaim": "sub",
    "clientConfiguration" : {
        "clientId" : "Client ID",
        "clientSecret" : "Client Secret",
        "responseType" : "code",
        "authorizationType" : "authorization_code",
        "scope" : "phone email address openid profile",
        "redirectURI" : "https://localhost:9443/store/jagg/jaggery_oidc_acs.jag",
        "postLogoutRedirectURI" : "https://localhost:9443/store/",
        "clientAlgorithm" : "RS256"
    }
}

🎉 Voila!!! 🎉

We have successfully configured SAML2 Federated Authentication between Keycloak and Single Sign-On with OpenID Connect with API Store. Next, we will be doing a small test drive…

👏 👏 👏

Test Drive

Direct to the Store portal using https://localhost:9443/store/ and click on Sign-In.

You will be redirected to the Keycloak’s login page to enter the credentials. Enter the credentials of our Keycloak User and then allow the attributes on the consent screen to continue with the federation and provision of the Keycloak users to the WSO2 API Manager.

Login to the Carbon Management console of WSO2 API Manager and list the Users. If the Federation is successful and JIT Provisioned performed without any errors, you will be able to see our Keycloak User in the prompted list.

Happy Stacking !!!! 🤘 ✌️

WSO2 API Manager & Keycloak SSO

Sun, 05 Apr 2020 00:00:00 GMT

In this medium, I will be 🚶 walking through on how to configure OpenID Connect SSO flow between WSO2 API Manager and Keycloak including JIT (User) Provisioning.

I will be using WSO2 API Manager 2.6 along with Identity Server as Key Manager 5.7 to instruct and configure the SSO flow with Keycloak

I have broken the guide into 3 tiers and we will be going through them as follows …

Keycloak Configurations
WSO2 IS-KM Configurations
WSO2 API Manager Configurations

Keycloak 🔑

Let’s start our journey by downloading and configuring the Keycloak server in our local environments.

🚧 Downloading & Starting-Up the Keycloak

You can click on Here to download the Standalone Keycloak server distribution to your environment. If you already have a Keycloak server up and running you can ignore these steps and move on to the creation of realms.

Extract the archive and execute the following command from the bin directory to start the Keycloak server

# move to bin directory and execute the following
# unix
sh standalone.sh
# windows
standalone.bat

After a successful server start, fire-up your favorite browser and go to http://localhost:8080/auth and register an Admin User for our Keycloak Server.

👉 You can follow up on the following Doc to get started with the Keycloak server …

OpenIDConnect Endpoint URLs

After a successful log-in to the Keycloak server, you will be looking into a similar UI as follows

Click on the OpenID Endpoint Configuration to list all required Endpoint URLs and data to configure OpenID Connect in our Identity Providers.

Make a note of the Endpoint URLs and continue forward with the demo. We will be using these endpoint URLs to configure the Federated Authenticator in the WSO2 Identity Server as Key Manager.

OIDC Client Registration

Next, we will be creating and registering an OIDC Client in the Keycloak server to represent our WSO2 Identity Server as Key Manager.

We will be using the existing Master realm to create required Clients, Users, and Roles in the Keycloak server

Click on the Clients under Configure to list all the existing registered clients. You will see a similar screen as follows

Click on the Create button to add a new client. Set the following

Client ID: wso2is-km
Client Protocol: openid-connect

and Save.

In the following prompted screen add the following to configure our wso2is-km client in the Keycloak

The IS KM server is configured with the port offset of 1. Hence, the common-auth URLs are presented with https://localhost:9444

Name: WSO2 IS KM
Enabled: true
Access Type: confidential
Standard Flow Enabled: true
Implicit Flow Enabled: true
Direct Access Grants Enabled: true
Root URL: https://localhost:9444/commonauth
Valid Redirect URIs: https://localhost:9444/commonauth/*
Admin URL: https://localhost:9444/commonauth

and click on Save.

Next, go to the Credentials tab of our WSO2IS-KM client in the Keycloak server and make a copy of the client-secret value for later usage.

If you want you can regenerate the secret and make a copy of it to configure Keycloak IDP in the WSO2 IS KM server

After noting down the Secrets, click on the Roles tab to create a Subscriber Role.

We will be creating a Subscriber role in the WSO2IS-KM client to federate and give permissions to access the Store portal of WSO2 API Manager.

You will find a similar UI under the Roles tab

Click on Add Role to create a new Role and input the following …

Role Name: subscriber

and Save

And finally, click on the Mappers tab, to configure a claim mapping to send and expose our created Roles through the OIDC SSO flow (incl. ID Token) and via the User Info endpoint.

You’ll find a similar UI under the Mappers section …

Select the Add Builtin, and enable the client roles in the prompted screen and Save

Edit the Client Roles mapper with the following properties …

Client ID: wso2is-km
Multivalued: true
Token Claim Name: roles
Claim JSON Type: String
Add to ID token: true
Add to access token: true
Add to userinfo: true

and Save.

User Registration

As the first step, we are done configuring our WSO2 IS-KM Client in the Keycloak. Next, we will be creating a new User in the Keycloak server for our demo.

Select the Users under the Manage section in your Left Navigation Panel. You will find the created Admin user in the prompted screen

Click on Add User and prompt the following …

Username: keycloakuser
Email: key@cloak.com
First Name: Keycloak
Last Name: User
User Enabled: true
Email Verified: true

and Save

Move to the Credentials tab our created user and enter a password. Disable the Temporary Password and click on Set Password to save.

Next, move to the Role Mappings tab to map the Subscriber (which we created earlier) with our User.

Select the WSO2IS-KM client in the Client Roles dropdown and then it will list all the associated roles under the Available Roles section. Select the subscriber role and click on Add Selected to assign it …

And that’s all, we are done with the Keycloak initialization and configurations. 👏

🔐 WSO2 Identity Server as Key Manager

We have successfully configured our Keycloak Server to send required claims and the roles to perform SSO and User Federation.

You can find Docs to configure WSO2 Identity Server as Key Manager with API Manager. The IS-KM server will be running with a port offset of 1
💡 Bonus
You can use the Hydrogen CLI tool to configure both WSO2 API Manager & Identity Server as Key Manager within seconds

Registering an Identity Provider

Now we have to register an Identity Provider in the WSO2 IS KM to represent our Keycloak server. Let’s fire up the WSO2 IS-KM Server and log-in to the Carbon Management console.

Click on Add under the Identity Provider section to register an Identity Provider

Enter the Basic Informations

Identity Provider Name: KeycloakIDP
Display Name: Keycloak Identity Provider
Description: Identity Provider for Keycloak
Alias: https://localhost:9444/oauth2/token

Expand the Claim Configurations to map User ID and Role claims with the associated claims exposed by the Keycloak server. Click on Define Custom Claim Dialect and Add Claim Mapping to add custom claim mappings. Add the following …

preferred_username : http://wso2.org/claims/displayName
roles : http://wso2.org/claims/role

Then, define the User ID Claim URI as preferred_username and the Role Claim URI as roles

Next, expand the Role Configuration accordion to map our Keycloak’s Subscriber role with the Internal/subscriber role respectively in the WSO2 IS KM.

Click on Add Role Mapping and add the following

subscriber : Internal/subscriber

Expand the Federated Authenticators and OAuth2/OpenID Connect Configuration accordion to configure federated authentication with the Keycloak Server

Enter the following respective to the secrets and information retrieved from the WSO2IS-KM client in the Keycloak

Enable OAuth2/OpenIDConnect: true
Client ID: wso2is-km (our client name in the Keycloak Server)
Client Secret: Paste the secret we acquired under credentials
Authorization Endpoint URL: *Authorization Endpoint URL collected from the OpenID Connect Endpoint Configuration*
Token Endpoint URL: *Token Endpoint URL collected from the OpenID Connect Endpoint Configuration*
Callback URL: https://localhost:9444/commonauth
Userinfo Endpoint URL: *Userinfo Endpoint URL collected from the OpenID Connect Endpoint Configuration*

Finally, expand the Just-In-Time Provisioning accordion and select the Always Provision to User Store Domain to PRIMARY and make it Provision silently.

and Save.

Given below is a full-snap of the KeycloakIDP configurations in the WSO2 Identity Server as Key Manager 😍

Registering a Service Provider

Since we are focusing on configuring the SSO flow for the API Store portal of the API Manager server, we will be creating and registering a Service Provider in the WSO2 Identity Server as Key Manager.

Log-in to the Carbon Management console of the WSO2 IS KM Server and click on the Add under the Service Provider section.

Enter the following in the initial screen

Service Provider Name: API_STORE
Description: A Service Provider for API Store

and click on Register

On the next screen, expand the Claim Configuration accordion and a custom claim mapping for the Display Name as follows

preferred_username : http://wso2.org/claims/displayName

Then, expand the Inbound Authentication Configuration > OAuth/OpenID Connect Configuration and register a provider. On the following screen input the following

? The following callback URL is the OIDC ACS URL of the API Store

Callback URL: https:/localhost:9443/store/jagg/jaggery_oidc_acs.jag

and Register

Copy and make a note of the generated Client ID and the Client Secret to configure the Store Site JSON in the API Manager server.

Expand the Local & Outbound Authentication Configuration and select the Federated Authentication as the KeycloakIDP we have registered earlier and click on Update to update the configuration of the Service Provider.

Given below is a full-snap of the API_STORE SP configuration in the WSO2 Identity Server as Key Manager 😍😍

And we are done with the configurations on the WSO2 Identity Server as Key Manager 😎🙂

WSO2 API Manager

Now we are in the last tier of our guide. In this section, we will be configuring the site.json of the Store node to initiate the SSO flow with the WSO2 Identity Server as Key Manager and then to Federate the flow with the Keycloak server.

WSO2 API Manager is running on the same server with the default port offset of 0

API Store Site JSON

Open-up the WSO2 API Manager’s directory and move to <apim>/repository/deployment/server/jaggeryapps/store/site/conf and open the site.json to edit and configure the required params.

Given below is a complete segment of the OIDC Configuration model in the site.json. You can refer to the following object to configure your site.json in your environment

Replace the Client ID and Client Secret with the credentials acquired from the API_STORE Service Provider

"oidcConfiguration": {
    "enabled": "true",
    "issuer": "API_STORE",
    "identityProviderURI": "https://localhost:9444/oauth2/token",
    "authorizationEndpointURI": "https://localhost:9444/oauth2/authorize",
    "tokenEndpointURI": "https://localhost:9444/oauth2/token",
    "userInfoURI": "https://localhost:9444/oauth2/userinfo",
    "jwksURI": "https://localhost:9444/oauth2/jwks",
    "logoutEndpointURI": "https://localhost:9444/oidc/logout",
    "authHttpMethod": "POST",
    "clientConfiguration": {
        "clientId": "{{Client ID}}",
        "clientSecret": "{{Client Secret}}",
        "responseType": "code",
        "authorizationType": "authorization_code",
        "scope": "phone email address openid profile",
        "redirectURI": "https://localhost:9443/store/jagg/jaggery_oidc_acs.jag",
        "postLogoutRedirectURI": "https://localhost:9443/store/",
        "clientAlgorithm": "RS256"
    }
}

🎉 Voila!!! 🎉

We have successfully configured Single Sign-On with OpenID Connect between WSO2 API Manager and Keycloak. Next, we will be doing a small test drive…

👏 👌 👏

Test Drive

Direct to the Store portal using https://localhost:9443/store/ and click on Sign-In.

You will be redirected to the Keycloak’s login page to perform SSO. Enter the credentials of our Keycloak User and then allow the attributes on the consent screen to continue with the federation and provision of the Keycloak users to the WSO2 IS KM and API Manager.

Login to the Carbon Management console of either the WSO2 API Manager or the WSO2 Identity Server as Key Manager and list the Users.
If the Federation is successful and JIT Provisioned performed without any errors, then you will be able to see our Keycloak User in the prompted list.

Happy Stacking !!!! 🤘 ✌️

WSO2 API Manager & OAuth2 Protected Endpoint

Sun, 29 Mar 2020 00:00:00 GMT

Intro

As out-of-the-box 📦, the WSO2 API Manager supports Basic Auth and Digest Auth Protocol protected APIs and Backend services to integrate through. But, what if we have an OAuth2 Protected service and want to integrate and expose the service through API Manager? 🤔🤔🤔

In this medium, we will be going through a couple of custom mediation sequence and custom mediator implementations to fulfill our requirements on integrating OAuth2 protected APIs and Backends.

WSO2 Products, to be more specific the underlying Carbon Kernal platform provides extension points to plug and play custom sequences and mediation implementations to achieve customize requirements. We will be going through a custom mediation sequence and a custom mediator implementation today to achieve our requirements.

Custom Mediation Sequence

Simple Mediation Sequence

We can make use of the Synapse engine and the Synapse mediation sequences in WSO2 API Manager to achieve our ultimate requirement. Given below is a sample mediation in-sequence developed to call the respective OAuth2 token endpoint and use the generated Bearer Token to access the Backend.

Please note that the below-given Synapse mediation sequence is a sample and it needs some tweaks to make it work with other customized use-cases

  
          <?xml version="1.0" encoding="UTF-8"?>
        
          <sequence name="oauth2-sequence" xmlns="http://ws.apache.org/ns/synapse">
        
              <!-- token generation to the oauth server's token endpoint -->
        
              <!-- add the base64 encoded credentials -->
        
              <property name="client-authorization-header" scope="default" type="STRING" value="MDZsZ3BTMnh0enRhOXBsaXZGUzliMnk4aEZFYTpmdE4yWTdLcnE2SWRsenBmZ1RuTVU1bkxjUFFh" />
        
              <property name="request-body" expression="json-eval($)" scope="default" type="STRING" />
        
              <property name="resource" expression="get-property('axis2', 'REST_URL_POSTFIX')" scope="default" type="STRING" />
        
              <!-- creating a request payload for client_credentials -->
        
              <payloadFactory media-type="xml">
        
                  <format>
        
                      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
        
                          <soapenv:Body>
        
                              <root xmlns="">
        
                                  <grant_type>client_credentials</grant_type>
        
                              </root>
        
                          </soapenv:Body>
        
                      </soapenv:Envelope>
        
                  </format>
        
                  <args></args>
        
              </payloadFactory>
        
              <!-- set related headers to call the token endpoint -->
        
              <header name="Authorization" expression="fn:concat('Basic ', get-property('client-authorization-header'))" scope="transport" />
        
              <header name="Content-Type" value="application/x-www-form-urlencoded" scope="transport" />
        
              <property name="messageType" value="application/x-www-form-urlencoded" scope="axis2" type="STRING" />
        
              <property name="REST_URL_POSTFIX" value="" scope="axis2" type="STRING" />
        
              <!-- change the token endpoint -->
        
              <call blocking="true">
        
                  <endpoint>
        
                      <http method="POST" uri-template="https://localhost:9443/oauth2/token" />
        
                  </endpoint>
        
              </call>
        
              <!-- append the acquired access token and make the call to the backend service -->
        
              <property name="bearer-token" expression="json-eval($.access_token)" scope="default" type="STRING" />
        
              <property name="REST_URL_POSTFIX" expression="get-property('resource')" scope="axis2" type="STRING" />
        
              <header name="Authorization" expression="fn:concat('Bearer ', get-property('bearer-token'))" scope="transport" />
        
              <payloadFactory media-type="json">
        
                  <format>$1</format>
        
                  <args>
        
                      <arg evaluator="xml" expression="get-property('request-body')" />
        
                  </args>
        
              </payloadFactory>
        
          </sequence>

view raw oauth2-sequence.xml hosted with ❤ by GitHub

Now you have given us a sample mediation sequence to call the token endpoint and then to invoke the actual endpoint. But wait ✋, I noticed that the mediation is going to perform a Token call each and every time, and that is going to be an extra call for the API Manager.

Hmmm … 🙄🤔

Yes true, as per the sample mediation, yes, it will perform Token call each and every time. Well, we can minimize that by storing the acquired access token and the validity period in a temporary location (probably a Registry location) and make use of it.

🚧Enhanced Mediation Sequence with Registry Access

Given-below is an enhanced sample mediation sequence to store and retrieve the access token and the generated time from a custom Registry location and based on the validity to perform the Token call. 👌

If you are willing to continue with the enhanced mediation sequence, then it is required to create the necessary Registry resource in the API Manager server prior to the usage for a flawless experience.

I will be creating the following two Registry resources in a custom Governance Registry location

access_token : To store the acquired Access Token
generated_time : To store the Generated time of the Access token

You can create the necessary Registry collections and resources by navigating to the Carbon Management Console > Browse > Registry > _system > governance and add a registry collection named oauth_endpoint.

After successfully creating the Registry collection (oauth_endpoint), create the above-mentioned two registry resources with the following content

access_token : Leave the content as empty
generated_time : 0 (this is because we will be referring to this as Long type)

  
          <?xml version="1.0" encoding="UTF-8"?>
        
          <sequence name="oauth2-enhanced-sequence" xmlns="http://ws.apache.org/ns/synapse">
        
              <!-- retreiving the access token and the generated time if exists in the registry location -->
        
              <property name="stored-token" expression="get-property('registry', 'gov:/oauth_endpoint/access_token')" scope="default" type="STRING" />
        
              <property name="generated-time" expression="get-property('registry', 'gov:/oauth_endpoint/generated_time')" scope="default" type="LONG" />
        
              <!-- token generation to the oauth server's token endpoint -->
        
              <!-- add the base64 encoded credentials -->
        
              <property name="client-authorization-header" scope="default" type="STRING" value="MDZsZ3BTMnh0enRhOXBsaXZGUzliMnk4aEZFYTpmdE4yWTdLcnE2SWRsenBmZ1RuTVU1bkxjUFFh" />
        
              <property name="request-body" expression="json-eval($)" scope="default" type="STRING" />
        
              <property name="resource" expression="get-property('axis2', 'REST_URL_POSTFIX')" scope="default" type="STRING" />
        
              <!-- enhanced to perform subtract function -->
        
              <property name="CURRENT_SYSTEM_TIME" expression="get-property('SYSTEM_TIME')" type="STRING" />
        
              <property name="token_generated_time" expression="get-property('generated-time')" type="STRING" />
        
              <!-- filter and based on the validity condition make the token call -->
        
              <filter xpath="get-property('CURRENT_SYSTEM_TIME') - get-property('token_generated_time') > 3600000 or get-property('stored-token') = ''">
        
                  <then>
        
                      <!-- creating a request payload for client_credentials -->
        
                      <payloadFactory media-type="xml">
        
                          <format>
        
                              <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
        
                                  <soapenv:Body>
        
                                      <root xmlns="">
        
                                          <grant_type>client_credentials</grant_type>
        
                                      </root>
        
                                  </soapenv:Body>
        
                              </soapenv:Envelope>
        
                          </format>
        
                          <args></args>
        
                      </payloadFactory>
        
                      <!-- set related headers to call the token endpoint -->
        
                      <header name="Authorization" expression="fn:concat('Basic ', get-property('client-authorization-header'))" scope="transport" />
        
                      <header name="Content-Type" value="application/x-www-form-urlencoded" scope="transport" />
        
                      <property name="messageType" value="application/x-www-form-urlencoded" scope="axis2" type="STRING" />
        
                      <property name="REST_URL_POSTFIX" value="" scope="axis2" type="STRING" /> 
        
                      <!-- change the token endpoint -->
        
                      <call blocking="true">
        
                          <endpoint>
        
                              <http method="POST" uri-template="https://localhost:9443/oauth2/token" />
        
                          </endpoint>
        
                      </call>
        
                      <!-- extract the access token from the response -->
        
                      <property name="bearer-token" expression="json-eval($.access_token)" scope="default" type="STRING" />
        
                      <!-- store the generated token and the time -->
        
                      <property name="gov:/oauth_endpoint/access_token" expression="get-property('bearer-token')" scope="registry" type="STRING" />
        
                      <property name="gov:/oauth_endpoint/generated_time" expression="get-property('SYSTEM_TIME')" scope="registry" type="LONG" />
        
                      <!-- append the acquired access token and make the call to the backend service -->
        
                      <property name="REST_URL_POSTFIX" expression="get-property('resource')" scope="axis2" type="STRING" />
        
                      <header name="Authorization" expression="fn:concat('Bearer ', get-property('bearer-token'))" scope="transport" />
        
                      <payloadFactory media-type="json">
        
                          <format>$1</format>
        
                          <args>
        
                              <arg evaluator="xml" expression="get-property('request-body')" />
        
                          </args>
        
                      </payloadFactory>
        
                  </then>
        
                  <else>
        
                      <!-- the stored access token is still active, so we will be using that to invoke the endpoint -->
        
                      <header expression="fn:concat('Bearer ', get-property('stored-token'))" name="Authorization" scope="transport" />
        
                  </else>
        
              </filter>
        
          </sequence>

view raw oauth2-enhanced-sequence.xml hosted with ❤ by GitHub

🚩 Note:
The above-given mediation sequence needs access to the Registry DB to store and retrieve the access token related data. Therefore, if you are using a Distributed deployment (separate Gateway node), we do not recommend this approach as it is required to configure the GW nodes with the Registry DB which can impact the performance.

Class Mediator: OAuth Mediator

In this section, we will be looking into a custom class mediator implementation developed especially to cater to the requirement on integrating OAuth2 Protected endpoint with the WSO2 API Manager.

You can find the complete implementation and the source of the OAuth Mediator (class mediator) in GitHub.

Clone the project and build it by executing the following command from the root directory of the project

mvn clean package

Copy and place the built JAR Artifact inside the <APIM>/repository/components/lib directory. Then create a JSON file named wso2-oauth-mediator.json with the following structure and configure the Authorization server’s Token endpoint and the credentials

[
     {
         "id": "EP1",
         "tokenApiUrl": "https://localhost:9443/oauth2/token",
         "apiKey": "1234567890",
         "apiSecret": "0987654321",
         "username": "admin",
         "password": "admin",
         "grantType": "client_credentials",
         "scope": "default",
         "tokenRefreshInterval": 20
     }
]

Place the wso2-oauth-mediator.json inside the <APIM>/repository/conf directory and restart the server to take effect on the changes.

🚀 After a successful restart, create an in-sequence for the protected API and define the class mediator inside the sequence to execute and acquire the token

<sequence xmlns="http://ws.apache.org/ns/synapse" name="oauth-sequence">
    <class name = "org.wso2.apim.mediators.oauth.OAuthMediator">
        <property name="endpointId" value="EP1" />
    </class>
</sequence>

🎉 Voila!!! 🎉

We have now successfully slid through the approaches on integrating OAuth2 Protected endpoint with the WSO2 API Manager 👏

Happy Stacking !!! 🤘 ✌️

WSO2 API Manager & Okta SAML2 SSO

Sun, 19 Jan 2020 00:00:00 GMT

Greetings Everyone! 👋

In this medium, I will be 🚶with you all on how to configure SAML2 SSO (Single-Sign-On) between Okta Cloud Identity Provider 🔒 and WSO2 API Manager.

The demonstrations are made using WSO2 API Manager v2.6 and WSO2 Identity Server as Key Manager v5.7
Sensitive data are masked in all attached screenshots [Therefore, don’t waste your time investigating 🕵 blank spaces]

🔐 Configuring Okta

We’ll start the demo by setting up the Okta and creating a SAML2 Provider.

We need an Okta account to continue. So, go to the Okta Developer portal, and sign-up for a developer account (it’s FREE 🎉 🙌 👌) if you don’t have one. After a successful creation and verification, log-in to your developer account and follow me …

Change the appearance of the Developer Console to Classic UI

Next, select the Add Application as shown below

Select the Create New App in the displayed UI, and select SAML 2.0 and click on Create as following

Prompt the following in the next screen (which will a step-progress form)

App Name: OktaSAMLApplication
Single Sign-On URL: https://localhost:9444/commonauth
Audience URI: OktaSAML

Now go to the Assignments tab and click on Assign to assign people and groups to the created SAML2 Provider.

Tip:
Assign the default profile to continue with the demo. If you don’t assign any people or group of people (Everyone), then at the point of SSO execution, Okta will throw an Error message

Go back to the Sign On tab and select View Setup Instructions as follows to download the Okta’s public Certificate and Metadata to configure Identity Provider in the WSO2 Identity Server.

Scroll down to the bottom, and you’ll find a Download Certificate button and a section named Optional.

Download and save them both in your environment for future references …

Note:
Configure Okta User Profile with Roles and add the Subscriber role. You can follow WSO2 API Manager & Okta SSO to configure Roles attribute.
Or, scroll to the very bottom (this article) to find the instructions …

😐 😐 🤐

Another Note:
If you want to change the Username pattern of the Okta User, refer Okta Username Format section in here

We are done with Okta

WSO2 Server Configurations 🛠

WSO2 API Manager & IS Key Manager

To get a fully-fledged SAML2 SSO experience, and User Provisioning features, we need to configure WSO2 Identity Server as Key Manager with the WSO2 API Manager.

You can follow up on this official Doc to configure WSO2 API Manager & IS Key Manager.

But, if you are too lazy to follow up on the docs (no hard feelings though), then I have a little SURPRISE for you …

May I introduce you to the one and only “Hydrogen CLI”, an interactive CLI tool to configure WSO2 Servers

Clone or download the latest release and fire up configuring WSO2 API Manager with WSO2 Identity Server as Key Manager.

Brief instructions on how to use hydrogen is given at the tail of this article

Identity Provider Configurations

I hope you all are good to continue the demo with a working environment… Yes ??? 🤔

If all are good, then we are good to go …

Fire up the WSO2 IS as Key Manager and navigate to the Carbon management console [https://localhost:9444/carbon]

I assume that you have configured port offset 0 to WSO2 API Manager & offset 1 to IS KM

Go to Main > Identity > Identity Providers > Add and enter the following to create an Identity Provider in the IS KM for our Okta Cloud IdP

Identity Provider Name: OktaSAMLIDP
Display Name & Description
Alias: https://localhost:9444/oauth2/token

Expand the Federated Authenticators and expand the SAML2 Web SSO Configuration accordion to register a SAML IDP.

Enable SAML2 Web SSO: true
Service Provider Entity ID: OktaSAML (which is the same value given when creating a SAML application in Okta)

Select the Metadata File Configuration for the Select Mode and upload the downloaded Okta metadata and click Register

After making the above-changes as the last step, expand the Just-In-Time Provisioning and select and mark the Always provision to User Store Domain to PRIMARY and make Provision Silently and Save.

Ohh, wait I forgot one thing… 😱😱😱

If we are doing User Provisioning then we have to map the Roles and Claims. Go back again to the Identity Provider Configurations [So sorry for that 😢] and expand the Claim Configurations > Basic Claim Configuration and Define a Custom Claim Dialect

roles : http://wso2.org/claims/role

Next, expand the Role Configurations and Add Role Mapping

subscriber : Internal/subscriber

Again I made your life easy with the following screenshot… I hope you have the same thing as mine or maybe more enhanced … 😏

😫 😓 Let’s meet again after a short commercial break …

Service Provider Configurations

Now, we’ll start configuring a Service Provider for our API Manager.

Direct (again) to the Carbon management console of the WSO2 Identity Server as Key Manager and route to Main > Identity > Service Providers > Add to create a Service Provider.

Service Provider Name: API_STORE
SaaS Application: true (enable it after registering the provider)

Expand Inbound Authentication Configuration > SAML2 Web SSO Configuration and click on Configure.

Issuer: API_STORE
Assertion Consumer URLs: https://localhost:9443/store/jagg/jaggery_acs.jag

Expand Local & Outbound Authentication Configuration and do the following …

Federated Authentication: OktaSAMLIDP
Use user store domain in roles: true

WSO2 API Manager & Site JSON

We have come to the last episode of our configurations (a new beginning). With all the above-mentioned guides and configurations, we have successfully created both Identity Provider as well as a Service Provider

In this section, we will be configuring the Store node of the WSO2 API Manager to contact the Identity Providers and Service Providers to federate with Okta. Route to <APIM>/repository/deployment/server/jaggeryapps/store/site/conf directory and edit the site.json file as follows…

Replace and configure the keyStoreName by pointing to the WSO2 Carbon JKS of the WSO2 IS KM pack. It has to be an actual path and not a relative path

"ssoConfiguration" : {
    "enabled" : "true",
    "issuer" : "API_STORE",
    "identityProviderURL" : "https://localhost:9444/samlsso",
    "keyStorePassword" : "wso2carbon",
    "identityAlias" : "wso2carbon",
    "responseSigningEnabled":"true",
    "assertionSigningEnabled":"true",
    "verifyAssertionValidityPeriod":"true",
    "timestampSkewInSeconds":"300",
    "audienceRestrictionsEnabled":"true",
    "keyStoreName" :"/Users/foo/wso2is-km-5.7.0/repository/resources/security/wso2carbon.jks",
    "passive" : "true",
    "signRequests" : "true",
    "assertionEncryptionEnabled" : "false",
    "idpInit" : "false",
    "idpInitSSOURL" : "https://localhost:9444/samlsso?spEntityID=API_STORE",
    "loginUserNameAttribute" : ""
}

🎉 Voila!!! 🎉

We have now successfully configured SAML2 SSO between Okta & WSO2 API Manager [more precisely with the API Store Portal] 👏 👏 👏

Happy Stacking !!!! 🤘 ✌️

Next, we’ll do a simple UAT to verify the reliability …

User Acceptance Testing

Fire up both the WSO2 API Manager & WSO2 Identity Server as Key Manager and direct to the Store portal [https://localhost:9443/store/] and click on Sign-In.

You will be redirected to the Okta’s login page to perform SSO with the Okta user. Enter the Okta credentials and then allow the attributes on the consent screen to continue with the federation and provisioning of the Okta users to the WSO2 API Manager & IS Key Manager.

💡 Bonus

Hydrogen 🔥🔥🔥

Hydrogen is an interactive CLI tool to configure WSO2 Servers (🚧 under construction & active development).

To configure WSO2 API Manager & WSO2 Identity Server as Key Manager, clone or download the hydrogen-cli from here, and follow the given instructions …

Toll-Free Tips:
I would recommend you to use NodeJS v8.9.0 to build the packages without any dependency conflicts
Please install and start your Docker environment, to create Databases and to persist

Download both WSO2 API Manager & WSO2 IS KM packs and unzip and place them inside a new folder (ex: Setup)

Navigate to the Setup folder and execute the following command (from inside of the folder) to configure IS KM with API Manager including Database creations and configurations

hydrogen distribute:am --is-km --datasource postgres --container --generate

This will configure both the WSO2 API Manager & IS KM packs with appropriate configurations. Download and place the Postgre (or relative) JDBC driver in <APIM>/repository/components/lib directory and start the servers and continue hacking … 🙌 👌

You can find more interesting examples and guides about hydrogen in here as well as from here

👨 Okta User Profile & Roles

To login to the WSO2 API Manager Store portal, Okta users need to have the Internal/subscriber roles assigned to them. As well as the Okta has to pass the assigned Roles with the SAML Assertion response to the WSO2 API Manager at the point of the federation to sign-in the Okta user to the Store portal.

In the Okta Developer portal (Developer console view and not Classic UI), navigate to Users > Profile Editor and select the Okta user profile to edit. On the following, select Add Attribute and make the following changes and Save the attribute

After the above, move to Users > People and select the current User and on the following screen select the Profile tab and click on Edit to add the subscriber role in the Roles field …

Even though we have introduced the Roles attribute to the Okta Users, still, we are missing one part which is we haven’t configured to add the Roles in the SAML Response Assertion

Switch back to Classic UI and navigate to Applications > Applications and select and edit [from the General > SAML Setting] our SAML2 Application. On the Configure SAML screen of the Progress-Form, make the following changes and save …

WSO2 API Manager & Custom Grant Handler

Sat, 11 Jan 2020 00:00:00 GMT

Greetings Everyone! 👋

In this medium, I will be 🚶 with you all on how to implement a custom Grant Handler for WSO2 Servers, especially for WSO2 API Manager when you are highly in need to introduce your own …

The demonstrations are presented and guided using WSO2 API Manager v2.6

Hmmm… alright. But,

Am I in need of one??? 🤔

Depends, maybe Yes, probably you are 💁.

Let me tell you a simple story, where a Goe-Location Startup needed to implement a custom grant to fulfill their security concerns and requirements.

Locus is a Geo-Location 🌏 service startup and it has been using the WSO2 API Manager to manage all of their exposed REST APIs and legacy SOAP services. Due to the increased demand for Geodata and analytics, one day the Locus team gathered to design a new architecture for their certified devices.

The 👮 platform security team and a group of Architectures 🤓 proposed Locus to isolate their certified devices from all registered devices by introducing a unique pattern for Access tokens 🔑.

When further breaking-down the features and analyzing the possibilities of implementing customized Tokens (you can refer to Customizing Opaque Access Token Generation), the devs found out that the WSO2 API Manager has extensions to develop and plug custom grants 🔐 and handlers.

👏 👏 👏 well-done guys… kudos for the effort and idea.

They re-engineered their architecture and introduced a custom grant named locus with the following required fields to fulfill their requirements

name: the unique ID name of the certified device
location: a regional code where the device has permissions and its current accessible location
key: a unique hash key embed to the certified device upon certification

I hope I made a good story to explain the case…

Let’s keep the stories aside and dive into implementations.

🚧 Implementation

The WSO2 API Manager, or more likely to say the WSO2 Carbon platform is built in a way to extend and plug and play with the functions if required.

On a Personal Note
It is always good to think twice before introducing any customizations or extensions to the platform

So to achieve our needs, We have to extend the implementation of AbstractAuthorizationGrantHandler and push our enhancements to it.

Let’s start by setting up a Maven project … Create a new Maven project and the following dependencies in the POM

<dependency>
    <groupId>org.wso2.carbon.identity.inbound.auth.oauth2</groupId>
    <artifactId>org.wso2.carbon.identity.oauth</artifactId>
    <version>6.0.53</version>
</dependency>

If you encounter any dependency resolution errors or if you are not able to resolve the dependencies, add the following repositories to fetch ‘em

<repositories>
    <repository>
        <id>wso2-nexus</id>
        <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </repository>
</repositories>
<pluginRepositories>
    <pluginRepository>
        <id>wso2-nexus</id>
        <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </pluginRepository>
</pluginRepositories>

With success, let’s dive into the implementation of Grant Handlers. Grant Handlers are responsible to validate the Grant type and to issue Access Tokens.

Since we don’t want to do any customizations to our Access Tokens, we will be only overriding the validateGrant() method to validate the inputs.

🌏 Locus Grant Handler

I’ve made it simple 🙌 for you all to save your precious time. You can find the complete development at the bottom of this story, but if you have time go through it (I’ve spent my time to write this one 😢)…

Given below is the complete implementation of the Locus Grant Handler. I’ve introduced a couple of isValid() methods to mock the validation and service calls to any defined data sources.

package com.grant.sample.handler;
import java.util.ArrayList;
import java.util.List;
import com.grant.sample.utils.LocusGrantConstants;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.wso2.carbon.identity.application.authentication.framework.model.AuthenticatedUser;
import org.wso2.carbon.identity.oauth2.IdentityOAuth2Exception;
import org.wso2.carbon.identity.oauth2.ResponseHeader;
import org.wso2.carbon.identity.oauth2.model.RequestParameter;
import org.wso2.carbon.identity.oauth2.token.OAuthTokenReqMessageContext;
import org.wso2.carbon.identity.oauth2.token.handlers.grant.AbstractAuthorizationGrantHandler;
public class LocusGrantHandler extends AbstractAuthorizationGrantHandler {
    private static final Log log = LogFactory.getLog(LocusGrantHandler.class);
    @Override
    public boolean validateGrant(OAuthTokenReqMessageContext tokReqMsgCtx) throws IdentityOAuth2Exception {
        log.info("Locus Grant Handler : Starting to validate grant");
        boolean isGrantValid = false;
        RequestParameter[] reqParams = tokReqMsgCtx.getOauth2AccessTokenReqDTO().getRequestParameters();
        String nameValue = null;
        String locationValue = null;
        String keyValue = null;
        for (RequestParameter param : reqParams) {
            switch (param.getKey()) {
                case LocusGrantConstants.LOCUS_NAME_GRANT_PARAM:
                    nameValue = param.getValue() != null && param.getValue().length > 0 ? param.getValue()[0] : null;
                    break;
                case LocusGrantConstants.LOCUS_LOCATION_GRANT_PARAM:
                    locationValue = param.getValue() != null && param.getValue().length > 0 ? param.getValue()[0] : null;
                    break;
                case LocusGrantConstants.LOCUS_KEY_GRANT_PARAM:
                    keyValue = param.getValue() != null && param.getValue().length > 0 ? param.getValue()[0] : null;
                    break;
            }
        }
        if (nameValue != null && locationValue != null && keyValue != null) {
            isGrantValid = (isValidName(nameValue) && isValidLocation(locationValue) && isValidKey(keyValue));
            if (isGrantValid) {
                AuthenticatedUser locusUser = new AuthenticatedUser();
                locusUser.setUserName(keyValue);
                tokReqMsgCtx.setAuthorizedUser(locusUser);
                tokReqMsgCtx.setScope(tokReqMsgCtx.getOauth2AccessTokenReqDTO().getScope());
            } else {
                ResponseHeader responseHeader = new ResponseHeader();
                responseHeader.setKey("LocusGrantError");
                responseHeader.setValue("Invalid Credentials");
                tokReqMsgCtx.addProperty("RESPONSE_HEADERS", new ResponseHeader[] { responseHeader });
            }
        }
        if (log.isDebugEnabled()) {
            log.debug("Locus Grant Handler : isGrantValid = " + isGrantValid);
        }
        return isGrantValid;
    }
    private boolean isValidName(String name) {
        // mocking database call with a sample list
        List<String> validNames = new ArrayList<>();
        validNames.add("locus-10-09874");
        validNames.add("locus-10-01219");
        return validNames.contains(name);
    }
    private boolean isValidLocation(String location) {
        // mocking the database with a sample list
        List<String> validLocations = new ArrayList<>();
        validLocations.add("LK-COLOMBO");
        validLocations.add("LK-KANDY");
        return validLocations.contains(location);
    }
    private boolean isValidKey(String key) {
        // mocking database call with a sample list
        List<String> validKeys = new ArrayList<>();
        validKeys.add("0987654321");
        validKeys.add("1234567890");
        return validKeys.contains(key);
    }
}

Find the util class implementation from here

A Toll-Free Tip 💪

It is required to create and set an AuthenticatedUser in the success flow to generate an access token and to bind it to that particular user. Otherwise, we’ll end up in a broken flow.
Due to that, I have introduced and configured the key value of the Device to bound the generated access tokens

And that’s all about the Grant handler …

Now let’s configure our API Manager server to support the custom grant

WSO2 API Manager Configurations

Before configuring our API Manager pack, we have to build our Maven project. Execute the following command to build the project

mvn clean package

And copy and place the built JAR artifact inside the <APIM>/repository/components/lib directory.

Now direct to the <APIM>/repository/conf/identity directory and open up the identity.xml to add and support our locus grant with API Manager

<SupportedGrantTypes>
  ...
    <SupportedGrantType>
        <GrantTypeName>locus</GrantTypeName>
        <GrantTypeHandlerImplClass>com.grant.sample.handler.LocusGrantHandler</GrantTypeHandlerImplClass>
        <GrantTypeValidatorImplClass>com.grant.sample.validator.LocusGrantValidator</GrantTypeValidatorImplClass>
        <IdTokenAllowed>false</IdTokenAllowed>
    </SupportedGrantType>
  ...
</SupportedGrantTypes>

and that’s all … 🎉

👏 Voila!!! 🙌

It is time to do an examination

Examine 🕵

Fire up the WSO2 API Manager server, and execute the request using either cURL or Postman or from your favorite REST client and take a note ✅

curl --location --request POST 'https://localhost:8243/token' \
   --header 'Authorization: Basic {base64<ClientID:Client Secret>}'\
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=locus' \
   --data-urlencode 'name=locus-10-09874' \
   --data-urlencode 'location=LK-COLOMBO' \
   --data-urlencode 'key=0987654321'

Customizing Opaque Access Token Generation

Thu, 26 Dec 2019 00:00:00 GMT

Hola 👋

Greetings Everyone 😊 …

This is another medium on walking 🚶 and swimming 🏊🏼 through customizing the opaque access tokens using APIM Token Issuer when we do have a requirement issue

The demo is presented and walked-through using WSO2 API Manager v2.6

Whaaaaat? wait… Why? 🤔

You probably now have a question on why do we need to do that and does it actually matter… Let me give you a simple stupid occasion on when and where I actually need that.

RepoDeWS is a developer-management system which has a set of in-built management services in SOAP. These SOAP services are exposed as REST APIs with the help of WSO2 API Manager. Now the RepoDeWS team is having an undergoing process of security maintenance and they are expecting their users to invoke the APIs using access tokens with a “Dev-Hash” value appended to it.

This “Dev-Hash” value will be passed as a Header (devhash) when requesting an Access Token and will be appended during the generation of the opaque access token

Oh… I forgot to mention that the Dev-Hash value is a unique hash value given to a set of top-rated developers to enrich their API responses with the last accessed timestamps 😅

Let’s just focus on the implementation and enhancements and will keep our use-cases behind that.

Implementation

To accomplish my simple requirement, We have to extend the implementation of APIMTokenIssuer and push our enhancements.

The APIMTokenIssuer is responsible for generating opaque access tokens and JWT tokens in the WSO2 API Manager platform

First, create a simple maven project and add the following dependency to the POM. This will help us to resolve most of the dependency issues when extending the APIMTokenIssuer class.

<dependencies>
    <dependency>
        <groupId>org.wso2.carbon.apimgt</groupId>
        <artifactId>org.wso2.carbon.apimgt.keymgt</artifactId>
        <version>6.5.222</version>
    </dependency>
</dependencies>

But, if you encounter any dependency problems or if you are not able to resolve the dependencies in the POM, then add the following as well …

<repositories>
    <repository>
        <id>wso2-nexus</id>
        <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </repository>
</repositories>
<pluginRepositories>
    <pluginRepository>
        <id>wso2-nexus</id>
        <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </pluginRepository>
</pluginRepositories>

Phew 😅

Managing dependencies is harder than managing expenses bruh 😬😬😭 …

Now let’s jump into the extended implementation. Given below is the piece of code (I) developed to solve my own problem [Am I overreacting 😳 ? I think I am 😒]

package com.sample.token;
import org.wso2.carbon.apimgt.impl.APIConstants;
import org.wso2.carbon.apimgt.impl.utils.APIUtil;
import org.wso2.carbon.apimgt.keymgt.issuers.APIMTokenIssuer;
import org.wso2.carbon.identity.oauth2.token.OAuthTokenReqMessageContext;
import org.wso2.carbon.identity.oauth2.model.RequestParameter;
public class MyAPIMTokenIssuer extends APIMTokenIssuer {
  private static final Log log = LoggerFactory.getLog(MyAPIMTokenIssuer.class)
  
    @Override
    public String accessToken(OAuthTokenReqMessageContext tokReqMsgCtx) throws OAuthSystemException {
        // generate access token using super method
        String accessToken = super.accessToken(tokReqMsgCtx);
        String clientId = tokReqMsgCtx.getOauth2AccessTokenReqDTO().getClientId();
        Application application;
        try {
            application = APIUtil.getApplicationByClientId(clientId);
            String tokenType = application.getTokenType();
            // only acceptable for opaque access tokens and not JWT tokens
            if (!APIConstants.JWT.equals(tokenType)) {
                // retrieve all request parameters sent to the token request
                RequestParameter[] reqParams = tokReqMsgCtx.getOauth2AccessTokenreqDTO().getRequestParameters();
                for (int i = 0l i < reqParams.length; i++) {
                    // check for devhash from the request parameters
                    // and append it to the access token
                    if ("devhash".equals(reqParams[i].getKey())) {
                        accessToken += reqParams[i].getValue()[0];
                        break;
                    }
                }
            }
        } catch (APIManagementException e) {
            log.error("Exception occured ", e);
        }
        return accessToken;
    }
}

I know right, it’s really hard to follow these things up 😐

Therefore, I give you a golden opportunity… Please go and find the sample implementation (gist) from GitHub Gist (save your time on reading this medium) and enjoy enriching it 😍

  
          package com.sample.token;
        
          import org.apache.oltu.oauth2.common.exception.OAuthSystemException;
        
          import org.wso2.carbon.apimgt.api.APIManagementException;
        
          import org.wso2.carbon.apimgt.api.model.Application;
        
          import org.wso2.carbon.apimgt.impl.APIConstants;
        
          import org.wso2.carbon.apimgt.impl.utils.APIUtil;
        
          import org.wso2.carbon.apimgt.keymgt.issuers.APIMTokenIssuer;
        
          import org.wso2.carbon.identity.oauth2.token.OAuthTokenReqMessageContext;
        
          import org.wso2.carbon.identity.oauth2.model.RequestParameter;
        
          import org.apache.commons.logging.Log;
        
          import org.apache.commons.logging.LogFactory;
        
          public class MyAPIMTokenIssuer extends APIMTokenIssuer {
        
          	private static final Log log = LogFactory.getLog(MyAPIMTokenIssuer.class);
        
          	@Override
        
          	public String accessToken(OAuthTokenReqMessageContext tokReqMsgCtx) throws OAuthSystemException {
        
          		// generate access token using super method
        
          		String accessToken = super.accessToken(tokReqMsgCtx);
        
          		String clientId = tokReqMsgCtx.getOauth2AccessTokenReqDTO().getClientId();
        
          		Application application;
        
          		try {
        
          			application = APIUtil.getApplicationByClientId(clientId);
        
          			String tokenType = application.getTokenType();
        
          			// only acceptable for opaque access tokens and not JWT tokens
        
          			if (!APIConstants.JWT.equals(tokenType)) {
        
          				// retrieve all request parameters sent to the token request
        
          				RequestParameter[] reqParams = tokReqMsgCtx.getOauth2AccessTokenReqDTO().getRequestParameters();
        
          				for (int i = 0; i < reqParams.length; i++) {
        
          					// check for devhash parameter from the request parameters and append it to the
        
          					// access token
        
          					if ("devhash".equals(reqParams[i].getKey())) {
        
          						accessToken += reqParams[i].getValue()[0];
        
          						break;
        
          					}
        
          				}
        
          			}
        
          		} catch (APIManagementException e) {
        
          			log.error("Exception occured in my piece of code ", e);
        
          		}
        
          		return accessToken;
        
          	}
        
          }

view raw MyAPIMTokenIssuer.java hosted with ❤ by GitHub

  
          <?xml version="1.0" encoding="UTF-8"?>
        
          <project xmlns="http://maven.apache.org/POM/4.0.0" 
        
          	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        
          	<modelVersion>4.0.0</modelVersion>
        
          	<groupId>com.sample.token</groupId>
        
          	<artifactId>custom-token-issuer</artifactId>
        
          	<version>1.0.0</version>
        
          	<!-- change the packaging to bundle (from jar) to support OSGi -->
        
          	<packaging>jar</packaging>
        
          	<properties>
        
          		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        
          		<maven.compiler.source>1.8</maven.compiler.source>
        
          		<maven.compiler.target>1.8</maven.compiler.target>
        
          	</properties>
        
          	<dependencies>
        
          		<dependency>
        
          			<groupId>org.wso2.carbon.apimgt</groupId>
        
          			<artifactId>org.wso2.carbon.apimgt.keymgt</artifactId>
        
          			<version>6.5.222</version>
        
          		</dependency>
        
           </dependencies>
        
          	<repositories>
        
          		<repository>
        
          			<id>wso2-nexus</id>
        
          			<url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        
          			<releases>
        
          				<enabled>true</enabled>
        
          				<updatePolicy>daily</updatePolicy>
        
          				<checksumPolicy>ignore</checksumPolicy>
        
          			</releases>
        
          		</repository>
        
          	</repositories>
        
          	<pluginRepositories>
        
          		<pluginRepository>
        
          			<id>wso2-nexus</id>
        
          			<url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        
          			<releases>
        
          				<enabled>true</enabled>
        
          				<updatePolicy>daily</updatePolicy>
        
          				<checksumPolicy>ignore</checksumPolicy>
        
          			</releases>
        
          		</pluginRepository>
        
          	</pluginRepositories>
        
          	<build>
        
          		<plugins>
        
          			<plugin>
        
          				<groupId>org.apache.maven.plugins</groupId>
        
          				<artifactId>maven-compiler-plugin</artifactId>
        
          				<version>2.0</version>
        
          				<configuration>
        
          					<source>1.8</source>
        
          					<target>1.8</target>
        
          				</configuration>
        
          			</plugin>
        
          			<!-- build plugin for OSGi Bundle support -->
        
          			<plugin>
        
          				<groupId>org.apache.felix</groupId>
        
          				<artifactId>maven-bundle-plugin</artifactId>
        
          				<version>2.3.4</version>
        
          				<extensions>true</extensions>
        
          				<configuration>
        
          					<instructions>
        
          						<Bundle-SymbolicName>com.sample.token</Bundle-SymbolicName>
        
          						<Bundle-Name>com.sample.token</Bundle-Name>
        
          						<Export-Package>
        
                                      com.sample.token.*,
        
          						</Export-Package>
        
          						<Import-Package>
        
                                      *; resolution:=optional
        
          						</Import-Package>
        
          					</instructions>
        
          				</configuration>
        
          			</plugin>
        
          		</plugins>
        
          	</build>
        
          </project>

view raw pom.xml hosted with ❤ by GitHub

Your inner voice: Hmmm… Thanks for that. I have gone through the samples and copied everything from the given sources. Now, what should I do next? Where should I put these implementations???

Me: Ummm… I think I heard your inner voice. But thank you for the question.

As of next steps we have to build-up the maven project by executing the following command from a terminal

mvn clean package

And then copy and place the built JAR artifact from the target folder to the <APIM>/repository/components/lib directory.

And at last [Whoa…. the magical keyword 🤗😍], change the APIMTokenIssuer class representation to the MyAPIMTokenIssuer class by editing the <IdentityOAuthTokenGenerator> property in the <APIM>/repository/conf/identity/identity.xml.

<IdentityOAuthTokenGenerator>com.sample.token.MyAPIMTokenIssuer</IdentityOAuthTokenGenerator>

🎉 Voila!!! 🎉

Let’s do a test-run with our piece of code…

Keep Stacking!!!

Test Drive

Fire up the WSO2 API Manager server with the artifacts and the above-mentioned configuration changes.

Execute the following CURL command to generate an Opaque Access Token and let’s verify whether it got generated with the specified Dev-Hash value or not…

curl --location --request POST 'https://localhost:8243/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {Base64<ClientID>:<ClientSecret>}' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=admin' \
--data-urlencode 'password=admin' \
--data-urlencode 'scope=default' \
--data-urlencode 'devhash=af1c4ca13ab7d6c8d2a887d7ce8250a2'

And the response should be as follows with the Dev-Hash value appended to the Access Token

{
  "access_token": "25b9ded7-7441-3b69-bb6b-b1f1828bfff9af1c4ca13ab7d6c8d2a887d7ce8250a2",
  "refresh_token": "d86ac9b8-a3aa-3664-9d39-090ca49a9435",
  "scope": "default",
  "token_type": "Bearer",
  "expires_in": 3600
}

WSO2 API Manager & Okta

Sat, 21 Dec 2019 00:00:00 GMT

Intro

This medium walks-through how to configure Okta IdP as third-party Key Manager with WSO2 API Manager

NOTE: Tested versions are WSO2 APIM v2.6

Guide

We will be swimming through the following steps

Create an Okta Developer account
Create an Authorization Server in Okta
Create an Okta Application
Configure Okta Extensions with WSO2 API Manager

Okta

Okta Developer Account

Our very first step will be to create an Okta Developer account to test and trial our Key Manager configurations.

Navigate to https://developer.okta.com and create a new Developer account to enjoy free trial on using Okta cloud IdP.

Okta Authorization Server

After successful account creation, now we have to create and register an Authorization server in Okta to communicate and to perform authorization flows.

In the Okta developer portal navigate to API > Authorization Servers (refer to the attached screen-shot)

We will be looking at a similar page as follows with a default Authorization server created in Okta.

For security concerns, all attached screenshots are masked

We can either create a new Authorization server or we can continue using the default Authorization server to configure Okta. Therefore, we will be continuing our configurations with the Default Authorization Server created by Okta…

Select the default Authorization server and click on the Scopes tab to create a Default Scope for the defined Authorization Server. Click on Add Scope and prompt the following

Name: default
Description: Default Scope
Default Scope: true
Metadata: true

and click Create to create the Default scope.

Next, select the Tokens tab to create a new API Token for WSO2 API Manager to communicate with our Okta server.

Click on Create Token and enter a name for the Token and copy and save the generated token value for future references. From now onwards, We will be referring to the token as Okta API Token.

Okta Application

Next, we have to create a client application in the Okta IdP to acquire the Consumer secrets to communicate with the Server.

Select the Applications from the top navigation bar and then select Add Application to create one.

On the next UI, select the platform as Web and click Next. Enter the Application name and tick the Client Credentials under Grant Type Allowed section and Done.

After the successful creation of the Application, copy both the Consumer Key and Consumer Secret for future references.

WSO2 API Manager

Okta Extension

Clone or download the WSO2 API Manager Okta extension implementation from here.

Navigate to the /artifacts folder in the root of the project to find the pre-built okta extension JAR artifacts and other related configuration artifacts. Moreover, you are welcomed to build the okta extension JAR artifact by building the project.

Copy and place the oktaoauthclient-x.x.x.jar inside the <APIM>/repository/components/lib directory.

API Manager XML

Download the WSO2 APIM v2.6 pack, extract and navigate to <APIM>/repostiry/conf/api-manager.xml to configure third-party Key Manager.

Uncomment the APIKeyManager configuration block in the api-manager.xml and edit/add the following

<APIKeyManager>
    <KeyManagerClientImpl>org.wso2.okta.client.OktaOAuthClient</KeyManagerClientImpl>
    <Configuration>
        <oktaInstanceUrl>{Okta Instance URL}</oktaInstanceUrl>
        <authorizationServerId>{Okta Authorization Server Name/ID}</authorizationServerId>
        <apiKey>{Okta Authorization Server API Token}</apiKey>
        <client_id>{Okta Application Client ID}</client_id>
        <client_secret>{Okta Application Client Secret}</client_secret>
    </Configuration>
</APIKeyManager>

Given below is a sample configuration

<APIKeyManager>
    <KeyManagerClientImpl>org.wso2.okta.client.OktaOAuthClient</KeyManagerClientImpl>
    <Configuration>
        <oktaInstanceUrl>https://dev-12345.oktapreview.com</oktaInstanceUrl>
        <authorizationServerId>default</authorizationServerId>
        <apiKey>00adc_bXcT123456789</apiKey>
        <client_id>0o2fg123456789gfL0h7</client_id>
        <client_secret>BwhHU123456789_wpKQg</client_secret>
    </Configuration>
</APIKeyManager>

Store Sub-Theme

As of the next step, we will be configuring the Store portal theme to revamp the Application generation UI to support Okta connected parameters and input fields.

Navigate to the <OktaProject>/artifacts/store directory and copy and place/replace the locale_default.json into <APIM>/repository/deployment/server/jaggeryapps/store/site/conf/locales/jaggery directory.

Copy the okta theme folder and place it inside the <APIM>/repository/deployment/server/jaggeryapps/store/site/themes/wso2/subthemes directory.

Open up the <APIM>/repository/deployment/server/jaggeryapps/store/site/conf/site.json and declare the okta as a sub-theme by making the following changes

{
  "theme": {
    "base": "wso2",
    "subtheme": "okta"
  }
  ...
}

🎉 Voila!!! 🎉

Now we have successfully configured Okta as a third-party Key Manager with the WSO2 API Manager. Let’s dive into a test-drive.

Test Drive with Okta

Let’s start the WSO2 API Manager server by navigating to <APIM>/bin directory and executing the following based on your environment

# linux
./wso2server.sh
# windows
wso2server.bat

After a successful startup, direct to https://<ip>:9443/publisher and log in with the admin credentials

Username: admin
Password: admin

and deploy a sample API for our test drive (let’s deploy the one and only PizzaShack API).

Next, direct to the Store portal by routing to https://<ip>:9443/store and let’s sign-in with the above-mentioned admin credentials.

Steer to Applications > Add Application to create a new Store Application.

By default, there will be a Default Application created (once logged in) for each and every user who has the internal/subscriber role and permissions

Give inputs to all required fields and click on Add to create the Application.

After the successful creation of our demo application, let’s direct to Production Keys tab to generate Consumer Secrets and Access Tokens using Okta third-party Key Manager.

A Quick Glance on the Generation Flow
At the generation of Production Keys and Sandbox Keys of an Application, the APIM will communicate with the configured Okta IdP to create a dynamic-client using the DCR (Dynamic Client Registration) endpoint. Upon successful creation, Okta responds back to the APIM Server with the populated metadata to store and to communicate again with Okta to generate the access tokens to invoke the APIs.
Please follow the given instructions in here to change the endpoints of Token, and Revoke endpoints to point to the Okta server.
All created dynamic-clients will follow the naming structure as {ApplicationName_[PRODUCTION|SANDBOX]} to keep track of the created clients based on the Key Type

Provide the following at the prompted UI to generate the Consumer keys

Callback URL: https://localhost
Application Type: web
Response Type: code,token,id_token
Token Endpoint Auth Method: client_secret_basic
Token Scope: default
Token Grant Type: client_credentials

Upon successful generation of the key, the APIM server will prompt a similar UI as following

Please make sure to note the generated Consumer Key and Consumer Secret because as this will be only displayed one time

If we navigate to the Okta Dev portal, there we can see a new application with the name OktaDemoApplication_PRODUCTION as follows

As of next step, copy the generated access token and invoke the deployed sample PizzaShack API.

Keep Stacking !!!

WSO2 API Manager & Okta SSO

Fri, 20 Dec 2019 00:00:00 GMT

🔑 Intro

This medium illustrates and walk-through on how to configure OpenID Connect SSO between WSO2 API Manager and Okta Identity Provider as well as to provision users from Okta to the WSO2 API Manager.

We will be using WSO2 API Manager v2.6 for this demo

We will be going through flows and the configurations with the following breakdowns

Okta Developer Account Creation
Okta Authorization Server
Okta Application
Okta User & Claims
WSO2 API Manager: Identity Provider
WSO2 API Manager: Service Provider
WSO2 API Manager: Store Configurations

Let’s get started…

Okta

Okta Developer Account

As of our very first step, we need an Okta Cloud IDP account. Therefore, for demo purposes, we will be creating an Okta Developer account for trial and error scenarios.

Open up your favorite browser and direct to https://developer.okta.com and register for a new Developer account to enjoy free trial on using Okta Cloud IDP.

Okta Authorization Server

After creating an Okta developer account, sign-in to the developer console and navigate to API > Authorization Server to list down the default Okta Authorization server.

We will be looking at a similar page as follows with a default Authorization server created in Okta.

For security concerns, all attached screenshots are masked

We can either create a new Authorization server or we can continue using the default Authorization server to configure Okta. As for this demo, we will be continuing our configurations with the Default Authorization Server created by Okta…

Okta OIDC Application

Next, we will be creating an Okta application for our OpenID Connect SSO flow. In the Okta developer portal, select Applications from the top navigation bar as follows…

Then, click on Add Application to create a new Okta application.

On the next UI, select the platform as Web and click on Next. Enter the Application Name and tick the Client Credentials under the Grant Type Allowed section and Done.

After successful creation of our Okta Application, click on Edit and make the following changes

Login Redirect URI: https://localhost:9443/commonauth
Logout Redirect URI: https://localhost:9443/commonauth
Initiate Login URI: https://localhost:9443/store/

Okta User & Claims

To login to the WSO2 API Manager Store portal, the Okta users need to have the internal/subscriber roles assigned to them. As well as the Okta has to pass the assigned Roles with the JWT to the WSO2 API Manager at the point of the federation to sign-in the Okta user to the Store portal.

Navigate to Users > Profile Editor and select the Okta user profile to edit it. On the following screen, select Add Attribute and make the following changes and Save the attribute

Then move to API > Authorization Server and select our default Authorization server. Direct to Claims tab and click on Add Claim to create a new claim for our Role attribute.

Do the following configurations and save…

At last, move to Users > People and select the current User and on the following screen select the Profile tab and click on Edit to add the subscriber role in the Role field.

WSO2 API Manager

OpenID Connect Federated Extension

By default as Out-Of-The-Box, the WSO2 API Manager is only shipped wit the SAML2 Federated Authentication configurations and artifacts. Therefore, to enable OpenID Connect, download the following OpenID Connect Authenticator artifact from here and place it inside the <APIM>/repository/components/dropins directory.

Please note that adding the above-mentioned artifact to the WSO2 API Manager to enable OpenID Connect features is not a best practice and not recommended in production environments. Since this is a demo, we have configured it by dropping the artifact inside the dropins folder.
If you want to enable OpenID Connect features in a Production environment, please setup and use WSO2 Identity Server as Key Manager for the WSO2 API Manager and follow the configurations on the WSO2 IS-KM

Identity Provider

After ensuring the OpenID Connect features in the WSO2 API Manager, we will be creating an Identity Provider to federate with our Okta Cloud provider.

Fire up the WSO2 API Manager server, and navigate to the Carbon management console and select Add under the Identity Providers section to register an Identity Provider.

Enter a name for the Identity Provider (for example OktaIDP) and select the OAuth2/OpenID Connect Configurations under the Federated Authenticators accordion.

Make the following configurations

Specifies if OAuth2/OpenID Connect is enabled for this Identity Provider: enable
Client ID: Paste the Consumer Key obtained from the Okta Application
Client Secret: Paste the Consumer Secret obtained from the Okta Application
Authorization Endpoint URL: https://<your-okta>.com/oauth2/default/v1/authorize
Token Endpoint URL: https://<your-okta>.com/oauth2/default/v1/token
Callback URL: https://localhost:9443/commonauth
Userinfo Endpoint URL: https://<your-okta>.com/oauth2/default/v1/userinfo
Additional Query Parameters: scope=openid profile

Next, expand the Claim Configuration > Basic Claim Configuration and select Define Custom Claim Dialect to add a custom mapping for the Roles claims for the Okta and WSO2 API Manager.

After making the above configurations, expand the Role Configuraiton and select the Add Role Mapping and enter the following to map the subscriber role with the internal/subscriber role of the WSO2 API Manager.

And at last, expand the Just-In-Time Provisioning and select the Always Provision to User Store Domain with the PRIMARY user store to provision the Okta users to the Primary user-store of the WSO2 API Manager. Please refer to the attached screenshot…

And save all the configurations.

Given below is a full rollover screenshot of the configurations of the created OktaIDP Identity Provider…

Service Provider

Now we have created an Identity Provider successfully to perform federated authentication with the Okta. As of the next step, we will be creating a Service Provider for the Store portal of the WSO2 API Manager.

Direct to the Carbon management console of the WSO2 API Manager server, and select Add under the Service Providers section to register a Service Provider.

Enter API_STORE as the name of the Service Provider and click on Register

On the following screen, expand the Inbound Authentication Configuration and select Configure under the OAuth/OpenID Connect Configuration.

And prompt the following

Callback URL: https://localhost:9443/store/jagg/jaggery_oidc_acs.jag

And register and save the configurations.

As a result, a Consumer Key and a Secret. Copy these credentials and store them as we will need them when configuring the site.json of the Store node.

Next, expand the Local & Outbound Authentication Configuration and select Federated Authentication with our created Identity Provider OktaIDP.

Proceeding further, expand the Local & Outbound Authentication Configuration and select the Federated Authentication along with created OktaIDP Identity Provider.

And at last, expand the Claim Configuration and select the Define Custom Claim Dialect and make the following changes to extract the preferred_username from the generated JWT to make it as the username and Display Name of the provisioned user.

And save and register all the configurations to create a Service Provider for the Store portal.

Given below is a full rollover screenshot of the configurations of the created API_STORE Service Provider…

Store Site.JSON

We have come to the last steps of our configurations. With all the above-mentioned guides and configurations, we have successfully created both Identity Provider as well as a Service Provider the OpenID Connect SSO flow.

Replace the API_STORE SP OIDC Client ID and API_STORE SP OIDC Client Secret with the consumer credentials created by the API_STORE service provider

"oidcConfiguration": {
    "enabled": "true",
    "issuer": "API_STORE",
    "identityProviderURI": "https://localhost:9443/oauth2/token",
    "authorizationEndpointURI": "https://localhost:9443/oauth2/authorize",
    "tokenEndpointURI": "https://localhost:9443/oauth2/token",
    "userInfoURI": "https://localhost:9443/oauth2/userinfo",
    "jwksURI": "https://localhost:9443/oauth2/jwks",
    "logoutEndpointURI": "https://localhost:9443/oidc/logout",
    "authHttpMethod": "POST",
    "clientConfiguration": {
      "clientId": "<API_STORE SP OIDC Client ID>",
      "clientSecret": "<API_STORE SP OIDC Client Secret>",
      "responseType": "code",
      "authorizationType": "authorization_code",
      "scope": "phone email address openid profile",
      "redirectURI": "https://localhost:9443/store/jagg/jaggery_oidc_acs.jag",
      "postLogoutRedirectURI": "https://localhost:9443/store/",
      "clientAlgorithm": "RS256"
    }
}

🎉 Voila!!! 🎉

We have successfully configured Single Sign-On with OpenID Connect between WSO2 API Manager and Okta Cloud Identity Provider. Next, we will be doing a small test drive…

Test Drive

Direct to the Store portal using https://localhost:9443/store/ and click on Sign-In.

The federated IDP authentication happens in org.wso2.carbon.identity.application.authenticator.oidc.OpenIDConnectAuthenticator class
JIT Provisioning makes way in the org.wso2.carbon.identity.application.authentication.framework.handler.request.impl.JITProvisionningPostAuthenticationHandler

Happy Stacking !!!! 🤘 ✌️

🚧 Troubleshooting

Okta Trusted Origins

If you encounter any Cross-Origin errors when accessing the Okta Cloud IDP, sign-in to the Okta developer portal and navigate API > Trusted Origins to add our Domain as a trusted origin in the Okta.

On the following screen select Add Origin and make the following…

Save the configurations.

Okta Username Format

If you encounter any error related to Username format as email while performing SSO, please follow the given instructions to change the Username format from Email pattern to any other…

Select the Profile of the Okta User. On the following screen, select the info icon of the Username attribute to edit it.

Change the Format Restrictions from Email Format to None or Custom Character Restrictions and Save Attribute.

Filter Request Headers

Fri, 15 Nov 2019 00:00:00 GMT

Stratagem

A Quick-Peak on using Filter mediators to filter and execute custom executions based on presented request header.

For example, check for the mycustomheader header value in the request and print the value using Log mediator.

<sequence name="custom-sequence" 
  xmlns="http://ws.apache.org/ns/synapse">
  <filter>
    <then></then>
    <else></else>
  </filter>
</sequence>

Given is a simple Synapse sequence with a Filter mediator skeleton.

<sequence name="custom-sequence" 
  xmlns="http://ws.apache.org/ns/synapse">
  <filter 
    source="get-property('mycustomheader', 'transport')">
    <then></then>
    <else></else>
  </filter>
</sequence>

We can use the get-property() method to access and retrieve properties from the Synapse context. We will be using get-property('mycustomheader', 'transport') to retrieve our mycustomheader value from the Synapse context using the scope as transport.

<sequence name="custom-sequence" 
  xmlns="http://ws.apache.org/ns/synapse">
  <filter 
    source="get-property('mycustomheader', 'transport')">
    <then>
      <log level="custom">
        <property 
          name="message" 
          value="Header is presented" />
      </log>
    </then>
    <else>
      <log level="custom">
        <property 
          name="message" 
          value="Header is not presented" />
      </log>
    </else>
  </filter>
</sequence>

Next we will add some Log mediators in both then and else sections of the Filter mediator to print and log success and failure messages.

<sequence name="custom-sequence" 
  xmlns="http://ws.apache.org/ns/synapse">
  <filter 
    source="get-property('mycustomheader', 'transport')">
    <then>
      <log level="custom">
        <property 
          name="message" 
          value="Header is presented" />
      </log>
    </then>
    <else>
      <log level="custom">
        <property 
          name="message" 
          value="Header is not presented" />
      </log>
    </else>
  </filter>
</sequence>

Now we have successfully written and modified our code to capture and retrieve the someHeaders value from the request headers. We will now print some custom message on success as well as on failure methods to prompt in the carbon logs

Given below is the complete sample Synapse sequence (in-sequence) used to filter request Headers using Filter mediator

<sequence name="custom-sequence" xmlns="http://ws.apache.org/ns/synapse">
    <filter source="get-property('mycustomheader', 'transport')">
        <then>
            <log level="custom">
                <property name="message" value="Header is presented" />
            </log>
        </then>
        <else>
            <log level="custom">
                <property name="message" value="Header is not presented" />
            </log>
        </else>
    </filter>
</sequence>

Subscribe APIs Using Store REST APIs

Sun, 29 Sep 2019 00:00:00 GMT

Intro

We will be creating APIs and subscribing and consuming them using RESTful APIs which are exposed by the WSO2 API Manager (2.6) platform.

The RESTful APIs of API Manager gives an extended platform to the end-users and developers to create APIs, create an application and to subscribe to them using REST clients without touching any UIs of API Manager. This simply makes life easier when creating hundreds of APIs and testing the platform.

In this demo, we will be covering and performing the following subjects …

Dynamic Client Registration
Create REST API
Create Application
Subscribe
Generate Keys and Access Token
Consume API

You can find more details on exposed APIs and Docs here. We will be using API Docs of API Manager v2.6. Also please find the Postman collection used for this demo at the end of this article

Dynamic Client Registration

Before executing any of the REST API, we have to invoke the dynamic client registration endpoint and want to get an Access Token to further continue and use the exposed APIs.

Server Startup

Download and start the WSO2 API Manager by directing to <APIM>/bin folder and executing the following

# linux env
foo@bar:~$ sh wso2server.sh
# windows env
wso2server.bat

Client Registration

After a successful startup, use the following endpoint reference to register a dynamic client

POST: https://localhost:9443/client-registration/v0.14/register
Authorization: Basic <Base64(admin:admin)>
Content-Type: application/json
{
  "callbackUrl": "localhost",
  "clientName": "rest_api_demo",
  "owner": "admin",
  "grantType": "password refresh_token",
  "saasApp": true
}

curl command

curl -X POST \
  https://localhost:9443/client-registration/v0.14/register \
  -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
  -H 'Content-Type: application/json' \
  -d '{
    "callbackUrl": "localhost",
    "clientName": "rest_api_demo",
    "owner": "admin",
    "grantType": "password refresh_token",
    "saasApp": true
}'

Markdown the clientId and clientSecret values from the response to generate an access token using the token endpoint.

Token Generation

Execute the following endpoint reference to generate an access token using the obtained clientId and clientSecret values.

POST: https://localhost:8243/token
Authorization: Basic <Base64(ClientID:ClientSecret)>
Content-Type: application/x-www-form-urlencoded
grant_type=password
username=admin
password=admin
scope=apim:api_view apim:api_create apim:api_publish apim:subscribe

curl command

curl -X POST \
  https://localhost:8243/token \
  -H 'Authorization: Basic <Base64(ClientID:ClientSecret)>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username=admin&password=admin&scope=apim%3Aapi_view%20apim%3Aapi_create%20apim%3Aapi_publish%20apim%3Asubscribe'

Now we have successfully generated an access token to use with our Store and Publisher REST APIs. Copy the generated access token from the response and keep it for future executions.

Create REST API

We will be using the exact request as defined here to create a test API for our demo. Our demo API will be the default shipped PizzaShackAPI. Please find the request endpoint reference below

POST: https://localhost:9443/api/am/publisher/v0.14/apis
Authorization: Bearer <Access Token>
Content-Type: application/json
{
  "name": "PizzaShackAPI",
  "description": "This document describe a RESTFul API for Pizza Shack online pizza delivery store.\r\n",
  "context": "/pizzashack",
  "version": "1.0.0",
  "provider": "admin",
  "apiDefinition": "{\"paths\":{\"/order\":{\"post\":{\"x-auth-type\":\"Application & Application User\",\"x-throttling-tier\":\"Unlimited\",\"description\":\"Create a new Order\",\"parameters\":[{\"schema\":{\"$ref\":\"#/definitions/Order\"},\"description\":\"Order object that needs to be added\",\"name\":\"body\",\"required\":true,\"in\":\"body\"}],\"responses\":{\"201\":{\"headers\":{\"Location\":{\"description\":\"The URL of the newly created resource.\",\"type\":\"string\"}},\"schema\":{\"$ref\":\"#/definitions/Order\"},\"description\":\"Created.\"}}}},\"/menu\":{\"get\":{\"x-auth-type\":\"Application & Application User\",\"x-throttling-tier\":\"Unlimited\",\"description\":\"Return a list of available menu items\",\"parameters\":[],\"responses\":{\"200\":{\"headers\":{},\"schema\":{\"title\":\"Menu\",\"properties\":{\"list\":{\"items\":{\"$ref\":\"#/definitions/MenuItem\"},\"type\":\"array\"}},\"type\":\"object\"},\"description\":\"OK.\"}}}}},\"schemes\":[\"https\"],\"produces\":[\"application/json\"],\"swagger\":\"2.0\",\"definitions\":{\"MenuItem\":{\"title\":\"Pizza menu Item\",\"properties\":{\"price\":{\"type\":\"string\"},\"description\":{\"type\":\"string\"},\"name\":{\"type\":\"string\"},\"image\":{\"type\":\"string\"}},\"required\":[\"name\"]},\"Order\":{\"title\":\"Pizza Order\",\"properties\":{\"customerName\":{\"type\":\"string\"},\"delivered\":{\"type\":\"boolean\"},\"address\":{\"type\":\"string\"},\"pizzaType\":{\"type\":\"string\"},\"creditCardNumber\":{\"type\":\"string\"},\"quantity\":{\"type\":\"number\"},\"orderId\":{\"type\":\"string\"}},\"required\":[\"orderId\"]}},\"consumes\":[\"application/json\"],\"info\":{\"title\":\"PizzaShackAPI\",\"description\":\"This document describe a RESTFul API for Pizza Shack online pizza delivery store.\\n\",\"license\":{\"name\":\"Apache 2.0\",\"url\":\"http://www.apache.org/licenses/LICENSE-2.0.html\"},\"contact\":{\"email\":\"architecture@pizzashack.com\",\"name\":\"John Doe\",\"url\":\"http://www.pizzashack.com\"},\"version\":\"1.0.0\"}}",    
  "wsdlUri": null,
  "status": "CREATED",
  "responseCaching": "Disabled",
  "cacheTimeout": 300,
  "destinationStatsEnabled": false,
  "isDefaultVersion": false,
  "type": "HTTP",
  "transport":["http","https"],
  "tags": ["pizza"],
  "tiers": ["Unlimited"],
  "maxTps":{
    "sandbox": 5000,
    "production": 1000
  },
  "visibility": "PUBLIC",
  "visibleRoles": [],
  "endpointConfig": "{\"production_endpoints\":{\"url\":\"https://localhost:9443/am/sample/pizzashack/v1/api/\",\"config\":null},\"sandbox_endpoints\":{\"url\":\"https://localhost:9443/am/sample/pizzashack/v1/api/\",\"config\":null},\"endpoint_type\":\"http\"}",
  "endpointSecurity":{
    "username": "user",
    "type": "basic",
    "password": "pass"
  },
  "gatewayEnvironments": "Production and Sandbox",
  "sequences":[
    {
      "name":"json_validator",
      "type": "in"
    },
    {
      "name":"log_out_message",
      "type": "out"
    }
  ],
  "subscriptionAvailability": null,
  "subscriptionAvailableTenants": [],
  "businessInformation":{
    "businessOwnerEmail": "marketing@pizzashack.com",
    "technicalOwnerEmail": "architecture@pizzashack.com",
    "technicalOwner": "John Doe",
    "businessOwner": "Jane Roe"
  },
  "corsConfiguration":{
    "accessControlAllowOrigins": ["*"],
    "accessControlAllowHeaders":["authorization","Access-Control-Allow-Origin","Content-Type","SOAPAction"],
    "accessControlAllowMethods":["GET","PUT","POST","DELETE","PATCH","OPTIONS"],
    "accessControlAllowCredentials": false,
    "corsConfigurationEnabled": false
  }
}

curl command

curl -X POST \
  https://localhost:9443/api/am/publisher/v0.14/apis \
  -H 'Authorization: Bearer <Access Token>' \
  -H 'Content-Type: application/json' \
  -d '{
   "name": "PizzaShackAPI",
   "description": "This document describe a RESTFul API for Pizza Shack online pizza delivery store.\r\n",
   "context": "/pizzashack",
   "version": "1.0.0",
   "provider": "admin",
   "apiDefinition": "{\"paths\":{\"/order\":{\"post\":{\"x-auth-type\":\"Application & Application User\",\"x-throttling-tier\":\"Unlimited\",\"description\":\"Create a new Order\",\"parameters\":[{\"schema\":{\"$ref\":\"#/definitions/Order\"},\"description\":\"Order object that needs to be added\",\"name\":\"body\",\"required\":true,\"in\":\"body\"}],\"responses\":{\"201\":{\"headers\":{\"Location\":{\"description\":\"The URL of the newly created resource.\",\"type\":\"string\"}},\"schema\":{\"$ref\":\"#/definitions/Order\"},\"description\":\"Created.\"}}}},\"/menu\":{\"get\":{\"x-auth-type\":\"Application & Application User\",\"x-throttling-tier\":\"Unlimited\",\"description\":\"Return a list of available menu items\",\"parameters\":[],\"responses\":{\"200\":{\"headers\":{},\"schema\":{\"title\":\"Menu\",\"properties\":{\"list\":{\"items\":{\"$ref\":\"#/definitions/MenuItem\"},\"type\":\"array\"}},\"type\":\"object\"},\"description\":\"OK.\"}}}}},\"schemes\":[\"https\"],\"produces\":[\"application/json\"],\"swagger\":\"2.0\",\"definitions\":{\"MenuItem\":{\"title\":\"Pizza menu Item\",\"properties\":{\"price\":{\"type\":\"string\"},\"description\":{\"type\":\"string\"},\"name\":{\"type\":\"string\"},\"image\":{\"type\":\"string\"}},\"required\":[\"name\"]},\"Order\":{\"title\":\"Pizza Order\",\"properties\":{\"customerName\":{\"type\":\"string\"},\"delivered\":{\"type\":\"boolean\"},\"address\":{\"type\":\"string\"},\"pizzaType\":{\"type\":\"string\"},\"creditCardNumber\":{\"type\":\"string\"},\"quantity\":{\"type\":\"number\"},\"orderId\":{\"type\":\"string\"}},\"required\":[\"orderId\"]}},\"consumes\":[\"application/json\"],\"info\":{\"title\":\"PizzaShackAPI\",\"description\":\"This document describe a RESTFul API for Pizza Shack online pizza delivery store.\\n\",\"license\":{\"name\":\"Apache 2.0\",\"url\":\"http://www.apache.org/licenses/LICENSE-2.0.html\"},\"contact\":{\"email\":\"architecture@pizzashack.com\",\"name\":\"John Doe\",\"url\":\"http://www.pizzashack.com\"},\"version\":\"1.0.0\"}}",
   "wsdlUri": null,
   "status": "CREATED",
   "responseCaching": "Disabled",
   "cacheTimeout": 300,
   "destinationStatsEnabled": false,
   "isDefaultVersion": false,
   "type": "HTTP",
   "transport":    [
      "http",
      "https"
   ],
   "tags": ["pizza"],
   "tiers": ["Unlimited"],
   "maxTps":    {
      "sandbox": 5000,
      "production": 1000
   },
   "visibility": "PUBLIC",
   "visibleRoles": [],
   "endpointConfig": "{\"production_endpoints\":{\"url\":\"https://localhost:9443/am/sample/pizzashack/v1/api/\",\"config\":null},\"sandbox_endpoints\":{\"url\":\"https://localhost:9443/am/sample/pizzashack/v1/api/\",\"config\":null},\"endpoint_type\":\"http\"}",
   "endpointSecurity":    {
      "username": "user",
      "type": "basic",
      "password": "pass"
   },
   "gatewayEnvironments": "Production and Sandbox",
   "sequences": [{"name":"json_validator","type": "in"},{"name":"log_out_message","type": "out"}],
   "subscriptionAvailability": null,
   "subscriptionAvailableTenants": [],
   "businessInformation":    {
      "businessOwnerEmail": "marketing@pizzashack.com",
      "technicalOwnerEmail": "architecture@pizzashack.com",
      "technicalOwner": "John Doe",
      "businessOwner": "Jane Roe"
   },
   "corsConfiguration":    {
      "accessControlAllowOrigins": ["*"],
      "accessControlAllowHeaders":       [
         "authorization",
         "Access-Control-Allow-Origin",
         "Content-Type",
         "SOAPAction"
      ],
      "accessControlAllowMethods":       [
         "GET",
         "PUT",
         "POST",
         "DELETE",
         "PATCH",
         "OPTIONS"
      ],
      "accessControlAllowCredentials": false,
      "corsConfigurationEnabled": false
   }
}'

After successful execution, copy the id value from the response. We will be using the id value to identify our Pizza Shack API when subscribing to an application.

Now we have to change the status of our created API from CREATED to PUBLISHED state.

POST: https://localhost:9443/api/am/publisher/v0.14/apis/change-lifecycle?apiId=<API Id Value>&action=Publish
Authorization: Bearer <Access Token>

curl command

curl -X POST \
  'https://localhost:9443/api/am/publisher/v0.14/apis/change-lifecycle?apiId=<API ID>&action=Publish' \
  -H 'Authorization: Bearer <Access Token>' \

Create Application

Before subscribing an API, we have to create an application for it with the appropriate throttling tiers/subscription level.

We can also use the DefaultApplication from the Store to subscribe to an API, but for the demo, we will be creating a new application

Below presented is the request endpoint reference to create a new application.

POST: https://localhost:9443/api/am/store/v0.14/applications
Authorization: Bearer <Access Token>
Content-Type: application/json
{
  "throttlingTier": "Unlimited",
  "description": "Demo App",
  "name": "DemoApp",
  "callbackUrl": "http://localhost"
}

curl command

curl -X POST \
  https://localhost:9443/api/am/store/v0.14/applications \
  -H 'Authorization: Bearer <Access Token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "throttlingTier": "Unlimited",
    "description": "Demo App",
    "name": "DemoApp",
    "callbackUrl": "http://localhost"
}'

Note down the applicationId value from the successful response.

At last, now we are in the section of subscribing to our created PizzaShackAPI with the above-generated DemoApp.

For subscription, we can use either the id value of our created API or the unique name of our PizzaShackAPI. Using the id value of an API is a straightforward execution. But sometimes, using the unique name will be more helpful when you know the minimal of an API.

If a user called admin has created an API named DemoAPI with version v1.0.0 then the unique name will be as admin-DemoAPI-v1.0.0
If a user called foo from a tenant named bar has created an API named TenantAPI with the version 1.0 then the unique name will be as foo-AT-bar.com-TenantAPI-1.0

POST: https://localhost:9443/api/am/store/v0.14/subscriptions
Authorization: Bearer <Access Token>
Content-Type: application/json
{
  "tier": "Unlimited",
  "apiIdentifier": "<API ID Value || API Unique Name>",
  "applicationId": "<Application ID Value>"
}

curl command

curl -X POST \
  https://localhost:9443/api/am/store/v0.14/subscriptions \
  -H 'Authorization: Bearer <Access Token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "tier": "Unlimited",
  "apiIdentifier": "admin-PizzaShackAPI-1.0.0",
  "applicationId": "Application ID"
}'

Generate Keys

Next, we will be generating Production Keys for our DemoApp to generate an access token for API consumption.

POST: https://localhost:9443/api/am/store/v0.14/applications/generate-keys?applicationId=<Application ID Value>
Authorization: Bearer <Access Token>
Content-Type: application/json
{
  "validityTime": "3600",
  "keyType": "PRODUCTION",
  "accessAllowDomains": [ "ALL" ],
  "scopes": [ "am_application_scope", "default" ],
  "supportedGrantTypes": [ "urn:ietf:params:oauth:grant-type:saml2-bearer", "iwa:ntlm", "refresh_token", "client_credentials", "password" ]
}

curl command

curl -X POST \
  'https://localhost:9443/api/am/store/v0.14/applications/generate-keys?applicationId=<Application ID>' \
  -H 'Authorization: Bearer <Access Token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "validityTime": "3600",
  "keyType": "PRODUCTION",
  "accessAllowDomains": [ "ALL" ],
  "scopes": [ "am_application_scope", "default" ],
  "supportedGrantTypes": [ "urn:ietf:params:oauth:grant-type:saml2-bearer", "iwa:ntlm", "refresh_token", "client_credentials", "password" ]
}'

Note down both the consumerKey and consumerSecret values to generate an Access Token.

POST: https://localhost:8243/token
Authorization: Basic <Base64(ConsumerKey:ConsumerSecret)>
Content-Type: application/x-www-form-urlencoded
grant_type=password
username=admin
password=admin
scope=default

curl command

curl -X POST \
  https://localhost:8243/token \
  -H 'Authorization: Basic <Base64(ConsumerKey:ConsumerSecret)>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username=admin&password=admin&scope=default'

Note the access_token value to invoke and consumer our Pizza Shack API

Consume & Test

At last, now we are going to invoke and consume our created Pizza Shack API using the below request endpoint reference with the above-generated access token.

GET: https://localhost:8243/pizzashack/1.0.0/menu
Authorization: Beaer <Access Token>

curl command

curl -X GET \
  https://localhost:8243/pizzashack/1.0.0/menu \
  -H 'Authorization: Bearer <Access Token>' \

After all these struggles, We have successfully created an API, application and subscribed and invoked them and achieved our goals.

I know it is hard to manage and remember these curl commands and you need a way to organize them. Therefore, please find the Postman REST API collection of this demo to make life easier.

Postman Collection

Expose SOAP as REST API

Sat, 28 Sep 2019 00:00:00 GMT

Intro

In this medium, we will be looking on how to expose a legacy web-service / SOAP service as REST APIs using both WSO2 API Manager (2.6.0) and Enterprise Integrator (6.5.0).

Why EI & API Manager? Can’t we do it using either one of them?
Of course we can. It is possible to expose a SOAP service as REST APIs using either API Manager or Enterprise Integrator. But, if you have added additional mediations and performing heavy-duty mediations in API sequences, then using both the API Manager and Enterprise Integrator is a best solution. Which is because, EI is scoped and capable to perform heavy-mediations as well as the API Manager is scoped to perform only API management processes.
This post illustrates how to add an LDAP user-store as a secondary user-store in WSO2 API Manager (in almost every WSO2 Product).

For demo purposes, I have implemented a mock Developer Management Web Service using Spring Boot and will be using that to configure our EI and API Manager instances.

Let’s dive into the demo …

Legacy Service

Entities & Services

The Developer Management Web Service contains the following entities and services …

Developer
    - Add Developer
    - Get Developer
    - Delete Developer
Repo
    - Add Repo
    - Get Repo

Build & Run

Clone or download the project from GitHub, and execute the following command from the root folder to start the web-service server

mvn spring-boot:run

If you don’t have maven installed, then use the following to start the server

./mvnw spring-boot:run

After a successful startup, navigate to https://localhost:8443/ws/developers.wsdl to access the WSDL definitions of our Developer Management service.

WSO2 Enterprise Integrator

We will be starting from WSO2 Enterprise Integrator instance to expose the provided legacy service as REST service.

Truststore & Certificate

Beforehand, we want to export the self-signed certificate of our Developer Management service to our EI instance for a hassle-free SSL connectivity and HTTPS communication.

Follow the given steps to export and import certificates of our legacy service to the EI’s trust-store.

Export or download the self-signed certificate of our legacy service from the browser.

Follow this https://www.shellhacks.com/get-ssl-certificate-from-server-site-url-export-download/ to export and download the self-signed certificate from the browser

Execute the following command to import the certificate to our EI instance

Navigate to <EI>/repository/resources/security folder and execute the following command. Enter wso2carbon as the password if it prompts

keytool -importcert -file <path to crt> -keystore client-truststore.jks -alias hydrogen.com

Carbon Artifact

Start the EI instance by navigating to the /bin folder and execute the following command based on your environment …

# linux env
sh integrator.sh
# windows env
integrator.bat

Fire up your favorite browser and route to https://localhost:9443/carbon and log in using the following credentials

username: admin
password: admin

I have implemented and provided a carbon archive with configurations related to SOAP to REST services, endpoints, and sequences. You can use the following artifact and deploy it our EI instance without any configurations hassle.

Select Add under Carbon Applications section and upload and deploy the above-provided carbon archive.

Below given is the source code of Developer Management Service API Carbon artifact

Run & Test

Before testing, make sure to verify whether the EI instance is running and deploy the provided Carbon archive

Test the exposed REST API service using the below cURL commands. Given below are a couple of cURL commands to test the exposed REST APIs.

Given below is a .http file, can be used with VS Code with REST Client Extension

  
          @hostname = https://localhost:8243/dev-management
        
          @username = athiththan11
        
          ### Get Developer
        
          # @name getDeveloper
        
          curl -k -X GET {{hostname}}/devs/{{username}} \
        
              -H "Content-Type: application/json"
        
          ### Get Repos of a Developer
        
          # @name getRepos
        
          curl -k -X GET {{hostname}}/devs/{{username}}/repos \
        
              -H "Content-Type: application/json"
        
          ### Delete a Developer
        
          # @name deleteDeveloper
        
          curl -k -X DELETE {{hostname}}/devs/{{username}} \
        
              -H "Content-Type: application/json"
        
          ### Create a Developer
        
          # @name addDeveloper
        
          curl -k -X POST {{hostname}}/devs \
        
              -d '{ "username": "athiththan11", "name": "Athiththan", "email": "athiththan11@test.com" }' \
        
              -H "Content-Type: application/json"
        
          ### Create a Repo
        
          # @name addRepo
        
          curl -k -X POST {{hostname}}/repos \
        
              -d '{ "name": "repodews", "username": "athiththan11", "forks": 0 }' \
        
              -H "Content-Type: application/json"

view raw wso2-trilogy-ei-curl.http hosted with ❤ by GitHub

WSO2 API Manager

Thereafter, we’ll configure a WSO2 API Manager instance to manage the API lifecycle, traffic, subscriptions, and analytics of our exposed REST service.

Port Offset

In advance, we need to configure a port off-set for our API Manager instance, this done because both our EI and API Manager instances will be running on a single machine.

Navigate to <APIM>/repository/conf/carbon.xml and change the <Offset> value from 0 to 1. And, start the API Manager instance by navigating to <APIM>/bin folder and execute the following command based on your environment …

# linux env
sh wso2server.sh
# windows env
wso2server.bat

Design & Publish REST API

After a successful startup, route to https://localhost:9444/publisher and login using admin as both the username and password.

Given below is a complete Swagger definition for our Developer Management REST API.

Click on Add New API

Then select I Have an Existing API and upload the provided swagger file.

Add the context as /dev-management and click Next: Implement

Add https://localhost:8243/dev-management as the Production Endpoint and click Next: Manage

Select all applicable throttling tiers and click Save & Publish to publish the Developer Management REST API to the Store portal.

After publishing the REST API from the Publisher portal, navigate to the Store portal by https://localhost:9444/store and log in as admin.

Select our published API and subscribe to the DefaultApplication with Unlimited Tier.

You can create a new application by navigating to the Application section in the Store portal and subscribe to that API with applicable Tier

Select View Subscriptions from the alert box and then navigate to the Production Keys tab and select Generate Keys to generate new consumer keys for our DefaultApplication.

After a successful generation, copy the Access Token value to invoke our defined REST APIs.

Run & Test

Before testing, make sure to verify whether the APIM instance is running and have successfully published the REST API and subscribed

Test the exposed REST APIs using the below cURL commands. Given below are a couple of cURL commands to test the exposed REST APIs. We can also test the REST APIs using the integrated Swagger tool in the Store portal.

You can replace the consumer-key and consumer-secret fields with the generated values or you can replace the {{access-token}} with the copied Access Token value and execute the cURL commands

  
          @consumer-key = <Replace with Consumer Key>
        
          @consumer-secret = <Replace with Consumer Secret>
        
          @api-hostname = https://10.100.5.220:8244/dev-management/v1.0.0
        
          # Username & Password
        
          @api-username = admin
        
          @api-password = admin
        
          @username = athiththan11
        
          ### Token Endpoint
        
          # @name tokenEndpoint
        
          curl -k -d "grant_type=password&username={{api-username}}&password={{api-password}}&scope=default" \
        
          	    -H "Authorization: Basic <Replace with Base64Encode(ClientID:ClientSecret)>" \
        
          	      https://localhost:8244/token
        
          @access-token = {{tokenEndpoint.response.body.access_token}}
        
          @authorization = Bearer {{access-token}}
        
          ### Get Developer
        
          # @name getDeveloperAPI
        
          curl -k -X GET {{api-hostname}}/devs/{{username}} \
        
              -H "accept: application/json" \
        
              -H "Authorization: {{authorization}}"
        
          ### Get Repos of a Developer
        
          # @name getReposAPI
        
          curl -k -X GET {{api-hostname}}/devs/{{username}}/repos \
        
              -H "accept: application/json" \
        
              -H "Authorization: {{authorization}}"
        
          ### Delete a Developer
        
          # @name deleteDeveloperAPI
        
          curl -k -X DELETE {{api-hostname}}/devs/{{username}} \
        
              -H "accept: application/json" \
        
              -H "Authorization: {{authorization}}"
        
          ### Create a Developer
        
          # @name addDeveloperAPI
        
          curl -k -X POST {{api-hostname}}/devs \
        
              -d '{ "username": "athiththan11", "name": "Athiththan", "email": "athiththan11@test.com" }' \
        
              -H "Content-Type: application/json" \
        
              -H "accept: application/json" \
        
              -H "Authorization: {{authorization}}"
        
          ### Create a Repo
        
          # @name addRepoAPI
        
          curl -k -X POST {{api-hostname}}/repos \
        
              -d '{ "name": "repodews", "username": "athiththan11", "forks": 0 }' \
        
              -H "Content-Type: application/json" \
        
              -H "accept: application/json" \
        
              -H "Authorization: {{authorization}}"

view raw wso2-trilogy-apim-curl.http hosted with ❤ by GitHub

GitHub

Configure LDAP as a Secondary User Store

Sun, 08 Sep 2019 00:00:00 GMT

Intro

This post illustrates how to add an LDAP user-store as a secondary user-store in WSO2 API Manager (in almost every WSO2 Product).

For demo purposes, we will be using a pre-configured LDAP user-store which resides in WSO2 Identity Server and shipped by default

Configure

Download both WSO2 API Manager (2.6.0) and WSO2 Identity Server (5.7.0) as binary artifacts from the official download page and follow the given steps to configure port offset on them.

WSO2 Identity Server

Extract the binary artifact of WSO2 Identity Server and navigate to [IS]/bin folder and execute the following command based on your environment to start the server …

# linux env
./wso2server.sh
# windows env
./wso2server.bat

WSO2 API Manager

Extract the binary artifact of WSO2 API Manager and navigate to [APIM]/repository/conf/carbon.xml to edit the port offset configurations of API Manager.

We will be using the default shipped LDAP user-store of WSO2 Identity Server as the secondary user-store in API Manager. Therefore, we will be running both the server nodes in a single machine. For this reason, we will be port off-setting the API Manager node

Open and edit the <Offset> element with the following …

<Offset>1</Offset>

Start the server by executing the following command based on your environment

# linux env
./wso2server.sh
# windows env
./wso2server.bat

And login to the management console by directing to https://localhost:9444/carbon and enter admin as both the username and password. Next select Add under User Stores section in Main tab.

Enter the inputs as follows …

User Store Manager Class: select ReadWriteLDAPUserStoreManager or ReadOnlyLDAPUserStoreManager based on your preference
Domain Name: give a related domain name to identify the users from this user-store. We will be using IS as the domain name
Connection URL: ldap://localhost:10389
Connection Name: uid=admin,ou=system
Connection Password: admin
User Search Based: ou=Users,dc=wso2,dc=org
User Entry Object Class: identityPerson
Username Attribute: uid
User Search Filter: (&(objectClass=person)(uid=?))
User List Filter: (objectClass=person)

Please enter relavant configuration values and properties if your LDAP configurations are different from the above-mentioned

Click on Add to save and add the user-store in WSO2 API Manager. The following alert box will appear if the user-store is added correctly.

Run & Test

Direct to https://localhost:9444/carbon and select List under Users and Roles section and select Users from the prompted page to list all available users from all defined user-stores.

You will see a similar page as follows …

Select View Roles of IS/admin user and click on Permissions of IS/admin role in the next page. Thereafter, select theLogin permission in the listed permission tree.

And select Update to update the permission tree. Now, logout from the carbon console and again Sign-in using the following credentials …

Username: IS/admin
Password: admin

The above-mentioned credentials are related to the admin user of the secondary user-store

After a successful login, the management console will be displayed with allowed features set and panels (allowed permissions).

Replace H2 with Postgres

Sat, 03 Aug 2019 00:00:00 GMT

Docker: Postgres

Pull

Prerequisites: Docker installed in your environment. You can follow the Docker docs to get it done.

Follow the given steps to set up Postgres using Docker in your dev environments. For this demo, we will be using Postgres - 9.6.14 and WSO2 Identity Server 5.7.

Start the Docker service and execute the following command to pull the Postgres (9.6.14) image from DockerHub

docker pull postgres:9.6.14

Run

After a successful pull, execute the below command to create and run a docker container for our pulled Postgres image. Replace the <CONTAINER_NAME> tag with your preferred name or use postgres-9.6.14 as the default value.

You can change the Postgres password by changing the POSTGRES_PASSWORD value from hydrogen to any preferred secured password

docker run --name <CONTAINER_NAME || postgres-9.6.14> -e POSTGRES_PASSWORD=hydrogen -p 5432:5432 -d -v $HOME/docker/volumes/postgres:/var/lib/postgresql postgres:9.6.14

Basic commands to start and stop a Docker container
docker start <CONTAINER_NAME> to start a container
docker stop <CONTAINER_NAME> to stop a running container

PSQL Terminal

Use the following command to hop into the PSQL terminal session.

docker exec -ti <CONTAINER_NAME || postgres-9.6.14> psql -h localhost -U postgres

Configurations

Postgres

To replace the default packaged H2 database with Postgres, initially, we have to create the databases and tables in Postgres. Find and execute the following PostgreSQL scripts to create and set up all necessary tables and indexes.

You can use either any database tools like DBeaver (Jump to DBeaver) or you can straightaway execute them using PSQL terminal (Jump to PSQL)

<IS>/dbscripts/postgresql.sql
<IS>/dbscripts/identity/postgresql.sql
<IS>/dbscripts/identity/uma/postgresql.sql
<IS>/dbscripts/identity/stored-procedures/postgre/postgresql.sql
<IS>/dbscripts/consent/postgresql.sql

Start the Postgres container (if not started before) using the following command

docker start postgres-9.6.14

PSQL

Execute the following command to enter the PSQL terminal session and run the create query to create a database named wso2postgres

docker exec -ti postgres-9.6.14 psql -h localhost -U postgres

create database wso2postgres;

After successful creation, try to connect to the wso2postgres database using the following command

\c wso2postgres;

Next, quite the terminal session using \q command and copy the dbscripts folder from the <IS_HOME> path to our postgres-9.6.14 container volume to execute all related scripts using the Docker PSQL terminal.

docker cp <IS_HOME>/dbscripts postgres-9.6.14:/

and run the following commands one by one to execute the scripts

docker exec -ti postgres-9.6.14 psql -h localhost -U postgres -d wso2postgres -f /dbscripts/postgresql.sql
-----
docker exec -ti postgres-9.6.14 psql -h localhost -U postgres -d wso2postgres -f /dbscripts/identity/postgresql.sql
-----
docker exec -ti postgres-9.6.14 psql -h localhost -U postgres -d wso2postgres -f /dbscripts/identity/uma/postgresql.sql
-----
docker exec -ti postgres-9.6.14 psql -h localhost -U postgres -d wso2postgres -f /dbscripts/identity/stored-procedures/postgre/postgresql.sql
-----
docker exec -ti postgres-9.6.14 psql -h localhost -U postgres -d wso2postgres -f /dbscripts/consent/postgresql.sql

After a successful connection, execute the above-mentioned SQL scripts to create related tables and indexes. But, before executing them, we have to copy the dbscripts folder to the related container volume to execute the script using PSQL terminal. Execute the following command to copy the dbscripts folder from the <IS_HOME> path to our postgres-9.6.14 container volume.

DBeaver

Prerequisites: DBeaver installed in your environment. You can follow the DBeaver site.

Open DBeaver and create a new database connection. Select PostgreSQL from the list and click Next.

Enter wso2postgres for the Database field and use hydrogen as Password.

Please change and use related values for the Host, Port, Database, User and Password fields if those are different from mentioned default values.
If you have not installed any PostgreSQL driver for DBeaver, it will prompt you to follow a couple of instructions to install necessary drivers to work with Postgres databases and connections

Click on Test Connection to test the database connection and if successful then click on Finish to finish the connection configuration process. The created connection will be listed under the Database Navigator panel (on the left-side navigation panel). Navigate to File -> Open File ... and select and open the above-listed PostgreSQL scripts in the DBeaver.

Select the database connection and the Postgres schema if not selected by default and click Execute SQL Script to execute the script. Do this for all above-mentioned PostgreSQL scripts.

WSO2 Identity Server

Below described steps and guides are based on fresh-pack installation. If you have any pre-stored data inside the H2 database, then you have to migrate them to the new data-source which is not covered in this topic.

After setting up the databases, now we have to install the Postgres JDBC connector (driver) for our WSO2 Identity Server. Download the Postgres driver from here, copy and place the jar file inside the <IS>/repository/components/lib directory.

Next, we have to configure our database connection settings in the Identity Server to connect to our Postgres source. Make changes to the following XML files to swap the connection from default H2 database to our Postgres database.

<IS>/repository/conf/datasources/master-datasources.xml
<IS>/repository/conf/identity/identity.xml
<IS>/repository/conf/registry.xml

Moreover, We will also be swapping the user store from the default LDAP server to the JDBC store

<IS>/repository/conf/user-mgt.xml

Replace and change the host, port, username, and password segments with respective values if different.

Master DataSource

Add the following data source configuration below the default H2 configuration.

<!-- master-datasources.xml -->
<datasource>
    <name>WSO2_CARBON_POSTGRES_DB</name>
    <description>The datasource used for registry and user manager</description>
    <jndiConfig>
        <name>jdbc/WSO2CarbonPostgresDB</name>
    </jndiConfig>
    <definition type="RDBMS">
        <configuration>
            <url>jdbc:postgresql://localhost:5432/wso2postgres</url>
            <username>postgres</username>
            <password>hydrogen</password>
            <driverClassName>org.postgresql.Driver</driverClassName>
            <maxActive>80</maxActive>
            <maxWait>60000</maxWait>
            <minIdle>5</minIdle>
            <testOnBorrow>true</testOnBorrow>
            <validationQuery>SELECT 1; COMMIT</validationQuery>
            <defaultAutoCommit>true</defaultAutoCommit>
            <validationInterval>30000</validationInterval>
        </configuration>
    </definition>
</datasource>

Identity

Change the data-source in repository/conf/identity/identity.xml with the Postgres JNDI configuration name.

<!-- identity.xml -->
<JDBCPersistenceManager>
        <DataSource>
            <!-- Include a data source name (jndiConfigName) from the set of data
                sources defined in master-datasources.xml -->
            <!-- <Name>jdbc/WSO2CarbonDB</Name> -->
            <Name>jdbc/WSO2CarbonPostgresDB</Name>
        </DataSource>
        ...

Registry

The following changes are made to mount the registries with our newly created Postgres data-source.

Don’t change the default wso2registry configurations unless if you want to. Add new registry mounting configurations below the default configurations.

<!-- registry.xml -->
<dbConfig name="wso2registry">
    <dataSource>jdbc/WSO2CarbonDB</dataSource>
</dbConfig>
<dbConfig name="govregistry">
    <dataSource>jdbc/WSO2CarbonPostgresDB</dataSource>
</dbConfig>
<remoteInstance url="https://localhost:9443/registry">
    <id>gov</id>
    <cacheId>postgres@jdbc:postgresql://localhost:5432/wso2postgres</cacheId>
    <dbConfig>govregistry</dbConfig>
    <readOnly>false</readOnly>
    <enableCache>true</enableCache>
    <registryRoot>/</registryRoot>
</remoteInstance>
<mount path="/_system/governance" overwrite="true">
    <instanceId>gov</instanceId>
    <targetPath>/_system/governance</targetPath>
</mount>
<mount path="/_system/config" overwrite="true">
    <instanceId>gov</instanceId>
    <targetPath>/_system/config</targetPath>
</mount>

User Management

Below described steps are to change the default LDAP user-store to JDBC user-store. You can skip the following changes if you want to keep the default LDAP user-store as out-of-the-box.

Comment the existing WSO2CarbonDB data source property tag and place the WSO2CarbonPostgresDB property tag inside the <Configuration> element as described below

<Configuration>
    ...
    <!-- <Property name="dataSource">jdbc/WSO2CarbonDB</Property> -->
    <Property name="dataSource">jdbc/WSO2CarbonPostgresDB</Property>
</Configuration>

Further, comment the LDAP user store manager configurations and uncomment the JDBC user store manager. This will route our default LDAP user store with JDBC user store.

Run & Test

Start the WSO2 Identity Server by navigating to the <IS>/bin folder and execute the following command based on your environment

# linux env
./wso2server.sh
# windows env
./wso2server.bat

The server will start and configure the platform to work with new configurations. After a successful startup, bring up your favorite browser and navigate to https://localhost:9443/carbon and enter admin as both username and password.

SAML SSO With Passport

Sat, 20 Jul 2019 00:00:00 GMT

Intro

This post narrates on how-to enable and register a service provider for SAML SSO using WSO2 Identity Server and to develop a simple Express-based web application with Passport-SAML component to support and authenticate the users via SAML SSO.

Security Assertion Markup Language (SAML) is an XML-based framework for authentication and authorization between a Service Provider and an Identity Provider. SAML is a standard Single-Sign-On (SSO) format. Authentication information is exchanged through digitally signed XML documents.
For more on SAML

Implementation

Express Application

Create an express application by executing npm init command, and provide all necessary properties to start the development.

Install all below-listed dependencies by either running npm install <module> --save command or by replacing the dependencies object with the values.

A complete package.json is given below.

  
          {
        
          	"name": "expresssaml",
        
          	"version": "1.0.0",
        
          	"description": "Express Application with SAML SSO",
        
          	"main": "server.js",
        
          	"scripts": {
        
          		"test": "echo \"Error: no test specified\" && exit 1"
        
          	},
        
          	"author": "athiththan11",
        
          	"homepage": "https://github.com/athiththan11/Passport-SAML-WSO2",
        
          	"keywords": [
        
          		"wso2-saml-sso",
        
          		"passport-saml"
        
          	],
        
          	"license": "ISC",
        
          	"dependencies": {
        
          		"body-parser": "1.19.0",
        
          		"dotenv": "8.0.0",
        
          		"ejs": "2.6.2",
        
          		"express": "4.17.1",
        
          		"express-session": "1.16.2",
        
          		"passport": "0.3.2",
        
          		"passport-saml": "0.15.0"
        
          	},
        
          	"devDependencies": {}
        
          }

view raw package.json hosted with ❤ by GitHub

Create a Javascript file named server.js in the root directory of our express application with the below-given code-segments.

Note: EJS template implementations are not covered here
Check out the complete implementation of our express application at the end of this blog followed by a GitHub repo. The implementation contains simple EJS templates to render the pages and outputs.

  
          require('dotenv').config();
        
          var path = require('path');
        
          var fs = require('fs');
        
          var express = require('express');
        
          var session = require('express-session');
        
          var passport = require('passport');
        
          var saml = require('passport-saml').Strategy;
        
          var bodyParser = require('body-parser');
        
          var userProfile;
        
          var app = express();
        
          app.set('views', path.join(__dirname, 'views'));
        
          app.set('view engine', 'ejs');
        
          app.use(express.static(path.join(__dirname, 'public')));
        
          app.use(bodyParser.urlencoded({ extended: true }));
        
          app.use(session({ secret: process.env.SESSION_SECRET }));
        
          app.use(passport.initialize());
        
          app.use(passport.session());
        
          passport.serializeUser((user, done) => {
        
          	done(null, user);
        
          });
        
          passport.deserializeUser((user, done) => {
        
          	done(null, user);
        
          });
        
          // saml strategy for passport
        
          var strategy = new saml(
        
          	{
        
          		entryPoint: process.env.SAML_ENTRYPOINT,
        
          		issuer: process.env.SAML_ISSUER,
        
          		protocol: process.env.SAML_PROTOCOL,
        
          		logoutUrl: process.env.SAML_LOGOUTURL
        
          	},
        
          	(profile, done) => {
        
          		userProfile = profile;
        
          		done(null, userProfile);
        
          	}
        
          );
        
          passport.use(strategy);
        
          var redirectToLogin = (req, res, next) => {
        
          	if (!req.isAuthenticated() || userProfile == null) {
        
          		return res.redirect('/app/login');
        
          	}
        
          	next();
        
          };
        
          app.get('/app', redirectToLogin, (req, res) => {
        
          	res.render('index', {
        
          		title: 'Express Web Application',
        
          		heading: 'Logged-In to Express Web Application'
        
          	});
        
          });
        
          app.get(
        
          	'/app/login',
        
          	passport.authenticate('saml', {
        
          		successRedirect: '/app',
        
          		failureRedirect: '/app/login'
        
          	})
        
          );
        
          app.get('/app/logout', (req, res) => {
        
          	if (req.user == null) {
        
          		return res.redirect('/app/home');
        
          	}
        
          	return strategy.logout(req, (err, uri) => {
        
          		req.logout();
        
          		userProfile = null;
        
          		return res.redirect(uri);
        
          	});
        
          });
        
          app.get('/app/failed', (req, res) => {
        
          	res.status(401).send('Login failed');
        
          });
        
          app.post(
        
          	'/saml/consume',
        
          	passport.authenticate('saml', {
        
          		failureRedirect: '/app/failed',
        
          		failureFlash: true
        
          	}),
        
          	(req, res) => {
        
          		// saml assertion extraction from saml response
        
          		// var samlResponse = res.req.body.SAMLResponse;
        
          		// var decoded = base64decode(samlResponse);
        
          		// var assertion =
        
          		// 	('<saml2:Assertion' + decoded.split('<saml2:Assertion')[1]).split(
        
          		// 		'</saml2:Assertion>'
        
          		// 	)[0] + '</saml2:Assertion>';
        
          		// var urlEncoded = base64url(assertion);
        
          		// success redirection to /app
        
          		return res.redirect('/app');
        
          	}
        
          );
        
          app.post('/app/home', (req, res) => {
        
          	res.render('home', {
        
          		title: 'Express Web Application',
        
          		heading: 'Express Web Application'
        
          	});
        
          });
        
          app.listen(process.env.PORT || 3000);

view raw server.js hosted with ❤ by GitHub

Passport

Passport is authentication middleware for Node.js and can be used with any Express-based web applications.

Passport has a comprehensive set of strategies to support different authentication mechanisms with different vendors.

For this implementation, we will be using Passport-SAML (which is an open-built strategy for SAML 2.0 authentication flows) strategy with our express web application to authenticate users.

Given below is a simple Passport-SAML strategy configuration …

  
          var passport = require('passport');
        
          var saml = require('passport-saml').Strategy;
        
          // saml strategy for passport
        
          var strategy = new saml(
        
          	{
        
          		entryPoint: <provide SAML entry point url : https://localhost:9443/samlsso>,
        
          		issuer: <provide SAML issuer name : SampleExpressApp>,
        
          		protocol: <provide the protocol used : http://>,
        
          		logoutUrl: <provide the logout url : https://localhost:9443/samlsso>
        
          	},
        
          	(profile, done) => {
        
          		// your body implementation on success
        
          	}
        
          );
        
          // register the strategy with passport
        
          passport.use(strategy);

view raw strategy.js hosted with ❤ by GitHub

Configurations

WSO2 Identity Server

Create a new Service Provider in the WSO2 Identity Server to register our express application as one. Follow the given step by step guide to create new Service Provider and to register our express application enabling SAML SSO.

Navigate to Main (Tab) -> Identity (Section) -> Service Providers (Sub-section) and select Add. The management console will display you the following screen to add a new service provider.

Provide …

Service Provider Name: SampleExpressApp
Description: Any valid description of the service provider

And click Register to register and create a new service provider. Afterward, the management console will display you the following screen to configure claim configuration, inbound authentication configurations and etc.

Expand the Claim Configurations (accordion) to configure wanted claims and subject claim URI. We will be using the Local Claim Dialect as the Claim mapping Dialect.

You can add all your wanted (requested claims) by clicking on the Add Claim URI button and selecting one from the drop-down menu

For the demo, we will be selecting the following claims

http://wso2.org/claims/emailaddress
http://wso2.org/claims/username
http://wso2.org/claims/role

And choose http://wso2.org/claims/emailaddress as the Subject Claim URI.

Next, expand the Inbound Authentication Configuration (accordion) and click on SAML2 Web SSO Configuration and select Configure to configure SAML web SSO for our implemented express application.

Configure the SAML SSO as follows …

Issuer: SampleExpressApp
Assertion Consumer URLs: http://localhost:3000/saml/consume
Enable Response Signing: True
Enable Signature Validation in Authentication Requests and Logout Requests: False

To enable signature validate in both authentication requests and logout requests, please refer the Certificates and Signing section.

Enable Single Logout: True
SLO Response URL: http://localhost:3000/app/home
SLO Request URL: http://localhost:3000/app/home
Enable Attribute Profile: True
Include Attributes in the Response Always: True

And select Register to register your SAML SSO configurations and the management console will prompt you to the previous configuration screen. Leave other configurations as it is and click on Update.

Expand Local & Outbound Authentication Configuration and select Default as the Authentication Type and enable Use user store domain in roles configuration.

Express Application

After implementing the express application, create a .env file in the root path and enter the following properties.

Change the SAML_ENTRYPOINT and SAML_LOGOUTURL properties if the IP-address and ports are different from default configurations

SESSION_SECRET="a well secured secret"
SAML_ENTRYPOINT="https://localhost:9443/samlsso"
SAML_ISSUER="SampleExpressApp"
SAML_PROTOCOL="http://"
SAML_LOGOUTURL="https://localhost:9443/samlsso"
WSO2_ROLE_CLAIM="http://wso2.org/claims/role"
WSO2_EMAIL_CLAIM="http://wso2.org/claims/emailaddress"

Certificates and Signing

To validate both authentication request and logout requests, we need to add relevant application certificates and private keys in both Identity Server and in our express application.

For this demo, we will be using the default wso2carbon key-store to generate application certificates and private keys. The wso2carbon key-store can be found inside <IS_HOME>/repository/resources/security directory

To export the certificate from the key-store, execute the following command from the security folder

keytool -export -keystore wso2carbon.jks -alias wso2carbon -file wso2carbon.crt

The above-generated certificate will be in binary format. Use the following command to convert the above binary encoded certificate to PEM encoded certificate

openssl x509 -inform der -in wso2carbon.crt -out wso2carbon.pem

Copy the generated wso2carbon.pem file to another easily accessible folder

Configure: WSO2 Identity Server

Open the Identity Server and navigate to Main (Tab) -> Identity (Section) -> Service Providers (Sub-section) -> select List and Edit (our service provider).

In the Basic Information panel, select the Choose File button which is associated with the Application Certificate field. Choose the above-created wso2carbon.pem file and open.

Next, expand the Inbound Authentication Configuration (accordion) and click on SAML2 Web SSO Configuration and select Edit to update our SAML web SSO configurations. Enable signature validation in authentication requests and logout requests.

Click Update and Update again to update the service provider configurations.

Configure: Passport & Express App

Generate a private certificate for our express application. Execute the following commands to generate a private certificate from the default wso2carbon key-store.

Use wso2carbon as the password for any password-prompts.

keytool -importkeystore -srckeystore wso2carbon.jks -destkeystore wso2carbon.p12 -deststoretype PKCS12 -srcalias wso2carbon -deststorepass wso2carbon -destkeypass wso2carbon
-------------
openssl pkcs12 -in wso2carbon.p12  -nodes -nocerts -out private-key.pem

Create folder named security in the root path of our express application and place both the generated private-key.pem and wso2carbon.pem inside.

After placing the certificates, update the passport SAML strategy as follows

  
          var passport = require('passport');
        
          var saml = require('passport-saml').Strategy;
        
          // saml strategy for passport
        
          var strategy = new saml(
        
          	{
        
          		entryPoint: <provide SAML entry point url : https://localhost:9443/samlsso>,
        
          		issuer: <provide SAML issuer name : SampleExpressApp>,
        
          		protocol: <provide the protocol used : http://>,
        
          		logoutUrl: <provide the logout url : https://localhost:9443/samlsso>,
        
              		privateCert: fs.readFileSync('./security/private-key.pem', 'utf-8'),
        
          		cert: fs.readFileSync('./security/wso2carbon.pem', 'utf8')
        
          	},
        
          	(profile, done) => {
        
          		// your body implementation on success
        
          	}
        
          );
        
          // register the strategy with passport
        
          passport.use(strategy);

view raw strategy.js hosted with ❤ by GitHub

Run & Test

Run

Run the express application by executing the given command from the root folder

npm start

Also, start your WSO2 Identity Server instance using the following command from your <IS_HOME>/bin directory

sh wso2server.sh

Test

Open your favorite browser and navigate to http://localhost:3000/app. The browser will redirect to the WSO2 Identity Server’s sign-in page to enter the login credentials.

For this demo, you can use admin as both the username and password to sign in with the WSO2 Identity Server

After presenting the login credentials, the Identity Server will prompt a user consent page to either approve or deny requested claims. Choose Select All and Approve.

After successful authentication, the browser will redirect and displays you the logged-in page of our express application.

Navigate to http://localhost:3000/app/logout to log-out from the SAML SSO session.

GitHub

Custom Class Mediators to Convert Payloads

Wed, 17 Jul 2019 00:00:00 GMT

Intro

Class mediators provide an extended platform to develop user-specific implementations and custom mediation logic in the form of Java classes. In this sheet, we will be developing a custom class mediator to read, manipulate and convert (change) a simple payload to meet our requirements.

Class mediators are designed to use on user-specific custom implementations when there are no other built-in mediators to solve the requirement

Requirement

The requirement is to develop a simple custom class mediator to read and change the value of the name attribute of a given payload from “medium” to “Athiththan”.

The actual payload and the expected converted (changed) payload formats are given below.

-------------------------------------
// request payload || original
{
    "post": "WSO2 Class Mediator: Convert Payload",
    "dev": {
        "name": "medium"
    }
}
-------------------------------------
// mediated payload || tconverted
{
    "post": "WSO2 Class Mediator: Convert Payload",
    "dev" : {
        "name": "Athiththan"
    }
}
-------------------------------------

Configure

To fabricate our custom class mediator or to generate a maven project, we can follow either

using the given pom.xml file to generate a maven project
using a custom-developed maven-archetype to generate a maven project

Following sections presents the steps on using given pom.xml and using custom developed-archetype to generate maven projects for our custom implementation.

pom.xml

Create a maven quick-start project and replace the dependencies with the following

<!-- change the packaging to bundle (from jar) to support OSGi -->
<packaging>jar</packaging>
<dependencies>
    <!-- apache synapse and related dependencies -->
    <dependency>
        <groupId>org.apache.synapse</groupId>
        <artifactId>synapse-core</artifactId>
        <version>2.1.7-wso2v60</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2.wso2</groupId
        <artifactId>axis2</artifactId
        <version>1.6.1.wso2v20</version>
    </dependency>
    <dependency>
        <groupId>commons-logging</groupId>
        <artifactId>commons-logging</artifactId
        <version>1.1.1</version>
    </dependency>
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.11</version>
        <scope>test</scope>
    </dependency>
</dependencies>
<repositories>
    <repository>
        <id>wso2-nexus</id
        <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </repository>
</repositories>
<pluginRepositories>
    <pluginRepository>
        <id>wso2-nexus</id
        <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        <releases>
            <enabled>true</enabled
            <updatePolicy>daily</updatePolicy
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </pluginRepository>
</pluginRepositories>
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId
            <artifactId>maven-compiler-plugin</artifactId
            <version>2.0</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
        </plugin>
        <!-- build plugin for OSGi Bundle support -->
        <plugin>
            <groupId>org.apache.felix</groupId>
            <artifactId>maven-bundle-plugin</artifactId
            <version>2.3.4</version>
            <extensions>true</extensions>
            <configuration>
                <instructions>
                    <Bundle-SymbolicName>
                        ${groupId}
                    </Bundle-SymbolicName>
                    <Bundle-Name>${groupId}</Bundle-Name
                    <Export-Package>
                        ${groupId}.*,
                    </Export-Package>
                    <Import-Package>
                        *; resolution:=optional
                    </Import-Package>
                </instructions>
            </configuration>
        </plugin>
    </plugins>
</build>

Build using Maven Archetype

Clone or download the custom-developed maven-archetype and run the following command to build and install the archetype locally on your machine to generate boilerplates for our custom class mediators.

mvn clean install

Then, execute the following command to generate a Maven project (boilerplate)

Change the command according to your required Group ID and Artifact ID arguments

mvn archetype:generate  -DarchetypeGroupId=com.athiththan.wso2     \
                        -DarchetypeArtifactId=wso2-mediators       \
                        -DarchetypeVersion=1.0.0                   \
                        -DgroupId=<Your Group ID>                  \
                        -DartifactId=<Your Artifact ID>

Development

Class Mediator

We can develop a custom Class mediator by implementing the Mediator class or by extending the AbstractMediator class. In this sheet, We will discuss developing a custom class mediator by extending the org.apache.synapse.mediators.AbstractMediator class.

The custom mediation logic has to defined inside the mediate() method to get execute

A simple class mediator implementation to convert the name attribute from medium to Athiththan is presented below.

  
          package <your package namespace>;
        
          import org.apache.synapse.MessageContext;
        
          import org.apache.synapse.commons.json.JsonUtil;
        
          import org.apache.synapse.core.axis2.Axis2MessageContext;
        
          import org.apache.synapse.mediators.AbstractMediator;
        
          import org.json.JSONObject;
        
          public class CustomMediator extends AbstractMediator {
        
              @Override
        
              public boolean mediate(MessageContext synCtx) {
        
                  org.apache.axis2.context.MessageContext axis2MessageContext = ((Axis2MessageContext) synCtx)
        
                          .getAxis2MessageContext();
        
                  try {
        
                      JSONObject jsonObject = new JSONObject(JsonUtil.jsonPayloadToString(axis2MessageContext));
        
                      if (jsonObject.has("dev") && jsonObject.getJSONObject("dev").has("name")
        
                              && "medium".equals((String) jsonObject.getJSONObject("dev").get("name"))) {
        
                          jsonObject.getJSONObject("dev").put("name", "Athiththan");
        
                      }
        
                      JsonUtil.newJsonPayload(axis2MessageContext, jsonObject.toString(), true, true);
        
                  } catch (JSONException e) {
        
                      e.printStackTrace();
        
                  }
        
                  return true;
        
              }
        
          }

view raw CustomMediator.java hosted with ❤ by GitHub

Build, Run & Test

Build

Execute the following command from our project root folder to build and package our custom mediator implementation.

mvn clean package

As a result, maven will package our implementation as a JAR (Java Archive) artifact, which can be found inside the /target folder.

Run & Test

For demonstration purposes

I will be mocking and using the Token_Endpoint of WSO2 API Manager (2.6.0) and will be referring to the installation path of WSO2 API-M as <API-M_HOME> and our JAR artifact as CM-IMPL-JAR.

Copy the CM-IMPL_JAR from the /target folder and paste it inside the <API-M_HOME>/repository/components/lib/ directory
Navigate to <API-M_HOME>/repository/deployment/server/synapse-configs/default/api/ and open and edit the inSequence tag of the _TokenAPI_.xml file as follows

<inSequence>
    <!-- <property name="uri.var.portnum" expression="get-property('keyManager.port')"/>
    <property name="uri.var.hostname" expression="get-property('keyManager.hostname')"/>
    <send>
        <endpoint>
            <http uri-template="https://{uri.var.hostname}:{uri.var.portnum}/oauth2/token">
                <timeout>
                    <duration>60000</duration
                    <responseAction>fault</responseAction>
                </timeout>
            </http>
        </endpoint>
    </send> -->
    <!-- convert dev.name to athiththan -->
    <class name="<YOUR PACKAGE NAME>.<CLASS NAME>" />
    <respond />
</inSequence>

Replace <YOUR PACKAGE NAME>.<CLASS NAME> with the actual package name and your Java class name.

For example …

If you have implemented your class mediator implementation in a Java class named CustomClassMediator inside the com.sample.demos package, then it comes as com.sample.demos.CustomClassMediator resulting <class name="com.sample.demos.CustomClassMediator" />.

After pasting our CM-IMPL_JAR and editing the _TokenAPI_.xml file, start the WSO2 API Manager instance using the following command.

sh wso2server.sh

Use the following cURL command to execute the Token Endpoint of the WSO2 API Manager instance by replacing the <Your Host> tag with respective host value

curl -k --request POST \
    -d '{"post":"WSO2 Class Mediator: Convert Payload","dev":{"name":"medium"}}' \
    -H "Content-Type: application/json" \
    https://<YOUR HOST>:8243/token

After successful execution, we can observe the response as follows

{
    "post":"WSO2 Class Mediator: Convert Payload",
    "dev":{
        "name":"Athiththan"
    }
}

GitHub

Custom Event Handlers for Password Validation

Sat, 15 Jun 2019 00:00:00 GMT

A Story Guide

Stackcheats is a cheat-blog platform where developers and technical writers can create & write tech-cheats by owning user accounts. More importantly, Stackcheats has been using the WSO2 Identity Server as its identity and access management tool to manage user registrations and management tasks.

A tech-developer named “Athiththan” have been requested to develop a custom component to validate the password against a list of defective passwords when users trying to update (renew).

Development

WSO2 Identity Server (5.3.0 ≤ onwards) now supports to handle published events using an integrated event framework by extending `AbstractEventHandler`

So, Athiththan chose to develop the custom component as an event-handler listening to different password-update events to trigger and to validate the given password. We can use the following custom maven archetype to generate boilerplate to extend and implement custom event-handlers for WSO2 Identity Server.

Handle Event

The AbstractEventHandler contains a method named handleEvent() which gets triggered whenever a pre-registered event is made upon the Identity Server. So, for this custom implementation, he will be using the following two publish events …

```
PRE_UPDATE_CREDENTIAL
```
```
PRE_UPDATE_CREDENTIAL_BY_ADMIN
```

  
          @Override
        
          public void handleEvent(Event event) throws IdentityEventException {
        
              if (log.isDebugEnabled()) {
        
                  log.debug("handleEvent() invoked");
        
              }
        
              if (IdentityEventConstants.Event.PRE_UPDATE_CREDENTIAL.equals(event.getEventName())
        
                      || IdentityEventConstants.Event.PRE_UPDATE_CREDENTIAL_BY_ADMIN.equals(event.getEventName())) {
        
                  Object credential = event.getEventProperties().get(IdentityEventConstants.EventProperty.CREDENTIAL);
        
                  if (!DefaultDefectivePasswordValidator.getInstance().validate(credential)) {
        
                      if (log.isDebugEnabled()) {
        
                          log.debug("given password is defective");
        
                      }
        
                      throw Utils.handleEventException(
        
                              DefectivePasswordValidatorConstants.ErrorMessages.ERROR_CODE_CRACKED_PASSWORD_VALIDATION, null);
        
                  }
        
              }
        
          }

view raw DefectivePasswordValidatorEventHandler.java hosted with ❤ by GitHub

Password Validator

Given below is the implementation to validate the given password against a list of defective passwords. The given implementation reads all the defective passwords from a text file named passwords.txt which is placed inside the /<IS_HOME>/deployments/server/defective folder.

For testing purposes, the given implementation can be modified to work with pre-defined list of defective passwords using ArrayList.

  
          public class DefaultDefectivePasswordValidator implements DefectivePasswordValidator {
        
              private static List<String> crackedPasswords = new ArrayList<>();
        
              private static DefaultDefectivePasswordValidator dPasswordValidator = new DefaultDefectivePasswordValidator();
        
              private static final Logger log = LoggerFactory.getLogger(DefaultDefectivePasswordValidator.class);
        
              private DefaultDefectivePasswordValidator() {
        
              }
        
              public static DefaultDefectivePasswordValidator getInstance() {
        
                  return dPasswordValidator;
        
              }
        
              /**
        
               * initialize defective password values from the given text file
        
               */
        
              @Override
        
              public void initValues() {
        
                  crackedPasswords = new ArrayList<>();
        
                  try {
        
                      crackedPasswords = Files.readAllLines(Paths.get(DefectivePasswordValidatorConstants.PASSWORD_FILE_PATH),
        
                              StandardCharsets.UTF_8);
        
                  } catch (IOException e) {
        
                      log.error("Exception occured while reading and initializing values from "
        
                              + DefectivePasswordValidatorConstants.PASSWORD_FILE_NAME, e);
        
                  }
        
              }
        
              /**
        
               * validate method
        
               */
        
              @Override
        
              public boolean validate(Object credential) {
        
                  return !crackedPasswords.contains((String) credential);
        
              }
        
          }

view raw DefaultDefectivePasswordValidator.java hosted with ❤ by GitHub

OSGi Component

The custom event-handler has to be registered as a service component (OSGi) with the Identity Server components to work flawlessly. In order to register the custom implementation as a service component, he wrote a ServiceComponent class containing both activate and deactivate methods to register it with the Bundle Context.

  
          @Activate
        
          protected void activate(ComponentContext context) {
        
              try {
        
                  context.getBundleContext().registerService(AbstractEventHandler.class.getName(),
        
                          new DefectivePasswordValidatorEventHandler(), null);
        
                  // initialize all defective passwords from the text file
        
                  DefaultDefectivePasswordValidator.getInstance().initValues();
        
                  // initialize watchservice on /defective directory
        
                  initializeWatchService();
        
              } catch (Throwable e) {
        
                  log.error("Error occured while initializing service component", e);
        
              }
        
          }
        
          @Deactivate
        
          protected void deactivate(ComponentContext context) { }

view raw DefectivePasswordValidatorServiceComponent.java hosted with ❤ by GitHub

Prepare

Defective Passwords Text File

Create a file called passwords.txt and add all defective-passwords (cracked passwords) at each line. These defined cracked passwords are the values, will be used to validate the entered password.

Create a folder named defective inside the <IS_HOME>/repository/deployment/server directory and place the above created passwords.txt file in it.

WSO2 Identity Server

Navigate to <IS_HOME>/repository/conf/identity directory and open the identity-event.properties file and add the following lines at the bottom to subscribe to the published events.

Please update the digit value according to your identity-event.properties file (last used value + 1)
The given module.name value is the same value which configured in the getName() method in DefectivePasswordValidatorEventHandler class

  
          module.name.13=defectivePasswordValidator
        
          defectivePasswordValidator.subscription.1=PRE_UPDATE_CREDENTIAL
        
          defectivePasswordValidator.subscription.2=PRE_UPDATE_CREDENTIAL_BY_ADMIN

view raw identity-event.properties hosted with ❤ by GitHub

Build, Run & Test

Build

You can clone or download the custom event-handler implementation project done by Athiththan from GitHub and build it using the following command …

mvn clean package

Run

After a successful build, copy the defective-password-validator-1.0.0.jar artifact and place it inside the <IS_HOME>/repository/components/dropins folder.

Start your WSO2 Identity Server by navigating to the <IS_HOME>/bin folder and executing the following command …

sh wso2server.sh

Test

After server startup, navigate to https://<ipaddress>:9443/dashboard and log in using admin as both username and password. Click on the “View Details” button on the “Change Password” section and type your current password and enter the new password as one of the defective passwords and try on.

	<?xml version="1.0" encoding="UTF-8"?>
	<sequence name="oauth2-sequence" xmlns="http://ws.apache.org/ns/synapse">
	<!-- token generation to the oauth server's token endpoint -->
	<!-- add the base64 encoded credentials -->
	<property name="client-authorization-header" scope="default" type="STRING" value="MDZsZ3BTMnh0enRhOXBsaXZGUzliMnk4aEZFYTpmdE4yWTdLcnE2SWRsenBmZ1RuTVU1bkxjUFFh" />
	<property name="request-body" expression="json-eval($)" scope="default" type="STRING" />
	<property name="resource" expression="get-property('axis2', 'REST_URL_POSTFIX')" scope="default" type="STRING" />

	<!-- creating a request payload for client_credentials -->
	<payloadFactory media-type="xml">
	<format>
	<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Body>
	<root xmlns="">
	<grant_type>client_credentials</grant_type>
	</root>
	</soapenv:Body>
	</soapenv:Envelope>
	</format>
	<args></args>
	</payloadFactory>

	<!-- set related headers to call the token endpoint -->
	<header name="Authorization" expression="fn:concat('Basic ', get-property('client-authorization-header'))" scope="transport" />
	<header name="Content-Type" value="application/x-www-form-urlencoded" scope="transport" />
	<property name="messageType" value="application/x-www-form-urlencoded" scope="axis2" type="STRING" />
	<property name="REST_URL_POSTFIX" value="" scope="axis2" type="STRING" />

	<!-- change the token endpoint -->
	<call blocking="true">
	<endpoint>
	<http method="POST" uri-template="https://localhost:9443/oauth2/token" />
	</endpoint>
	</call>

	<!-- append the acquired access token and make the call to the backend service -->
	<property name="bearer-token" expression="json-eval($.access_token)" scope="default" type="STRING" />
	<property name="REST_URL_POSTFIX" expression="get-property('resource')" scope="axis2" type="STRING" />
	<header name="Authorization" expression="fn:concat('Bearer ', get-property('bearer-token'))" scope="transport" />
	<payloadFactory media-type="json">
	<format>$1</format>
	<args>
	<arg evaluator="xml" expression="get-property('request-body')" />
	</args>
	</payloadFactory>
	</sequence>

	<?xml version="1.0" encoding="UTF-8"?>
	<sequence name="oauth2-enhanced-sequence" xmlns="http://ws.apache.org/ns/synapse">
	<!-- retreiving the access token and the generated time if exists in the registry location -->
	<property name="stored-token" expression="get-property('registry', 'gov:/oauth_endpoint/access_token')" scope="default" type="STRING" />
	<property name="generated-time" expression="get-property('registry', 'gov:/oauth_endpoint/generated_time')" scope="default" type="LONG" />

	<!-- token generation to the oauth server's token endpoint -->
	<!-- add the base64 encoded credentials -->
	<property name="client-authorization-header" scope="default" type="STRING" value="MDZsZ3BTMnh0enRhOXBsaXZGUzliMnk4aEZFYTpmdE4yWTdLcnE2SWRsenBmZ1RuTVU1bkxjUFFh" />
	<property name="request-body" expression="json-eval($)" scope="default" type="STRING" />
	<property name="resource" expression="get-property('axis2', 'REST_URL_POSTFIX')" scope="default" type="STRING" />

	<!-- enhanced to perform subtract function -->
	<property name="CURRENT_SYSTEM_TIME" expression="get-property('SYSTEM_TIME')" type="STRING" />
	<property name="token_generated_time" expression="get-property('generated-time')" type="STRING" />

	<!-- filter and based on the validity condition make the token call -->
	<filter xpath="get-property('CURRENT_SYSTEM_TIME') - get-property('token_generated_time') > 3600000 or get-property('stored-token') = ''">
	<then>
	<!-- creating a request payload for client_credentials -->
	<payloadFactory media-type="xml">
	<format>
	<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Body>
	<root xmlns="">
	<grant_type>client_credentials</grant_type>
	</root>
	</soapenv:Body>
	</soapenv:Envelope>
	</format>
	<args></args>
	</payloadFactory>

	<!-- set related headers to call the token endpoint -->
	<header name="Authorization" expression="fn:concat('Basic ', get-property('client-authorization-header'))" scope="transport" />
	<header name="Content-Type" value="application/x-www-form-urlencoded" scope="transport" />
	<property name="messageType" value="application/x-www-form-urlencoded" scope="axis2" type="STRING" />
	<property name="REST_URL_POSTFIX" value="" scope="axis2" type="STRING" />

	<!-- change the token endpoint -->
	<call blocking="true">
	<endpoint>
	<http method="POST" uri-template="https://localhost:9443/oauth2/token" />
	</endpoint>
	</call>

	<!-- extract the access token from the response -->
	<property name="bearer-token" expression="json-eval($.access_token)" scope="default" type="STRING" />

	<!-- store the generated token and the time -->
	<property name="gov:/oauth_endpoint/access_token" expression="get-property('bearer-token')" scope="registry" type="STRING" />
	<property name="gov:/oauth_endpoint/generated_time" expression="get-property('SYSTEM_TIME')" scope="registry" type="LONG" />

	<!-- append the acquired access token and make the call to the backend service -->
	<property name="REST_URL_POSTFIX" expression="get-property('resource')" scope="axis2" type="STRING" />
	<header name="Authorization" expression="fn:concat('Bearer ', get-property('bearer-token'))" scope="transport" />

	<payloadFactory media-type="json">
	<format>$1</format>
	<args>
	<arg evaluator="xml" expression="get-property('request-body')" />
	</args>
	</payloadFactory>
	</then>
	<else>
	<!-- the stored access token is still active, so we will be using that to invoke the endpoint -->
	<header expression="fn:concat('Bearer ', get-property('stored-token'))" name="Authorization" scope="transport" />
	</else>
	</filter>
	</sequence>

	package com.sample.token;

	import org.apache.oltu.oauth2.common.exception.OAuthSystemException;
	import org.wso2.carbon.apimgt.api.APIManagementException;
	import org.wso2.carbon.apimgt.api.model.Application;
	import org.wso2.carbon.apimgt.impl.APIConstants;
	import org.wso2.carbon.apimgt.impl.utils.APIUtil;
	import org.wso2.carbon.apimgt.keymgt.issuers.APIMTokenIssuer;
	import org.wso2.carbon.identity.oauth2.token.OAuthTokenReqMessageContext;
	import org.wso2.carbon.identity.oauth2.model.RequestParameter;

	import org.apache.commons.logging.Log;
	import org.apache.commons.logging.LogFactory;

	public class MyAPIMTokenIssuer extends APIMTokenIssuer {

	private static final Log log = LogFactory.getLog(MyAPIMTokenIssuer.class);

	@Override
	public String accessToken(OAuthTokenReqMessageContext tokReqMsgCtx) throws OAuthSystemException {

	// generate access token using super method
	String accessToken = super.accessToken(tokReqMsgCtx);

	String clientId = tokReqMsgCtx.getOauth2AccessTokenReqDTO().getClientId();
	Application application;
	try {
	application = APIUtil.getApplicationByClientId(clientId);
	String tokenType = application.getTokenType();

	// only acceptable for opaque access tokens and not JWT tokens
	if (!APIConstants.JWT.equals(tokenType)) {

	// retrieve all request parameters sent to the token request
	RequestParameter[] reqParams = tokReqMsgCtx.getOauth2AccessTokenReqDTO().getRequestParameters();
	for (int i = 0; i < reqParams.length; i++) {

	// check for devhash parameter from the request parameters and append it to the
	// access token
	if ("devhash".equals(reqParams[i].getKey())) {
	accessToken += reqParams[i].getValue()[0];
	break;
	}
	}
	}
	} catch (APIManagementException e) {
	log.error("Exception occured in my piece of code ", e);
	}

	return accessToken;
	}
	}

	<?xml version="1.0" encoding="UTF-8"?>

	<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<groupId>com.sample.token</groupId>
	<artifactId>custom-token-issuer</artifactId>
	<version>1.0.0</version>

	<!-- change the packaging to bundle (from jar) to support OSGi -->
	<packaging>jar</packaging>

	<properties>
	<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
	<maven.compiler.source>1.8</maven.compiler.source>
	<maven.compiler.target>1.8</maven.compiler.target>
	</properties>

	<dependencies>
	<dependency>
	<groupId>org.wso2.carbon.apimgt</groupId>
	<artifactId>org.wso2.carbon.apimgt.keymgt</artifactId>
	<version>6.5.222</version>
	</dependency>
	</dependencies>

	<repositories>
	<repository>
	<id>wso2-nexus</id>
	<url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
	<releases>
	<enabled>true</enabled>
	<updatePolicy>daily</updatePolicy>
	<checksumPolicy>ignore</checksumPolicy>
	</releases>
	</repository>
	</repositories>

	<pluginRepositories>
	<pluginRepository>
	<id>wso2-nexus</id>
	<url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
	<releases>
	<enabled>true</enabled>
	<updatePolicy>daily</updatePolicy>
	<checksumPolicy>ignore</checksumPolicy>
	</releases>
	</pluginRepository>
	</pluginRepositories>

	<build>
	<plugins>

	<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-compiler-plugin</artifactId>
	<version>2.0</version>
	<configuration>
	<source>1.8</source>
	<target>1.8</target>
	</configuration>
	</plugin>

	<!-- build plugin for OSGi Bundle support -->
	<plugin>
	<groupId>org.apache.felix</groupId>
	<artifactId>maven-bundle-plugin</artifactId>
	<version>2.3.4</version>
	<extensions>true</extensions>
	<configuration>
	<instructions>
	<Bundle-SymbolicName>com.sample.token</Bundle-SymbolicName>
	<Bundle-Name>com.sample.token</Bundle-Name>
	<Export-Package>
	com.sample.token.*,
	</Export-Package>
	<Import-Package>
	*; resolution:=optional
	</Import-Package>
	</instructions>
	</configuration>
	</plugin>

	</plugins>
	</build>
	</project>

	@hostname = https://localhost:8243/dev-management
	@username = athiththan11

	### Get Developer
	# @name getDeveloper
	curl -k -X GET {{hostname}}/devs/{{username}} \
	-H "Content-Type: application/json"

	### Get Repos of a Developer
	# @name getRepos
	curl -k -X GET {{hostname}}/devs/{{username}}/repos \
	-H "Content-Type: application/json"

	### Delete a Developer
	# @name deleteDeveloper
	curl -k -X DELETE {{hostname}}/devs/{{username}} \
	-H "Content-Type: application/json"

	### Create a Developer
	# @name addDeveloper
	curl -k -X POST {{hostname}}/devs \
	-d '{ "username": "athiththan11", "name": "Athiththan", "email": "athiththan11@test.com" }' \
	-H "Content-Type: application/json"

	### Create a Repo
	# @name addRepo
	curl -k -X POST {{hostname}}/repos \
	-d '{ "name": "repodews", "username": "athiththan11", "forks": 0 }' \
	-H "Content-Type: application/json"

	@consumer-key = <Replace with Consumer Key>
	@consumer-secret = <Replace with Consumer Secret>
	@api-hostname = https://10.100.5.220:8244/dev-management/v1.0.0

	# Username & Password
	@api-username = admin
	@api-password = admin

	@username = athiththan11

	### Token Endpoint
	# @name tokenEndpoint
	curl -k -d "grant_type=password&username={{api-username}}&password={{api-password}}&scope=default" \
	-H "Authorization: Basic <Replace with Base64Encode(ClientID:ClientSecret)>" \
	https://localhost:8244/token

	@access-token = {{tokenEndpoint.response.body.access_token}}
	@authorization = Bearer {{access-token}}

	### Get Developer
	# @name getDeveloperAPI
	curl -k -X GET {{api-hostname}}/devs/{{username}} \
	-H "accept: application/json" \
	-H "Authorization: {{authorization}}"

	### Get Repos of a Developer
	# @name getReposAPI
	curl -k -X GET {{api-hostname}}/devs/{{username}}/repos \
	-H "accept: application/json" \
	-H "Authorization: {{authorization}}"

	### Delete a Developer
	# @name deleteDeveloperAPI
	curl -k -X DELETE {{api-hostname}}/devs/{{username}} \
	-H "accept: application/json" \
	-H "Authorization: {{authorization}}"

	### Create a Developer
	# @name addDeveloperAPI
	curl -k -X POST {{api-hostname}}/devs \
	-d '{ "username": "athiththan11", "name": "Athiththan", "email": "athiththan11@test.com" }' \
	-H "Content-Type: application/json" \
	-H "accept: application/json" \
	-H "Authorization: {{authorization}}"

	### Create a Repo
	# @name addRepoAPI
	curl -k -X POST {{api-hostname}}/repos \
	-d '{ "name": "repodews", "username": "athiththan11", "forks": 0 }' \
	-H "Content-Type: application/json" \
	-H "accept: application/json" \
	-H "Authorization: {{authorization}}"

	{
	"name": "expresssaml",
	"version": "1.0.0",
	"description": "Express Application with SAML SSO",
	"main": "server.js",
	"scripts": {
	"test": "echo \"Error: no test specified\" && exit 1"
	},
	"author": "athiththan11",
	"homepage": "https://github.com/athiththan11/Passport-SAML-WSO2",
	"keywords": [
	"wso2-saml-sso",
	"passport-saml"
	],
	"license": "ISC",
	"dependencies": {
	"body-parser": "1.19.0",
	"dotenv": "8.0.0",
	"ejs": "2.6.2",
	"express": "4.17.1",
	"express-session": "1.16.2",
	"passport": "0.3.2",
	"passport-saml": "0.15.0"
	},
	"devDependencies": {}
	}

	require('dotenv').config();
	var path = require('path');
	var fs = require('fs');

	var express = require('express');
	var session = require('express-session');
	var passport = require('passport');
	var saml = require('passport-saml').Strategy;

	var bodyParser = require('body-parser');

	var userProfile;
	var app = express();

	app.set('views', path.join(__dirname, 'views'));
	app.set('view engine', 'ejs');

	app.use(express.static(path.join(__dirname, 'public')));

	app.use(bodyParser.urlencoded({ extended: true }));
	app.use(session({ secret: process.env.SESSION_SECRET }));

	app.use(passport.initialize());
	app.use(passport.session());

	passport.serializeUser((user, done) => {
	done(null, user);
	});

	passport.deserializeUser((user, done) => {
	done(null, user);
	});

	// saml strategy for passport
	var strategy = new saml(
	{
	entryPoint: process.env.SAML_ENTRYPOINT,
	issuer: process.env.SAML_ISSUER,
	protocol: process.env.SAML_PROTOCOL,
	logoutUrl: process.env.SAML_LOGOUTURL
	},
	(profile, done) => {
	userProfile = profile;
	done(null, userProfile);
	}
	);

	passport.use(strategy);

	var redirectToLogin = (req, res, next) => {
	if (!req.isAuthenticated() \|\| userProfile == null) {
	return res.redirect('/app/login');
	}
	next();
	};

	app.get('/app', redirectToLogin, (req, res) => {
	res.render('index', {
	title: 'Express Web Application',
	heading: 'Logged-In to Express Web Application'
	});
	});

	app.get(
	'/app/login',
	passport.authenticate('saml', {
	successRedirect: '/app',
	failureRedirect: '/app/login'
	})
	);

	app.get('/app/logout', (req, res) => {
	if (req.user == null) {
	return res.redirect('/app/home');
	}

	return strategy.logout(req, (err, uri) => {
	req.logout();

	userProfile = null;
	return res.redirect(uri);
	});
	});

	app.get('/app/failed', (req, res) => {
	res.status(401).send('Login failed');
	});

	app.post(
	'/saml/consume',
	passport.authenticate('saml', {
	failureRedirect: '/app/failed',
	failureFlash: true
	}),
	(req, res) => {

	// saml assertion extraction from saml response
	// var samlResponse = res.req.body.SAMLResponse;
	// var decoded = base64decode(samlResponse);
	// var assertion =
	// ('<saml2:Assertion' + decoded.split('<saml2:Assertion')[1]).split(
	// '</saml2:Assertion>'
	// )[0] + '</saml2:Assertion>';
	// var urlEncoded = base64url(assertion);

	// success redirection to /app
	return res.redirect('/app');
	}
	);

	app.post('/app/home', (req, res) => {
	res.render('home', {
	title: 'Express Web Application',
	heading: 'Express Web Application'
	});
	});

	app.listen(process.env.PORT \|\| 3000);

	package <your package namespace>;

	import org.apache.synapse.MessageContext;
	import org.apache.synapse.commons.json.JsonUtil;
	import org.apache.synapse.core.axis2.Axis2MessageContext;
	import org.apache.synapse.mediators.AbstractMediator;
	import org.json.JSONObject;

	public class CustomMediator extends AbstractMediator {

	@Override
	public boolean mediate(MessageContext synCtx) {

	org.apache.axis2.context.MessageContext axis2MessageContext = ((Axis2MessageContext) synCtx)
	.getAxis2MessageContext();

	try {
	JSONObject jsonObject = new JSONObject(JsonUtil.jsonPayloadToString(axis2MessageContext));
	if (jsonObject.has("dev") && jsonObject.getJSONObject("dev").has("name")
	&& "medium".equals((String) jsonObject.getJSONObject("dev").get("name"))) {
	jsonObject.getJSONObject("dev").put("name", "Athiththan");
	}

	JsonUtil.newJsonPayload(axis2MessageContext, jsonObject.toString(), true, true);

	} catch (JSONException e) {
	e.printStackTrace();
	}

	return true;
	}
	}

	@Override
	public void handleEvent(Event event) throws IdentityEventException {

	if (log.isDebugEnabled()) {
	log.debug("handleEvent() invoked");
	}

	if (IdentityEventConstants.Event.PRE_UPDATE_CREDENTIAL.equals(event.getEventName())
	\|\| IdentityEventConstants.Event.PRE_UPDATE_CREDENTIAL_BY_ADMIN.equals(event.getEventName())) {

	Object credential = event.getEventProperties().get(IdentityEventConstants.EventProperty.CREDENTIAL);
	if (!DefaultDefectivePasswordValidator.getInstance().validate(credential)) {

	if (log.isDebugEnabled()) {
	log.debug("given password is defective");
	}

	throw Utils.handleEventException(
	DefectivePasswordValidatorConstants.ErrorMessages.ERROR_CODE_CRACKED_PASSWORD_VALIDATION, null);
	}
	}
	}

	public class DefaultDefectivePasswordValidator implements DefectivePasswordValidator {

	private static List<String> crackedPasswords = new ArrayList<>();
	private static DefaultDefectivePasswordValidator dPasswordValidator = new DefaultDefectivePasswordValidator();

	private static final Logger log = LoggerFactory.getLogger(DefaultDefectivePasswordValidator.class);

	private DefaultDefectivePasswordValidator() {
	}

	public static DefaultDefectivePasswordValidator getInstance() {
	return dPasswordValidator;
	}

	/**
	* initialize defective password values from the given text file
	*/
	@Override
	public void initValues() {
	crackedPasswords = new ArrayList<>();
	try {
	crackedPasswords = Files.readAllLines(Paths.get(DefectivePasswordValidatorConstants.PASSWORD_FILE_PATH),
	StandardCharsets.UTF_8);
	} catch (IOException e) {
	log.error("Exception occured while reading and initializing values from "
	+ DefectivePasswordValidatorConstants.PASSWORD_FILE_NAME, e);
	}
	}

	/**
	* validate method
	*/
	@Override
	public boolean validate(Object credential) {
	return !crackedPasswords.contains((String) credential);
	}
	}

	@Activate
	protected void activate(ComponentContext context) {

	try {

	context.getBundleContext().registerService(AbstractEventHandler.class.getName(),
	new DefectivePasswordValidatorEventHandler(), null);

	// initialize all defective passwords from the text file
	DefaultDefectivePasswordValidator.getInstance().initValues();

	// initialize watchservice on /defective directory
	initializeWatchService();

	} catch (Throwable e) {
	log.error("Error occured while initializing service component", e);
	}
	}

	@Deactivate
	protected void deactivate(ComponentContext context) { }

	module.name.13=defectivePasswordValidator
	defectivePasswordValidator.subscription.1=PRE_UPDATE_CREDENTIAL
	defectivePasswordValidator.subscription.2=PRE_UPDATE_CREDENTIAL_BY_ADMIN