IBM Security Verify

Expand all | Collapse all

API call for "Email One-time Password" auth mechanism

  • 1.  API call for "Email One-time Password" auth mechanism

    Posted 26 days ago
    Hi Community,

    We are on ISVA 10.0.2.0

    We are working on automating an MFA configuration (email one-time password) through playbook (API calls).

    We have done the setup manually through the LMI first (in dev), now it's time to automate the process for higher environments.

    This question is about the Authentication Mechanisms. To understand the exact key/value syntax to use for the parameter setup, we do manual API calls and look at the json returned.

    For example, calling https://blahblahblah.ca.net/iam/access/v8/authentication/mechanisms
    gave us the details for the "MAC One-time Password" mechanism in which the keys to use are "otp.macotp.length", "otp.macotp.lifetime", "otp.macotp.characters" and "otp.macotp.hashAlgorithm".

    Now our problem is that we need to do the equivalent for "Email One-time Password" in which we set the following properties:
    SMTP Host Name,SMTP Password,SMTP Port,SMTP User Name,Sender Email,TLS Protocol,Use SSL and Use STARTTLS

    The problem is that this mechanism ("Email One-time Password") is not returned by /iam/access/v8/authentication/mechanisms.

    We did an F12 on the LMI page and it does 2 GET calls:
    https://blahblahblah.ca.net/iam/access/v8/authentication/mechanism/types/
    and
    https://blahblahblah.ca.net/iam/access/v8/authentication/mechanisms/
    neither of which returns any value for "Email One-time Password".

    We also notice in the LMI, when we edit the "Email One-time Password" mechanism that (in the "general" tab) the fields "identifier" and "type" are blank.

    How can we find information about this particular mechanism (which API call)?

    ( in other words how does the LMI "know" about this mechanism? is it a standard one that is always there? in which case can we still set it up programmatically? etc. )

    We would need to set it up through API calls since the smtp config is required in our setup.

    Thanks for your help,
    Louis

    ------------------------------
    Louis Beaudry
    Access Management
    Intact Financial Corporation
    ------------------------------


  • 2.  RE: API call for "Email One-time Password" auth mechanism

    Posted 26 days ago
    Hi Louis,

    What you're discovering here is that there a few "older" mechanisms in Verify Access which are a little different than most of the mechanisms that were added in later versions.  The E-mail OTP mechanism is one of these.  The E-mail OTP password mechanism you see in the LMI is really a hard-coded wrapper around the generic "MAC One-Time Password" mechanism.  That's why it doesn't have a Type listed in LMI.  The SMS OTP mechanism is the same.

    I did some analysis of the REST calls made for mechanism management.

    First of all, the mechanism types are returned from this call:

    https://lmi.iamlab.ibm.com/iam/access/v8/authentication/mechanism/types/

    The response includes an entry for the generic MAC OTP mechanism type (but not for the E-mail OTP because that's not real):

    [
    ...
    {
    "implementationVersion": "8.0.0.3",
    "description": "MAC one-time password authentication",
    "type": "MAC One-time Password",
    "enabled": true,
    "predefined": true,
    "supportsSelector": false,
    "implementationType": "Authenticator",
    "allowMultipleInstances": false,
    "implementationId": "MACOTPAuthenticator",
    "name": "MAC One-time Password",
    "id": "1",
    "parameters": [{
    "datatype": "Boolean",
    "defaultValue": "true",
    "name": "reauthenticate",
    "validValues": [],
    "required": true
    }, ...
    }]
    },
    ...
    ]

    The generic MAC OTP mechanism is also returned from the call to get mechanisms.  The mechanism call is:

    https://lmi.iamlab.ibm.com/iam/access/v8/authentication/mechanisms/

    The response includes this:
    [
    ...
    {
    "name": "MAC One-time Password",
    "description": "MAC one-time password authentication",
    "typeId": "1",
    "attributes": [],
    "id": "1",
    "uri": "urn:ibm:security:authentication:asf:mechanism:macotp",
    "predefined": true,
    "properties": [{
    "value": "300",
    "key": "otp.macotp.lifetime"
    }, {
    "value": "0123456789",
    "key": "otp.macotp.characters"
    }, {
    "value": "SHA-256",
    "key": "otp.macotp.hashAlgorithm"
    }, {
    "value": "6",
    "key": "otp.macotp.length"
    }]
    },
    ..
    ]

    If you want to update the properties associated with the Generic OTP mechanism, this is done in the standard way - a PUT to the mechanism endpoint (the "1" here comes from the id of the generic OTP mechanism):

    https://lmi.iamlab.ibm.com/iam/access/v8/authentication/mechanisms/1

    The body of this POST contains the properties to set:

    {
    "id": "1",
    "name": "MAC One-time Password",
    "predefined": true,
    "description": "MAC one-time password authentication",
    "uri": "urn:ibm:security:authentication:asf:mechanism:macotp",
    "attributes": [],
    "typeId": "1",
    "properties": [{
    "key": "otp.macotp.hashAlgorithm",
    "value": "SHA-256"
    }, {
    "key": "otp.macotp.length",
    "value": "8"
    }, {
    "key": "otp.macotp.lifetime",
    "value": "600"
    }, {
    "key": "otp.macotp.characters",
    "value": "abcdefghij"
    }]
    }

    The settings for this mechanism affect both the E-mail and SMS OTP mechanisms.

    So here's the interesting part...

    The settings for the "wrapper" e-mail OTP mechanism are returned via this call:

    https://lmi.iamlab.ibm.com/iam/access/v8/override-configs/?filter=category%20equals%20otp.email

    "otp.email" in the category is a fixed string.  The response looks like this:

    [{
    "datatype": "String",
    "readOnly": false,
    "id": "10401",
    "sensitive": false,
    "validValues": [],
    "category": "otp.email",
    "value": "admin@localhost",
    "key": "otp.email.senderEmail"
    }, {
    "datatype": "String",
    "readOnly": false,
    "id": "10402",
    "sensitive": false,
    "validValues": [],
    "category": "otp.email",
    "value": "localhost",
    "key": "otp.email.smtpHostname"
    },
    ...
    ]

    The properties for the Email OTP wrapper are set by PUTing to the override-configs endpoint where they were retrieved:

    https://lmi.iamlab.ibm.com/iam/access/v8/override-configs/

    The format of the PUT body is an array of properties to be updated.  Each property is identified by the id from the GET of override-configs:

    [{
    "id": "10401",
    "sensitive": false,
    "value": "admin@localhost"
    }, {
    "id": "10403",
    "sensitive": false,
    "value": ""
    }, {
    "id": "10405",
    "sensitive": false,
    "value": "25"
    }, {
    "id": "10406",
    "sensitive": false,
    "value": "false"
    }, {
    "id": "10407",
    "sensitive": false,
    "value": "false"
    }, {
    "id": "10408",
    "sensitive": false,
    "value": "TLS"
    }, {
    "id": "10402",
    "sensitive": false,
    "value": "mailserver"
    }]

    Hopefully this gives you what you need to update the configuration programmatically.

    Jon.

    ------------------------------
    Jon Harry
    Consulting IT Security Specialist
    IBM
    ------------------------------



  • 3.  RE: API call for "Email One-time Password" auth mechanism

    Posted 26 days ago

    Hi Louis,

    I've asked Jasmine from the development to help with a response to this one as I am sure there is a way to do it, and I have done so for "some" of the properties you refer to by way of some special advanced tuning parameters however I want to check if this is the preferred/only way to do it automatically and if so for Jasmine to provide a more complete list of the advanced tuning property names for you. I suspect she may be out of office at the moment and may take a little while to get back to you.

    If you want to continue to attempt to reverse engineer what the LMI actually does, take a look at the system where you configured things manually, go to the LMI (System -> Advanced Tuning Parameters), and see if some new advanced tuning parameters have "appeared" with names like otp.email.?????

    If so, use the advanced tuning parameter setting APIs to automate the setup in other environments. These are documented in the RAPI doc for web services under Manage: System Settings -> System Settings -> Advanced Tuning Parameters.

    Regards,
    Shane.



    ------------------------------
    Shane Weeden
    IBM
    ------------------------------