Okta Identity Engine provides increased flexibility for Authentication with Application Level Policies and easy to configure passwordless sign-in experiences. These are covered extensively in our deployment guides: Authentication policies deployment guide and Passwordless authentication deployment guide. It also provides a simplified administrator experience by moving from Factor sequencing to Assurance Models. This new experience is simple and allows you to specify things like Any 1 Factor or Password + Another Factor or Any 2 Factors with the ability to specify constraints such as Phishing-resistance (i.e. FIDO2/WebAuthN) and Hardware protected (i.e. device has a TPM or secure enclave).
The downside of this new experience is that it is not possible in the standard administrator interface to specify specific factors to meet regulatory or other requirements. You may have specific factor requirements that you would like users to adhere to that you cannot specify in the web interface. For example several financial services customers would like the ability to force sending a push request via Okta Verify to a mobile device in the users possession. To achieve this level of customisation the Policy API needs to be used. This blog post will briefly detail how to use Postman to access the Policy API to create more fine grain authentication options for applications on Okta Identity Engine.
Postman is an API platform for building and using APIs. In this case we will be using the Postman desktop client to access Okta’s administration APIs. Okta publishes Postman Collections for its APIs which allows for easy use from any computer without any development. For details on how to setup Postman to use the Okta APIs please refer to Test the Okta REST APIs using Postman. For the examples in this blog post you’ll want to download the Policy API Collection.
Before diving into the API here it is worth briefly outlining how policies and rules work. An authentication policy is a collection of rules that can be applied to one or more applications. Each rule then consists of an IF and a THEN as shown below. The IF which specifies the conditions that must be met to trigger the rule such as Groups, Device Management status, platform type, IP range, Risk etc. The THEN specifies whether to allow access and what types of authentication is required.
While it is possible to perform all actions for policies with the API for the purposes of this blog I recommend creating a policy and assigning a test application to it in the web interface. To do this head to Security -> Authentication Policies in the Administrator interface and click Add a Policy. If you don’t have an Application that you’re comfortable playing around with for this example you could setup one of the Redirection Authentication apps from here. Once you have created a policy you can retrieve all the policies using the API by running the command Get Authentication Policies from inside the Authentication Policies Folder of the downloaded Postman collection. Once you have run this find the policy you have just created and set it as the {{policyId}} by highlighting and right clicking as below. This takes advantage of Postman’s environment variables collections.
Now that you have set the policy ID you can retrieve all current Rules by GETing {{url}}/api/v1/policies/{{policyId}}/rules If you’ve just created this policy it will just contain the Catch All Rule as shown below.
[
{
"id": "{{ruleId}}",
"status": "ACTIVE",
"name": "Catch-all Rule",
"priority": 99,
"created": "2022-09-01T06:01:13.000Z",
"lastUpdated": "2022-09-01T06:01:13.000Z",
"system": true,
"conditions": null,
"actions": {
"appSignOn": {
"access": "ALLOW",
"verificationMethod": {
"factorMode": "2FA",
"type": "ASSURANCE",
"reauthenticateIn": "PT12H",
"constraints": [
{
"possession": {
"deviceBound": "REQUIRED"
}
}
]
}
}
},
"_links": {
"self": {
"href": "https://{{url}}/api/v1/policies/{{policyId}}/rules/{{ruleId}}",
"hints": {
"allow": [
"GET",
"PUT"
]
}
}
},
"type": "ACCESS_POLICY"
}
]While you can modify the catch all rule it is just as easy to create a new rule for this policy by POSTing to {{url}}/api/v1/policies/{{policyId}}/rules/ with the appropriate body. Fortunately for us Okta has provided a sample that we can start with in the Postman collection Authentication Policies -> Create single factor password rule. To view the Sample Policy select the body tab in Postman. To specify PUSH as a single factor modify the actions section of the sample body as below. This specifies only 1 factor is required and that is needs to satisfy the constraint of being a possession factor with method PUSH and reauthentication is required every 2 hours. The full format and available options for these settings can be found in the developer documentation.
"actions": {
"appSignOn": {
"access": "ALLOW",
"verificationMethod": {
"factorMode": "1FA",
"reauthenticateIn": "PT2H",
"constraints": [
{
"possession": {
"methods": [ "PUSH"]
}
}
],
"type": "ASSURANCE"
}
}
}Once you have created the rule you can retrieve it by HTTP GETing {{url}}/api/v1/policies/{{policyId}}/rules/{{ruleId}} and if you with to modify an existing rule you HTTP PUT with the modified body. I recommend first GETing the existing policy and then changing the fields you wish to change and PUTing it back. There are several Verification Method JSON Examples in the documentation.
Please note that Factor Sequencing from Classic Engine has been replaced by Assurance Models as noted here. This does not provide the same level of explicit control for the administrator however it does make administration simpler and generally easier for the end user. For existing Classic customers currently using factor sequencing functionality will be preserved after upgrade. Additionally, OIE adds more detailed levels of device trust which can be leveraged for greater security. For example you can create application policies now such that only a managed device running Windows or macOS can access an application and leverage PUSH as a factor constraint to effectively require the employee to have 2 managed devices, their laptop and mobile phone, to access a particular application. Finally, we recommend using phishing resistant factors wherever possible i.e. WebAuthN/FIDO2 or Okta FastPass.
