SCIM for OTP devices
SCIM for OTP devices
⏰ Getting Started
Introduction
Soffid allows you to combine two of the most powerful addons you can use into Soffid Console, SCIM, and OTP.
Please note that the SCIM REST Web Service Add-on installed must be installed, please check this part in How to use SCIM in Soffid # Installation
Please note that a user with the authentication is required, please check this part in How to use SCIM in Soffid # Confirm authorization
Please note that is recommended to use a REST client, please see our example in Testing tool # RESTer
Please note that the correct header parameters must be used, please browse them in SCIM in Soffid # HTTP request
Please note that the OTP addon must be installed and configured, check it in OTP Settings
OTP Device Types
OTP device types available
- TOTP: Time based HMAC Token
- HOTP: Event based HMAC Token
- SMS
- PIN: Security PIN
OTP Device Status
OTP device status available :
- C: Created
- V: Validated
- L: Locked
- D: Disabled
OTP Operations
Soffid provides an API that allows you to connect to the OTP microservices.
The available operations are the following
- List all
- List by filter
- Query by id
- Create
- Update
- Validate
- Send SMS
- Delete
You can visit the SCIM OTP devices examples page for more detailed information
Workflows
With the previous operations, using the SCIM OTP API, we can define some workflows.
You can visit the SCIM OTP devices Workflows examples page
SCIM OTP devices examples
Operations
This page shows the operations that can be performed for the OTP devices object.
List all
Request
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice
Response 200 OK
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 25,
"startIndex": 1,
"Resources": [
{
"lastUsed": "2021-10-14 06:57:00",
"created": "2021-10-14 06:44:43",
"meta": {
"location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880",
"links": {
"requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880/requestChallenge",
"responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880/responseChallenge"
},
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"name": "TOTP00000001",
"id": 4022880,
"type": "TOTP",
"user": "franck",
"fails": 0,
"status": "D"
},
{
"created": "2021-10-14 08:37:38",
"meta": {
"location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4024384",
"links": {
"requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4024384/requestChallenge",
"responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4024384/responseChallenge"
},
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"name": "Email message to pg*****@so****.co*",
"id": 4024384,
"type": "EMAIL",
"user": "patricia",
"fails": 0,
"email": "patricia@soffid.com",
"status": "D"
},
{
"created": "2021-10-14 11:17:52",
"meta": {
"location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4024416",
"links": {
"requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4024416/requestChallenge",
"responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4024416/responseChallenge"
},
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"phone": "666555444",
"name": "SMS message to 66*****44",
"id": 4024416,
"type": "SMS",
"user": "agatha",
"fails": 0,
"status": "V"
},
.............
.............
]
}
List by filter
List all the OTP devices with a filter expression.
It is allowed to use pagination and sort the information, for more information visit the Sorting and Pagination information.
Request
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice?filter=type eq "TOTP"
Response 200 OK
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 7,
"startIndex": 1,
"Resources": [
{
"lastUsed": "2021-10-14 06:57:00",
"created": "2021-10-14 06:44:43",
"meta": {
"location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880",
"links": {
"requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880/requestChallenge",
"responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880/responseChallenge"
},
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"name": "TOTP00000001",
"id": 4022880,
"type": "TOTP",
"user": "franck",
"fails": 0,
"status": "D"
},
.............
.............
]
}
Query by id
Query a OTP device by its id (primary key).
Request
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5007882
Response 200 OK
{
"created": "2022-02-22 07:46:51",
"meta": {
"location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882",
"links": {
"requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882/requestChallenge",
"responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882/responseChallenge"
},
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"name": "TOTP00000035",
"id": 5007882,
"type": "TOTP",
"user": "admin",
"fails": 0,
"status": "C"
}
Create
Allows you to create a new OTP device. It is important the type of the OTP you want to create, and depending on this, it will be mandatory to add new attributes to the request.
- SMS: add to the JSON the phone attribute
- EMAIL: add to the JSON the email attribute
- PIN: add to the JSON the pin attribute
Request
http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice
JSON
{
"meta": {
"location": "http://<your-domain>/webservice/scim2/v1/OtpDevice",
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"type": "TOTP",
"user": "admin"
}
Response 200 OK
{
"image": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAAC3klEQVR4Xu2XP66jMBDGB7lwFy5gydeg40rkAoRcgFzJna+B5AtA58Ji9hueQvJWu8UbS6stMoqiwA9lrPn7Qfw3o99vnPYhHyL2L0mghhOz2Xue+tJGIltBIm9haQPdgufsButxp4LQlc1M+C5tSLt1TSWJyy26Jvipd2NfTTJPHU/kmlxariS8RX6w2fhwwt+i82OC/ER3fX2+Ze7HBJbp0iGieCQh54dpSaCBaOz8SmbukfY0C1STJAHIZkdQe947d6khkYau3KKZrNktzs77MwYawoTCuTFqEDytHY1PPxqSEQPPwY3WoOeu0WzPbGtIoNH6tTdzt1BX2ky3w7mSZAnkA95sQge3eRmfMdAQhh8pwLFL94ACR/9VkOzvbB5oX0LnuaEz9xoS/YORcNROGY7jn/nREE5bwCRwFwtveOQtBgoSJc9rnzggOWm27nUCBcnws1wI3OPgeOpVVQqCkdynqU+rLWQx+fwxEtTEEZXBLoO4KjcpzAqScZWQbczRNphZOq+CBHcNkuQmSs+hm4enHw1hXBWM9o39PS4XW161oyBhIZt2MishP/imy3kCDUEAyo3LpZe2m/BUDYlmtdjbUoDYtIQNyRUkLPj7jdNE5g4hIKVUQWK5BszRQh3PWBf0pncUJCAhRjJDGPZokbdtpiCMooYHs8rZ4WehKuIhnZqM0YIKSo+czsmnIRFKpxyyArfd8FY7GoKRzISg7gSInqsj2UwdYVZh+c+9jATMZj2J0rUi7ix0YsFsFt9qIrtR5PA9o10wYPx0nlpDjJRhD4Xi0MoP6NnTj4KEQ4WJFvNbXlDWZ+1oCCwujWhYg7S3sVQR0bDUYj3GI+3xpa81BPoah+3T/UvDygqqIShDNxIq2q8dftD7W4GGRLyBYT0ujdRRedOwOgKRgvMiS446z2JqwjKfMJUJextCm87dqCHIj+xGj0WxMbT/8v7G8mPyZ/uQDxH7n8kvJ2XgRr9Rxi0AAAAASUVORK5CYII=",
"created": "2022-02-22 07:46:51",
"meta": {
"location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882",
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"name": "TOTP00000035",
"id": 5007882,
"type": "TOTP",
"user": "admin",
"fails": 0,
"status": "C"
}
Example JSON SMS
{
"type": "SMS",
"user": "dilbert",
"phone": "6665552222"
}
Example JSON EMAIL
{
"type": "EMAIL",
"user": "dilbert",
"email": "dilbert@soffid.com"
}
Example JSON PIN
{
"type": "PIN",
"user": "dilbert",
"email": "123456789"
}
Update partial
Only attributes with changes will be updated, the other will mantain the same value. This example shows how to enable an OTP device.
Request
PATCH http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5007882
JSON
{
"Operations":
[
{
"op": "replace",
"path": "status",
"value": "V"
}
]
}
Response 200 OK
{
"created": "2022-02-22 07:46:51",
"meta": {
"location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882",
"links": {
"requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882/requestChallenge",
"responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882/responseChallenge"
},
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"name": "TOTP00000035",
"id": 5007882,
"type": "TOTP",
"user": "admin",
"fails": 0,
"status": "V"
}
Request Challenge
This operation allows Soffid to obtain the PIN code for a specific OTP device. We can use this method to send an email or SMS, depending on the type of OTP device.
Request
GET http://<your-domain>//soffid/webservice/scim2/v1/OtpDevice/<OTP_ID>/requestChallenge
Response 200 OK
{
"cell": "PIN",
"cardNumber": "SMS message to 66*****22"
}
Response Challenge
This operation allows you to validate a PIN code for a specific OTP device.
Request
POST http://<your-domain>//soffid/webservice/scim2/v1/OtpDevice/<OTP_ID>/responseChallenge
JSON
{
"pin": "12345678"
}
Response 200 OK
{
"success": false,
"locked": false
}
Delete
In this case, delete operation will cancel the TaskInstace, but does not be deleted form database.
Please note after this delete, the account has to be created again to use it in the next examples.
Request
DELETE - http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5007967
Response 204 No Content
204 No Content
Error response
For more information about error response visit https://bookstack.soffid.com/link/116#bkmrk-error-response
SCIM OTP devices Workflows examples
Workflow Examples
Workflow 1
1. Create Email OTP device
Request
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice
JSON
{
"type": "EMAIL",
"user": "dilbert",
"email": "dilbert@soffid.com"
}
Response 200 OK
{
"created": "2022-03-09 13:39:52",
"meta": {
"location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5099461",
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"name": "Email message to di*****@so****.co*",
"id": 5099461,
"type": "EMAIL",
"user": "dilbert",
"fails": 0,
"email": "dilbert@soffid.com",
"status": "C"
}
2. RequestChallenge to get the PIN code
Request
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5099461/requestChallenge
Response 200 OK
{
"cell": "PIN",
"cardNumber": "Email message to di*****@so****.co*"
}
3. ResponseChallenge to validate the PIN code
Request
POST http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5099461/responseChallenge
JSON
{
"pin": "839231"
}
Response 200 OK
{
"success": true,
"locked": false
}
4. Enable OTP device
Request
PATCH http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5099461
JSON
{
"Operations":
[
{
"op": "replace",
"path": "status",
"value": "V"
}
]
}
Response
{
"created": "2022-03-09 13:39:52",
"meta": {
"location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5099461",
"links": {
"requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5099461/requestChallenge",
"responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5099461/responseChallenge"
},
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"name": "Email message to di*****@so****.co*",
"id": 5099461,
"type": "EMAIL",
"user": "dilbert",
"fails": 0,
"email": "dilbert@soffid.com",
"status": "V"
}
Workflow 2
1. Get TOTP devices
Obtain all unused OTP devices by 2022.
Request
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice?filter=lastUsed le "2022-01-01"
Response 200 Ok
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 5,
"startIndex": 1,
"Resources": [
{
"lastUsed": "2021-10-14 06:57:00",
"created": "2021-10-14 06:44:43",
"meta": {
"location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880",
"links": {
"requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880/requestChallenge",
"responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880/responseChallenge"
},
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"name": "TOTP00000001",
"id": 4022880,
"type": "TOTP",
"user": "admin",
"fails": 0,
"status": "E"
},
{
"lastUsed": "2021-10-14 06:59:33",
"created": "2021-10-14 06:58:05",
"meta": {
"location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022891",
"links": {
"requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022891/requestChallenge",
"responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022891/responseChallenge"
},
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"name": "TOTP00000002",
"id": 4022891,
"type": "TOTP",
"user": "ckelp",
"fails": 0,
"status": "C"
},
.....
]
}
2. Disable OTP device
Disble the OTP devices one by one
Request
PATCH http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/4022880
JSON
{
"Operations":
[
{
"op": "replace",
"path": "status",
"value": "D"
}
]
}
Response 200 Ok
{
"lastUsed": "2021-10-14 06:57:00",
"created": "2021-10-14 06:44:43",
"meta": {
"location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880",
"links": {
"requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880/requestChallenge",
"responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880/responseChallenge"
},
"resourceType": "OtpDevice"
},
"schemas": [
"urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
],
"name": "TOTP00000001",
"id": 4022880,
"type": "TOTP",
"user": "admin",
"fails": 0,
"status": "D"
}