Runtime API Endpoints
This section provides details about the PolicyServer Runtime API endpoints and routes. See detailed descriptions for exact payloads.
Route |
Method |
Name |
|---|---|---|
POST |
Evaluate Policy |
Evaluate Policy
To evaluate a policy, the name of the policy is required and the claims of the user must be submitted to the runtime endpoint. The result will be the roles and permissions the user is assigned to for the requested policy.
For a policy named EmergencyRoom and a user with a subject identifier of 1 the exchange would be:
Request
POST /runtime/policy/EmergencyRoom
Data posted:
{
"Claims": [
{
"Type": "sub",
"Value": "1"
}
]
}
Successful Response
Data returned:
{
"roles": ["doctor"],
"permissions": ["SeePatients","PerformSurgery","PrescribeMedication"]
}
Note that when sending a policy evaluation request, the sub claim type is used as the user’s unique identifier, and the role claim type is used as the external role identifier for user assignments to application roles.
The tenant claim type is used to indicate for which tenant the user is to be evaluated.
Multiple sub or tenant claims are not allowed.
An error response would return a status code of 400 and a response payload as such:
Error Response
Data returned:
{
"errors": ["Too many subject ids provided."]
}
Policy Hierarchy Evaluation
Policies can be defined in a hierarchy.
The name of the policy is defined by a path made up of the policy names in the hierarchy, separated by the / character.
For example, the name of the MedicalRecords policy defined as a child of the HospitalSystem policy would be HospitalSystem/MedicalRecords.
When evaluating a policy in the hierarchy, this path is passed as the {policyName} parameter in the URL, as such:
Request
POST /runtime/policy/HospitalSystem/MedicalRecords
Data posted:
{
"Claims": [
{
"Type": "sub",
"Value": "1"
}
]
}
Response
Data returned:
{
"roles": ["Admin"],
"permissions": ["Create","Delete"]
}
The returned roles and permissions are the accumulated roles and permissions across both policies in the hierarchy.
Debugging Policy Hierarchy Evaluation
When evaluating a policy that resides within a hierarchy, roles and permissions can be assigned at any level in the hierarchy.
If you wish to debug which policy in the hierarchy has made specific assignments, the IncludePolicyDiagnostics flag can be used:
Request
POST /runtime/policy/HospitalSystem/MedicalRecords
Data posted:
{
"Claims": [
{
"Type": "sub",
"Value": "1"
}
],
"IncludePolicyDiagnostics": true
}
Response
Data returned:
{
"roles": ["Admin"],
"permissions": ["Create","Delete"],
"diagnostics": {
"segments": [
{
"path":"/HospitalSystem",
"tenant":null,
"rolesAdded":["Admin"],
"rolesRemoved":[],
"permissionsAdded":[]
},
{
"path":"/HospitalSystem/MedicalRecords",
"tenant":null,
"rolesAdded":[],
"rolesRemoved":[],
"permissionsAdded":["Create","Delete"]
}
]
}
}
The top level roles and permissions results are the same as before for the same policy.
But notice that the diagnostics indicates that the Admin role was assigned at the HospitalSystem policy, whereas the Create and Delete permissions were assigned at the MedicalRecords level in the policy hierarchy.
Evaluating Child Policies
When evaluating a policy, you can also request that the child policies are also evaluated and returned in the response (which includes the child policies’ roles and permissions) with the EvaluateChildPolicies parameter.
This only evaluates the immediate child policies, not the entire descendant hierarchy. If no roles or permissions are matched in the child policy, then the child policy is not included in the response. This indicates that the user has no access to the policy.
Request
POST /runtime/policy/HospitalSystem
Data posted:
{
"Claims": [
{
"Type": "sub",
"Value": "1"
}
],
"EvaluateChildPolicies" : true
}
Response
Data returned:
{
"roles": ["Admin"],
"permissions": [],
"childPolicies":[
{
"name":"MedicalRecords",
"roles":["Admin"],
"permissions":["Create","Delete"]
},
{
"name":"Accounting",
"roles":["Admin"],
"permissions":["SubmitToInsurance","PayInvoice"]
}
]
}
The above response shows that the user was in the Admin role for the Hospital policy, but had no permissions assigned.
In the Hospital/MedicalRecords policy the user was in the Admin role, and had the Create and Delete permissions assigned.
Similarly, in the Hospital/Accounting policy the user was in the Admin role, and had the SubmitToInsurance and PayInvoice permissions assigned.
Evaluating Descendant Policies
When evaluating child policies (as described above), children where no role or permission is issued is not emitted in the response. There might be descendant policies beneath the child that do have role or permission assignments, but when simply evaluating child policies those are not taken into consideration.
If, when evaluating child policies, you do want the policies where some assignment is granted somewhere in the descendant policy hierarchy, then include the IncludeChildrenWithDescendantAssignments in the request.
Request
POST /runtime/policy/Hospitals
Data posted:
{
"Claims": [
{
"Type": "sub",
"Value": "1"
}
],
"EvaluateChildPolicies" : true,
"IncludeChildrenWithDescendantAssignments" : true
}
Response
Data returned:
{
"roles": [],
"permissions": [],
"childPolicies":[
{
"name":"Hospital1",
"roles":["HospitalAdmin"],
"permissions":[]
},
{
"name":"Hospital2",
"roles":[],
"permissions":[]
}
]
}
Note in the above example the Hospital1 child policy has roles assigned, whereas the Hospital2 policy does not.
This indicates that the Hospital1 policy had an explicit role assignment at the Hospital1 policy in the policy hierarchy.
Conversely, Hospital2 did not have any explicit assignments for the user, but some descendant policy of Hospital2 did have an assignment for the user, therefore Hospital2 was included in the results.
The descendant policies of Hospital2 for which the roles or permissions are assigned are not included.
To determine which descendant policies have the assignment, another policy evaluation that includes children (and possibly descendants) would be required for the Hospitals/Hospital2 policy.
Passing Application Roles
Normally application roles are evaluated by PolicyServer and included in the results of a policy evaluation. But in some circumstances an application might already know or want to treat the user as if they are in an application role. This can be used if the application only wants to know the permissions of a policy evaluation for the application role.
The ApplicationRoles parameter in a policy evaluation request allows an application to make this type of policy evaluation request.
Request
POST /runtime/policy/EmergencyRoom
Data posted:
{
"Claims": [],
"ApplicationRoles": ["doctor"]
}
Response
Data returned:
{
"roles": [],
"permissions": ["SeePatients","PerformSurgery","PrescribeMedication"]
}
Notice in the above response, no user claims are passed in the request, yet the response returns the permissions a user that is mapped to the doctor role would normally be granted.
Include Tenant roles
Normally the runtime API evaluation return the subject roles in all policies, but does not include the tenant roles even if the tenant claim was sent in the evaluation request.
The IncludeTenantRoles parameter in a policy evaluation request allows the runtime API to include the roles for the tenant claim sent in the request.
Request
POST /runtime/policy/EmergencyRoom
Data posted:
{
"Claims": [
{
"Type": "sub",
"Value": "1"
},
{
"Type": "tenant",
"value": "tenant1"
}
],
"IncludeTenantRoles" : true,
}
Response
Data returned:
{
"roles": [
"doctor",
"tenantRole"
],
"permissions": [
"PerformSurgery",
"PrescribeMedication",
"SeePatients"
],
"childPolicies": null,
"diagnostics": null,
"errors": null
}