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/1The 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
------------------------------
Original Message:
Sent: Thu September 23, 2021 02:51 PM
From: Louis Beaudry
Subject: API call for "Email One-time Password" auth mechanism
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
------------------------------