Manage org recovery with Okta Enhanced Disaster Recovery

Early Access

This guide explains how to manage a failover and failback of your Okta org using Okta Enhanced Disaster Recovery (DR).

Note: Enhanced DR is a self-service Early Access (EA) feature. See Manage Early Access and Beta features (opens new window) to enable.

---

Learn outcomes

• Check the disaster recovery status for your org using the Okta API.
• Initiate an org failover using the Okta API.
• Initiate an org failback using the Okta API.
• Review the System Log data and notifications for disaster recovery.

What you need

• An Okta production org (Enhanced DR is not available for Okta Preview or Okta Integrator Free Plan orgs)
• The Enhanced DR product enabled for your org
• Super administrator privileges or Enhanced DR privileges
• Enhanced Disaster Recovery APIs (opens new window)

---

About Okta Enhanced Disaster Recovery

Okta Enhanced DR reduces the recovery time objective (RTO) from one hour to five minutes in the event of a regional infrastructure-related outage. Enhanced DR improves on the standard disaster recovery RTO available to all Okta production orgs. It ensures service continuity during total regional outages, allowing users to continue authenticating into all their apps. In Enhanced DR mode, your Okta org becomes read-only. See Understanding Okta's "Read-only Mode" (opens new window).

Enhanced DR also supports self-service failover, which grants admins the ability to initiate an org failover and failback. Admins can initiate failover and failback through APIs or the Okta Disaster Recovery Admin app (opens new window). See the following sections on how to manage Enhanced DR using the Okta APIs.

Note: If your server or network policies restrict traffic to certain IPs, Okta recommends that you allow access to the Okta cell IPs. See Allow access to Okta IP addresses (opens new window).

User roles and permissions for Enhanced DR

You can manage Enhanced DR by using the super administrator role or by creating a custom role.

To create an Enhanced DR custom role, use the Admin Console or the APIs. See Roles in Okta (opens new window) or Use custom admin roles (opens new window). The following permissions, resource, and resource type are required when creating the Enhanced DR custom role:

• Permissions: Manage disaster recovery (okta.dr.manage) or view disaster recovery (okta.dr.read)
• Resource type: Business continuity
• Resource: Disaster recovery

Make secure API requests with OAuth 2.0

Okta Enhanced DR only supports API access through scoped OAuth 2.0 access tokens, and uses the following scopes: okta.dr.manage, okta.dr.read.

To make secure Okta API requests to configure your Okta orgs, obtain OAuth 2.0 access tokens for the Authorization header in requests. The Okta setup to obtain access tokens depends on whether you want the token to have a user-based or a service-based context:

• User-based access: The access token is tied to a specific admin user. For this access, you need to provide an Okta admin username and credentials. See User-based API access setup. Grant the appropriate scopes for your endpoint and use case. Use this access type for simple testing of the APIs.
• Service-based access: If you have a service app or script that makes API requests to Okta without user context, see Service-based API access setup. Grant the appropriate scopes for your endpoint and use case.

Check the disaster recovery status of your org

Use the following disaster recovery API endpoint, https://drapp.{yourOktaDomain}/api/v1/dr/status (Retrieve the disaster recovery status for all domains for your org (opens new window)), to understand the current disaster recovery state for all domains associated with your Okta org.

Note: The base URL for the disaster recovery APIs is https://drapp.{yourOktaDomain}/. Replace {yourOktaDomain} with your Okta domain. For example, if your Okta domain is https://example.okta.com, use https://drapp.example.okta.com.

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {yourAccessToken}" \
"https://drapp.{yourOktaDomain}/api/v1/dr/status"

Response example

{
    "status": [
        {
            "domain": "yourOktaDomain.okta.com",
            "isFailedOver": false
        }
    ]
}

Initiate an org failover

Use the following disaster recovery API to initiate your org failover: https://drapp.{yourOktaDomain}/api/v1/dr/failover (Start the failover of your org (opens new window)). The request body is optional. You can specify a domain to failover, an empty object ({}), or no payload.

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {yourAccessToken}" \
"https://drapp.{yourOktaDomain}/api/v1/dr/failover"

After a failover, all end users in that org are in read-only mode (opens new window).

Response example

{
    "results": [
        {
        "domain": "yourOktaDomain.okta.com",
        "message": "Failover was successful"
        }
    ]
}

Initiate an org failback

Use the following disaster recovery API to initiate your org failback: https://drapp.{yourOktaDomain}/api/v1/dr/failbackStart (Start the failback of your org (opens new window)). The request body is optional. You can specify a domain to failback, an empty object ({}), or no payload.

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {yourAccessToken}" \
"https://drapp.{yourOktaDomain}/api/v1/dr/failback"

Response example

{
    "results": [
        {
        "domain": "yourOktaDomain.okta.com",
        "message": "Failback was successful"
        }
    ]
}

Review disaster recovery auditing data

Review the Enhanced DR status in the System Log. Use the System Log API (opens new window) or review through the Admin Console to confirm details on the org failover or failback. Search on the event types system.dr.failover or system.dr.failback.

Note: Your OAuth 2.0 scoped token requires the okta.logs.read scope to call the System Log endpoint.

Request example

Filter on both enhanced DR event types:

filter=eventType eq "system.dr.failback" or eventType eq "system.dr.failover"

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {yourAccessToken}" \
"https://{yourOktaDomain}/api/v1/logs?filter=eventType%20eq%20%22system.dr.failback%22%20or%20eventType%20eq%20%22system.dr.failover%22"

Response example

Note: The response is truncated for clarity.

{ ...
    "displayMessage": "The Enhanced Disaster Recovery (EDR) failover operation for the org domains was initiated",
    "eventType": "system.dr.failover",
    "outcome": {
        "result": "SUCCESS",
        "reason": null
    },
  ...
}

The super administrator accounts also receive email notifications during the failover and failback process.