diff --git a/docs/architecture.md b/docs/architecture.md index b6829028..bcad2dcd 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -433,6 +433,10 @@ In openDesk, OX App Suite is used for email, calendar, address book and personal [XWiki](https://www.xwiki.org) is an open-source wiki platform for knowledge management and collaboration. +## Jitsi Phone Dial-in + +[Dial-in architecture notes](phone-dial-in/notes.md) describes the infrastructure to integrate an ability to participate in Jitsi calls. + # Application specific user accounts While the IAM managed users centrally, some applications come with local accounts for administrative purposes. diff --git a/docs/phone-dial-in/architcture.drawio.png b/docs/phone-dial-in/architcture.drawio.png new file mode 100644 index 00000000..d53df91b Binary files /dev/null and b/docs/phone-dial-in/architcture.drawio.png differ diff --git a/docs/phone-dial-in/notes.md b/docs/phone-dial-in/notes.md new file mode 100644 index 00000000..7c69d43c --- /dev/null +++ b/docs/phone-dial-in/notes.md @@ -0,0 +1,190 @@ +# Phone dial in + + +![alt text](architcture.drawio.png) + +#### Dial-in related jitsi configs + +https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts/opendesk-jitsi/-/blob/main/charts/opendesk-jitsi/values.yaml?ref_type=heads#L226-230 + +`values.yaml` +```yaml +extraConfig: + doNotStoreRoom: false + dialinCountryCode: "DE" + # e.g. "+49 1111 22233344" + dialinPhoneNumbers: "" +extraEnvs: + COLIBRI_WEBSOCKET_REGEX: "[a-z0-9._-]+" + # This value will be replace with internal conference mapper later when + # it is ready. + CONFCODE_URL: "https://jitsi-api.jitsi.net/conferenceMapper" + DIALIN_NUMBERS_URL: "/static/dialin-phone-numbers.json" +``` + +The template to generate the `dial-phone-numbers.json` +https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts/opendesk-jitsi/-/blob/main/charts/opendesk-jitsi/files/web/dialin-phone-numbers.json?ref_type=heads + + + + +## 1. ovc-frontent -> opendesk + +ovc-frontend env +```properties +NEXT_PUBLIC_ICS_DOMAIN=https://ics.nightly.opendesk.qa +NEXT_PUBLIC_PORTAL_DOMAIN=https://portal.nightly.opendesk.qa +``` + +## 2. ovc-frontend -> jitsi + +ovc-frontend env +```properties +NEXT_PUBLIC_JITSI_LINK=https://jitsi.opendesk.qa +``` + +## 3. ovc-frontend -> keycloak + +[NEXTAUTH_SECRET](https://next-auth.js.org/configuration/options#nextauth_secret) + +client_id and client_secret provided by keycloak. +end_session and refresh urls can be found in keycloak `keycloak.com/realms/{realm}/.well-known` page. + + +ovc-frontend env +```properties +KEYCLOAK_CLIENT_ID=ovc-client +KEYCLOAK_CLIENT_SECRET=clientSecret +NEXTAUTH_SECRET=clientSecret +KEYCLOAK_ISSUER=https://KEYCLOAK.io/realms/opendesk +END_SESSION_URL=https://KEYCLOAK.io/realms/opendesk/protocol/openid-connect/logout +REFRESH_TOKEN_URL=https://KEYCLOAK.io/realms/opendesk/protocol/openid-connect/token + +``` + +## 4. ovc-frontend -> ovc-backend + +ovc-frontend env +```properties +NEXT_PUBLIC_BACKEND_BASE_URL=https://api.opendesk.qa +``` + +## 5. ovc-frontend <-> ovc-videotest + +OPTIONAL, can be disabled and th videotest button will be hidden. + +ovc-frontend env +```properties +NEXT_PUBLIC_VIDEO_TEST_ENABLED=true +NEXT_PUBLIC_VIDEO_TEST_LINK=https://videotest.opendesk.qa +``` + + +## 6. ovc-backend -> postgres + +backend env vars +``` +spring.datasource.password=secret +spring.datasource.url=jdbc:postgresql://{{ $dbService }}:5432/{{ db.name }} +spring.datasource.username=user +``` + +## 7. ovc-backend -> keycloak + +``` +spring.security.oauth2.resourceserver.jwt.issuer-uri={{ .Values.settings.keycloak.url }}/realms/{{ .Values.settings.keycloak.realm }} +``` + +## 8. JITSI -> ovc-backend + +#### Conference mapper for dial-in + + +Phone line users that use a regular phone to attend a jitsi meeting can only enter numbers after they have dialed in a phone number. For Jitsi and the SIP server to know which conference they are calling into a mapping is created `conference name <-> pin number (conference code)`. A conference mapper api allows an external system to find a conference name by pin number or a pin number from a conference name. + + + +Jitsi uses `CONFCODE_URL` env param that "conference mapper" conference search api, it will use the `search pin by conference` functionality to present a dialog with a PIN number if a dial-in user wishes to know it. + +In the dial-in backend the endpoint has this template +`/api/v1.0/conference-mapper/jigasi/by-meeting-id?conference=` + +jitsi-meet configuration environment can be set like this +``` +CONFCODE_URL=https://backend.domain/api/v1.0/conference-mapper/jigasi/by-meeting-id +``` + +SIP server may use a `search conference id by pin` functionality api from the dial-in backend conference mapper. +`/api/v1.0/conference-mapper/jigasi/by-pin?id={pin}` + + +> The way a SIP server communicates with the dial-in backend conference mapper and JIGASI (Jitsi component) depends on the SIP server vendor, this is outside the scope of this document. + + +Jitsi implementation of the conference mapper API is described in +https://github.com/jitsi/jitsi-meet/blob/master/resources/cloud-api.swagger +They support a `/conferenceMapper` api endpoint that can search by `id` (pin) or `conference`. So both Jitsi and the SIP server can connect to a sigle endpoint. In the ovc-backend it's separated into 2 endpoints. + + +## ovc-backend SIP config + +Used in "Copy Info" functionality. +```properties +sip.phone.number=+49 40 3003 5005 +jibri.link=112233@sip.opendesk.domain +``` + +## ovc-backend JWT token api + +OPTIONAL, may be needed if jitsi requires a JWT token. + +```yaml +## this is part of Spring Boot application.yaml, can also be provided as env vars +jitsi: + domain: https://jitsi.opendesk.domain + jwt: + secret: oeRaYY7 + expiration-in-minutes: 60 # how much longer after meeting end time the token is valid + expiration-for-rooms-in-minutes: 180 # same as above, but for rooms and instant meetings + not-before-in-minutes: 30 # how many minutes earlier the meeting can be opened +``` + +## ovc-videotest + +Optional component, phone dial-in can function without it. + +It's a frontend only and doesn't require a backend to function. Configured by mounting a file in `/app/build/config/config.js` + +`config.js` example +```js +window.customConfig = { + // jitsi host + "REACT_APP_JITSI_FQDN": "meet.jit.si", + + // If jitsi requires a JWT, point it to a running ovc-videotest-backend api that + // will return a token for a specific room. {roomName} is a special hardcoded placeholder that will be replaced by the real room name when the api is being called (to make the api call flexible). + // "REACT_APP_JWT_ENDPOINT_URL": "http://localhost:8081/{roomName}", + + // prefix for videotest rooms. If a backend is used it may reject generating a JWT token if a room name doesn't have this prefix + "REACT_APP_ROOM_PREFIX":"videotest", + + // if no callback parameter is provided, should be the ovc-frontend url + "REACT_APP_DEFAULT_CALLBACK_URL":"http://localhost:8080", + + // to improve security only URLS in the list are allowed as callbacks + // if the list is empty any callback url is allowed + "REACT_APP_ALLOWED_CALLBACK_URLS":"http://localhost:3000,https://localhost:3000", + + // If you don't have a backend and jitsi requires a JWT token, for debugging purposes put the entire JWT here. + "REACT_APP_DEBUG_JITSI_JWT": "" +} +``` + + + + + + + + + \ No newline at end of file