IDX Authenticators Admin API

AuthenticatorsAdminAPI.md

Authenticator Admin API

Authenticator Admin API enables an Org Administrator to configure which authenticators are available to end users to be used for signing into applications.

End users would be required to use one or more authenticators depending on the security requirements of the application sign-on policy.

IDX currently supports authenticators for the following:

Knowledge based:

• Password
• Security Question

Possession based:

• Phone (supports SMS, Call)
• Email
• WebAuthn

Authenticator Admin Operations

Authenticator APIs involve working with authenticator objects.

Following is the schema of authenticator object

Authenticator object

{
    "type": Type of authenticator. Curently supported values: "password" | "security_question" | "phone" | "email" | "security_key"
    "id": Unique Id of the authenticator. Use this as the handle when referring to an authenticator.
    "key": Unique key of the authenticator.
    "name": Display name of the Authenticator. 
    "status": Status of the authenticator. Can be "ACTIVE" or "INACTIVE"
    "created": Created timestamp
    "lastUpdated": Last updated timestamp
    "_links": Link relations for this object
}

The Authenticator Admin API supports the following operations:

• List Authenticators available to activate or deactivate
• Activate an Authenticator
• Deactivate an Authenticator

List Authenticators

This lists all the authenticators that can be activated or deactivated

Request:

GET /api/v1/authenticators

Response: This API returns an array of authenticator objects.

Example Response:

[
  {
    "type": "email",
    "id": "aut1nbsPHh7jNjjyP0g4",
    "key": "okta_email",
    "status": "ACTIVE",
    "name": "Email",
    "created": "2020-07-26T21:05:23.000Z",
    "lastUpdated": "2020-07-26T21:05:23.000Z",
    "_links": {
        "self": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbsPHh7jNjjyP0g4",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      },
      "methods": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbsPHh7jNjjyP0g4/methods",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      }
    }
  },
  {
    "type": "password",
    "id": "aut1nbtrJKKA9m45a0g4",
    "key": "okta_password",
    "status": "ACTIVE",
    "name": "Password",
    "created": "2020-07-26T21:05:23.000Z",
    "lastUpdated": "2020-07-26T21:05:23.000Z",
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbtrJKKA9m45a0g4",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      },
      "methods": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbtrJKKA9m45a0g4/methods",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      }
    }
  },
  {
    "type": "phone",
    "id": "aut1nbuyD8m1ckAYc0g4",
    "key": "phone_number",
    "status": "INACTIVE",
    "name": "Phone",
    "created": "2020-07-26T21:05:23.000Z",
    "lastUpdated": "2020-07-26T21:09:53.000Z",
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbuyD8m1ckAYc0g4",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      },
      "methods": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbuyD8m1ckAYc0g4/methods",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "activate": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbuyD8m1ckAYc0g4/lifecycle/activate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
    "type": "security_key",
    "id": "aut1nd8PQhGcQtSxB0g4",
    "key": "webauthn",
    "status": "INACTIVE",
    "name": "Security Key or Biometric",
    "created": "2020-07-26T21:16:37.000Z",
    "lastUpdated": "2020-07-26T21:16:37.000Z",
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      },
      "methods": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/methods",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "activate": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/lifecycle/activate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
    "type": "security_question",
    "id": "aut1nbvIgEenhwE6c0g4",
    "key": "recovery_question",
    "status": "ACTIVE",
    "name": "Security Question",
    "created": "2020-07-26T21:05:23.000Z",
    "lastUpdated": "2020-07-26T21:05:23.000Z",
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbvIgEenhwE6c0g4",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "methods": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbvIgEenhwE6c0g4/methods",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "deactivate": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbvIgEenhwE6c0g4/lifecycle/deactivate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  }
]

Activate Authenticator

This API involves using the authenticator Id to activate.

Request:

POST /api/v1/authenticators/{authenticatorId}/lifecycle/activate

Request Path Parameters authenticatorId -> Id of the authenticator that needs to be activated

Response: This API returns the object of the authenticator that is activated

Example Response:

{
    "type": "security_key",
    "id": "aut1nd8PQhGcQtSxB0g4",
    "key": "webauthn",
    "status": "ACTIVE",
    "name": "Security Key or Biometric",
    "created": "2020-07-26T21:16:37.000Z",
    "lastUpdated": "2020-07-26T21:59:33.000Z",
    "_links": {
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4",
            "hints": {
                "allow": [
                    "GET",
                    "PUT"
                ]
            }
        },
        "methods": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/methods",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        },
        "deactivate": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/lifecycle/deactivate",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

Deactivate Authenticator

This API involves using the authenticator Id to deactivate.

Request:

POST /api/v1/authenticators/{authenticatorId}/lifecycle/deactivate

Request Path Parameters authenticatorId -> Id of the authenticator that needs to be deactivated

Response: This API returns the object of the authenticator that is deactivated

Example Response

{
    "type": "security_key",
    "id": "aut1nd8PQhGcQtSxB0g4",
    "key": "webauthn",
    "status": "INACTIVE",
    "name": "Security Key or Biometric",
    "created": "2020-07-26T21:16:37.000Z",
    "lastUpdated": "2020-07-26T22:01:46.000Z",
    "_links": {
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4",
            "hints": {
                "allow": [
                    "GET",
                    "PUT"
                ]
            }
        },
        "methods": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/methods",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        },
        "activate": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/lifecycle/activate",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

In the List Authenticators example above - The Phone Authenticator has the allowedForSSO field, while the email doesn't. I think we should show it for both, or just omit it altogether in the API docs.
The allowedForSSO setting basically applies to only Phone and Email Authenticator(s) and it is only displayed (returned) if allowedForSSO=false, and once it is toggled to true - it is an irreversible one-time operation and is never set in the response after that even for Phone/Email.

A few comments:

• At the top, while listing the possession based factors, nit Webauthn -> WebAuthn
• At the List Authenticators Example Response: would "settings" always be shown even if empty (e.g. in the "email" authenticator object)? If so, then I guess we would want to display it for "password", "security_key", and "security_question" authenticators as well; otherwise remove from "email" maybe
• Looks like we do allow PUT requests on the self links -- does this mean we should document the PUT endpoints too?

Summary of decisions:

• We are not going to doc "allowedForSSO" setting.
• We are documenting only the list, activate, deactivate APIs for now