Customizing the Oracle Universal Authenticator Client Application Using REST APIs

Introduction

This tutorial demonstrates how to customize the Oracle Universal Authenticator client application using REST API’s and Postman.

Prerequisites

Before starting this tutorial you must have:

1. Read and understood Customizing the Oracle Universal Authenticator Client Application.
2. A running Oracle Advanced Authentication installation deployed with Oracle Universal Authenticator.
3. Installed Oracle Universal Authenticator client application on devices as per Installing the Oracle Universal Authenticator Client Application.
4. Familiarity with the REST architecture style.
5. Native Postman client application installed.
6. Downloaded the json files Oracle_Universal_Authenticator_REST_API.postman_collection.json, Oracle_Universal_Authenticator_Example_Environment.postman_environment.json.

Note: Administrators should be aware of the following when updating properties using REST APIs:

• Any property previously customized during installation as per Customizing During Installation, will be overwritten. If you wish to keep some of these customized properties, you must add them all again in a theme, using the REST API’s outlined in this tutorial.
• No themes exist by default. This is true even if you customized properties during installation as per Customizing During Installation.
• Themes must be created using REST API on a per locale basis as required.
• To activate themes, you must set oua.themes.custom.distribution to 1 as shown later in this tutorial.
• Once themes are activated, the device periodically contacts the OAA server for any updates, and will use the theme once notified. This overwrites any installations that were customized during installation.
• Any subsequent updates to the themes will be delivered to the device the next time the OUA client application contacts the OAA server.

Install the Oracle Advanced Authentication Postman Collection

Set the Environment Parameters in Postman

Note: The steps below may vary depending on your version of Postman.

1. Open Postman and in your Workspace select Environments.

   

2. Click Import.

3. In the Import dialog box, select or drop the Oracle_Universal_Authenticator_Example_Environment.postman_environment.json, and then click Open.

4. In the environment list displayed, to the right of Oracle Universal Authenticator Example Environment, click the ellipsis and then Duplicate.

   

5. On Oracle Universal Authenticator Example Environment Copy, which appears above the original environment, click the elipsis and rename to Oracle Universal Authenticator Environment for REST APIs.

6. Update the environment variables for the new environment by entering the following values for Initial Value and Current Value. Once complete click Save:

   • RELEASENAME: The RELEASENAME assigned to the Oracle Advanced Authentication setup, for example oaainstall.
   • DRSS_URL: The URL for the DRSS endpoint in Oracle Advanced Authentication, for example https://oaa.example.com/oaa-drss.
   • DRSS_USERNAME: The username for DRSS APIs in the format of RELEASENAME-oaa-drss, for example oaainstall-oaa-drss.
   • DRSS_PASSWORD: The drssapikey for the Oracle Advanced Authentication setup.

   Note: If you do not know the RELEASENAME, DRSS_URL, DRSS_USERNAME and DRSS_PASSWORD, see Printing Deployment Details.

   The environment will look similar to the following:

   

7. Click the Environment drop-down list, and then select the updated environment from the list:

   

Import the Postman Collection

1. To import the Oracle Advanced Authentication REST API Postman collection, select Collections > Import.

2. In the Import dialog box, select or drop the Oracle_Universal_Authenticator_REST_API.postman_collection.json.

   The collection should display as follows:

   

Test the Theme APIs

Create Language Themes

Note : To prevent SSL certificate verification errors, in the navigation hamburger menu navigate to File > Settings, and in the General tab turn off SSL certificate verification.

In this section you create language themes for the items you want to customize.

1. In the Collections tab, navigate to Oracle Universal Authenticator REST API > Themes Management APIs.

2. Select PUT updateLocale. This request makes a PUT request to the oaa-drss/v1/themes/<locale> endpoint, and creates a theme for the locale you require based on the information in the Body.

   Change or remove fields and values as appropriate.

   In this example a theme for en_US language is created, oaa-drss/v1/themes/en_US, and all customizable properties are updated.

   For the logo value, you must convert the bmp file to BASE64 using a utility of your choice, and paste the value into the logo entry.

   

3. Click Send.

4. In the response, confirm that the 204 No Content appears.

   

5. Create any more themes for the other languages you require. In this example a theme for the French fr language is created, oaa-drss/v1/themes/fr, and all customizable properties are updated.

   Note: All text that is customized must be in the language for the theme you are creating.

   

6. Click Send.

7. In the response, confirm that the 204 No Content appears.

   

8. Repeat the above for any other language themes you require, for example Spanish etc.

Get Language Themes

1. In the Collections tab, navigate to Oracle Universal Authenticator REST API > Themes Management APIs

2. Select GET getLocale. This request makes a GET request to the oaa-drss/v1/themes/locales endpoint, and returns all the themes created.

   

3. Click Send.

4. In the response, confirm that the Status: 200 OK appears. The list of themes is returned.

   

Get Customized Properties for a Theme

1. In the Collections tab, navigate to Oracle Universal Authenticator REST API > Themes Management APIs.

2. Select GET getLocale. This request makes a GET request to the oaa-drss/v1/themes/<locale> endpoint, and returns all the customized properties for a theme.

   

3. Click Send.

4. In the response, confirm that the Status: 200 OK appears. The list of properties customized is returned.

   Note: As well as the parameters you have customized, you will see defaults for parameters you haven’t customized, and other parameters that are not customizable.

   

Activate Themes

In order to start using the themes in the Oracle Universal Authenticator client application, you must set the oua.themes.custom.distribution property to “1”.

1. In the Collections tab, navigate to Oracle Universal Authenticator REST API > Themes Management APIs.

2. Select PUT oua.themes.custom.distribution. This request makes a PUT request to the oaa-drss/oua/property/v1 endpoint, by setting the oua.themes.custom.distribution property in the body. A value of 1 activates themes, and a value of 0 deactivates the themes. The default value is 0.

   

3. Click Send.

4. In the response, confirm that the Status: 200 OK appears and that the response contains oua.themes.custom.distribution set to 1.

   

Update a Theme

1. In the Collections tab, navigate to Oracle Universal Authenticator REST API > Themes Management APIs.

2. Select PUT updateLocale. This request makes a PUT request to the oaa-drss/v1/themes/<locale> endpoint, and creates or updates a theme for the locale you require based on the information in the Body.

   Update or remove fields and values as appropriate.

   Note: As well as the fields you want to update, you must include all fields that you previously customized. If you do not add the previously customized properties, they will be overwritten with the default values.

   In this example, CPFT_TILE_IMAGE is updated to Enter your Example Company Username".

   

3. Click Send.

4. In the response, confirm that the 204 No Content appears.

   

Delete a Theme

Deleting a theme removes the theme entirely. Administrators should be careful when deleting themes and be aware of the following:

• If you delete a theme the Oracle Universal Client Authenticator client application will continue to use the theme it was using before the theme was deleted.
• If you want to the Oracle Universal Client Authenticator client application to revert to the out of the box defaults then you can do one of the following:
  • Delete the theme and then create the theme again with a dummy value.
  • Don’t delete the theme, but instead update the theme with "status": 0.

1. In the Collections tab, navigate to Oracle Universal Authenticator REST API > Themes Management APIs.

2. Select DEL deleteLocale. This request makes a DELETE request to the oaa-drss/v1/themes/<locale> endpoint, and deletes the theme for the locale specified.

   In this example, the Spanish locale (es) is deleted.

   

3. Click Send.

4. In the response, confirm that the 204 No Content appears.

   

5. If you need to update the theme with a dummy value, use the PUT updateLocale to update the theme, and click Send. A 204 No Content message appears:

   

Learn More

• Oracle Universal Authenticator

Feedback

To provide feedback on this tutorial, please contact idm_user_assistance_ww_grp@oracle.com

Acknowledgements

• Author - Russ Hodgson

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.