Coding custom scripts and pages

#Overview

oxAuth is a Weld+JSF application. That means custom scripts and custom pages (JSF facelets) can make use of business logic already encapsulated in the (Weld) managed beans available.

#Objects available

Specifically, custom pages can use EL expressions to get/bind values or call methods of classes annotated with javax.inject.Named as long as they are part of the application's WAR file or external libraries added to the classpath. Thus, practically all @Named beans belonging to oxAuth or oxCore subprojects are potential candidates.

In addition to that, there are the usual implicit JSP/JSF objects plus the i18n labels map (msgs) used for localization purposes.

In the case of custom scripts, any class in oxAuth's classpath can be used as well as the standard Java 8 classes.

While there are hundreds of classes available for reuse, the following summarizes the most commonly used:

#Category: Authentication

#Class: AuthenticationService

Relevant methods:

#Class: Authenticator

Relevant methods:

See also: Person authentication

#Category: User Management

#Class: UserService

Relevant methods:

See also:

• User data object
• CustomAttribute data object

#Class: User

#Class: CustomAttribute

#Category: Session Management

#Class: Identity

Relevant methods:

#Category: Networking

#Class: HttpService

Relevant methods:

#Category: Cache

#Class: CacheService

Relevant methods:

See also: Cache Provider

#Category: JSF

#Class: FacesService

Relevant methods:

#Class: FacesMessages

Relevant methods:

See also: "Displaying error conditions to end-users"

#Category: Miscellaneous Utilities

#Class: CdiUtil

Relevant methods:

Example (jython code):

from org.gluu.oxauth.service import UserService
from org.gluu.oxauth.service import AuthenticationService
...
userService = CdiUtil.bean(UserService)
authenticationService = CdiUtil.bean(AuthenticationService)

#Class: StringHelper

Relevant methods:see "References" column.

#Class: EncryptionService

Relevant methods:

#Examples

#Displaying error conditions to end-users

When coding certain flows, it is important to be able to display errors in the xhtml templates based on conditions that occur as the associated custom script runs. For this purposes, the FacesMessage bean can be used. Here is an example that adds an error message in the UI:

from org.gluu.jsf2.message import FacesMessages
from org.gluu.service.cdi.util import CdiUtil
from javax.faces.application import FacesMessage
...

facesMessages = CdiUtil.bean(FacesMessages) 
facesMessages.setKeepMessages()
facesMessages.add(FacesMessage.SEVERITY_ERROR, "Please enter a valid username")

The error will appear in the associated template using the following markup:

...
<h:messages />
...

#Redirecting to a third-party application and back

For user authentication or consent gathering, there might be a need to redirect to a third party application to perform some operation and return the control back to authentication steps of the custom script. Please apply these steps to a person authentication script in such a scenario:

1. Return from def getPageForStep(self, step, context), a page /auth/method_name/redirect.html ; with content similar to the code snippet below -

    def getPageForStep(self, step, context):
        return "/auth/method_name/redirect.html"

Contents of redirect.xhtml should take the flow to prepareForStep method

...
	<f:metadata>
		<f:viewAction action="#{authenticator.prepareForStep}" if="#{not identity.loggedIn}" />
	</f:metadata>
	

1. In method prepareForStep prepare data needed for redirect and perform the redirection to the external service.

def prepareForStep(self, step, context):
        .....
	facesService = CdiUtil.bean(FacesService)
	facesService.redirectToExternalURL(third_party_URL )

	return True
	

1. In order to resume flow after the redirection, invoke a similar URL to https://my.gluu.server/postlogin.htm?param=123 from the third party app which takes the flow back to the authenticate method of the custom script.

So create an xhtml page postlogin.xhtml which will look like this :

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:f="http://xmlns.jcp.org/jsf/core">

<f:view transient="true" contentType="text/html">
	<f:metadata>
		<f:viewAction action="#{authenticator.authenticateWithOutcome}" />
	</f:metadata>
</f:view>

</html>

1. The <f:viewAction action="#{authenticator.authenticate}" /> in step 3 takes us to the def authenticate(self, configurationAttributes, requestParameters, step):. Here you can use parameters from request (param = ServerUtil.getFirstValue(requestParameters, "param-name")) , perform the state check and finally, return true or false from this method.

#Authenticating via an External IDP a New User Created Using a Custom Authentication Script in a Cloud Native Setup with Kubernetes

#General Overview

This section explains how to authenticate a new user that has been created with a custom authentication script in a cloud native setup of Gluu that uses LDAP as the backend persistence. For reference, click here for guidance on installing Gluu with Kubernetes

#Custom Authentication Script Overview

In the sample script, we assume that the user is to be authenticated via an external IDP. If the user doesn't exist in OpenDJ, the script automatically creates the user in the database before trying to authenticate them.

• For example consider the snippet below extracted from the script:

  find_user_by_uid = userService.addUser(user, True)
  found_user_name = find_user_by_uid.getUserId()
  user_authenticated = authenticationService.authenticate(found_user_name)

  Copy

#Cloud Native Setup Overview

LDAP is supported for backend persistence. Refer to the link shared in the general overview on how to achieve this with Kubernetes. A complete cloud native setup with replication enables having synchronized database instances for high availability. However for certain reasons for example limited computing resources, OpenDJ replication might get so slow leading to unsynchronized databases at any given time intervals.

For instance a find_user_by_uid.getUserId() function in our script can fail because an opendj database connection could be routed to a different pod for every request made. Therefore the newly created user is not replicated quickly enough to all opendj pods hence causing authentication to fail.

#Solution

To solve the issue above, a tested solution is to configure the services in a way that binds oxAuth service to the same opendj pod it got connected to when it created the user. This enables the client session to be reserved as long as the OpenDJ hasn't been restarted.

• In the OpenDJ service, set service.spec.sessionAffinity to ClientIP. By default the session held by the service is 3 hours and can be modified by setting service.spec.sessionAffinityConfig.clientIP.timeoutSeconds. For example to configure the sessionAffinity to the opendj service, refer to the snippet below.

  "sessionAffinity": "ClientIP",
  
  "sessionAffinityConfig": {
      "clientIP": {
          "timeoutSeconds": 28800
      }
  },

  Copy

#Troubleshooting

• Ensure the setup is correct and the pods are running.

      kubectl get pods -n gluu

  Copy

• Use the 'netstat' command to test if the opendj pods are connected

      kubectl exec -it -n gluu oxauth-xxxxxxxxxx-xxxx  -- sh 
  
      / # netstat -na |grep 1636

  Copy