Swagger API Help

[Luke 40086]

The changes are in the browsers getting more strict about it.

[ShadowKindjal 19]

Understood, thank you for the clarification 

[ShadowKindjal 19]

To conclude, there isn't a secure way to notify swagger I'm using a reverse proxy and enable HTTPS requests. Is that a correct assumption?

[Luke 40086]

What do you mean by notify swagger?

[ShadowKindjal 19]

On 3/28/2023 at 12:13 AM, Luke said:

What do you mean by notify swagger?

I may be using the wrong terminology but I'm asking if there's a way to notify Swagger that I'm using HTTPS via a reverse proxy. Right now Swagger loads with a HTTP address.

 

[Luke 40086]

What do you want it to load with?

[ShadowKindjal 19]

I figured it would load with my HTTPS prefixed web address unless I'm understanding something incorrectly. Attempting to run Swagger APIs fails because of the wrong URL. Copying the request URL and switching to HTTPS works.

[Luke 40086]

How is the url wrong?

[ShadowKindjal 19]

The URL in swagger is http://emby.domain.org but it should be https://emby.domain.org

[rbjtech 4997]

Rewind a bit - are you trying to use swagger (https://swagger.emby.media) to send remote API requests to your external site via https ?

If yes, then just change the 'serverUrl' to https and it'll work.

If you wanna use http - then you can - but it needs to be localhost due to CORS.  You can add an exception into the browser which allows you to use other hosts as well (this is what I do).

In Edge - 'edge://flags' - then add your emby url (http) and you can access it via the swagger API (https) using a local http listener.

Edited April 4, 2023 by rbjtech

[softworkz 4569]

4 hours ago, ShadowKindjal said:

The URL in swagger is http://emby.domain.org but it should be https://emby.domain.org

Do you mean that this link

...is referring to your server with an http URL instead of an https URL?

So essentially, you are asking for the letter 's' to be added to that URL, right?

[softworkz 4569]

Do you know that you can just open

https://swagger.emby.media/

and then, enter:

https://emby.domain.org/emby/openapi into the box?

[Happy2Play 9444]

3 hours ago, softworkz said:

Do you know that you can just open

https://swagger.emby.media/

and then, enter:

https://emby.domain.org/emby/openapi into the box?

Won't OP reverse proxy do the same thing with the "Servers" box, as this does not happen for a direct https connection?

[softworkz 4569]

50 minutes ago, Happy2Play said:

Won't OP reverse proxy do the same thing with the "Servers" box, as this does not happen for a direct https connection?

Ah yes, you're right. He would need to add the serverUrl parameter, like this: https://emby.domain.org/emby/openapi?serverUrl=https%3A%2F%2Femby.domain.org

[ShadowKindjal 19]

5 hours ago, softworkz said:

Do you mean that this link

...is referring to your server with an http URL instead of an https URL?

So essentially, you are asking for the letter 's' to be added to that URL, right?

Yes, that's what I was referring to. I apologize for not making that clear.

[ShadowKindjal 19]

10 minutes ago, softworkz said:

Ah yes, you're right. He would need to add the serverUrl parameter, like this: https://emby.domain.org/emby/openapi?serverUrl=https%3A%2F%2Femby.domain.org

This is the format of my current server url parameter but all of the request URL that popular when i click "try it out" are http URLs 

 

[softworkz 4569]

But not when you add the 's' here, right?

[rbjtech 4997]

3 hours ago, softworkz said:

Ah yes, you're right. He would need to add the serverUrl parameter, like this: https://emby.domain.org/emby/openapi?serverUrl=https%3A%2F%2Femby.domain.org

Yep - that's what I said in a previous reply  ...  

https://emby.media/community/index.php?/topic/110642-swagger-api-help/&do=findComment&comment=1241449

[rbjtech 4997]

3 hours ago, softworkz said:

But not when you add the 's' here, right?

Agreed - if you add the https into the URL - swagger then using it ongoing (as the listed 'server').

[softworkz 4569]

The reasons why this is a bit complicated are these:

The swagger/openapi spec is intended to describe rest api services in the cloud that are reachable via a fixed defined URL, but in case of Emby, there are at multiple possible URLs how one might can access the server:

• localhost
• LAN IP
• LAN host/dns name (with or without SSL)
• Public IP
• Public host/dns name (with or without SSL)

And for all these cases, there may be different ports in place.
Usually Emby 'knows' all these from the network configuration where you can define this.

But at the time when I had done all this, OpenAPI (Swagger 3.0) was just brand-new and Swagger (2.0) doesn't allow specifying multiple server URLs. Yet we wanted to support 2.0 as well, so I came to the "trick" of serving the swagger JSON document dynamically, which works in a way that the server uses the http(s) through which the swagger.json or openapi.json documents are requested, to build the server URL and put it into the json doc before it's being served.

This way, the URL in the doc is (almost) always the right one.

OpenAPI allow specifying multiple URLs (that's why you see a dropdown), but I chose not to populate them from the server configuration for two reasons:

• Security
  The swagger/openapi docs are accessible without authentication and adding all the server urls to the doc would reveal your internal ports and IP addresses
• Auto-Authorization
  The hosted swagger UI (https://swagger.emby.media/) has a few modifications. One of them is automatic authorization. 
  When you go through the link from the dashboard page, it conveys an api_key with which you are authorized automatically and you're ready to try out the APIs.
  This wouldn't work when there would be multiple URLs

I guess I made it all a bit too convenient. After all, it was just meant to be an API documentation for developers as we didn't have any at that time (until recently: https://dev.emby.media/reference/RestAPI.html), When it doesn't work perfectly in a few edge cases, then I wouldn't see that as a critical thing as there are multiple easy ways to deal with it:

1. Just save the corrected URL somewhere and use it instead of the API link
2. Download the OpenAPI document, enter the correct server url and save it wherever you want
   (on some web server,  web storage, or even put it somewhere under 'dashboard-ui' in the Emby server installation, so you can access it through Emby)
3. Save it locally and load it into any of the swagger.io tools or postman or whatever...

For 2 and 3, you'll need to authorize manually by entering the api_key, but that's not really a big thing.

[rbjtech 4997]

Thanks for the Info @softworkz

While on the topic - is there a way on the emby server to reject non-local LAN use of an API key ?

I purposely remove remote access for my only Admin user - would this apply to an API key remote request (which effectively acts as an Admin user ?)

I reject swagger on the Reverse Proxy, but I'd like to block it on the emby server as well if possible..

thanks.

Edited April 5, 2023 by rbjtech

[softworkz 4569]

14 minutes ago, rbjtech said:

I purposely remove remote access for my only Admin user - would this apply to an API key remote request (which effectively acts as an Admin user ?)

No, this is separate.

16 minutes ago, rbjtech said:

I reject swagger on the Reverse Proxy

How do you "reject swagger"?

[rbjtech 4997]

3 minutes ago, softworkz said:

How do you "reject swagger"?

I just return 404 in the nginx config.

        location ^~/swagger {
                return 404;
        }

 

[softworkz 4569]

You would need

• /openapi
• /openapi.json
• /swagger
• /swagger.json
• /emby/openapi
• /emby/openapi.json
• /emby/swagger
• /emby/swagger.json

But that's kind of pointless, because none of those URLs is needed to access your server via API and neither does it prevent your server from being recognized as Emby server.

[rbjtech 4997]

1 minute ago, softworkz said:

You would need

• /openapi
• /openapi.json
• /swagger
• /swagger.json
• /emby/openapi
• /emby/openapi.json
• /emby/swagger
• /emby/swagger.json

But that's kind of pointless, because none of those URLs is needed to access your server via API and neither does it prevent your server from being recognized as Emby server.

Exactly - which is why I asked the question  - can it just be blocked on the Emby Server itself - blocking API for remote use should be a configurable item imo.