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

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

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 `String`s
`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

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

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:

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>

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

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>
```
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>

```

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

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>
```
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
```

A reference for coding custom scripts and pages#

Overview#

Objects available#

Category: Authentication#

Class: AuthenticationService#

Class: Authenticator#

Category: User Management#

Class: UserService#

Class: User#

Class: CustomAttribute#

Category: Session Management#

Class: Identity#

Category: Networking#

Class: HttpService#

Category: Cache#

Class: CacheService#

Category: JSF#

Class: FacesService#

Class: FacesMessages#

Category: Miscellaneous Utilities#

Class: CdiUtil#

Class: StringHelper#

Class: EncryptionService#

Developer notes: Displaying error conditions to end-users#

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

Redirection in a Consent Gathering script. -#

Redirection in a Person Authentication script.#

Class: `AuthenticationService`#

Class: `Authenticator`#

Class: `UserService`#

Class: `User`#

Class: `CustomAttribute`#

Class: `Identity`#

Class: `HttpService`#

Class: `CacheService`#

Class: `FacesService`#

Class: `FacesMessages`#

Class: `CdiUtil`#

Class: `StringHelper`#

Class: `EncryptionService`#