Rotate a device registration secret

Rotate a secret when you suspect that its value was exposed, or when the secret reaches its maximum number of registrations.

About this task

Early Access release

You can't change the value of an existing secret. Instead, generate a new secret, move the devices that haven't registered yet to the new secret, and then deactivate the old secret.

Devices that already registered don't need the new secret. Only devices that are still Preregistered are affected.

You can move the devices in the Admin Console or with the Okta API.

Before you begin

  • To use the Admin Console, sign in as a super admin or an org admin. These roles have the Manage devices and Manage device integrations permissions. See Devices permissions by admin role.
  • To send the API requests in this task, obtain an API token created by a super admin or an org admin, or an OAuth 2.0 access token with the okta.deviceIntegrations.manage and okta.devices.manage scopes. Authenticate the API requests with that token. See Manage Okta API tokens.
  • Find the devices that haven't registered. On the Devices page, filter by the Preregistered status. If you use the API, also note the serial number and platform of each device.

Procedure

  1. Generate a new secret. See Create a device registration secret.

    Copy the new secret value. If you plan to use the API, also note the ID of the new secret. Keep the old secret active until you finish the rotation.

  2. Move the devices that haven't registered to the new secret.

    In the Admin Console, preregister the devices again with the new secret. Follow the steps in Preregister mobile devices, with these changes:

    • On the Select devices step, remove the Imported filter and filter by the Preregistered status. Then select the devices that haven't registered.
    • On the Choose secret key step, select Use existing secret key and select the new secret.

    To move the devices with the API instead, send a POST request to /device-identity/api/v1/registration-grants with the serial number, the platform, and the ID of the new secret for each device. A request can include up to 1,000 devices. Devices that are still waiting to register move to the new secret. If any device in the request can't be updated, the whole request fails and Okta changes no devices. The response lists every error, so you can correct them and send the request again.

    [
      {
        "serialNumber": "DNQJQ4GFF1GH",
        "platform": "IOS",
        "registrationGrants": [
          {
            "grantType": "DEVICE_REGISTRATION",
            "registrationSecretId": "{newSecretId}"
          }
        ]
      }
    ]
  3. In your Mobile Device Management (MDM) solution, replace the OktaVerify.DeviceRegistrationSecret value with the new secret value for those devices.

    Use the secret value, not the secret ID. See Set up Device Posture Sensor Mode on mobile devices.

  4. Sync the devices in your MDM solution, and make sure that Okta Verify runs once on each device.
  • Deactivate the old secret

    After all the devices that you moved are Active, deactivate the old secret.

    1. In the Admin Console, go to Security > Device Integrations.
    2. Select the Device registration tab.
    3. In the Secret for device registration section, open the Actions menu for the old secret and select Edit.
    4. Under Trust this secret for Device Registration?, select Not now.

      A device can't register with a secret that you don't trust.

    5. Select Save.

      To deactivate the secret with the API instead, send a PUT request to /device-identity/api/v1/registration-secrets/{oldSecretId} and set status to INACTIVE. Preserve the current description and registration limit: replace {existingDescription} and 10000 in the example with the secret's existing values. A device can't register with an inactive secret.

      {
        "description": "{existingDescription}",
        "status": "INACTIVE",
        "maxRegistrations": 10000
      }

    New and unregistered devices register with the new secret. The old secret is inactive and can't register devices.