Category: SSOAdm

How to set up an OAuth2 provider with ssoadm

The ssoadm command line tool is a quite powerful ally if you want to set up your OpenAM environment without performing any operation through the user interface, i.e. when you just want to script everything.

Whilst the tool itself allows you to do almost anything with the OpenAM configuration, finding the right set of commands for performing a certain task, is not always that straightforward… In today’s example we will try to figure out which commands to use to set up an OAuth2 provider.

When using the Common Tasks wizard to set up an OAuth2 Provider we can see that there are essentially two things that the wizard does for us:

  • Configure a realm level service for the OAuth2 Provider
  • Set up a policy to control access to the /oauth2/authorize endpoint

Setting up a realm level service

Well, we know that we are looking for something that sets up a service, so let’s see what command could help us:

$ openam/bin/ssoadm | grep -i service -B 1
        Add service to a realm. 

Well, we want to add a service to a realm, so add-svc-realm sounds like a good fit. Let’s see what parameters it has:

$ openam/bin/ssoadm add-svc-realm
    --realm, -e
        Name of realm.

    --servicename, -s
        Service Name.

    --attributevalues, -a
        Attribute values e.g. homeaddress=here.

    --datafile, -D
        Name of file that contains attribute values data.

Alright, so the realm is straightforward, but what should we use for servicename and datafile?

Each service in OpenAM has a service schema that describes what kind of attributes can that service contain and with what syntaxes/formats/etc. Since all the default service definitions can be found in ~/openam/config/xml directory, let’s have a look around and see if there is anything OAuth2 related:

$ ls ~/openam/config/xml
... OAuth2Provider.xml ...

After opening up OAuth2Provider.xml we can find the service name under the name attribute of the Service element (happens to be OAuth2Provider).

So the next question is what attributes should you use to populate the service? All the attributes are defined in the very same service definition XML file, so it’s not too difficult to figure out what to do now:

$ echo "forgerock-oauth2-provider-authorization-code-lifetime=60
forgerock-oauth2-provider-access-token-lifetime=600" > attrs.txt
$ openam/bin/ssoadm add-svc-realm -e / -s OAuth2Provider -u amadmin -f .pass -D attrs.txt

Creating a policy

Creating a policy is a bit more complex since 12.0.0 and the introduction of XACML policies, but let’s see what we can do about that.

Using ssoadm create-xacml

The XACML XML format is not really pleasant for the eyes, so I would say that you better create that policy using the policy editor first, and then export that policy in XACML format, so that you can automate this flow.

Once you have the policy in XACML format, the ssoadm command itself would look something like this:

$ openam/bin/ssoadm create-xacml -e / -X oauth2-policy.xml -u amadmin -f .pass

Using the REST API

The policy REST endpoints introduced with 12.0.0 are probably a lot more friendly for creating policies, so let’s see how to do that:

$ echo '{
   "resources" : [
   "subject" : {
      "type" : "AuthenticatedUsers"
   "active" : true, 
   "name" : "OAuth2ProviderPolicy",
   "description" : "", 
   "applicationName" : "iPlanetAMWebAgentService",
   "actionValues" : {
      "POST" : true, 
      "GET" : true
}' > policy.json
$ curl -v -H "iplanetdirectorypro: AQIC5wM...*" -H "Content-Type: application/json" -d @policy.json

Hope you found this useful.

How to backup and restore DataStore configurations

Creating DataStore configurations is never fun. You have to fill those lists with LDAP objectclasses and attributes, so OpenAM will see them, and if you have mistyped something then you’re probably going to end up debugging, why X functionality is broken and such. That’s why the best way to create datastore configurations is using the ssoadm command. The ssoadm is essentually a command line interface for OpenAM management. With help of ssoadm you can create scripts, which will configure OpenAM in the way you want, and sometimes you can configure things that you’ve never heard of in Console.

So let’s state, that you have an already working DataStore configuration, which you want to move to an another server or just simply backup for later. Here’s the command that you need to use from ssoadm install directory:

openam/bin/ssoadm show-datastore --realm / --name OpenDS --adminid amadmin
--password-file .pass > datastore_config.txt

As you can see, you can specify the realm and the datastore name which one you want to backup, the adminid is the name of the realm admin, the last one is the password-file parameter, in this case the .pass file is containing the amadmin password in plain text. Unfortunately there is no output-file but you could easily redirect the output with the > sign, or just copy the output into a file for later.
So backup done, but how could you restore it? Use the following command:

openam/bin/ssoadm create-datastore -e / -m OpenDS -t LDAPv3ForOpenDS
-u amAdmin -f .pass -D datastore_config.txt

At the restore you’re specifying the realm and the name again, but yet you have a magic parameter, the –datatype parameter. After some Googling around I was able to find some doc about it, but it’s not that uptodate, so here is what we (Allan and me) could find out about these types:

  • Database -> some kind of Database Server
  • LDAPv3 -> Generic LDAPv3 Server
  • LDAPv3ForAD -> Microsoft Active Directory with Host and Port
  • LDAPv3ForADAM -> Active Directory Application Mode
  • LDAPv3ForAMDS -> Equivalent with Sun DS in OpenAM console
  • LDAPv3ForOpenDS – Sun OpenDS
  • LDAPv3ForTivoli -> IBM Tivoli Directory Server

These are the valid values for the datatype parameter, choose one based on your DataStore.

And that’s it, this is how you can backup and restore datastore configurations, cheers!