Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Markdown
# DualShield DAS Restful API Instruction

## Introduction

The document will demo how to operate the DualShield authentication APIs.

Before use this document please setup as follows:

Before using this collection, there are several requirement for the Postman configuration:

1.  Add client certificate for your domain and port (management api: 8070, authentication api: 8071). Please read this  [Wiki](http://wiki.deepnetsecurity.com/x/6w5HAQ)  for detail.
2.  Update the Postman Environment Variables to match your server such as host, user loginName, domain name, and token serial and so on. If you nor familiar for the Postman Environment Variable, please read this official doc:  [Intro to environments and globals](https://learning.getpostman.com/docs/postman/environments_and_globals/intro_to_environments_and_globals)

The Postman Document: https://documenter.getpostman.com/view/7531413/S1Lzwm3s?version=latest

## API Doc

### Verify spass

```
POST
https://YOUR_FQDN:8071/das5/rest/auth/verify
```
Body

```json
{
    "credential": {
        "password": YOUR_STATIC_PASSWORD,
        "method": "SPASS"
    },
    "user": { 
    	"loginName": "YOUR_LOGIN_NAME",
    	"domain.name":"YOUR_DOMAIN_OF_USER"
    },
    "return": [
        "*"
    ]
}
```

Verify static password


### Verify otp

```
POST
https://YOUR_FQDN:8071/das5/rest/auth/verify
```
Body

```json
{
    "credential": {
        "otp": "VALID_OTP_CODE"
    },
    "user": {
        "loginName": "YOUR_LOGIN_NAME",
    	"domain.name":"YOUR_DOMAIN_OF_USER"
    },
    "return": [
        "*"
    ]
}
```
Verify one time password

### List tokens with attributes

```
POST
https://YOUR_FQDN:8071/das5/rest/auth/listTokens
```
Body

```json
{
    "user": {
        "loginName": "YOUR_LOGIN_NAME",
        "domain.name": "YOUR_DOMAIN_OF_USER"
    },
    "return": [
        "*"
    ]
}
```


Get tokens by user.

This API will return all tokens assigned to the provided user. 

Note: If you get the error:

```
{
    "error": 242,
    "message": "The requested domain is not defined in the realm",
    "severity": "ERROR"
}
```

Please check the `Applications` of API agent which you are using. Make sure that `domain` you are quering in this api has the relation to this API agent:

For example: 

The domain name is `DomainA`, `DomainA` belong to an realm, such as realm `Self-Service Console`. And the application `Self-Service-Console` has been configured with the realm.
Then this API agent should contain assigned application with `Self-Service-Console`.

![](http://wiki.deepnetsecurity.com/download/attachments/21434103/Selection_256.png?version=1&modificationDate=1559312798915&api=v2)
![](http://wiki.deepnetsecurity.com/download/attachments/21434103/Selection_257.png?version=1&modificationDate=1559312798915&api=v2)
![](http://wiki.deepnetsecurity.com/download/attachments/21434103/Selection_258.png?version=1&modificationDate=1559312798915&api=v2)

### Get token attributes

```
POST
https://YOUR_FQDN:8071/das5/rest/auth/getTokenAssignment
```
Body

```json
{
    "match": [
        [
            "token.serial",
            "=",
            "SPECIFIED_VERIFY_TOKEN_SERIAL"
        ]
    ],
    "return": [
        "*"
    ]
}
```

Get token attributes by providing specific token serial


### Get user attributes

```
POST
https://YOUR_FQDN:8071/das5/rest/auth/findUser
```
Body

```json
{
    "user": {
        "loginName": "YOUR_LOGIN_NAME",
        "domain.name": "YOUR_DOMAIN_OF_USER"
    },
    "application": {
        "name": "YOUR_APPLICATION_NAME"
    },
    "return": [
        "loginName",
        "personalEmail",
        "personalMobile",
        "personalTelephone",
        "mobile",
        "email",
        "telephone"
    ]
}
```
This API will return user attributes, you can define what attributes return by using the `return` parameter. If you want to all attributes, you can change the `return` to "*" like this:

```
"return": [
    "*"
]
```


### Send tpass

```
POST
https://YOUR_FQDN:8071/das5/rest/auth/sendOTP
```
Body

```json
{
    "credential": {
        "method": "SPASS",
        "password": "YOUR_STATIC_PASSWORD"
    },
    "user": {
        "loginName": "YOUR_LOGIN_NAME",
        "domain.name": "YOUR_DOMAIN_OF_USER"
    },
    "token": {
        "serial": "SPECIFIED_VERIFY_TOKEN_SERIAL"
    },
    "options": {
        "format": "TEXT",
        "channel": "EMAIL"
    },
    "return": [
        "*"
    ]
}
```

### Verify tpass without token serial

```
POST
https://YOUR_FQDN:8071/das5/rest/auth/verify
```
Body

```json
{
    "credential": {
        "otp": "VALID_TPASS_CODE"
    },
    "user": {
        "loginName": "YOUR_LOGIN_NAME",
    	"domain.name":"YOUR_DOMAIN_OF_USER"
    },
    "return": [
        "*"
    ]
}
```
Verify TPass without providing the token serial. If the token serial is not specified in the request, the server will try to verify every token with provided credential.

### Verify-tpass with token serial

```
POST
https://YOUR_FQDN:8071/das5/rest/auth/verify
```
Body

```json
{
    "credential": {
        "otp": "VALID_TPASS_CODE"
    },
    "user": {
        "loginName": "YOUR_LOGIN_NAME",
    	"domain.name":"YOUR_DOMAIN_OF_USER"
    },
    "token": {
    	"serial": "SPECIFIED_VERIFY_TOKEN_SERIAL"
    },
    "return": [
        "*"
    ]
}
```

Verify TPass by providing the specific token with serial. It will only return the verify result for provided token.

...