README.md revision ac3d0527956d93d93c68e3cd2d70d15ee1e654f6
/*
* The contents of this file are subject to the terms of the Common Development and
* Distribution License (the License). You may not use this file except in compliance with the
* License.
*
* You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
* specific language governing permission and limitations under the License.
*
* When distributing Covered Software, include this CDDL Header Notice in each file and include
* the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
* Header, with the fields enclosed by brackets [] replaced by your own identifying
* information: "Portions copyright [year] [name of copyright owner]".
*
* Copyright 2015 ForgeRock AS.
*/
--header "X-OpenIDM-Password: openidm-admin" \
--header "X-OpenIDM-Username: openidm-admin" \
--insecure \
--data '
{
"userName": "bjensen",
"telephoneNumber": "6669876987",
"givenName": "Barbara",
"sn": "Jensen",
"description": "Example User",
"mail": "bjensen@example.com",
"authzRoles" : [
{
"_ref" : "repo/internal/role/openidm-authorized"
}
]
}' \
{
"effectiveAssignments": [],
"effectiveRoles": [],
"accountStatus": "active",
"_id": "bjensen",
"_rev": "1",
"userName": "bjensen",
"telephoneNumber": "6669876987",
"givenName": "Barbara",
"sn": "Jensen",
"description": "Example User",
"mail": "bjensen@example.com"
}
we'll set it using a special header. Normally a servlet filter used for authentication
would not allow a client to masquerade as any user it wished through a simple header.
This sample merely demonstrates the simplest use of a servlet filter "establishing
the authentication id".
$ curl --header "X-Special-Trusted-User: bjensen" \
--insecure \
If successful, you will get a JSON structure that shows the user's authentication and authorization details:
{
"authorization": {
"roles": [
"openidm-authorized"
],
"id": "bjensen"
},
"authenticationId": "bjensen",
"_id": ""
}
final String specialHeader = ((HttpServletRequest) servletRequest).getHeader("X-Special-Trusted-User");
to the sample filter implementation:
"filterClass" : "org.forgerock.openidm.sample.trustedservletfilter.SampleTrustedServletFilter"
### The Trusted Attribute Auth Module
OpenIDM includes a "Trusted Attribute Auth Module" which can be configured to
trust a HttpServletRequest attribute of your choosing. It is configured by
adding the TRUSTED_ATTRIBUTE auth module to your authentication.json:
{
"name" : "TRUSTED_ATTRIBUTE",
"properties" : {
"propertyMapping" : {
"authenticationId" : "username",
"userRoles" : "authzRoles"
},
"defaultUserRoles" : [ ],
"authenticationIdAttribute" : "X-ForgeRock-AuthenticationId"
},
"enabled" : true
}
The queryOnResource, propertyMapping, and defaultUserRoles attributes are no
different than they are for other auth modules, so they will not be discussed
here. The new attribute, "authenticationIdAttribute" specifies the name of
the servlet request attribute that was set by the servlet filter indicating
the authenticated userId. Note the consistency in the value
"X-ForgeRock-AuthenticationId" in this configuration and the sample servlet
filter code.
## Customizing the Sample
To customize this sample for an external authentication/authorization system,
you will need to a servlet filter that performs the necessary authentication
using the third-party system. You may use a third-party supplied filter, or
write your own using the one in this sample as an aid. The filter may perform
REST calls to another system, database lookup, or inspection of headers,
cookies, or other request data. This servlet filter must set the username
of the authenticated user in a special request attribute that you choose.
This same attribute name must be configured in the TRUSTED_ATTRIBUTE auth
module configuration as the "authenticationIdAttribute" value.
If your filter does not produce an authentication that can be queried using
queryOnResource + "/" + authenticationId
that returns a user object with the userRoles property, you will need to
provide a security context augmentation script that populates the following
authorization properties in the "security" object given in the script scope:
* security.authorization.component
* security.authorization.roles
The value for component will be automatically set to the value specified
in the auth module property configuration "queryOnResource", if present.