Use temporal constraints to restrict effective roles
Temporal constraints restrict the period that a role is effective. You can apply temporal constraints to managed and internal roles, and to role grants (for individual users).
For example, you may want a role, contractors-2020, to apply to all contract employees for the year 2020. In this case, you would set the temporal constraint on the role. Alternatively, you may want to assign a contractors role that applies to an individual user only for the period of their contract of employment.
The following examples show how to set temporal constraints on role definitions, and on individual role grants.
Add a temporal constraint to a role
When you create a role, you can include a temporal constraint in the role definition that restricts the validity of the role, regardless of how that role is granted. Temporal constraints are expressed as a time interval in ISO 8601 date and time format. For more information on this format, refer to the ISO 8601 standard.
The following example adds a contractor role over the REST interface. The role is effective from March 1, 2020 to August 31, 2020:
curl \ --header "Authorization: Bearer <token>" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "name": "contractor", "description": "Role granted to contract workers for 2020", "temporalConstraints": [ { "duration": "2020-03-01T00:00:00.000Z/2020-08-31T00:00:00.000Z" } ] }' \ "https://<tenant-env-fqdn>/openidm/managed/realm-name_role?_action=create" { "_id": "ed761370-b24f-4e21-8e58-a3230942da67", "_rev": "000000007429750e", "name": "contractor", "description": "Role granted to contract workers for 2020", "temporalConstraints": [ { "duration": "2020-03-01T00:00:00.000Z/2020-08-31T00:00:00.000Z" } ] }
This example specifies the time zone as Coordinated Universal Time (UTC) by appending Z to the time. If no time zone information is provided, the time zone is assumed to be local time. To specify a different time zone, include an offset (from UTC) in the format ±hh:mm. For example, an interval of 2020-03-01T00:00:00.000-07:00/2020-08-31T00:00:00.000-07:00 specifies a time zone seven hours behind UTC.
When the period defined by the constraint ends, the role object remains in the repository, but the effective roles script will not include the role in the list of effective roles for any user.
The following example assumes the user scarter was granted a role contractor-march. A temporal constraint was included in the contractor-march role definition, specifying that the role should be applicable only during the month of March 2020. At the end of this period, a query on scarter’s entry shows that his roles property still includes the contractor-march role (with ID 0face495-772d-4d36-a30d-8594618aba0d), but his effectiveRoles property does not:
curl \ --header "Authorization: Bearer <token>" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://<tenant-env-fqdn>/openidm/managed/realm-name_user/<scarterUUID>?_fields=_id,userName,roles,effectiveRoles" { "_id": "scarter", "_rev": "00000000e5fdeb51", "userName": "scarter", "effectiveRoles": [], "roles": [ { "_ref": "managed/realm-name_role/0face495-772d-4d36-a30d-8594618aba0d", "_refResourceCollection": "managed/realm-name_role", "_refResourceId": "0face495-772d-4d36-a30d-8594618aba0d", "_refProperties": { "_id": "5f41d5a5-19b4-4524-a4b1-445790ff14da", "_rev": "00000000cb339810" } } ] }
The role is still in place but is no longer effective.
To restrict the period a role is valid by using the IDM admin UI, select Temporal Constraint on the role Details tab, then select a time zone offset relative to GMT and the start and end dates for the required period.
Add a temporal constraint to a role grant
To restrict the validity of a role for individual users, apply a temporal constraint at the grant level, rather than as part of the role definition. In this case, the temporal constraint is taken into account per user, when the user’s effective roles are calculated. Temporal constraints defined at the grant level can differ for each user who is a member of that role.
To apply a temporal constraint to a grant over the REST interface, include the constraint as one of the _refProperties of the relationship between the user and the role. The following example assumes a contractor role, with ID ed761370-b24f-4e21-8e58-a3230942da67. The command adds user bjensen as a member of that role, with a temporal constraint that specifies she be a member of the role for one year only, from January 1, 2020 to January 1, 2021:
curl \ --header "Authorization: Bearer <token>" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PATCH \ --data '[ { "operation": "add", "field": "/members/-", "value": { "_ref": "managed/realm-name_user/bjensen", "_refProperties": { "temporalConstraints": [{"duration": "2020-01-01T00:00:00.000Z/2021-01-01T00:00:00.000Z"}] } } } ]' \ "https://<tenant-env-fqdn>/openidm/managed/realm-name_role/<contractorUUID>" { "_id": "ed761370-b24f-4e21-8e58-a3230942da67", "_rev": "000000007429750e", "name": "contractor", "description": "Role granted to contract workers for 2020", "temporalConstraints": [ { "duration": "2020-03-01T00:00:00.000Z/2020-08-31T00:00:00.000Z" } ] }
A query on bjensen’s roles property shows the temporal constraint was applied to this grant:
curl \ --header "Authorization: Bearer <token>" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://<tenant-env-fqdn>/openidm/managed/realm-name_user/<bjensenUUID>/roles?_queryFilter=true" { "result": [ { "_id": "40600260-111d-4695-81f1-450365025784", "_rev": "00000000173daedb", "_ref": "managed/realm-name_role/ed761370-b24f-4e21-8e58-a3230942da67", "_refResourceCollection": "managed/realm-name_role", "_refResourceId": "ed761370-b24f-4e21-8e58-a3230942da67", "_refProperties": { "temporalConstraints": [ { "duration": "2020-01-01T00:00:00.000Z/2021-01-01T00:00:00.000Z" } ], "_id": "40600260-111d-4695-81f1-450365025784", "_rev": "00000000173daedb" } } ], ... }
To restrict the period that a role grant is valid using the IDM admin UI, set a temporal constraint when you add the member to the role.
For example, to specify that bjensen is added to a Contractor role only for the period of her employment contract, select Manage > Role, select the Contractor role, then select Add Role Members. On the Add Role Members screen, select bjensen from the list, then enable the Temporal Constraint, and specify the start and end date of her contract.