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:
- Password
- Security Question
- Phone (supports SMS, Call)
- WebAuthn
Authenticator APIs involve working with authenticator objects.
Following is the schema of 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
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"
]
}
}
}
}
]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"
]
}
}
}
}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"
]
}
}
}
}
A few comments:
Webauthn->WebAuthn"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