Skip to content

Commit a85a1f5

Browse files
ddsharpeddsharpe
authored
Merge pull request #250 from oracle/security-readme-custom-provider
changes to Security Providers documentation and addition of custom security providers
2 parents 80380dc + c68079b commit a85a1f5

File tree

2 files changed

+117
-94
lines changed

2 files changed

+117
-94
lines changed

‎README.md

Lines changed: 4 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ Many organizations are using WebLogic Server, with or without other Oracle Fusio
1515
- [Simple Example](#simple-example)
1616
- [Model Names](#model-names)
1717
- [Model Semantics](#model-semantics)
18-
- [Modeling Security Providers](#modeling-security-providers)
18+
- [Modeling Security Providers](site/security_providers.md)
19+
- [Custom Security Providers](site/security_providers.md#custom-security-providers)
1920
- [Variable Injection](site/variable_injection.md)
2021
- [Model Filters](site/tool_filters.md)
2122
- [Downloading and Installing](#downloading-and-installing-the-software)
@@ -143,7 +144,7 @@ Users can create further directory structures underneath the above locations to
143144

144145
One final note is that the framework is written in such a way to allow the model to be extended for use by other tools. Adding other top-level sections to the model is supported and the existing tooling and framework will simply ignore them, if present. For example, it would be possible to add a `soaComposites` section to the model where SOA composite applications are described, and a location within the archive file where those binaries can be stored, so that a tool that understands SOA composites and how to deploy them could be run against the same model and archive files.
145146

146-
#### Model Names
147+
### Model Names
147148

148149
The WebLogic Deploy Tooling handles names of WebLogic Server configuration artifacts in a very prescribed way. To understand how names are handled, users first need a basic understanding of WLST offline naming. In WLST offline, there are two general categories of configuration artifacts:
149150

@@ -176,7 +177,7 @@ topology:
176177

177178
As the example above shows, the `SecurityConfiguration` element has no named sub-element, as there is with `JDBCSystemResource`, even though the WLST path to the `SecurityConfiguration` attributes is `/SecurityConfiguration/<domain-name>`. The WebLogic Deploy Tooling has built-in rules and a knowledge base that controls how these names are handled so that it can complete the configuration of these artifacts. As with the previous class of configuration artifact, the folder almost always contains a ` Name` attribute that, in WLST, could be used to change the name. As with the previous class of artifact, the WebLogic Deploy Tooling does not support the use of the `Name` attribute in these folders and any attempt to set the `Name` attribute will not be honored. In general, the only model location that uses the `Name` attribute is the top-level topology section, because this maps to where WLST stores the domain name.
178179

179-
#### Model Semantics
180+
### Model Semantics
180181

181182
When modeling configuration attributes that can have multiple values, the WebLogic Deploy Tooling tries to make this as painless as possible. For example, the `Target` attribute on resources can have zero or more clusters and/or servers specified. When specifying the value of such list attributes, the user has freedom to specify them as a list or as a comma-delimited string (comma is the only recognized delimiter for lists). For attributes where the values can legally contain commas, the items must be specified as a list. Examples of each are shown below.
182183

@@ -214,97 +215,6 @@ In the example above, the `Target` attribute is specified three different ways,
214215

215216
One of the primary goals of the WebLogic Deploy Tooling is to support a sparse model where the user can specify just the configuration needed for a particular situation. What this implies varies somewhat between the tools but, in general, this implies that the tools are using an additive model. That is, the tools add to what is already there in the existing domain or domain templates (when creating a new domain) rather than making the domain conform exactly to the specified model. Where it makes sense, a similar, additive approach is taken when setting the value of multi-valued attributes. For example, if the model specified the cluster `mycluster` as the target for an artifact, the tooling will add `mycluster` to any existing list of targets for the artifact. While the development team has tried to mark attributes that do not make sense to merge accordingly in our knowledge base, this behavior can be disabled on an attribute-by-attribute basis, by adding an additional annotation in the knowledge base data files. The development team is already thinking about how to handle situations that require a non-additive, converge-to-the-model approach, and how that might be supported, but this still remains a wish list item. Users with these requirements should raise an issue for this support.
216217

217-
#### Modeling Security Providers
218-
One place where the semantics are different is for WebLogic security providers. Because provider ordering is important, and to make sure that the ordering is correctly set in the newly created domain, the Create Domain Tool will look for security providers of each base type (for example, Authentication Providers, Credential Mappers, and such) to see if any are included in the model. If so, the tool will make sure that the providers only listed for a type are present in the resulting domain so that the providers are created in the necessary order. For example, if the model specified an `LDAPAuthenticator` and an `LDAPX509IdentityAsserter` similar to what is shown below, the `DefaultAuthenticator` and `DefaultIdentityAsserters` will be deleted. If no providers for a base type are listed in the model, then the default providers will be left untouched.
219-
220-
```yaml
221-
topology:
222-
SecurityConfiguration:
223-
Realm:
224-
myrealm:
225-
AuthenticationProvider:
226-
My LDAP authenticator:
227-
LDAPAuthenticator:
228-
ControlFlag: SUFFICIENT
229-
PropagateCauseForLoginException: true
230-
EnableGroupMembershipLookupHierarchyCaching: true
231-
Host: myldap.example.com
232-
Port: 389
233-
UserObjectClass: person
234-
GroupHierarchyCacheTTL: 600
235-
SSLEnabled: true
236-
UserNameAttribute: cn
237-
Principal: 'cn=foo,ou=users,dc=example,dc=com'
238-
UserBaseDn: 'OU=Users,DC=example,DC=com'
239-
UserSearchScope: subtree
240-
UserFromNameFilter: '(&(cn=%u)(objectclass=person))'
241-
AllUsersFilter: '(memberOf=CN=foo,OU=mygroups,DC=example,DC=com)'
242-
GroupBaseDN: 'OU=mygroups,DC=example,DC=com'
243-
AllGroupsFilter: '(&(foo)(objectclass=group))'
244-
StaticGroupObjectClass: group
245-
StaticMemberDNAttribute: cn
246-
StaticGroupDNsfromMemberDNFilter: '(&(member=%M)(objectclass=group))'
247-
DynamicGroupObjectClass: group
248-
DynamicGroupNameAttribute: cn
249-
UseRetrievedUserNameAsPrincipal: true
250-
KeepAliveEnabled: true
251-
GuidAttribute: uuid
252-
My LDAP IdentityAsserter:
253-
LDAPX509IdentityAsserter:
254-
ActiveType: AuthenticatedUser
255-
Host: myldap.example.com
256-
Port: 389
257-
SSLEnabled: true
258-
```
259-
260-
To keep the `DefaultAuthenticator` and `DefaultIdentityAsserter`, simply add the default names and types in the correct positions in the model's `AuthenticationProvider` list. If desired, settings on the default providers can be changed, as shown below.
261-
262-
```yaml
263-
topology:
264-
SecurityConfiguration:
265-
Realm:
266-
myrealm:
267-
AuthenticationProvider:
268-
My LDAP authenticator:
269-
LDAPAuthenticator:
270-
ControlFlag: SUFFICIENT
271-
PropagateCauseForLoginException: true
272-
EnableGroupMembershipLookupHierarchyCaching: true
273-
Host: myldap.example.com
274-
Port: 389
275-
UserObjectClass: person
276-
GroupHierarchyCacheTTL: 600
277-
SSLEnabled: true
278-
UserNameAttribute: cn
279-
Principal: 'cn=foo,ou=users,dc=example,dc=com'
280-
UserBaseDn: 'OU=Users,DC=example,DC=com'
281-
UserSearchScope: subtree
282-
UserFromNameFilter: '(&(cn=%u)(objectclass=person))'
283-
AllUsersFilter: '(memberOf=CN=foo,OU=mygroups,DC=example,DC=com)'
284-
GroupBaseDN: 'OU=mygroups,DC=example,DC=com'
285-
AllGroupsFilter: '(&(foo)(objectclass=group))'
286-
StaticGroupObjectClass: group
287-
StaticMemberDNAttribute: cn
288-
StaticGroupDNsfromMemberDNFilter: '(&(member=%M)(objectclass=group))'
289-
DynamicGroupObjectClass: group
290-
DynamicGroupNameAttribute: cn
291-
UseRetrievedUserNameAsPrincipal: true
292-
KeepAliveEnabled: true
293-
GuidAttribute: uuid
294-
My LDAP IdentityAsserter:
295-
LDAPX509IdentityAsserter:
296-
ActiveType: AuthenticatedUser
297-
Host: myldap.example.com
298-
Port: 389
299-
SSLEnabled: true
300-
DefaultAuthenticator:
301-
DefaultAuthenticator:
302-
ControlFlag: SUFFICIENT
303-
DefaultIdentityAsserter:
304-
DefaultIdentityAsserter:
305-
306-
```
307-
308218
## Downloading and Installing the Software
309219

310220
The Oracle WebLogic Server Deploy Tooling project repository is located at [`https://github.com/oracle/weblogic-deploy-tooling`](https://github.com/oracle/weblogic-deploy-tooling). Binary distributions of the `weblogic-deploy.zip` installer can be downloaded from the [GitHub Releases page](https://github.com/oracle/weblogic-deploy-tooling/releases). To install the software, simply unzip the `weblogic-deploy.zip` installer on a machine that has the desired versions of WebLogic Server installed. After being unzipped, the software is ready to use, just set the `JAVA_HOME` environment variable to point to a Java 7 or higher JDK and the shell scripts are ready to run.

‎site/security_providers.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
### Modeling Security Providers
2+
WebLogic Server security configuration requires special handling and causes the need for the model semantics to differ from other folders. Because provider ordering is important, and to make sure that the ordering is correctly set in the newly created domain, the Create Domain Tool and Update Domain Tool require that all providers be specified in the model for any provider type that will be created or altered. For example, if you want to change one of the providers in the provider type `AuthenticationProvider`, your model must specify all of the `AuthenticationProvider` providers and any non-default attributes for those providers. In order to apply security providers, these tools will delete all providers from the target domain for those provider types specified in the model before adding the providers from the model to the target domain. Provider types that are omitted from the model will be unchanged. Example provider types are `Adjudicator`, `AuthenticationProvider`, `Authorizer`, `CertPathProvider`, `CredentialMapper`, `PasswordValidator`, and `RoleMapper`.
3+
4+
For example, if the model specified an `LDAPAuthenticator` and an `LDAPX509IdentityAsserter` similar to what is shown below, the `DefaultAuthenticator` and `DefaultIdentityAsserter` would be deleted. In this example, other provider types like `RoleMapper` and `CredentialMapper` are not specified and would be left untouched by the tools.
5+
6+
```yaml
7+
topology:
8+
SecurityConfiguration:
9+
Realm:
10+
myrealm:
11+
AuthenticationProvider:
12+
My LDAP authenticator:
13+
LDAPAuthenticator:
14+
ControlFlag: SUFFICIENT
15+
PropagateCauseForLoginException: true
16+
EnableGroupMembershipLookupHierarchyCaching: true
17+
Host: myldap.example.com
18+
Port: 389
19+
UserObjectClass: person
20+
GroupHierarchyCacheTTL: 600
21+
SSLEnabled: true
22+
UserNameAttribute: cn
23+
Principal: 'cn=foo,ou=users,dc=example,dc=com'
24+
UserBaseDn: 'OU=Users,DC=example,DC=com'
25+
UserSearchScope: subtree
26+
UserFromNameFilter: '(&(cn=%u)(objectclass=person))'
27+
AllUsersFilter: '(memberOf=CN=foo,OU=mygroups,DC=example,DC=com)'
28+
GroupBaseDN: 'OU=mygroups,DC=example,DC=com'
29+
AllGroupsFilter: '(&(foo)(objectclass=group))'
30+
StaticGroupObjectClass: group
31+
StaticMemberDNAttribute: cn
32+
StaticGroupDNsfromMemberDNFilter: '(&(member=%M)(objectclass=group))'
33+
DynamicGroupObjectClass: group
34+
DynamicGroupNameAttribute: cn
35+
UseRetrievedUserNameAsPrincipal: true
36+
KeepAliveEnabled: true
37+
GuidAttribute: uuid
38+
My LDAP IdentityAsserter:
39+
LDAPX509IdentityAsserter:
40+
ActiveType: AuthenticatedUser
41+
Host: myldap.example.com
42+
Port: 389
43+
SSLEnabled: true
44+
```
45+
46+
In order to keep the `DefaultAuthenticator` and `DefaultIdentityAsserter` while changing/adding providers, they must be specified in the model with any non-default attributes as shown in the example below. Keep in mind, the ordering of providers in the model will be the order the providers are set in the WebLogic security configuration.
47+
48+
```yaml
49+
topology:
50+
SecurityConfiguration:
51+
Realm:
52+
myrealm:
53+
AuthenticationProvider:
54+
My LDAP authenticator:
55+
LDAPAuthenticator:
56+
ControlFlag: SUFFICIENT
57+
PropagateCauseForLoginException: true
58+
EnableGroupMembershipLookupHierarchyCaching: true
59+
Host: myldap.example.com
60+
Port: 389
61+
UserObjectClass: person
62+
GroupHierarchyCacheTTL: 600
63+
SSLEnabled: true
64+
UserNameAttribute: cn
65+
Principal: 'cn=foo,ou=users,dc=example,dc=com'
66+
UserBaseDn: 'OU=Users,DC=example,DC=com'
67+
UserSearchScope: subtree
68+
UserFromNameFilter: '(&(cn=%u)(objectclass=person))'
69+
AllUsersFilter: '(memberOf=CN=foo,OU=mygroups,DC=example,DC=com)'
70+
GroupBaseDN: 'OU=mygroups,DC=example,DC=com'
71+
AllGroupsFilter: '(&(foo)(objectclass=group))'
72+
StaticGroupObjectClass: group
73+
StaticMemberDNAttribute: cn
74+
StaticGroupDNsfromMemberDNFilter: '(&(member=%M)(objectclass=group))'
75+
DynamicGroupObjectClass: group
76+
DynamicGroupNameAttribute: cn
77+
UseRetrievedUserNameAsPrincipal: true
78+
KeepAliveEnabled: true
79+
GuidAttribute: uuid
80+
My LDAP IdentityAsserter:
81+
LDAPX509IdentityAsserter:
82+
ActiveType: AuthenticatedUser
83+
Host: myldap.example.com
84+
Port: 389
85+
SSLEnabled: true
86+
DefaultAuthenticator:
87+
DefaultAuthenticator:
88+
ControlFlag: SUFFICIENT
89+
DefaultIdentityAsserter:
90+
DefaultIdentityAsserter:
91+
92+
```
93+
94+
#### Custom Security Providers
95+
96+
**NOTE:** Creating and updating domains with custom security providers is limited to WebLogic version 12.1.2 and newer.
97+
98+
Prior to using this tooling to create or update a domain with a custom security provider, there are several prerequisites. First, WebLogic Server requires the custom MBean JAR to be in the Oracle Home directory before it can be configured, `WLSERVER/server/lib/mbeantypes`. Second, WebLogic Scripting Tool, WLST, requires that the schema JAR be placed in the Oracle Home directory before WLST offline can be used to configure it, `ORACLEHOME/oracle_common/lib/schematypes`. Generating an MBean JAR documentation can be found in the WebLogic Server [documentation](https://docs.oracle.com/middleware/12213/wls/DEVSP/generate_mbeantype.htm#DEVSP617). Generating the schema JAR can be done with the `prepareCustomProvider` script provided in the WebLogic Server installation.
99+
100+
The format for a custom security provider is slightly different from a built-in provider in that the custom provider must supply the fully-qualified name of the class for the provider in the model between the provider name and the attributes for that provider. Note that the generated Impl suffix is omitted from the name. In the custom `CredentialMapper` example below, note the location in the model of 'examples.security.providers.SampleCredentialMapper':
101+
102+
```yaml
103+
CredentialMapper:
104+
'Sample CredentialMapper':
105+
'examples.security.providers.SampleCredentialMapper':
106+
UserNameMapperClassName: 'examples.security.providers.CredentialMapperProviderImpl'
107+
CredentialMappingDeploymentEnabled: true:
108+
```
109+
110+
#### Known Limitations
111+
112+
- `Adjudicator` provider types cannot be added or modified due to a limitation in WLST.
113+
- `PasswordCredentials` provider types cannot be updated in WLST online.

0 commit comments

Comments
 (0)