How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I customize authorization rules for http requests in IDM 5.x and 6.x?

Last updated Jun 28, 2022

The purpose of this article is to provide information on customizing authorization rules for http requests (endpoints) in IDM.


1 reader recommends this article

Overview

Access rules are configured over REST in IDM 7 and the access.js script has been replaced with an access.json configuration file. See Security Guide › Protect REST Endpoints With Authorization and Access Control for further information on configuring access and authorization rules.

Pre-IDM 7

Authorization rules for http requests are derived from the access.js and router-authz.js files (located in the /path/to/idm/script and /path/to/idm/bin/defaults/script directories respectively). These two files are used together to validate inbound REST requests and determine if the user has access.

access.js allows you to specify authorization rules for each http request, where the configurations for each http request follow a set format:

  • pattern - resource requested, for example, managed/user. You can also use "*" to indicate all patterns are allowed.
  • roles - role of requesting user, for example, internal/role/openidm-authorized. In pre-IDM 6.5, you do not need to include the full path; you can just refer to the role name, for example, openidm-authorized
  • methods - comma separated list of methods to which access is being granted (for example, create, read, patch etc.) You can also use "*" to indicate all methods are allowed or "" to indicate no methods are allowed.
  • actions - comma separated list of allowed actions. The possible values depend on the URL being exposed as detailed in Integrator's Guide › Understanding the Access Configuration Script (access.js). You can also use "*" to indicate all actions are allowed or "" to indicate no actions are allowed.
  • customAuthz (optional) - reference to function names of scripts contained within router-authz.js.
  • excludePatterns (optional) - resources to which access is not permitted.

The access.js file format is described in more detail in Integrator's Guide › Understanding the Access Configuration Script (access.js).

router-authz.js contains a set of functions, where each function must return a boolean value. These scripts all have access to the openidm.[method]() functionality along with the request, config and context variables, which all contain useful information.

The router-authz.js file is described in more detail in Integrator's Guide › Understanding the Router Authorization Script (router-authz.js); further information on openidm.[method]() calls can be found in Integrator's Guide › Function Reference.

Customizing authorization rules for http requests

You can update and add entries to access.js to provide simple authorization rules, such as restricting certain actions to a given role. For greater control, you can combine this with calls to an appropriate function (or functions) written within the router-authz.js file to provide context-based authorization rules.

Note

You should copy the router-authz.js file to the /path/to/idm/script directory and update the copy rather than the default file itself.

Additionally, if you add new roles or custom http requests to IDM, you should configure the appropriate access by updating access.js to include the new roles and/or custom http requests.

Example 1

The info http request in IDM (which provides detailed information about a running IDM instance) is configured by default to be accessible to all roles:

{            "pattern" : "info/*",            "roles" : "*",            "methods" : "read",            "actions" : "*"         },

You could change this so it is only accessible to users assigned the internal/role/openidm-admin role by updating this as follows:

{            "pattern" : "info/*",            "roles" : "internal/role/openidm-admin",            "methods" : "read",            "actions" : "*"         },

Example 2

If you had a new custom http request that you wanted to be accessible to users assigned a new role or the existing internal/role/openidm-cert role, you would add something similar to the following to access.js:

{ "pattern" : "custom/*""roles" : "managed/role/NewRole,internal/role/openidm-cert""methods" : "*", // default to all methods allowed "actions" : "*", // default to all actions allowed }

See Also

How does IDM (All versions) use anonymous access?

Integrator's Guide › Roles and Authentication

Integrator's Guide › Working With Managed Roles

Integrator's Guide › Authorization

Related Training

ForgeRock Identity Management Deep Dive (IDM-420)

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2022 ForgeRock, all rights reserved.