How to specify OAuth 'realm'

[Download]

I am using the latest version of Swagger UI (cloned from master yesterday 👍 ). I love Swagger it is fantastic. I use it for testing as well as documentation.

I have been setting up authorization using OAuth2 with Keycloak as the backend. It's a rocky ride due to fragmented / outdated / missing documentation but I got things to work. But there is this one thing I can't wrap my head around.

In my swagger.json I have a securitydefinitions section that looks like this:

{
	"securityDefinitions": {
		"oauth2": {
			"type": "oauth2",
			"flow": "accessCode",
			"authorizationUrl": "http://localhost:8080/auth/realms/master/protocol/openid-connect/auth",
			"tokenUrl": "http://localhost:8080/auth/realms/master/protocol/openid-connect/token",
			"scopes": {
				"supervisor": "Supervisor",
				"admin": "Admin"
			}
		}
	}
}

In the index.html file, I made some changes to set the URL of the definition and the oauth redirect URL, like so:

window.onload = function() {
  var a = document.createElement('a');
  a.href = 'swagger.json'
  var r = document.createElement('a');
  r.href = 'oauth2-redirect.html'
  // Build a system
  const ui = SwaggerUIBundle({
    url: a.href,  
    oauth2RedirectUrl: r.href,
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })

  window.ui = ui

  ui.initOAuth({
    clientId: "api-docs",
    realm: "myrealm",
    appName: "api-docs",
    scopeSeparator: " ",
    additionalQueryStringParams: {test: "hello"},
  })
}

This shows my API as expected with an Authorize button at the top. When I press it I get the dialog as expected. The client ID is prefilled as I like it and when I hit the button I go to my login page and all is well.... As long as I make sure I configure everything in the master realm on Keycloak.

As you can see the config has a field for realm and it's actually set to 'myrealm'. However when I configure stuff in Keycloak under 'myrealm', it does not work. It has to be under the 'master' realm.

I figure this is because Keycloak mentions the realm in the path part of the authorization / token URLs:

"authorizationUrl": "http://localhost:8080/auth/realms/master/protocol/openid-connect/auth",
                                                         ^
                                                       realm

I can of course change these URLs in the definition. But it would be much nicer imho if the definition could be independent of the actual auth implementation, same as is done for clientId.

So finally, my question / feature request:

Is it possible to specify a parameter in the URL where realm should be filled in?

Something like this perhaps?:

"authorizationUrl": "http://localhost:8080/auth/realms/${realm}/protocol/openid-connect/auth",
                                                          ^
                                                        parameter

If this stuff is in the docs then sorry for bothering you. I did search, I swear! 👍

EDIT:
I just found this related closed issue:
#1424

[Andresbu]

Same issue here. We have a development, staging and production environment. Each with its own realm. But the swagger.yml is always the same and points to exactly one of these three realms by the 'authorizationUrl'. Making it configurable in some way would be great.

[Download]

I actually implemented a PR for this. See the referenced #3410

[patrykorwat]

When waiting for the PR to be merged, as a workaround I can suggest to setup a backend endpoint that would accept realm name as an input and perform adjustment of the name in the swagger document.

[hkosova]

There's a feature request OAI/OpenAPI-Specification#551 to support parameters in tokenUrl as part of standard OpenAPI syntax.