OpenDJ: Configuration over REST

ForgeRock LogoIn recent builds of OpenDJ directory server, the REST to LDAP configuration changed quite a bit… for the better.

The draft release notes tell only part of the story:

The changes let you configure multiple endpoints each with multiple versions, resource type inheritance, subresource definitions, and protection with OAuth 2.0. This version of REST to LDAP also brings many minor improvements.

A really cool “minor” improvement is that you can now configure OpenDJ directory server over HTTP. In the draft Admin Guide, you can also find a procedure titled, To Set Up REST Access to Administrative Data.

tl;dr—Directory administrators can configure the server over REST through the /admin/config endpoint, and can read monitoring info under the /admin/monitor endpoint.

Important note: Before you go wild writing a whole new OpenDJ web-based console as a single-page app, keep in mind that the REST to LDAP implementation is still an Evolving interface, so incompatible changes can happen even in minor releases.

Here’s one example using /admin/config:

#
# This example demonstrates 
# using the /admin/config endpoint
# to create a password policy
# as a directory administrator
# who is also a regular user.
# 
# This requires a nightly build or release 
# from no earlier than late June 2016.
# 
# In order to get this working,
# first set up OpenDJ directory server
# with data from Example.ldif,
# and enable the HTTP connection handler.
#

#
# Give Kirsten Vaughan the right
# to read/write the server configuration.
# This command updates privileges, 
# which are explained in the Admin Guide:
#
/path/to/opendj/bin/ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password
dn: uid=kvaughan,ou=People,dc=example,dc=com
changetype: modify
add: ds-privilege-name
ds-privilege-name: config-read
-
add: ds-privilege-name
ds-privilege-name: config-write

#
# Give Kirsten access to write password policies.
# This command adds a global ACI.
# Global ACIs are explained in the Admin Guide:
#
/path/to/opendj/bin/dsconfig \
 set-access-control-handler-prop \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword "password" \
 --add global-aci:"(target=\"ldap:///cn=Password Policies,cn=config\")(targetscope=\"subtree\")(targetattr=\"*\")(version 3.0; acl \"Manage password policies\"; allow (all) userdn=\"ldap:///uid=kvaughan,ou=People,dc=example,dc=com\";)" \
 --trustAll \
 --no-prompt

#
# Server config-based password policies
# are under the container entry
# /admin/config/password-policies.
# This corresponds to 
# cn=Password Policies,cn=config in LDAP.
#
# The following are standard common REST operations.
# Common REST is explained and demonstrated
# in the OpenDJ Server Dev Guide.
#
# In production, of course,
# use HTTPS (as described in the Admin Guide).
#

#
# Add a new password policy:
#
curl \
 --user kvaughan:bribery \
 --request POST \
 --header "Content-Type: application/json" \
 --data '{
    "_id": "New Account Password Policy",
    "_schema": "password-policy",
    "password-attribute": "userPassword",
    "force-change-on-add": true,
    "default-password-storage-scheme": "Salted SHA-1"
}' http://opendj.example.com:8080/admin/config/password-policies

#
# Read the new password policy:
#
# curl --user kvaughan:bribery http://opendj.example.com:8080/admin/config/password-policies/New%20Account%20Password%20Policy

#
# An exercise for the reader:
# Figure out how to set a user's pwd policy over REST.
#

If you have not yet learned how to use commons REST and OpenDJ REST to LDAP, have a look at the Server Dev Guide chapter, Performing RESTful Operations.

Leave a comment

Filed under Directory Services and LDAP

ForgeRock repos and mirrors

ForgeRock LogoYou might already know that ForgeRock’s platform is built on open source software. We have been using Stash, now BitBucket, to host the git repos and to manage the review process.

If you want to read the code or the doc source code, you will find the canonical copies on that server. For example—there are more repos on the server, but here are some of the most popular links:

If you want to contribute a patch or a feature, sign up, login, and follow the development process. That process involves working on https://stash.forgerock.org/.

You will also find read-only mirrors (and other goodies) at GitHub, under https://github.com/ForgeRock:

Either server is fine if you just want to read the code or clone a repo.

Leave a comment

Filed under Tools

docbkx-tools 2.0.17 is out

Congratulations to Cedric on the release of docbkx-tools 2.0.17 earlier this week.

For those of you working with DocBook and Maven, docbkx-tools provides a plugin to generate output formats (HTML, PDF, etc.) as part of the Maven build, by applying the DocBook XSL stylesheets.

The 2.0.17 release adds some improvements, including support for DocBook XSL 1.79.1.

At ForgeRock, we have been relying on docbkx-tools since 2011. The next release of our doc build plugin is using 2.0.17. Upgrade was straightforward. The only issue that still needs fixing is olink support in chunked HTML.

Leave a comment

Filed under Docs, Tools

OpenDJ: Uploading a photo over REST

ForgeRock LogoOpenDJ REST to LDAP is based on ForgeRock common REST. ForgeRock common REST handles HTTP multipart requests, so you can upload binary data, such as JPEG photos. This blog entry demonstrates how to upload a JPEG photo as a patch using the curl command.

Before you start, set up OpenDJ server and configure HTTP access to sample directory data, as described in the OpenDJ server dev guide chapter on Performing RESTful Operations. To follow the example below, make sure you have imported data from Example.ldif and that you can read Babs’s resource over HTTP as shown in the documentation.

As of this writing, the default configuration for OpenDJ REST to LDAP does not include a mapping for a user’s jpegPhoto attribute, so you must add a mapping. To add the mapping, edit the "/users" attributes section in the configuration file /path/to/opendj/config/http-config.json to include a "photo" property in user resources. The following line adds a simple mapping from the "photo" property to the jpegPhoto LDAP attribute:

"photo" : { "simple" : { "ldapAttribute" : "jpegPhoto", "isSingleValued" : true } },

When finished, save your changes and restart OpenDJ server or at least the HTTP connection handler to have the connection handler reread the updated configuration file:

/path/to/opendj/bin/stop-ds --restart

To test your changes, copy a JPEG photo to picture.jpg in the current directory and patch Babs’s resource to add the photo:

curl \
 --request PATCH \
 --form 'json=[{"operation": "add", "field": "/photo", 
         "value": {"$ref":"cid:picture#content"}}];type=application/json' \
 --form 'picture=@picture.jpg;type=image/jpeg' \
 'http://bjensen:hifalutin@opendj.example.com:8080/users/bjensen'

The result of the operation should be Babs’s resource with the photo a (potentially very long) base64-encoded string:

{
	"_id": "bjensen",
	"_rev": "00000000160694db",
	"schemas": ["urn:scim:schemas:core:1.0"],
	"userName": "bjensen@example.com",
	"displayName": "Barbara Jensen",
	"name": {
		"givenName": "Barbara",
		"familyName": "Jensen"
	},
	"photo": "_9j_4RZJRXhpZg...AA",
	"manager": [{
		"_id": "trigden",
		"displayName": "Torrey Rigden"
	}],
	"contactInformation": {
		"telephoneNumber": "+1 408 555 1862",
		"emailAddress": "bjensen@example.com"
	},
	"meta": {
		"lastModified": "2016-03-22T09:13:23Z"
	}
}

Notice the curl command form data. When you specify the reference to the content ID, the reference takes the form:

{"$ref":"cid:identifier#(content|filename|mimetype)"}

If you want other attributes to hold the filename (picture.jpg) and MIME type (image/jpeg) of the file you upload, you can reference those as well. In the example above, {"$ref":"cid:picture#filename"} gets picture.jpg and {"$ref":"cid:picture#mimetype"} gets image/jpeg.

Leave a comment

Filed under Directory Services and LDAP

ForgeRock doc tools 3.2.0 released

ForgeRock Logo ForgeRock doc tools 3.2.0 were released today.

This is a minor release, compatible with earlier 3.x releases, with one small exception. See the release notes for details.

ForgeRock doc tools 3.2.0 includes the following components:

  • forgerock-doc-maven-plugin
  • forgerock-doc-common-content
  • forgerock-doc-default-branding

This release brings several improvements and squashes a few bugs.

Big thanks once again to Chris Lee for enhancements to the Bootstrap-styled HTML (the default for draft, in-progress docs to read when trying nightly builds), for identifying problems, and for help debugging.

Thanks also to Joanne Henry, Lana Frost, Lori Goldman, David Goldsmith, Gene Hirayama, and Mike Jang for testing and bug reports.

Leave a comment

Filed under Docs, Tools

ForgeRock Common Audit

ForgeRock LogoCommon Audit is another new feature of the ForgeRock platform.

Common Audit is part of the platform-wide infrastructure: a framework to handle audit events using common audit event handlers that are plugged in to the individual products. The handlers record events, logging them for example into files, relational databases, or syslog. Because handlers are pluggable, new handlers can be added to interoperate with your systems that store and analyze audit data.

Each audit event is identified by a unique transaction ID. The IDs can be communicated across the products and recorded for each local event. The transaction ID is the means to track requests as they traverse the platform.

In the current platform, configuring handlers depends on the product. So there are several places in the docs to read about how to configure Common Audit:

In addition, if you want to get the source code for Common Audit, or are interested in trying out new handlers and developments, you can find it on the ForgeRock Stash server. Right now it is in the forgerock-audit git repository. (To access most code on the ForgeRock Stash server, sign in with your ForgeRock credentials. You can sign up if you have not done so.)

Leave a comment

Filed under Access Management, Directory Services and LDAP, Docs, Identity Management

User-Managed Access from ForgeRock

ForgeRock LogoLast week ForgeRock released a platform update, including many new features. One of those features is support for User-Managed Access (UMA). UMA is a profile of OAuth 2.0 that allows resource owners to share their resources with others in a standard way. UMA puts resource owners in charge of defining policies for accessing their resources. From that perspective, UMA could be seen as highly scalable delegated policy administration.

At a very high level, this short video on privacy introduces the ideas it.

At a level closer to the implementation, UMA describes how authorization servers, resource servers, and UMA clients interact to enable resource sharing. In the ForgeRock platform, OpenAM plays the role of authorization server. OpenIG plays the role of resource server. (These are currently the working parts of OpenUMA.) In the present implementation, the client side is for you to implement, although the OpenIG docs include an example client, and there are ForgeRock demos that cover the client side as well. You can download OpenAM 13 and OpenIG 4 from the ForgeRock BackStage downloads page.

To get started with OpenAM authorization server implementation, install OpenAM and then have a look at the Administration Guide chapter on Managing UMA Authorization.

To try OpenIG’s UMA resource server capabilities, install OpenIG and then have a look at the OpenIG Gateway Guide chapter on OpenIG As an UMA Resource Server.

The latter chapter is a tutorial that describes how to get everything working together including a minimalist, browser-based UMA client.

 

Leave a comment

Filed under Uncategorized