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 

OTP Device Status

OTP device status available :

OTP Operations

Soffid provides an API that allows you to connect to the OTP microservices.

The available operations are the following

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.

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