OpenAM v.13 – REST STS OpenAM Token Translation

A quick demo of OpenAM’s Token Translation Service

According to Wikipedia:

In a typical usage scenario, a client requests access to a secure software application, often called a relying party. Instead of the application authenticating the client, the client is redirected to an STS. The STS authenticates the client and issues a security token. Finally, the client is redirected back to the relying party where it presents the security token. The token is the data record in which claims are packed, and is protected from manipulation with strong cryptography. The software application verifies that the token originated from an STS trusted by it, and then makes authorization decisions accordingly. The token is creating a chain of trust between the STS and the software application consuming the claims. This process is illustrated in the Security Assertion Markup Language (SAML) use case, demonstrating how single sign-on can be used to access web services.

Here is a quick video (w/o audio) demonstrating how to create an STS instance in OpenAM v.13 and then using Postman (REST client) to translate the tokenid of an authenticated user.

Caveat: There are obviously more configuration requirements for an actual deployment, the ACS URL would be key, for example. Refer to the STS documentation linked below the video.

References:

  • OpenAM 13 Admin Guide – 17.2. Configuring the Security Token Service
  • OpenAM 13 Developer’s Guide – 2.1.7. RESTful Secure Token Service
  • REST Requests:

    Authenticate:
    POST /openam/json/authenticate HTTP/1.1
    Host: am.example.com:8080
    X-OpenAM-Username: username
    X-OpenAM-Password: password
    Content-Type: application/json
    Cache-Control: no-cache

    {}

    Translate:
    POST /openam/rest-sts/sts-test?_action=translate HTTP/1.1
    Host: am.example.com:8080
    Content-Type: application/json
    Cache-Control: no-cache

    {
    “input_token_state”: {
    “token_type”: “OPENAM”,
    “session_id”: “AQIC5wM2LY4SfczD8y5-kVgiXY7rxxxxxxxxx8k0o8.*AAJTSQACMDEAAlNLABQtNjY4MzQxNjkzMDg2ODI1MjIzOQACUzEAAA..*”
    },
    “output_token_state”: {
    “token_type”: “SAML2”,
    “subject_confirmation”: “BEARER”
    }
    }

    Next Steps?
    We implement solutions like this for our clients nearly every day. Are you looking for assistance on a current project? Maybe you have a future project and you just want to keep in touch. Awesome! Head on over to our contact page and drop us a line. We’re looking forward to hearing from you.

    ForgeRock upgrades entire stack today! #OpenAM #OpenIDM #OpenDJ #OpenIG

    ok guys … ForgeRock released updates across the board today:

  • Access Management – AM 13
  • Identity Management – IDM 4
  • Directory Services – DJ 3
  • Identity Gateway – IG 4
  • I have only had a chance to go through the OpenAM release notes … and this is a big release for OpenAM. Clearly a ton of effort was put into this version. Check out the release notes for a comprehensive list of new features. I have highlighted my favorites here:

  • Contextual Authorization
  • SAML 2 Authentication Module
  • OAuth 2.0 Device Flow
  • Additional UMA Support (you knew this was coming)
  • OAuth 2.0 Enhancements
  • Elasticity and Scaling Features (Stateless Sessions and Dynamic Configuration, Yay!!)
  • Soap STS is back … so, you have REST and SOAP STS services now
  • OpenIG to replace DAS (bye-bye DAS … you won’t be missed, along with your little friend JATO too)
  • One more – listed under “User Experience Enhancements” there is a new one “Recording Troubleshooting Information” – I don’t know much about this and need to find out some more but looks really useful
  • So, go download these new versions and check out this new stuff. Let me know if you find new stuff that I haven’t found yet.

    OpenAM: Forcing users to reset password on next login.

    Overview

    A very common use case, when implementing ForgeRock’s OpenAM, is forcing a user to reset their password the next time they login. Seems easy enough right? … next time a particular user authenticates in they should be prompted to change their password before continuing on to the resource (web page) that they had originally requested.

    The documentation does mention a setting, in section 8.3, to enable this:

    Force Change Password on Next Login

    When enabled, the user must change her password next time she logs in after OpenAM resets her password.

     

    Unfortunately, this doesn’t seem to work. Doing a little “googling” you can find there is an open bug on this.

    There are several places online where ForgeRock’s Peter Major (aka @aldaris) recommends implementing this at the directory server layer instead. This is pretty easy to implement if you are using OpenDJ as your user identity repository.

    I am going to explain how to configure this here:

    OpenAM

    In OpenAM your authenication module needs to be set to LDAP instead of DataStore. The default ldapService authentication module uses the DataStore authentication module, which does not support forcing a user to reset their password. Instead you shoud create a new authentication chain which uses LDAP as the authentication module.

    Note
    : I am assuming that your LDAP authentication module is configured to use an OpenDJ instance.

    OpenDJ

    There are two settings in OpenDJ which need to be enabled.

    1. Modify the Password Policy to enforce Password Reset on Next Login
    2. Enable pwdReset attribute on the user’s record

    Modify the Password Policy:
    Using OpenDJ’s dsconfig command line tool you can edit the user’s password policy to enable the Password Reset settings. In this example the user’s password policy is the Default Password Policy. Change the setting force-change-on-reset from false to true. (Note: in production you probably would have created a different policy and wouldn’t be using the default policy)

    Enable pwdReset attribute on the user’s record:
    This setting can be changed either via an ldap browser, command line (ldapmodify) or even by using a provisioning tool like OpenIDM. Keep in mind that this is considered an operational attribute so you’ll need to ensure that you have permission to change the value.

    Note: The embedded OpenDJ instance that comes with OpenAM is configured to prevent a user from changing their password so you will likely run into errors unless you have modified the ACI. It’s actually not recommended to use the embedded OpenDJ instance as a user identity store, in production. So, use an external instance of OpenDJ and you’ll be fine.

    So, let’s see this in action:

    by the way … this works just fine using the XUI as well:

    Wrap up

    So, we’ve demonstrated how easy it is to implement the force password reset on next login functionality. We’ve validated that this approach works whether you are using the legacy UI or the new modern XUI.

    Don’t hesitate to reach out if you have any questions. If you need help implementing OpenAM or any other product’s in ForgeRock’s Open Identity Suite drop us a line through our contact page.

    open_applications_files@2x

    ForgeRock Docs and Alfred

    On average I spend a lot of time opening documents online.  One set of documents I refer to frequently is the ForgeRock Technical Document set.  While it’s not overly arduous to open a browser tab and click on a bookmark or type in the URL, I have wanted to find a better shortcut for this task.  I have used the launcher utility Alfred for most of the time that I have been a Mac user but have never used it for anything more advanced than opening applications on my laptop.  I finally took a few minutes yesterday to add a couple of new shortcuts to Alfred that would allow me quickly open the documentation I needed by just typing in a particular keyword.  I thought this was pretty convenient so I made a screencast to share.  I hope you enjoy and possibly get some ideas for improving your own productivity.

     

    LDAP Command Line Cheat #OpenDJ

    I use the command line a lot when interfacing with OpenDJ. One of the issues with this is that I often run into an issue with the BindDN user’s password has an “!” (bang) in it. As this is a special character in Unix/Linux command line, it will typically cause unexpected results.

    With ldapsearch you can just leave the password paramater off and you will be prompted to provide the password. I have found that this is not the case with ldapmodify and ldapdelete. So, this can be problematic when trying to delete a user’s record.

    Another work-around is to set up a tools.properties file in your user’s home directory. So, if you typically run these commands as a user named “opendj” then you would create the following file, in the opendj user’s home directory:

    ~/.opendj/tools.properties
    hostname=directory.example.com
    port=1389
    bindDN=uid=kvaughn,ou=People,dc=example,dc=com
    ldapcompare.port=1389
    ldapdelete.port=1389
    ldapmodify.port=1389
    ldappasswordmodify.port=1389
    ldapsearch.port=1389

    So, then to delete a user:

    Create an ldif file containing the user’s DN and the change type:

    ex. vi deleuser.ldif
    dn: uid=newuser,ou=People,dc=example,dc=com
    changetype: delete

    Then run the ldapmodify command:

    $ldapmodify -p 1389 -f deluser.ldif

    You will be prompted for the password which you can type in and not worry about any conflicts with the OS command line.

    Custom Password Policy Validation in OpenIDM

    A customer needed to ensure that passwords contained at least one ‘special character’ when a new password was created in OpenIDM.

    I borrowed heavily from the provided samples but had to figure out the correct regexp formatting.

    Here is the function that I used to implement this:

    function atLeastXSpecialChars(fullObject, value, params, property) {
       isRequired = _.find(this.failedPolicyRequirements, function (fpr) {
           return fpr.policyRequirement === "REQUIRED";
       }),
       isNonEmptyString = (typeof(value) === "string" && value.length),
       valuePassesRegexp = (function (v) {
       var testResult = isNonEmptyString ? v.match(/\(|\)|\!|\$|\`|\~|\:|\.|\,|\<|\>|\=|\?|\^|\_|\{|\}/g) : false;
           return testResult;
       }(value));
       if ((isRequired || isNonEmptyString) && !valuePassesRegexp) {
           return [ {"policyRequirement" : "AT_LEAST_X_SPECIAL_CHARS"}];
       }
        return [];
    };

    Using a different Oracle schema with OpenIDM’s Scripted SQL Connector

    Here is a quick note to help you correctly configure the Scripted SQL Connector when working with different schemas in an Oracle Database.  By default the connector assumes that you are querying the default schema, which can be problematic if you happen to be using a different schema (user).

    The default connector file will look something like this:

    "configurationProperties" : {
        "host" : "localhost",
        "port" : "3306",
        ...
        "database" : "HRDB",
        "autoCommit" : false,
        "reloadScriptOnExecution" : true,
        "createScriptFileName" : "&{launcher.project.location}/tools/CreateScript.groovy",
    
    

    To query a different schema you can add the attribute “defaultCatalog” to the configurationProperties.  So, if for example your database schema is “myschema” you can add “defaultCatalog” : “myschema”, as shown below:

    "configurationProperties" : {
        "host" : "localhost",
        "port" : "3306",
        ...
        "database" : "HRDB",
        "defaultCatalog" : "myschema".
        "autoCommit" : false,

    Once you save the connector you should be able to query the correct schema.

    Resetting Forgotten Passwords with @ForgeRock #OpenAM

    Implementing the “Resetting Forgotten Passwords” functionality as described in the OpenAM Developer’s Guide requires some additional custom code.

    It’s pretty straight forward to implement this functionality and can be done in 4 steps (per the Developer’s Guide):

    1. Configure the Email Service
    2. Perform an HTTP Post with the user’s id
    3. OpenAM looks up email address (based on user id) and sends an email with a link to reset the password
    4. Intercept the HTTP GET request to this URL when the user clicks the link.

    All of this functionality is available out of the box with the exception of #4.  I wrote some really simple javascript that can be deployed to the OpenAM server that will handle this.  This code was written as a proof-of-concept and doesn’t include any data-validation or error handling but that could be added fairly easily.  This script can be deployed to the root directory of your OpenAM deployment.  Just be sure to update the Forgot Password Confirmation Email URL in the OpenAM Console under Configuration > Global > REST Security.

    I have made the code available on my GitHub page and you are welcome to use it or modify it.

    As described on the README:

    • These files are a proof of concept to extend OpenAM’s REST-based password reset functionalit
    • Add these two files to your OpenAM deployment root (e.g. /tomcat7/webapps/openam
    • Modify the server urls to the appropriate servers in your environmet
    • Change the REST Security settings in the OpenAM console (e.g. http://[AM server and port]/openam/forgotPassword.jsp)

    The file resetPassword.jsp is an optional file that will display a field for the user to provide their id and will then POST to /json/users?_action=forgotPassword (Step #2 from the Developer’s Guide).

    Acknowledgements:

    Thanks to @Aldaris and @ScottHeger for providing advice while I was working on this.

    Seeking Senior OpenAM Engineers

    A client of mine has asked me to assist them in finding a full-time Senior OpenAM Engineer.  They are a startup, based in Northern, Virginia.  They are working on some pretty cool initiatives with OAUTH2 and SAML and need an experienced engineer to lead this effort. 

    If you are interested in this please feel free to reach out to me and I’ll put you in touch.

    Cool Open Identity Stack Scripts/Utilities – GitHub Repos #ForgeRock #IDM

    I was working on a few scripts to test out some of the new REST APIs in OpenAM 11.  I saved them out to GitHub and you are welcome to have at them.

    I thought it might also be cool to share some of the other Repo’s that are related to ForgeRock as well.  There are some really cool scripts available for interacting with OpenAM, OpenIDM and OpenDJ.

    These are freely available but not officially supported by ForgeRock or the developers of the scripts.  Just click on the person’s name to go to their GitHub repo.

    OpenAM:

    • Brad Tumy (AuthNUser, checkEntitlements, listAgents *New API and Legacy API*, updatePolicy)
    • Simon Moffatt (Really cool interactive menu!)

    OpenDJ:

    • Ludo Poitou (Some really handy utilities e.g.: logstat.py & filterstat.py)
    • Chris Ridd (Very handy utils e.g.: slowops: analyzes operation times in access logs)
    • Simon Moffatt

    OpenIDM:

    • Simon Moffatt (Interactive mode menu for calling OpenIDM’s REST APIs)

    Full OIS Stack:

    • Warren Strange (Ansible (like puppet) scripts for deploying the OIS stack to Vagrant)

    I am sure there are other great repos that I have missed, so feel free to add them in the comments and I can update the post.

    Disclaimer: These scripts have been very handy to me but YMMV.