Skip to content

Commit 2e2bfc7

Browse files
oheimburgeroheimburger
authored
Merge pull request #1060 from oracle-devrel/oig-eh-password-change
Add a Password Reset On User Role Change event handler for OIG
2 parents c327f46 + 8620dc0 commit 2e2bfc7

File tree

7 files changed

+358
-0
lines changed

7 files changed

+358
-0
lines changed

‎security/identity-and-access-management/oracle-identity-governance/event-handler-samples/password-reset-on-user-role-change/LICENSE

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
Copyright (c) 2024 Oracle and/or its affiliates.
2+
3+
The Universal Permissive License (UPL), Version 1.0
4+
5+
Subject to the condition set forth below, permission is hereby granted to any
6+
person obtaining a copy of this software, associated documentation and/or data
7+
(collectively the "Software"), free of charge and under any and all copyright
8+
rights in the Software, and any and all patent rights owned or freely
9+
licensable by each licensor hereunder covering either (i) the unmodified
10+
Software as contributed to or provided by such licensor, or (ii) the Larger
11+
Works (as defined below), to deal in both
12+
13+
(a) the Software, and
14+
(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
15+
one is included with the Software (each a "Larger Work" to which the Software
16+
is contributed by such licensors),
17+
18+
without restriction, including without limitation the rights to copy, create
19+
derivative works of, display, perform, and distribute the Software and make,
20+
use, sell, offer for sale, import, export, have made, and have sold the
21+
Software and the Larger Work(s), and to sublicense the foregoing rights on
22+
either these or other terms.
23+
24+
This license is subject to the following condition:
25+
The above copyright notice and either this complete permission notice or at
26+
a minimum a reference to the UPL must be included in all copies or
27+
substantial portions of the Software.
28+
29+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
30+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
31+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
32+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
33+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
34+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
35+
SOFTWARE.

‎security/identity-and-access-management/oracle-identity-governance/event-handler-samples/password-reset-on-user-role-change/README.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Password Reset On User Role Change Event Handler
2+
3+
This asset contains the code and deployment items for an event handler that automatically triggers a password reset flow for a user once a user's role attribute changes.
4+
5+
Note that by "user role" we are reffering to the user's role attribute (also known as "employee type") in this context, not to changes in a user's membership to any particular OIG role.
6+
7+
Developed on and compatible with OIG 11g R2 PS3 and above.
8+
9+
Review Date: 28.10.2024
10+
11+
# When to use this asset?
12+
13+
When there's a need to provide or demonstrate the functionality described above or something similar, which can be adapted from the provided code.
14+
15+
Note that password resets for lifecycle events involving other attribute value changes, such as for example a user's parent Organization, can be easily retrofitted based on the provided sample.
16+
17+
# How to use this asset?
18+
19+
## Building and deployment
20+
21+
Here's a short build and deployment checklist:
22+
23+
1. Generate a jar file containing the sample code.
24+
2. Copy the jar file under the `lib` directory of the provided `plugin` folder structure and create a zip file with the following root structure:
25+
- lib
26+
- META-INF
27+
- plugin.xml
28+
3. Register the plugin zip file to an OIG environment using OIG's plugin registration utility script.
29+
30+
Please see the useful link below for detailed build and deployment steps.
31+
32+
## How do I execute the event handler?
33+
34+
Once registered the code will be run automatically when user lifecycle events occur in the system. Note that password resets will be triggered only when the target attribute value changes (in this sample, the user's role), during modify events.
35+
36+
# Useful Links
37+
38+
[Oracle Identity Governance developer's guide - Developing plugins](https://docs.oracle.com/en/middleware/idm/identity-governance/12.2.1.4/omdev/developing-plug-ins.html#GUID-7F4EE3EA-076C-45DB-B13D-2905AB5AF6CB)
39+
40+
# License
41+
42+
Copyright (c) 2024 Oracle and/or its affiliates.
43+
44+
Licensed under the Universal Permissive License (UPL), Version 1.0.
45+
46+
See [LICENSE](https://github.com/oracle-devrel/technology-engineering/blob/main/LICENSE) for more details.

‎security/identity-and-access-management/oracle-identity-governance/event-handler-samples/password-reset-on-user-role-change/files/plugin/META-INF/EventHandlers.xml

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<?xml version='1.0' encoding='utf-8'?>
2+
<eventhandlers xmlns="http://www.oracle.com/schema/oim/platform/kernel"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://www.oracle.com/schema/oim/platform/kernel
5+
orchestration-handlers.xsd">
6+
<!-- Custom preprocess event handlers -->
7+
<action-handler
8+
class="com.oracle.sample.PasswordResetOnUserRoleChange"
9+
entity-type="User"
10+
operation="MODIFY"
11+
name="PasswordResetOnUserRoleChange"
12+
stage="preprocess"
13+
order="999"
14+
sync="TRUE"/>
15+
</eventhandlers>

‎security/identity-and-access-management/oracle-identity-governance/event-handler-samples/password-reset-on-user-role-change/files/plugin/lib/README.txt

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Place the plugin jar file in this directory before creating the plugin zip file.
2+
3+
Note the zip file structure must contain:
4+
- lib
5+
- META-INF
6+
- plugin.xml
7+
8+
Do NOT create an archive of the entire plugin directory, only of its contents, as specified above.

‎security/identity-and-access-management/oracle-identity-governance/event-handler-samples/password-reset-on-user-role-change/files/plugin/plugin.xml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<oimplugins>
3+
<plugins pluginpoint="oracle.iam.platform.kernel.spi.EventHandler">
4+
<plugin pluginclass="com.oracle.sample.PasswordResetOnUserRoleChange"
5+
version="1.0"
6+
name="PasswordResetOnUserRoleChange">
7+
</plugin>
8+
</plugins>
9+
</oimplugins>

‎security/identity-and-access-management/oracle-identity-governance/event-handler-samples/password-reset-on-user-role-change/files/src/com/oracle/sample/EventHandlerException.java

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
/*******************************************************************************
2+
* Copyright (c) 2024 Oracle and/or its affiliates. All rights reserved. DO NOT
3+
* ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
*
5+
* The Universal Permissive License (UPL), Version 1.0
6+
*
7+
* Subject to the condition set forth below, permission is hereby granted to any
8+
* person obtaining a copy of this software, associated documentation and/or
9+
* data (collectively the "Software"), free of charge and under any and all
10+
* copyright rights in the Software, and any and all patent rights owned or
11+
* freely licensable by each licensor hereunder covering either (i) the
12+
* unmodified Software as contributed to or provided by such licensor, or (ii)
13+
* the Larger Works (as defined below), to deal in both
14+
*
15+
* (a) the Software, and
16+
*
17+
* (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
18+
* one is included with the Software each a "Larger Work" to which the Software
19+
* is contributed by such licensors),
20+
*
21+
* without restriction, including without limitation the rights to copy, create
22+
* derivative works of, display, perform, and distribute the Software and make,
23+
* use, sell, offer for sale, import, export, have made, and have sold the
24+
* Software and the Larger Work(s), and to sublicense the foregoing rights on
25+
* either these or other terms.
26+
*
27+
* This license is subject to the following condition:
28+
*
29+
* The above copyright notice and either this complete permission notice or at a
30+
* minimum a reference to the UPL must be included in all copies or substantial
31+
* portions of the Software.
32+
*
33+
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
34+
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
35+
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
36+
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
37+
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
38+
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
39+
* SOFTWARE.
40+
*******************************************************************************/
41+
42+
package com.oracle.sample;
43+
44+
public class EventHandlerException extends Exception {
45+
public EventHandlerException(String errorMessage) {
46+
super(errorMessage);
47+
}
48+
}

‎security/identity-and-access-management/oracle-identity-governance/event-handler-samples/password-reset-on-user-role-change/files/src/com/oracle/sample/PasswordResetOnUserRoleChange.java

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
/*******************************************************************************
2+
* Copyright (c) 2024 Oracle and/or its affiliates. All rights reserved. DO NOT
3+
* ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
*
5+
* The Universal Permissive License (UPL), Version 1.0
6+
*
7+
* Subject to the condition set forth below, permission is hereby granted to any
8+
* person obtaining a copy of this software, associated documentation and/or
9+
* data (collectively the "Software"), free of charge and under any and all
10+
* copyright rights in the Software, and any and all patent rights owned or
11+
* freely licensable by each licensor hereunder covering either (i) the
12+
* unmodified Software as contributed to or provided by such licensor, or (ii)
13+
* the Larger Works (as defined below), to deal in both
14+
*
15+
* (a) the Software, and
16+
*
17+
* (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
18+
* one is included with the Software each a "Larger Work" to which the Software
19+
* is contributed by such licensors),
20+
*
21+
* without restriction, including without limitation the rights to copy, create
22+
* derivative works of, display, perform, and distribute the Software and make,
23+
* use, sell, offer for sale, import, export, have made, and have sold the
24+
* Software and the Larger Work(s), and to sublicense the foregoing rights on
25+
* either these or other terms.
26+
*
27+
* This license is subject to the following condition:
28+
*
29+
* The above copyright notice and either this complete permission notice or at a
30+
* minimum a reference to the UPL must be included in all copies or substantial
31+
* portions of the Software.
32+
*
33+
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
34+
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
35+
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
36+
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
37+
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
38+
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
39+
* SOFTWARE.
40+
*******************************************************************************/
41+
42+
package com.oracle.sample;
43+
44+
import java.io.Serializable;
45+
import java.util.HashMap;
46+
import java.util.HashSet;
47+
import java.util.Set;
48+
import java.util.logging.Level;
49+
import java.util.logging.Logger;
50+
51+
import oracle.iam.identity.usermgmt.api.UserManager;
52+
import oracle.iam.identity.usermgmt.api.UserManagerConstants;
53+
import oracle.iam.identity.usermgmt.vo.User;
54+
import oracle.iam.platform.context.ContextAware;
55+
import oracle.iam.platform.entitymgr.vo.SearchCriteria;
56+
import oracle.iam.platform.Platform;
57+
import oracle.iam.platform.kernel.OrchestrationEngine;
58+
import oracle.iam.platform.kernel.spi.PreProcessHandler;
59+
import oracle.iam.platform.kernel.vo.AbstractGenericOrchestration;
60+
import oracle.iam.platform.kernel.vo.BulkEventResult;
61+
import oracle.iam.platform.kernel.vo.BulkOrchestration;
62+
import oracle.iam.platform.kernel.vo.EventResult;
63+
import oracle.iam.platform.kernel.vo.Orchestration;
64+
65+
/**
66+
*
67+
* Sample event handler implementation that triggers a user reset password
68+
* flow once a user's role changes. Note that in this context we are referring
69+
* to a user role attribute, also known as "employee type", not to a change
70+
* in the membership status of a user to a particular OIG role.
71+
*
72+
* @author mgere-oracle
73+
*
74+
*/
75+
public class PasswordResetOnUserRoleChange implements PreProcessHandler {
76+
private static final Logger logger = Logger.getLogger(PasswordResetOnUserRoleChange.class.getName());
77+
78+
private static final String ORCHESTRATION_CREATE_EVENT = "CREATE";
79+
private static final String ORCHESTRATION_MODIFY_EVENT = "MODIFY";
80+
81+
@Override
82+
public EventResult execute(long arg0, long arg1, Orchestration arg2) {
83+
logger.log(Level.INFO, "Event handler execution has started.");
84+
85+
EventResult eventResult = new EventResult();
86+
87+
if (arg2 == null) {
88+
// arg2 will never be null if execute is called from an OIM event handler
89+
logger.log(Level.SEVERE, "Invalid orchestration payload.");
90+
eventResult.setFailureReason(new EventHandlerException("Invalid orchestration payload."));
91+
}
92+
93+
else {
94+
try {
95+
HashMap<String, Serializable> parameters = arg2.getParameters();
96+
97+
UserManager userManager = Platform.getService(UserManager.class);
98+
99+
String operation = arg2.getOperation();
100+
logger.log(Level.INFO, "Orchestration event: {0}", operation);
101+
102+
// should only run on MODIFY orchestration events, as per provided metadata
103+
if (operation.equals(ORCHESTRATION_MODIFY_EVENT)) {
104+
String userKey = getUserKey(arg0, arg2);
105+
logger.log(Level.FINE, "User Key: {0}", userKey);
106+
107+
String userEmpType = getParamaterValue(parameters,
108+
UserManagerConstants.AttributeName.EMPTYPE.getId());
109+
logger.log(Level.FINE, "User EmpType: {0}", userEmpType);
110+
111+
Set<String> retAttrs = new HashSet<>();
112+
SearchCriteria searchCriteria = new SearchCriteria(
113+
UserManagerConstants.AttributeName.USER_KEY.getId(), userKey,
114+
SearchCriteria.Operator.EQUAL);
115+
116+
User modifiedUser = userManager.search(searchCriteria, retAttrs, null).get(0);
117+
118+
// should only trigger when the role/empType changes
119+
if (userEmpType != null
120+
&& parameters.containsKey(UserManagerConstants.AttributeName.EMPTYPE.getId())) {
121+
logger.log(Level.INFO, "Resetting user password for: {0}", modifiedUser.getLogin());
122+
userManager.resetPassword(userKey, false);
123+
}
124+
} else {
125+
logger.log(Level.SEVERE, "Invalid event type.");
126+
eventResult.setFailureReason(new EventHandlerException("Invalid event type."));
127+
}
128+
} catch (Exception e) {
129+
logger.log(Level.SEVERE, "User password reset has failed with: ", e);
130+
eventResult.setFailureReason(e);
131+
}
132+
}
133+
134+
logger.log(Level.INFO, "Event handler execution has stopped");
135+
return eventResult;
136+
}
137+
138+
/**
139+
* Retrieve ContextAware values of parameters from an event handler
140+
* orchestration event, based on a desired key.
141+
*
142+
* @param parameters
143+
* @param key
144+
* @return
145+
*/
146+
private String getParamaterValue(HashMap<String, Serializable> parameters, String key) {
147+
if (parameters.containsKey(key)) {
148+
return (parameters.get(key) instanceof ContextAware)
149+
? (String) ((ContextAware) parameters.get(key)).getObjectValue()
150+
: (String) parameters.get(key);
151+
} else {
152+
return null;
153+
}
154+
}
155+
156+
/**
157+
* Return the affected user key from an orchestration event.
158+
*
159+
* @param processID
160+
* @param orchestration
161+
* @return
162+
*/
163+
private String getUserKey(long processID, Orchestration orchestration) {
164+
String userKey;
165+
166+
if (!orchestration.getOperation().equals(ORCHESTRATION_CREATE_EVENT)) {
167+
userKey = orchestration.getTarget().getEntityId();
168+
} else {
169+
OrchestrationEngine orchEngine = Platform.getService(OrchestrationEngine.class);
170+
userKey = (String) orchEngine.getActionResult(processID);
171+
}
172+
173+
return userKey;
174+
}
175+
176+
@Override
177+
public void initialize(HashMap<String, String> arg0) {
178+
}
179+
180+
@Override
181+
public void compensate(long arg0, long arg1, AbstractGenericOrchestration arg2) {
182+
}
183+
184+
@Override
185+
public boolean cancel(long arg0, long arg1, AbstractGenericOrchestration arg2) {
186+
return false;
187+
}
188+
189+
@Override
190+
public BulkEventResult execute(long arg0, long arg1, BulkOrchestration arg2) {
191+
BulkEventResult bulkEventResult = new BulkEventResult();
192+
193+
logger.log(Level.WARNING, "The event handler does not reset passwords for bulk events.");
194+
195+
return bulkEventResult;
196+
}
197+
}

0 commit comments

Comments
 (0)