Authentication and roles

When a user authenticates, the user is given a set of default internal roles. These roles determine what Advanced Identity Cloud resources the user can access. Advanced Identity Cloud includes a number of default internal roles on the openidm/internal/roles endpoint. You can configure additional internal roles to customize how you restrict access to the server.

The following internal roles are defined by default:

openidm-admin: IDM administrator role, excluded from the reauthorization required policy definition by default.
openidm-authorized: Default role for any user who authenticates with a username and password.
openidm-cert: Default role for any user who authenticates with mutual SSL authentication.

This role applies only to mutual authentication. The shared secret (certificate) must be adequately protected. The openidm-cert role is excluded from the reauthorization required policy definition by default.
openidm-reg: Assigned to users who access Advanced Identity Cloud with the default anonymous account.

The openidm-reg role is excluded from the reauthorization required policy definition by default.
openidm-tasks-manager: Role for users who can be assigned to workflow tasks.
platform-provisioning: Role for platform provisioning access.

When a user authenticates, Advanced Identity Cloud calculates that user’s roles as follows:

Each authentication module includes a defaultUserRoles property. Depending on how the user authenticates, Advanced Identity Cloud assigns the roles listed in that module’s defaultUserRoles property to the user on authentication. The defaultUserRoles property is specified as an array. For most authentication modules, the user obtains the openidm-authorized role on authentication. For example:
```
{
    "name" : "MANAGED_USER",
    "properties" : {
        ...
        "defaultUserRoles" : [
            "internal/role/openidm-authorized"
        ]
    },
    ...
}
```
The userRoles property in an authentication module maps to an attribute (or list of attributes) in a user entry that contains that user’s authorization roles. This attribute is usually authzRoles, unless you have changed how user roles are stored.

Any internal roles that are conditionally applied are also calculated and included in the user’s authzRoles property at this point.
If the authentication module includes a groupRoleMapping, groupMembership, or groupComparison property, Advanced Identity Cloud can assign additional roles to the user, depending on the user’s group membership on an external system. Learn more in Map external groups to internal authz roles.

The roles calculated in sequence are cumulative. Roles with temporal restrictions aren’t included in that list if the current time is outside of the time assigned to the role.

Dynamic role calculation

By default, Advanced Identity Cloud calculates a user’s roles only on authentication. You can configure Advanced Identity Cloud to recalculate a user’s roles dynamically, with each request, instead of only when the user reauthenticates. To enable this feature, set enableDynamicRoles to true in the JWT_SESSION session module in the authentication configuration.

Roles, authentication, and the security context

The security context (context.security), consists of a principal (defined by the authenticationId property) and an access control element (defined by the authorization property).

If authentication is successful, the authentication framework sets the principal. Advanced Identity Cloud stores that principal as the authenticationId.

The authorization property includes an id, an array of roles, and a component, that specifies the resource against which authorization is validated.

Change the authentication configuration over REST

You can change the authentication configuration using the endpoint openidm/config/authentication. First, get the entire current authentication configuration with a GET request, then modify it as necessary, and finally, resubmit the complete, updated configuration using a PUT request.

Get an access token.

Get the current authentication configuration:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0"  \
--request GET \
"https://<tenant-env-fqdn>/openidm/config/authentication"

Show response

{
  "_id": "authentication",
  "rsFilter": {
    "augmentSecurityContext": {
      "source": "require('auth/orgPrivileges').assignPrivilegesToUser(resource, security, properties, subjectMapping, privileges, security.authorization.component.includes('/alpha_') ? 'alphaOrgPrivileges' : 'bravoOrgPrivileges', 'privilegeAssignments');",
      "type": "text/javascript"
    },
    "cache": {
      "maxTimeout": "300 seconds"
    },
    "scopes": [
      "fr:idm:*"
    ],
    "subjectMapping": [
      {
        "additionalUserFields": [
          "adminOfOrg",
          "ownerOfOrg"
        ],
        "defaultRoles": [
          "internal/role/openidm-authorized"
        ],
        "propertyMapping": {
          "sub": "_id"
        },
        "queryOnResource": "managed/{{substring realm 1}}_user",
        "userRoles": "authzRoles/*"
      }
    ]
  }
}

Create a local copy of the authentication configuration from the response in step 2, then modify it.

This example adds a staticUserMapping attribute. It contains configuration that assigns the access management OAuth 2.0 client myrcs1-client the myrcs1-client-authorized role after successful authentication.

{
  "_id": "authentication",
  "rsFilter": {
    "augmentSecurityContext": {
      "source": "require('auth/orgPrivileges').assignPrivilegesToUser(resource, security, properties, subjectMapping, privileges, security.authorization.component.includes('/alpha_') ? 'alphaOrgPrivileges' : 'bravoOrgPrivileges', 'privilegeAssignments');",
      "type": "text/javascript"
    },
    "cache": {
      "maxTimeout": "300 seconds"
    },
    "scopes": [
      "fr:idm:*"
    ],
    "staticUserMapping": [ (1)
      {
        "subject": "myrcs1-client",
        "roles": [
          "myrcs1-client-authorized"
        ]
      }
    ],  (2)
    "subjectMapping": [
      {
        "additionalUserFields": [
          "adminOfOrg",
          "ownerOfOrg"
        ],
        "defaultRoles": [
          "internal/role/openidm-authorized"
        ],
        "propertyMapping": {
          "sub": "_id"
        },
        "queryOnResource": "managed/{{substring realm 1}}_user",
        "userRoles": "authzRoles/*"
      }
    ]
  }
}

1	Start of `staticUserMapping` attribute.
2	End of `staticUserMapping` attribute.

Replace the authentication configuration:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Content-type: application/json" \
--header "Accept-API-Version: resource=1.0"  \
--request PUT \
--data '{
  "_id": "access",
  "rsFilter": <authentication-configuration-object> (1)
}' \
"https://<tenant-env-fqdn>/openidm/config/authentication"

1	Replace <authentication-configuration-object> with the `rsFilter` object you modified in step 3.

Show response

{
  "_id": "authentication",
  "rsFilter": {
    "augmentSecurityContext": {
      "source": "require('auth/orgPrivileges').assignPrivilegesToUser(resource, security, properties, subjectMapping, privileges, security.authorization.component.includes('/alpha_') ? 'alphaOrgPrivileges' : 'bravoOrgPrivileges', 'privilegeAssignments');",
      "type": "text/javascript"
    },
    "cache": {
      "maxTimeout": "300 seconds"
    },
    "scopes": [
      "fr:idm:*"
    ],
    "staticUserMapping": [ (1)
      {
        "subject": "myrcs1-client",
        "roles": [
          "myrcs1-client-authorized"
        ]
      }
    ],
    "subjectMapping": [
      {
        "additionalUserFields": [
          "adminOfOrg",
          "ownerOfOrg"
        ],
        "defaultRoles": [
          "internal/role/openidm-authorized"
        ],
        "propertyMapping": {
          "sub": "_id"
        },
        "queryOnResource": "managed/{{substring realm 1}}_user",
        "userRoles": "authzRoles/*"
      }
    ]
  }
}

1	The authentication configuration contains the new `staticUserMapping` attribute.

You can also modify configuration using a PATCH request to the same endpoint.

The following example adds the same staticUserMapping attribute example in step 3 directly to the rsFilter attribute:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Content-type: application/json" \
--header "Accept-API-Version: resource=1.0"  \
--request PATCH \
--data '
[
  {
    "operation" : "add",
    "field" : "/rsFilter/staticUserMapping/", (1)
    "value" : [ {
        "subject" : "myrcs1_client",
        "roles" : [
          "myrcsclient1-authorized"
        ]
      }
    ]
  }
]' \
"https://<tenant-env-fqdn>/openidm/config/authentication"

1	If you specify the field name on its own (`/rsFilter/staticUserMapping/`), the value is added on the first request and overwrites on subsequent requests.

The following example appends an object to the staticUserMapping attribute:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Content-type: application/json" \
--header "Accept-API-Version: resource=1.0"  \
--request PATCH \
--data '
[
  {
    "operation" : "add",
    "field" : "/rsFilter/staticUserMapping/-", (1)
    "value" : {
      "subject" : "myrcs2_client",
      "roles" : [
        "myrcsclient2-authorized"
      ]
    }
  }
]' \
"https://<tenant-env-fqdn>/openidm/config/authentication"

1	If you specify the field name followed by a hyphen (`/rsFilter/staticUserMapping/-`), the value is appended.

PingOne Advanced Identity Cloud

Authentication and roles

Dynamic role calculation

Roles, authentication, and the security context

Change the authentication configuration over REST