Security Enforcement Integrations

Write back to enforce policy in Okta

Building from the foundation laid in our Security Analytics guide

To resolve an incident or mitigate a perceived threat, an external system may want to affect a user’s state, modify authentication policies or reduce application availability. This document will describe how and when a system might take these actions.

Information About Examples

Simplified Examples

For readability simplified versions of the API transactions are illustrated below. We use the following modifications:

  • Repetitive details like content-type and authorization headers will be excluded
  • Request and response objects will be truncated to focus on the most relevant information
    • Truncated sections will be denoted by an ellipsis (“…”)
  • In syntax statements introducing each endpoint, the base URL is omitted.
  • Replacement values will be noted in italicized braces {}
  • Examples:
    • {yourOktaDomain}.com = Base URL of the Okta org (e.g. https://acme.okta.com ) If you are logged in, your Okta domain name appears instead of the placeholder.
    • {user_id} = Opaque and Immutable Okta ID for a user (e.g. 00u1ae58uup0y5Qkg1d8)
    • {group_id} = Opaque and Immutable Okta ID for a group (e.g. 00g1at1k0dzmV839P1d8)

Resolving Okta identifiers

When using logs from Okta to write back to Okta, the values for user_id, group_id and others will be present in the log. They will be found in the actor or target object, along with other references suitable for distinction.

When using logs from outside of Okta to trigger to coorelate or trigger events, use the lookup and search functions described in the Users and Groups sections above to retrieve the Okta identifier for those objects.

Examples

Users

An individual user’s state, sessions, credentials and profile can be updated depending on the specific use case.

User - Change State

A user’s state can be toggled according to a prescribed state machine

Suspending a user is a non-destructive operation that will leave a user profile, credentials, enrolled factors, groups membership and assigned applications intact while still preventing the user from signing into Okta or any subordinate application. The act of suspending a user will destroy any existing Okta session for that user.

Suspend a User

Request

POST https://{yourOktaDomain}.com/api/v1/users/{user_id}/lifecycle/suspend

Response

HTTP/1.1 200 OK

To reverse this operation after a threat has been cleared or an internal timer has elapsed you can return a suspended user back to an active state:

Unsuspend a User

Request

POST https://{yourOktaDomain}.com/api/v1/users/{user_id}/lifecycle/unsuspend

Response

HTTP/1.1 200 OK

There are other user state operations that can be changed. Be aware of the full effect of such changes before implementing this feature. Read our online documentation for more details about user lifecycle operations.

User - Clear Sessions

You can clear existing user sessions, forcing a user to authenticate on the next operation. This action may be taken alone to clear suspicious sessions or in conjunction with other actions – like changing authentication policies to enforce MFA or expiring a password – to accelerate the enforcement of that change.

Clear User Session

Request

DELETE https://{yourOktaDomain}.com/api/v1/users/{user_id}/sessions

Response

HTTP/1.1 204 NO CONTENT

User - Credentials

In certain situations, expiring or changing a user’s password might also be prudent. Okta provides a consistent mechanism for expiring and changing passwords for users regardless of password authority. For example, when integrated with an on premise Active Directory (AD) expiring or resetting passwords will propagate through Okta to AD with no changes required to the calling client.

While there are more operations you can perform against a user’s credentials we will focus on expiring and changing passwords. Changing or expiring a password does not clear existing sessions for that user.

User - Expire Password

Use this flow to expire a password. This will cause a user to be foreced to change their current password the next time they login to a connected system. Applies to AD mastered accounts too.

Expire Password

Request

POST https://{yourOktaDomain}.com/api/v1/users/{user_id}/lifecycle/expire_password

Response

{
  "id": "{user_id}",
  "...": "...",
}
User - Reset Password Flow 1

Use this password expiration flow along with a flag to define a tempPassword, as a result the password will be expired and a randomly generated yet policy compliant password will be set. With this flow you can determine what – if anything – is done with the returned tempPassword. Key benefits associated with this flow are:

  • Not needing to develop different password reset or expiration flows based on an underlying directory
    • Okta will broker the password reset if there is an underlying directory
  • Not needing to code in password complexity parameters or risk generating passwords that aren’t compliant
    • Okta is aware of it’s own policies or the policies of the underlying directory and will generate compliant passwords

Expire Password with random tempPassword

Request

POST https://{yourOktaDomain}.com/api/v1/users/{user_id}/lifecycle/expire_password?tempPassword=True

Response

{
  "tempPassword": "{compliantPassword"
}
User - Reset Password Flow 2

Use this password reset flow to generate an Okta password reset flow link. Use of these links is contingent upon an Okta Org having a password reset flows enabled and will require additional security measures based on the configuration of the Okta org. These additional security measures can include password reset Security Question and SMS challenge.

Using an Okta password reset link will direct the user to an Okta password reset sequence. You can choose to have Okta send the link to the user directly or you can have the link returned and choose to provide it to the user through other means.

Reset a password

Request (Okta returns link)

#have the password reset link returned
POST https://{yourOktaDomain}.com/api/v1/users/{user_id}/lifecycle/reset_password?sendEmail=False

Response (Okta returns link)

{
  "resetPasswordUrl": "{yourOktaDomain}.com/reset_password/XE6wE17zmphl3KqAPFxO"
}

Request (Okta sends link)

#have Okta send the email
POST https://{yourOktaDomain}.com/api/v1/users/{user_id}/lifecycle/reset_password?sendEmail=True

Response (Okta sends link)

{
  "id": "{user_id}",
  "...": "...",
}

User - Profile

With the backing of Universal Directory, Okta Expression Language and rules based groups, a user profile is also a prime mechanism to enforce policy in Okta

  • Profile mappings can change user state in downstream applications based on an attribute value
  • Rules based group memberships can be driven by a variety of inputs, one of which is user attribute values

The following are ways to benefit from these capabilities

  • Extend a user profile
    • example add a health indicator attribute
  • Configure policies in Okta based on that attribute value
  • Configure an integration to manipulate that value in Okta based on your observations
    • example a UEBA might be configured to set a health indicator attribute to indicate risk
    • example rules in Okta could drive group memberships based on attribute value
    • example application assignment, sign-on and authentication policies could be driven by membership (or lack of) of such a rule based group

User attributes are:

  • Extensible
  • Strongly Typed (string, number, Boolean, integer, etc.)
  • Capable of being mapped downstream or leveraged by rules based groups
  • Discoverable through our Schemas API
User - Profile Change

Even with all this power and flexibility a partial update of a user profile to a known or set of known attributes is a simple operation.

Update Profile

Request

POST https://{yourOktaDomain}.com/api/v1/users/{user_id}
"{
  "profile":
  {
    "uebaHealth": 75
  }
}"

Response

{
  "id": "{user_id}",
  "...": "...",
  "profile":
  {
      "...": "...",
      "uebaHealth": 75
  },
  "...":"..."
}

Groups

Groups are a first-class citizen in the Okta environment. They serve purposes including but not limited to:

  • Application Assignment
  • Application Role
  • Policy Assignment

With that in mind, the simple manipulation of group membership can have far reaching effects to strengthen your customer’s security posture.
For example

  • Adding a user to a group could enforce a restrictive authentication policy with short session lifetimes that always require MFA policy
  • Removing a user from a group could un-assign a sensitive application or remove a permissive role in a downstream application

As previously mentioned, the {group_id} referenced below is an opaque Okta ID and may need to be discovered or configured in some way.
Refer to the Groups section in our analytics guide for ideas related to working with groups.

Group - Add Member

Follow these steps to add a user to a group

Request

PUT https://{yourOktaDomain}.com/api/v1/users/{user_id}

Response

HTTP/1.1 204 No Content

Group - Remove Member

Follow these steps to remove a user from a group

Request

DELETE https://{yourOktaDomain}.com/api/v1/users/{user_id}

Response

HTTP/1.1 204 No Content
Top of Page