OathModule

Realm Operations

Resource path: /realm-config/authentication/modules/oath

Resource version: 1.0

create

Usage:

am> create OathModule --realm Realm --id id --body body

Parameters:

--id

The unique identifier for the resource.

--body

The resource in JSON format, described by the following JSON schema:

{
  "type" : "object",
  "properties" : {
    "oathAlgorithm" : {
      "title" : "OATH Algorithm to Use",
      "description" : "Choose the algorithm your device uses to generate the OTP.<br><br>HOTP uses a counter value that is incremented every time a new OTP is generated. TOTP generates a new OTP every few seconds as specified by the time step interval.",
      "propertyOrder" : 500,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "truncationOffset" : {
      "title" : "Truncation Offset",
      "description" : "This adds an offset to the generation of the OTP.<br><br>This is an option used by the HOTP algorithm that not all devices support. This should be left default unless you know your device uses a offset.",
      "propertyOrder" : 900,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "forgerock-oath-sharedsecret-implementation-class" : {
      "title" : "The Shared Secret Provider Class",
      "description" : "The fully qualified class name for the Shared Secret Provider extension.<br><br>The class that is used to process the user profile attribute used to store the user secret key.",
      "propertyOrder" : 1300,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "authenticationLevel" : {
      "title" : "Authentication Level",
      "description" : "The authentication level associated with this module.<br><br>Each authentication module has an authentication level that can be used to indicate the level of security associated with the module; 0 is the lowest (and the default).",
      "propertyOrder" : 100,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "minimumSecretKeyLength" : {
      "title" : "Minimum Secret Key Length",
      "description" : "Number of hexadecimal characters allowed for the Secret Key.",
      "propertyOrder" : 300,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "timeStepSize" : {
      "title" : "TOTP Time Step Interval",
      "description" : "The TOTP time step in seconds that the OTP device uses to generate the OTP.<br><br>This is the time interval that one OTP is valid for. For example, if the time step is 30 seconds, then a new OTP will be generated every 30 seconds. This makes a single OTP valid for only 30 seconds.",
      "propertyOrder" : 1000,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "stepsInWindow" : {
      "title" : "TOTP Time Steps",
      "description" : "The number of time steps to check before and after receiving a OTP.<br><br>This is the number of time step intervals to check the received OTP against both forward in time and back in time. For example, with 2 time steps and a time step interval of 30 seconds the server will allow a clock drift between client and server of 89 seconds. (2-30 second steps and 29 seconds for the interval that the OTP arrived in)",
      "propertyOrder" : 1100,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "addChecksum" : {
      "title" : "Add Checksum Digit",
      "description" : "This adds a checksum digit to the OTP.<br><br>This adds a digit to the end of the OTP generated to be used as a checksum to verify the OTP was generated correctly. This is in addition to the actual password length. You should only set this if your device supports it.",
      "propertyOrder" : 800,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "secretKeyAttribute" : {
      "title" : "Secret Key Attribute Name",
      "description" : "The name of the attribute in the user profile to store the user secret key.",
      "propertyOrder" : 400,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "lastLoginTimeAttribute" : {
      "title" : "Last Login Time Attribute",
      "description" : "Attribute to store the time of the users last login. This is required if TOTP is chosen as the OATH algorithm.<br><br>This attribute stores the last time a user logged in to prevent time based attacks. The value is stored as a number (Unix Time).",
      "propertyOrder" : 1200,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "oathOtpMaxRetry" : {
      "title" : "One Time Password Max Retry",
      "description" : "The number of times entry of the OTP may be attempted. Minimum is 1 maximum is 10 and default is 3.",
      "propertyOrder" : null,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "passwordLength" : {
      "title" : "One Time Password Length ",
      "description" : "The length of the generated OTP in digits. Must be 6 digits or longer.",
      "propertyOrder" : 200,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "forgerock-oath-maximum-clock-drift" : {
      "title" : "Maximum Allowed Clock Drift",
      "description" : "Number of time steps a client is allowed to get out of sync with the server before manual resynchronisation is required. This should be greater than the TOTP Time Steps value.<br><br>As this checks the time drift over multiple requests it needs to be greater than the value specified in TOTP Time Steps.",
      "propertyOrder" : 1500,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "hotpWindowSize" : {
      "title" : "HOTP Window Size",
      "description" : "The size of the window to resynchronize with the client.<br><br>This sets the window that the OTP device and the server counter can be out of sync. For example, if the window size is 100 and the servers last successful login was at counter value 2, then the server will accept a OTP from the OTP device that is from device counter 3 to 102.",
      "propertyOrder" : 600,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "forgerock-oath-observed-clock-drift-attribute-name" : {
      "title" : "Clock Drift Attribute Name",
      "description" : "The name of the attribute in the user profile to store the clock drift. If left empty then clock drift checking is disabled.<br><br>The name of the attribute used to store the last observed clock drift which is used to indicated when a manual resynchronisation is required.",
      "propertyOrder" : 1400,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "hotpCounterAttribute" : {
      "title" : "Counter Attribute Name",
      "description" : "The name of the attribute in the user profile to store the user counter. This is required if HOTP is chosen as the OATH algorithm.",
      "propertyOrder" : 700,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    }
  }
}

delete

Usage:

am> delete OathModule --realm Realm --id id

Parameters:

--id

The unique identifier for the resource.

getAllTypes

Obtain the collection of all secondary configuration types related to the resource.

Usage:

am> action OathModule --realm Realm --actionName getAllTypes

getCreatableTypes

Obtain the collection of secondary configuration types that have yet to be added to the resource.

Usage:

am> action OathModule --realm Realm --actionName getCreatableTypes

nextdescendents

Obtain the collection of secondary configuration instances that have been added to the resource.

Usage:

am> action OathModule --realm Realm --actionName nextdescendents

query

Get the full list of instances of this collection. This query only supports `_queryFilter=true` filter.

Usage:

am> query OathModule --realm Realm --filter filter

Parameters:

--filter

A CREST formatted query filter, where "true" will query all.

read

Usage:

am> read OathModule --realm Realm --id id

Parameters:

--id

The unique identifier for the resource.

update

Usage:

am> update OathModule --realm Realm --id id --body body

Parameters:

--id

The unique identifier for the resource.

--body

The resource in JSON format, described by the following JSON schema:

{
  "type" : "object",
  "properties" : {
    "oathAlgorithm" : {
      "title" : "OATH Algorithm to Use",
      "description" : "Choose the algorithm your device uses to generate the OTP.<br><br>HOTP uses a counter value that is incremented every time a new OTP is generated. TOTP generates a new OTP every few seconds as specified by the time step interval.",
      "propertyOrder" : 500,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "truncationOffset" : {
      "title" : "Truncation Offset",
      "description" : "This adds an offset to the generation of the OTP.<br><br>This is an option used by the HOTP algorithm that not all devices support. This should be left default unless you know your device uses a offset.",
      "propertyOrder" : 900,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "forgerock-oath-sharedsecret-implementation-class" : {
      "title" : "The Shared Secret Provider Class",
      "description" : "The fully qualified class name for the Shared Secret Provider extension.<br><br>The class that is used to process the user profile attribute used to store the user secret key.",
      "propertyOrder" : 1300,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "authenticationLevel" : {
      "title" : "Authentication Level",
      "description" : "The authentication level associated with this module.<br><br>Each authentication module has an authentication level that can be used to indicate the level of security associated with the module; 0 is the lowest (and the default).",
      "propertyOrder" : 100,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "minimumSecretKeyLength" : {
      "title" : "Minimum Secret Key Length",
      "description" : "Number of hexadecimal characters allowed for the Secret Key.",
      "propertyOrder" : 300,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "timeStepSize" : {
      "title" : "TOTP Time Step Interval",
      "description" : "The TOTP time step in seconds that the OTP device uses to generate the OTP.<br><br>This is the time interval that one OTP is valid for. For example, if the time step is 30 seconds, then a new OTP will be generated every 30 seconds. This makes a single OTP valid for only 30 seconds.",
      "propertyOrder" : 1000,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "stepsInWindow" : {
      "title" : "TOTP Time Steps",
      "description" : "The number of time steps to check before and after receiving a OTP.<br><br>This is the number of time step intervals to check the received OTP against both forward in time and back in time. For example, with 2 time steps and a time step interval of 30 seconds the server will allow a clock drift between client and server of 89 seconds. (2-30 second steps and 29 seconds for the interval that the OTP arrived in)",
      "propertyOrder" : 1100,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "addChecksum" : {
      "title" : "Add Checksum Digit",
      "description" : "This adds a checksum digit to the OTP.<br><br>This adds a digit to the end of the OTP generated to be used as a checksum to verify the OTP was generated correctly. This is in addition to the actual password length. You should only set this if your device supports it.",
      "propertyOrder" : 800,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "secretKeyAttribute" : {
      "title" : "Secret Key Attribute Name",
      "description" : "The name of the attribute in the user profile to store the user secret key.",
      "propertyOrder" : 400,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "lastLoginTimeAttribute" : {
      "title" : "Last Login Time Attribute",
      "description" : "Attribute to store the time of the users last login. This is required if TOTP is chosen as the OATH algorithm.<br><br>This attribute stores the last time a user logged in to prevent time based attacks. The value is stored as a number (Unix Time).",
      "propertyOrder" : 1200,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "oathOtpMaxRetry" : {
      "title" : "One Time Password Max Retry",
      "description" : "The number of times entry of the OTP may be attempted. Minimum is 1 maximum is 10 and default is 3.",
      "propertyOrder" : null,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "passwordLength" : {
      "title" : "One Time Password Length ",
      "description" : "The length of the generated OTP in digits. Must be 6 digits or longer.",
      "propertyOrder" : 200,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "forgerock-oath-maximum-clock-drift" : {
      "title" : "Maximum Allowed Clock Drift",
      "description" : "Number of time steps a client is allowed to get out of sync with the server before manual resynchronisation is required. This should be greater than the TOTP Time Steps value.<br><br>As this checks the time drift over multiple requests it needs to be greater than the value specified in TOTP Time Steps.",
      "propertyOrder" : 1500,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "hotpWindowSize" : {
      "title" : "HOTP Window Size",
      "description" : "The size of the window to resynchronize with the client.<br><br>This sets the window that the OTP device and the server counter can be out of sync. For example, if the window size is 100 and the servers last successful login was at counter value 2, then the server will accept a OTP from the OTP device that is from device counter 3 to 102.",
      "propertyOrder" : 600,
      "required" : true,
      "type" : "integer",
      "exampleValue" : ""
    },
    "forgerock-oath-observed-clock-drift-attribute-name" : {
      "title" : "Clock Drift Attribute Name",
      "description" : "The name of the attribute in the user profile to store the clock drift. If left empty then clock drift checking is disabled.<br><br>The name of the attribute used to store the last observed clock drift which is used to indicated when a manual resynchronisation is required.",
      "propertyOrder" : 1400,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    },
    "hotpCounterAttribute" : {
      "title" : "Counter Attribute Name",
      "description" : "The name of the attribute in the user profile to store the user counter. This is required if HOTP is chosen as the OATH algorithm.",
      "propertyOrder" : 700,
      "required" : true,
      "type" : "string",
      "exampleValue" : ""
    }
  }
}

Global Operations

Resource path: /global-config/authentication/modules/oath

Resource version: 1.0

getAllTypes

Obtain the collection of all secondary configuration types related to the resource.

Usage:

am> action OathModule --global --actionName getAllTypes

getCreatableTypes

Obtain the collection of secondary configuration types that have yet to be added to the resource.

Usage:

am> action OathModule --global --actionName getCreatableTypes

nextdescendents

Obtain the collection of secondary configuration instances that have been added to the resource.

Usage:

am> action OathModule --global --actionName nextdescendents

read

Usage:

am> read OathModule --global

update

Usage:

am> update OathModule --global --body body

Parameters:

--body

The resource in JSON format, described by the following JSON schema:

{
  "type" : "object",
  "properties" : {
    "defaults" : {
      "properties" : {
        "stepsInWindow" : {
          "title" : "TOTP Time Steps",
          "description" : "The number of time steps to check before and after receiving a OTP.<br><br>This is the number of time step intervals to check the received OTP against both forward in time and back in time. For example, with 2 time steps and a time step interval of 30 seconds the server will allow a clock drift between client and server of 89 seconds. (2-30 second steps and 29 seconds for the interval that the OTP arrived in)",
          "propertyOrder" : 1100,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "hotpCounterAttribute" : {
          "title" : "Counter Attribute Name",
          "description" : "The name of the attribute in the user profile to store the user counter. This is required if HOTP is chosen as the OATH algorithm.",
          "propertyOrder" : 700,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "oathAlgorithm" : {
          "title" : "OATH Algorithm to Use",
          "description" : "Choose the algorithm your device uses to generate the OTP.<br><br>HOTP uses a counter value that is incremented every time a new OTP is generated. TOTP generates a new OTP every few seconds as specified by the time step interval.",
          "propertyOrder" : 500,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "timeStepSize" : {
          "title" : "TOTP Time Step Interval",
          "description" : "The TOTP time step in seconds that the OTP device uses to generate the OTP.<br><br>This is the time interval that one OTP is valid for. For example, if the time step is 30 seconds, then a new OTP will be generated every 30 seconds. This makes a single OTP valid for only 30 seconds.",
          "propertyOrder" : 1000,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "secretKeyAttribute" : {
          "title" : "Secret Key Attribute Name",
          "description" : "The name of the attribute in the user profile to store the user secret key.",
          "propertyOrder" : 400,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "minimumSecretKeyLength" : {
          "title" : "Minimum Secret Key Length",
          "description" : "Number of hexadecimal characters allowed for the Secret Key.",
          "propertyOrder" : 300,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "lastLoginTimeAttribute" : {
          "title" : "Last Login Time Attribute",
          "description" : "Attribute to store the time of the users last login. This is required if TOTP is chosen as the OATH algorithm.<br><br>This attribute stores the last time a user logged in to prevent time based attacks. The value is stored as a number (Unix Time).",
          "propertyOrder" : 1200,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "truncationOffset" : {
          "title" : "Truncation Offset",
          "description" : "This adds an offset to the generation of the OTP.<br><br>This is an option used by the HOTP algorithm that not all devices support. This should be left default unless you know your device uses a offset.",
          "propertyOrder" : 900,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "addChecksum" : {
          "title" : "Add Checksum Digit",
          "description" : "This adds a checksum digit to the OTP.<br><br>This adds a digit to the end of the OTP generated to be used as a checksum to verify the OTP was generated correctly. This is in addition to the actual password length. You should only set this if your device supports it.",
          "propertyOrder" : 800,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "forgerock-oath-sharedsecret-implementation-class" : {
          "title" : "The Shared Secret Provider Class",
          "description" : "The fully qualified class name for the Shared Secret Provider extension.<br><br>The class that is used to process the user profile attribute used to store the user secret key.",
          "propertyOrder" : 1300,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "authenticationLevel" : {
          "title" : "Authentication Level",
          "description" : "The authentication level associated with this module.<br><br>Each authentication module has an authentication level that can be used to indicate the level of security associated with the module; 0 is the lowest (and the default).",
          "propertyOrder" : 100,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "forgerock-oath-maximum-clock-drift" : {
          "title" : "Maximum Allowed Clock Drift",
          "description" : "Number of time steps a client is allowed to get out of sync with the server before manual resynchronisation is required. This should be greater than the TOTP Time Steps value.<br><br>As this checks the time drift over multiple requests it needs to be greater than the value specified in TOTP Time Steps.",
          "propertyOrder" : 1500,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "oathOtpMaxRetry" : {
          "title" : "One Time Password Max Retry",
          "description" : "The number of times entry of the OTP may be attempted. Minimum is 1 maximum is 10 and default is 3.",
          "propertyOrder" : null,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "hotpWindowSize" : {
          "title" : "HOTP Window Size",
          "description" : "The size of the window to resynchronize with the client.<br><br>This sets the window that the OTP device and the server counter can be out of sync. For example, if the window size is 100 and the servers last successful login was at counter value 2, then the server will accept a OTP from the OTP device that is from device counter 3 to 102.",
          "propertyOrder" : 600,
          "required" : true,
          "type" : "integer",
          "exampleValue" : ""
        },
        "forgerock-oath-observed-clock-drift-attribute-name" : {
          "title" : "Clock Drift Attribute Name",
          "description" : "The name of the attribute in the user profile to store the clock drift. If left empty then clock drift checking is disabled.<br><br>The name of the attribute used to store the last observed clock drift which is used to indicated when a manual resynchronisation is required.",
          "propertyOrder" : 1400,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        },
        "passwordLength" : {
          "title" : "One Time Password Length ",
          "description" : "The length of the generated OTP in digits. Must be 6 digits or longer.",
          "propertyOrder" : 200,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        }
      },
      "type" : "object",
      "title" : "Realm Defaults"
    }
  }
}
Read a different version of :