# SCIM for OTP devices

SCIM for OTP devices

# ⏰ Getting Started

## Introduction

<p class="callout info">Soffid allows you to combine two of the most powerful addons you can use into Soffid Console, **SCIM,** and **OTP**. </p>

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](https://bookstack.soffid.com/link/120#bkmrk-installation)

Please note that a user with the authentication is required, please check this part in [How to use SCIM in Soffid # Confirm authorization](https://bookstack.soffid.com/link/120#bkmrk-confirm-authorizatio)

Please note that is recommended to use a REST client, please see our example in [Testing tool # RESTer](https://bookstack.soffid.com/link/118#bkmrk-rester)

Please note that the correct header parameters must be used, please browse them in [SCIM in Soffid # HTTP request](https://bookstack.soffid.com/link/114#bkmrk-http-request)

Please note that the OTP addon must be installed and configured, check it in [OTP Settings](https://bookstack.soffid.com/books/two-factor-authentication-2fa-VsJ/page/otp-settings)

### OTP Device Types

OTP device types available

- **TOTP**: Time based HMAC Token
- **HOTP**: Event based HMAC Token
- **EMAIL**
- **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

<p class="callout info">You can visit the [SCIM OTP devices examples page](https://bookstack.soffid.com/books/scim/page/scim-otp-devices-examples) for more detailed information</p>

#### Workflows

With the previous operations, using the SCIM OTP API, we can define some workflows.

<p class="callout info">You can visit the [SCIM OTP devices Workflows examples page](https://bookstack.soffid.com/books/scim/page/scim-otp-devices-workflows-examples)</p>

# SCIM OTP devices examples

## Operations

This page shows the operations that can be performed for the OTP devices object.

### List all

##### Request

```MarkDown
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice
```

##### Response 200 OK

```JSON
{
    "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.

<p class="callout info">It is allowed to use pagination and sort the information, for more information visit the [Sorting](https://bookstack.soffid.com/link/116#bkmrk-sorting) and [Pagination](https://bookstack.soffid.com/link/116#bkmrk-pagination) information.</p>

##### Request

```MarkDown
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice?filter=type eq "TOTP"
```

##### Response 200 OK

```JSON
{
    "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

```MarkDown
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5007882
```

##### Response 200 OK

```JSON
{
    "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

```XML
http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice
```

**JSON**

```XML
{
    "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

```JSON
{
    "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

```JSON
{
    "type": "SMS",
    "user": "dilbert",
    "phone": "6665552222"
}
```

##### Example JSON EMAIL

```JSON
{
    "type": "EMAIL",
    "user": "dilbert",
    "email": "dilbert@soffid.com"
}
```

##### Example JSON PIN

```JSON
{
    "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

```XML
PATCH http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5007882
```

**JSON**

```JSON
{
    "Operations": 
    [
        {
            "op": "replace",
            "path": "status",
            "value": "V"
        }
    ]
}
```

##### Response 200 OK

```JSON
{
    "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

```XML
GET http://<your-domain>//soffid/webservice/scim2/v1/OtpDevice/<OTP_ID>/requestChallenge
```

##### Response 200 OK

```JSON
{
    "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

```XML
POST http://<your-domain>//soffid/webservice/scim2/v1/OtpDevice/<OTP_ID>/responseChallenge
```

**JSON**

```JSON
{
    "pin": "12345678"
}
```

##### Response 200 OK

```JSON
{
    "success": false,
    "locked": false
}
```

### Delete

In this case, delete operation will cancel the TaskInstace, but does not be deleted form database.

<p class="callout warning">Please note after this delete, the account has to be created again to use it in the next examples.</p>

##### Request

```MarkDown
DELETE - http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5007967
```

##### Response 204 No Content

```
204 No Content
```

### Error response

<p class="callout info">For more information about error response visit [https://bookstack.soffid.com/link/116#bkmrk-error-response](https://bookstack.soffid.com/link/116#bkmrk-error-response)</p>

# SCIM OTP devices Workflows examples

## Workflow Examples

### Workflow 1

#### 1. Create Email OTP device

##### Request

```XML
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice
```

**JSON**

```JSON
{
    "type": "EMAIL",
    "user": "dilbert",
    "email": "dilbert@soffid.com"
}
```

##### Response 200 OK

```JSON
{
    "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

```XML
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5099461/requestChallenge
```

##### Response 200 OK

```JSON
{
    "cell": "PIN",
    "cardNumber": "Email message to di*****@so****.co*"
}
```

#### 3. ResponseChallenge to validate the PIN code

##### Request

```XML
POST http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5099461/responseChallenge
```

**JSON**

```Java
{
    "pin": "839231"
}
```

##### Response 200 OK

```JSON
{
    "success": true,
    "locked": false
}
```

#### 4. Enable OTP device

##### Request

```XML
PATCH http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5099461
```

**JSON**

```JSON
{
    "Operations": 
    [
        {
            "op": "replace",
            "path": "status",
            "value": "V"
        }
    ]
}
```

##### Response

```JSON
{
    "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 

```MarkDown
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice?filter=lastUsed le "2022-01-01"
```

##### Response 200 Ok

```JSON
{
    "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

```MarkDown
PATCH http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/4022880
```

**JSON**

```JSON
{
    "Operations": 
    [
        {
            "op": "replace",
            "path": "status",
            "value": "D"
        }
    ]
}
```

##### Response 200 Ok

```JSON
{
    "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"
}
```

##