Skip to content

A reference for 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.

Note

Find the javadocs here: oxAuth (choose the version matching your Gluu Server version).

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

Category: Authentication#

Class: AuthenticationService#

Description Managed bean Project Full name References
Allows to authenticate a user or obtain the current authenticated user Yes (Stateless) oxauth-server org.gluu.oxauth.service.AuthenticationService code

Relevant methods:

Signature Description
boolean authenticate(String userName) Performs authentication for the user whose identifier (userName) is passed as parameter
boolean authenticate(String userName, String password) Performs authentication for the user whose identifier (userName) is passed as parameter. The password supplied must be the correct password of the user in question
User getAuthenticatedUser() Returns a representation of the currently authenticated user. null if no user is currently authenticated. See User data object

Class: Authenticator#

Description Managed bean Project Full name References
This class is mainly used in facelets templates for authentication flows to proceed in the sequence of steps Yes (RequestScoped) oxauth-server org.gluu.oxauth.auth.Authenticator code

Relevant methods:

Signature Description
boolean authenticate() Makes the authentication flow proceed by calling the authenticate method of the custom script
String prepareAuthenticationForStep() Makes the authentication flow proceed by calling the prepareForStep method of the custom script

See also: Person authentication

Category: User Management#

Class: UserService#

Description Managed bean Project Full name References
Allows CRUD of users in the local database Yes (ApplicationScoped) oxauth-common org.gluu.oxauth.service.UserService code

Relevant methods:

Signature Description
User addUser(User user, boolean active) Creates a new user based on the representation passed as parameter. active parameter denotes whether user status (gluuStatus attribute) will be active or register
User addUserAttribute(String userId, String attributeName, String attributeValue) Adds an attribute to the user identified by userId in the database with the name and value passed. Returns a representation of the modified user or null in case of failure or if such name/attribute is already part of such user
boolean addUserAttribute(User user, String attributeName, String attributeValue) Adds an attribute to the user object with the name and value passed. This method only alters the user argument and does not persist changes. Returns false if such name/attribute is already part of user
User addUserAttributeByUserInum(String userInum, String attributeName, String attributeValue) Adds an attribute to the user whose inum attribute (in the database) equals to userInum using the name and value passed. Returns a representation of the modified user or null in case of failure or if such name/attribute is already part of such user
CustomAttribute getCustomAttribute(User user, String attributeName) Gets a representation of the attribute whose name is passed for the user in question (user). Returns null if no such attribute is populated
String getDnForUser(String inum) Obtains the DN (distinguished name) of the user whose inum attribute equals to userInum (no check that such user may exist is actually made)
User getUser(String userId, String... returnAttributes) Retrieves a user representation for the user identified with userId containing only the attributes requested (returnAttributes). null is returned if no such user exists
User getUserByAttribute(String attributeName, String attributeValue) Retrieves a user (first available) such that the attribute referenced (attributeName) has the value passed (attributeValue). null is returned if no such user exists
String getUserInum(String userId) Retrieves the inum database attribute for the user identified with userId.null is returned if no such user exists
User removeUserAttribute(String userId, String attributeName, String attributeValue) Removes attributeValue from the values of the attribute whose name is passed (attributeName) for the user identified with userId
User replaceUserAttribute(String userId, String attributeName, String oldAttributeValue, String newAttributeValue) Updates the user identified with userId by replacing the value of the attribute attributeName with the value passed. null is returned if no such user exists
void setCustomAttribute(User user, String attributeName, String attributeValue) Sets the value of the attribute attributeName with the single value attributeValue for the user representation passes as parameter. This method does not persist changes
User updateUser(User user) Updates the user represented by user object in the database

See also:

Class: User#

Description Managed bean Project Full name References
A class employed to represent a user entry in the database. Provides getters and setters to retrieve and assign value(s) for attributes No oxauth-common org.gluu.oxauth.model.common.User code

Class: CustomAttribute#

Description Managed bean Project Full name References
A class that models an attribute. An attribute has a name and a collection of associated values No oxcore-persistence-model org.gluu.persist.model.base.CustomAttribute code

Category: Session Management#

Class: Identity#

Description Managed bean Project Full name References
Mainly used to carry data between steps of authentication flows Yes (RequestScoped) oxauth-server org.gluu.oxauth.security.Identity code

Relevant methods:

Signature Description
Object getWorkingParameter(String name) Retrieves a working parameter by name previously set via setWorkingParameter
void setWorkingParameter(String name, Object value) Binds data to a name for further use in an authentication flow. Recommended values to store are Strings
SessionId getSessionId() Retrieves a reference to the associated server session object, see SessionId

Category: Networking#

Class: HttpService#

Description Managed bean Project Full name References
Provides utility methods to execute HTTP requests, manipulate responses, etc. Yes (ApplicationScoped) oxauth-server org.gluu.oxauth.service.net.HttpService code

Relevant methods:

Signature Description
HttpClient getHttpsClient() Returns an instance of org.apache.http.client.HttpClient (see oxcore-util class SslDefaultHttpClient)
HttpServiceResponse executeGet(HttpClient httpClient, String requestUri) Perform a GET on the URI requested. Returns an instance of org.gluu.oxauth.model.net.HttpServiceResponse (a wrapper on org.apache.http.HttpResponse)
byte[] getResponseContent(HttpResponse httpResponse) Consumes the bytes of the associated response. Returns null if the response status code is not 200 (OK)

Category: Cache#

Class: CacheService#

Description Managed bean Project Full name References
Provides a unified means to interact with the underlying cache provider configured in the Gluu Server Yes (ApplicationScoped) oxcore-service org.gluu.service.CacheService code

Relevant methods:

Signature Description
void clear() Flushes the whole cache
Object get(String key) Retrieves the value of key in the cache. null if there is no such key present
void put(int expirationInSeconds, String key, Object object) Puts an object in the cache associated to the key passed. An expiration in seconds can be provided
put(String key, Object object) Puts an object in the cache associated to the key passed. The expiration used is the default expiration configured in Gluu
void remove(String key) Removes an entry from the cache

See also: Cache Provider

Category: JSF#

Class: FacesService#

Description Managed bean Project Full name References
Provides utilities to properly build encoded URLs and make redirections. This class is often used in custom scripts Yes (RequestScoped) oxcore-jsf-util org.gluu.jsf2.service.FacesService code

Relevant methods:

Signature Description
void redirectToExternalURL(String url) Redirects the user's browser to the URL passed as parameter
String encodeParameters(String url, Map<String, Object> parameters) Builds a URL by appending query parameters as supplied in parameters map. Every value in the map is properly URL-encoded

Class: FacesMessages#

Description Managed bean Project Full name References
Allows manipulation of JSF context messages No oxcore-jsf-util org.gluu.jsf2.message.FacesMessages code

Relevant methods:

Signature Description
void add(Severity severity, String message) Adds a message to the JSF context with the severity (javax.faces.application.FacesMessage.Severity) specified
void clear() Clears the messages of the JSF context
String evalAsString(String expression) Evaluates an EL expression using the JSF context and returns the result as a String
void setKeepMessages() Sets the "keep messages" property of the JSF flash

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

Category: Miscellaneous Utilities#

Class: CdiUtil#

Description Managed bean Project Full name References
Allows to obtain references of managed beans. This is particularly useful in custom scripts No oxcore-service org.gluu.service.cdi.util.CdiUtil code

Relevant methods:

Signature Description
T bean(Class clazz) Gets the managed bean belonging to the class passed as parameter

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#

Description Managed bean Project Full name References
Provides many utility methods that often arise in the manipulation of Strings No oxcore-util org.gluu.util.StringHelper code

Relevant methods:see "References" column.

Class: EncryptionService#

Description Managed bean Project Full name References
Allows to encrypt/decrypt strings using a 3DES cipher whose salt is found in chroot at /etc/gluu/conf/salt Yes (ApplicationScoped) oxauth-server org.gluu.oxauth.service.EncryptionService code

Relevant methods:

Signature Description
String decrypt(String encryptedString) Decrypts the encrypted string supplied
Properties decryptAllProperties(Properties connectionProperties) Returns a java.util.Properties object with all decrypted values found in connectionProperties
String encrypt(String unencryptedString) Encrypts the string supplied

Developer notes: 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 purpose, 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 />
...

Developer notes: Redirecting to a third-party application in a custom script.#

In many cases of user authentication, consent gathering there might be a need to redirect to a third party application to perform some operation and redirect back to the Gluu server. This can be done inside prepareForStep method of the custom script.

Here is a sample script for consent gathering which has a redirection to a third party app.

Steps:

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

        def getPageForStep(self, step, context):
            return "/authz/method_name/redirect.html"
    
    ...
     <f:metadata>
         <f:viewAction action="#{consentGatherer.prepareForStep}" if="#{identity.loggedIn}"/>
     </f:metadata>
    
  2. In method prepareForStep, prepare data that is needed for the redirect and redirect to the external service.

    def prepareForStep(self, step, context):
        facesService = CdiUtil.bean(FacesService)
        facesService.redirectToExternalURL(self.third_party_URL )
    
        return True
    
  3. In order to resume flow after the redirection we can add postauthorize.html In this new page we need make a call:

     <f:metadata>
         <f:viewAction action="#{consentGatherer.authorize}" />
     </f:metadata>
    
  4. The action in step 3 takes us to the def authorize(self, step, context). Here you can use parameters from request, call external API to validate data if needed etc. And finally, return false/true from this method.

Redirection in a Person Authentication script.#

Here is a sample script for person which has a redirection to a third party app. Steps : 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"
```

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

```
  1. In method prepareForStep, prepare data that is needed for the redirection and redirect to the external service.

    def prepareForStep(self, step, context):
        facesService = CdiUtil.bean(FacesService)
            facesService.redirectToExternalURL(self.third_party_URL )
    
        return True
    
  2. In order to resume flow after the redirection we can use postlogin.xhtml (used to resume AuthN flow on call back). In this page a call is made to:

     <f:metadata>
         <f:viewAction action="#{authenticator.authenticate}" />
     </f:metadata>
    
  3. The action in step 3 takes us to the def authorize(self, step, context). Here you can use parameters from request, call external API to validate data if needed etc. And finally, return false/true from this method.

    def authorize(self, step, context): 
        param1 =  ServerUtil.getFirstValue(context.getRequestParameters(), "param1") 
        if (param1 == "true"):
            return True
        else:
            return False