# SEID-SDO signing

> **This feature is deprecated**
>
> The SEID-SDO format is **not supported** in the new BankID Signing solution.
> We recommend migrating to [PAdES signing](https://docs.stoe.no/bankid-esign-provider/apis/signdoc-intro.md) for documents, [CSC Signing API](https://docs.stoe.no/bankid-esign-provider/apis/csc/CSC.md) for hashes or [Permissions API](https://docs.stoe.no/bankid-with-biometrics/permission-types.md) for payment related signing.

[SEID-SDO](https://nkom.no/internett/elektronisk-id-og-tillitstjenester/seid-prosjektet) is an extension of ETSI
(the European Telecommunications Standards Institute) CAdES/XAdES standard for signing PDF documents, XML files,
and plain text.

## Flow

The BankID SEID-SDO signing flow makes use of the SignDoc API to:

- create a sign order by uploading the document(s) to be signed
- check the status of the signing process
- download the signed document(s) after the signing process is complete

In order to use the SEID-SDO signing flow, you need to get an access token with the `signdoc/read_write` scope
and use it to create a sign order.

Furthermore, you need to redirect the end user to the BankID authorize endpoint with the `sign` scope
and the `sign_id` parameter.

Finally, you can download the signed document(s) using the SignDoc API once the signing process is complete.

## Steps

1. Request an access token with the `signdoc/read_write` scope using [Client Credentials](https://docs.stoe.no/bankid-oidc-provider/flows.md) flow.
2. Create a sign order by uploading the document(s) to be signed to the SignDoc API. You will receive a `sign_id`.
3. Redirect the end user to the BankID authorize endpoint with the `sign` scope and the `sign_id` parameter.
4. The end user signs the document(s).
5. You can check the status of the signing process using the SignDoc API. (Optional)
6. BankID returns to your callback URL following the standard [Authorization Code](https://docs.stoe.no/bankid-oidc-provider/flows.md) flow.
7. Your service exchanges the `code` for tokens and [verifies](https://docs.stoe.no/bankid-oidc-provider/advanced-topics/verify-token.md) them.
8. Download the signed document(s) using the SignDoc API once the signing process is complete.

> **Warning**
>
> The sign order is only valid for 90 seconds **before** signing starts, and 90 seconds **after** signing ends.

## Sequence diagram

```mermaid
sequenceDiagram
    actor u as User
    participant Merchant as Your Web App
    participant BankID as BankID
    participant SignDoc as SignDoc API
    u ->> Merchant: Request signing
    Note right of Merchant: (1) Client requests access token
    Merchant->>BankID: POST /token with `signdoc/read_write` scope
    BankID-->>Merchant: Access token
    Note right of Merchant: (2) Client creates sign order
    Merchant-->>SignDoc: POST /signdoc with parameters and document(s) data
    SignDoc-->>Merchant: Sign ID
    Note right of Merchant: (3) Client redirects user to BankID with sign_id
    Merchant->>BankID: GET /authorize?scope=sign&sign_id=xxxx-xxxx&client_id=...
    BankID-->> Merchant: Redirect to callback with code
    Note right of Merchant: (7) Client fetches tokens and verifies
    Merchant->>BankID: POST /token with code
    BankID-->>Merchant: ID tokens
    Note right of Merchant: (8) Client downloads signed document(s)
    Merchant->>SignDoc: DELETE /signdoc?sign_id={sign_id}
    SignDoc-->>Merchant: Signing results and document(s)
    Merchant->>u: Signing complete
```

## API

> **Note**
>
> You will always find the up-to-date URL for the SignDoc API in the [OpenID Configuration](https://docs.stoe.no/bankid-oidc-provider/api/openid-configuration.md)
>
> - as `signdoc-baseurl`.

API reference: [OpenAPI specification](https://docs.stoe.no/bankid-oidc-provider/api/signing/signdoc-sdo.yaml)

## Examples

### Create a sign order

#### Request

```
POST [signdoc-baseurl]/signdoc
```

You can find the signdoc-baseurl for the appropriate environment in the [OpenID Configuration](https://docs.stoe.no/bankid-oidc-provider/api/openid-configuration.md).

##### Headers

```
Authorization: Bearer [access_token]
Content-Type: application/json
```

##### Body

```json
{
  "signProperties": {
    "orderName": "My order name",
    "documentDisplayMode": "interior",
    "showConfirmation": true,
    "showUnderstanding": true,
    "timeoutSeconds": 1800
  },
  "documents": [
    {
      "description": "My PDF document",
      "pdf": "JVBER..."
    },
    {
      "description": "My text",
      "text": "My text to sign..."
    },
    {
      "xml": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?> ...",
      "xls": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?><xsl:stylesheet ..."
    }
  ],
  "resultContent": [
    "basicSignature",
    "documentHash",
    "sdo"
  ]
}

```

#### Response

##### Status

```
201 Created
```

##### Headers

```
Content-Type: application/json
```

##### Body

```json
{
  "signId": "2a8d69ba-2607-9a1e-9e60-bdb6cc67eacf"
}
```

The result contains the `sign_id` reference which is used to identify the sign order.

### Check the status of a sign order

#### Request

```
GET [signdoc-baseurl]/signdoc?sign_id={sign_id}
```

##### Headers

```
Authorization: Bearer [access_token]
Content-Type: application/json
```

#### Response

##### Status

```
200 OK
```

##### Body

Sign order was found. Returns the order state.

```json
{
    "orderState": "ORDER_RECEIVED"
}
```

Possible values are:

- `ORDER_RECEIVED`
- `GRABBED_BY_IDP`
- `USER_SIGNING`
- `FAILED`
- `CANCELLED`
- `SIGN_COMPLETED`

### Download signing results

#### Request

```
DELETE [signdoc-baseurl]/signdoc?sign_id={sign_id}
```

##### Headers

```
Authorization: Bearer [access_token]
Content-Type: application/json
```

#### Response

##### Status

```
200 OK
```

##### Body

```json
{
    "documentHashes": [
        "5OKv0...",
        "l5hoT...",
        "PyLlx..."
    ],
    "merchantSignatures": [
        "MIAGC...",
        "MIAGC...",
        "MIAGC..."
    ],
    "sdos": [
        "PD94b...",
        "PD94b...",
        "PD94b...",
    ],
    "endUserSignatures": [
        "MIAGC...",
        "MIAGC...",
        "MIAGC..."
    ],
    "clientId": "my-oidc-client-id",
    "signId": "2a8d69ba-2607-9a1e-9e60-bdb6cc67eacf",
    "orderState": "SIGN_COMPLETED",
    "orderName": "My order name"
}
```
