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" : {
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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-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" : ""
    },
    "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" : ""
    },
    "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" : ""
    }
  }
}

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" : {
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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" : ""
    },
    "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-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" : ""
    },
    "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" : ""
    },
    "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" : ""
    }
  }
}

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" : {
        "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" : ""
        },
        "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" : ""
        },
        "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" : ""
        },
        "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" : ""
        },
        "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-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" : ""
        },
        "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" : ""
        },
        "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" : ""
        },
        "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" : ""
        },
        "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" : ""
        },
        "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" : ""
        },
        "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" : ""
        },
        "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" : ""
        },
        "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" : ""
        },
        "minimumSecretKeyLength" : {
          "title" : "Minimum Secret Key Length",
          "description" : "Number of hexadecimal characters allowed for the Secret Key.",
          "propertyOrder" : 300,
          "required" : true,
          "type" : "string",
          "exampleValue" : ""
        }
      },
      "type" : "object",
      "title" : "Realm Defaults"
    }
  }
}