# 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