---
# System prepended metadata

title: Blackmoon-Spotware single sign-on schema <a name="top"></a>

---

# Blackmoon-Spotware single sign-on schema <a name="top"></a>

## Flows <a name="fl"></a>

### Auth <a name="au"></a>

```mermaid
sequenceDiagram
participant U as User (Browser)
participant B as Blackmoon Server
participant F as Blackmoon Front
participant SF as SW Front
participant SB as SW Server
U->>+B: Login procedure
note right of U: BM auth flow
B-->>B: Store session
B->>-F: TOKEN1
note over B,F: http-link to SW contains TOKEN1
U->>F: click link to SW
U->>SF: url/?TOKEN1
SF->>+SB: invoke session check
SB->>B: req(TOKEN1)
note over B,SB: request session status and meta for TOKEN1
B->>SB: resp(STATUS, META, USERID)
SB-->>SB: set SW user status
SB->>-SF: activate/deactivate
note over SB,SF: set actual state of user
```

### Check SW session <a name="sw"></a>

```mermaid
sequenceDiagram
participant U as User (Browser)
participant B as Blackmoon Server
participant F as Blackmoon Front
participant SF as SW Front
participant SB as SW Server
U->>SF: direct url (no TOKEN1)
SF->>SB: invoke session check
SB-->>SB: internal checks
alt no SW session
    SB->>F: static redirect + meta
note over SB,F: see "Negative status" for details
end
```

### User logout <a name="ul"></a>

```mermaid
sequenceDiagram
participant U as User (Browser)
participant B as Blackmoon Server
participant F as Blackmoon Front
participant SF as SW Front
participant SB as SW Server
U->>F: click logout
note over U,F: also: session expire, account info change, etc
B-->>B: internal actions
B->>SB: invalidate(USERID)
SB-->>SB: expire SW sessions for USERID
SB->>SF: deactivate
note over SB,SF: set actual state of user
```

### Negative status <a name="ns"></a>

```mermaid
sequenceDiagram
participant U as User (Browser)
participant B as Blackmoon Server
participant F as Blackmoon Front
participant SF as SW Front
participant SB as SW Server
U->>SF: url/?TOKEN1
SF->>SB: invoke session check
    SB->>B: req(TOKEN1)
B->>SB: resp(false, META?, USERID?)
opt if USERID
SB-->>SB: expire all TOKEN2 for USERID
SB->>SF: deactivate
end
SB->>F: static redirect + meta
note over SB,F: redirect to Blackmoon endpoint to handle auth errors
F->>B: check meta/session/etc
alt Recoverable
    note over B,SB: session check flow
    B->>F: TOKEN1
    U->>SF: redirected with new TOKEN1
    note over SF: ...
else
    note over B,SB: new session flow
    B-->>B: internal actions
    B->>SB: invalidate(USERID)
    B->>F: render login form
    note over F: ...
end
```

## API <a name="api"></a>

All communication between `Blackmoon Server` and `SW Server` must meet requirements:

- IPs of both whitelisted on each side
- Transport is HTTPS

### Entities <a name="en"></a>

- BM_URL: Blackmoon Auth API url, static
- BM_CALLBACK: Blackmoon static url for [Negative status](#ns)
- SW_URL: Spotware Auth API url, static
- SW_ENTRY: default Spotware url for Front application

### TOKEN1 interchange

`TOKEN1` is for single-time use, produced and managed on Blackmoon side and must be sent to `SW Front` as HTTP GET unnamed parameter:

```
https://SW_ENTRY/?TOKEN1
```

### `GET BM_CALLBACK/redir`

See [Negative status](#ns) and [Check SW Status](#sw)

Request:

```
BM_CALLBACK/redir?DATA
```

`DATA` - base64-encoded of:

```
{
  errno: ERR,
  data: {
    token1: TOKEN1
    ip: IP,
    ua: USER_AGENT,
  }
}
```

### `POST BM_URL/auth`

Perform exchange from `TOKEN1` to user session status and additional user info.

Request:

```
{
  "data": {
    "token1": TOKEN1,
    "ip": IP,
    "ua": USER_AGENT,
  }
}
```

Response:

```
{
  "errno": ERR,
  "errstr": "",
  "data": {
    "logged": BOOL,
    "token1": TOKEN1,
    "swuid": SW_USER_ID,
    "info": {
      "name": "",
    }
  }
}
```

### `POST SW_URL/revokeAllTokens`

Reset all sessions for user

Request:

```
POST SW_URL/revokeAllTokens
Content-type: application/x-www-form-urlencoded

userId=SW_USER_ID
```

Response:

```
{
  "errno": ERR,
  "errstr": ""
  "data": {
    CONTEXT_TBD
  }
}
```

## Error codes

- `0`: no error
- TBD