Support for Kerberos and others as type values of Security Scheme Object

[lennybacon]

We want to use swagger for an internal system. The authentication mechanism we use is Kerberos.

Currently this is not a supported type value of the Security Scheme Object.

To support Negotiate (for Kerberos), NTML or Digest (as values for the WWW-Authenticate-Header) it would be nice if the type values would be added to the specification.

[webron]

What additional fields would be required to support Kerberos or other schemes you had in mind? As you can see in the spec, basic has no additional metadata, apiKey has the name of the field and where it's located, oauth2 has the flow type and based on the flow the additional token urls.

[lennybacon]

Digest, NTLM and Negotiate work like basic (RFC 2617 contains basic and digest http://www.ietf.org/rfc/rfc2617.txt)

in HTTP its

GET --->
< --- 401 WWW-Authenticate [Basic|Digest|NTLM|Negotiate] 
GET ---> Authorization: [Basic|Digest|NTLM|Negotiate] [TOKEN]
<--- 200 | 304

As you said is swagger basic has no additional metadata. So as far as I can see it's just adding the values digest, ntml, negotiate as allowed for types of the Security Scheme Object.

[webron]

I wonder whether we should just add those as types or possibly group them all under the access type and have another field specifying the specific type. Don't know if there are any benefits to either approach (though my suggestion is more verbose).

As a side note, and possible workaround for now, you can use vendor extensions to specify the specific type. Just set it to type basic, and add something like x-extended-type: digest.

[lennybacon]

I think we are already at the right place as OAUTH uses the same mechanism to authenticate (when headers are used) and should just add them:

GET ---> Authorization: Bearer [TOKEN]
<--- 200 | 304

[lennybacon]

And as we are on the authentication topic... What about client certificates? Had that in mind yet? If not we should consider to include it when extending the auth types.

[dolmen]

Related: #583

[webron]

How is #583 related to this and not a duplicate of this?

[dolmen]

@webron This ticket is about Kerberos and WWW-Authenticate header. #583 is about the Authorization header.
They are different use cases but they are related as ideally a single common solution could fix both.

As a user I don't think it is my task to decide when tickets must be grouped because I don't have your global vision of the issues.

[webron]

@dolmen of course, I much rather people open new issues than not comment at all. If issues are related, it may make sense to expand the discussion on the issue rather than open a new ticket, but either works - it's no big deal most of the times.

Sometimes the differences are not clear - was just checking how the issues differ 😉

[webron]

Parent issue: #585

[darrelmiller]

The pr #807 now allows you to specific the scheme in the security definition, so you can specify the negotiate scheme.

[webron]

Closing as done.

[ashishdhyani]

How the Kerberos will work with Swagger?
I have put the settings like below, but it doesn't work. I am still receiving 401.

"paths": {
    "/": {
        "get": {
            "tags": [
                "unix-services"
            ],
            "summary": "Get all service statuses..",
            "description": "",
            "operationId": "get",
            "consumes": [
            ],
            "produces": [
                "application/json"
            ],
            "parameters": [
            ],
            "responses": {
                "405": {
                    "description": "Invalid input"
                },
                "401": {
                    "description": "Access Denied"
                }
            },
            "security": [
                {
                    "negotiationAuth": [
                    ]
                }
            ]
        }
    }
},
"securityDefinitions": {
    "negotiationAuth": {
        "type": "http",
        "scheme": "negotiate",
        "in": "header"
    }
},

Can anyone help please ?

[MikeRalphson]

@ashishdhyani you are mixing OAS v2 and v3 syntaxes. A securityScheme of type: http and scheme: negotiate is only supported in OAS 3.x

[ashishdhyani]

Hi @MikeRalphson,
Thanks.
I am settings up Swagger first time, could you please point out where to fix ?
I changed from "securityDefinitions" ==> "securitySchemes", but still the same 401.

{
    "swagger": "2.0",
    "info": {
        "description": "description",
        "version": "1.0.0",
        "title": "S Desktop",
        "termsOfService": "",
        "contact": {
            "email": "ashish.dhyani@xyz.com"
        },
        "license": {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
        }
    },
    "host": "xyz.net:9999",
    "basePath": "/",
    "tags": [
        {
            "name": "unix-services",
            "description": "Unix services",
            "externalDocs": {
                "description": "Find out more",
                "url": ""
            }
        }
    ],
    "schemes": [
        "http"
    ],
    "paths": {
        "/": {
            "get": {
                "tags": [
                    "unix-services"
                ],
                "summary": "Get all service statuses..",
                "description": "",
                "operationId": "get",
                "consumes": [
                ],
                "produces": [
                    "application/json"
                ],
                "parameters": [
                ],
                "responses": {
                    "405": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Access Denied"
                    }
                },
                "security": [
                    {
                        "negotiationAuth": [
                        ]
                    }
                ]
            }
        }
    },
    "securitySchemes": {
        "negotiationAuth": {
            "type": "http",
            "scheme": "negotiate",
            "in": "header"
        }
    },
    "definitions": {
        "ApiResponse": {
            "type": "object",
            "properties": {
                "code": {
                    "type": "integer",
                    "format": "int32"
                },
                "type": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                }
            }
        }
    },
    "externalDocs": {
        "description": "Find out more about Swagger",
        "url": "http://swagger.io"
    }
}

[MikeRalphson]

@ashishdhyani if you can post your v2 document as a gist, we can take a look at it, alternatively have a look at the following blog posting.

[ashishdhyani]

Hi @MikeRalphson,

I converted the file to OAS 3.x format (server name changed). Still I get 401 as response.
The same link works at the browser.

Attached specification.
swagger.txt
swagger_another.txt

[MikeRalphson]

Hi @ashishdhyani securitySchemes should live under the components object, perhaps this will fix the problem you are having with whichever tools you are using. https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#components-object-example

[ashishdhyani]

unfortunately, even after putting under components, I am getting error

swagger.txt

[MikeRalphson]

Not all tools are going to support all possible authentication schemes. Especially when they may be hosted on a different domain to the one which may contain your credentials. Please could you raise an issue on the relevant tool repository?

[ashishdhyani]

Thanks Mike, will check.

Hi @lennybacon, in earlier message of yours, you have the similar requirement.
Were you able to achieve it, using Negotiate (Kerberos) authentication ?

GET --->
< --- 401 WWW-Authenticate [Basic|Digest|NTLM|Negotiate]
GET ---> Authorization: [Basic|Digest|NTLM|Negotiate] [TOKEN]
<--- 200 | 304

[lennybacon]

@ashishdhyani I used this for API-documentation purposes only. Of course I was able to use Negotiate in custom code. But I have never used the interactive client or something like that.

[ashishdhyani]

@lennybacon, custom code you mean outside of swagger ?
Swagger team should consider to making HTTP request with clientCredential option, so that we don't need specify the security scheme for negotiate, it will work automatically.
Like in axios, we have an option to set clientCredential=true while making http calls.

[lennybacon]

custom code = of swagger!

clientCredential=true sounds like a good idea for the interactive client tools.

[MikeRalphson]

@ashishdhyani this is not the correct repository to reach out to the swagger team.

[MikeRalphson]

Reopening, as we'd like to get feedback on peoples experiences with using Kerberos / NTLM / negotiate http security schemes. Are other metadata / hints required to make client or server implementations easier? For a 'try it out' type application, is prompting for realm/domain, username and password sufficient etc?

[lennybacon]

Prompting for realm/domain, username and password sufficient. If its is javascript/XHR setting clientCredential=true would be even better.

[MikeRalphson]

@lennybacon could you expand on that a little (with links if necessary)? I'm only familiar with clientCredentials as a Windows concept. What if the service calling the API is on a different machine/realm to the one bearing the user's credentials for the API (think hosted Swagger-UI)? Forgetting the 'try it out' and web-browser clients for now, would clientCredentials mean much to a machine-to-machine API call, such as from a mobile application (where the user may be logged into many different services)?

[lennybacon]

@MikeRalphson clientCredentials refer to the implementation of the XmlHttpRequest object in javascript that is used to enable automatic authentication of javascript backend communication if the direct browser communication is already authenticated - in therms of BASIC/DIGEST/Negotiate - The Authentication HTTP Headers of the browser request are also used by the javascript requests. If the browser communication is not authenticated the clientCredentials will show the ugly grey dialog that prompts for a certificate or user name and password - exactly what is needed in a try it out app.

What if the service calling the API is on a different machine/realm to the one bearing the user's credentials for the API (think hosted Swagger-UI)?

From an API-Spec it is the same as Basic Authentication.

Forgetting the 'try it out' and web-browser clients for now, would clientCredentials mean much to a machine-to-machine API call, such as from a mobile application (where the user may be logged into many different services)?

I don't know i I get your question right... Http-Headers is a common scenario for authentication, also for machine-to-machine communication.

[keith6014]

So, I am wondering does Kerberos work with SwaggerUI?

[keith6014]

anyone?

[MikeRalphson]

Apologies for leaving you hanging, though the swagger-ui repository would probably be the best place to ask, I don't believe Kerberos is supported in swagger-ui's Try It Out console today. Though there might be a hook you could use to implement it...

[lennybacon]

I just looked at the repo and from the code I guess it will not work. For basic they have a username and password field which means they stuff the header by themselves: https://github.com/swagger-api/swagger-ui/blob/12e350fcad66f7708e6bc3e18d8cb2c9a107bc16/src/core/components/auth/basic-auth.jsx

[keith6014]

@MikeRalphson
No problem! Thanks for the idea and keep up the good work.

@lennybacon
yeah, doesn't seem so. Thanks for looking.

Kerberos/SSO is the single most feature most of our user base has required. I will consider asking swagger-ui group https://github.com/swagger-api/swagger-ui

[MikeRalphson]

We're actively looking at security improvements for v3.1 so let us know if Kerberos / SSO needs further support in the spec.

[keith6014]

Yes. Kerberos is needed. Its used quite heavily in the world. So far in the 3 large companies I worked for Kerberos was the primary auth method.

[MikeRalphson]

Technically, the spec supports it today, but tooling is free to support whichever auth schemes they want. But do we require any new metadata fields to make support actually work?

[stevendearborn]

According to the OAS 3.0.2 documentation, all of the IANA-registered HTTP authentication schemes are supported, with the qualification as to this relates to the authorization header. As posted on Feb 9, 2018 these are not supported by the Swagger Editor or UI tooling as was mentioned. Also, the 'in' property is not valid when type is set to 'http'; only scheme is valid. Presently, the only option is to use type: http, scheme: Custom, use vendor extensions (i.e. x-) to stipulate the remainder of the security scheme, and write a very clear description for application developers. There is a lot of work to be done here, potentially modifying the OAS 3.x JSON schema but mostly the tooling.

I would like to open another issue to expand the concept of 'security scheme' not to just authentication and authorization but to other security schemes such as data integrity/digital signature, non-repudiation, PKI/digital certificates, etc.. This would create a more 'normalized' JSON schema structure in the OAS specification while allowing flexibility in the tooling implementations. In absence of defining security schemes for these, the concepts, and related input and output parameters are becoming conflated with the actual resource-related inputs and outputs. The separation of these concepts would make APIs more readable especially when the complexities of API security are required.

[MikeRalphson]

expand the concept of 'security scheme' not to just authentication and authorization but to other security schemes such as data integrity/digital signature, non-repudiation, PKI/digital certificates, etc.

Some work on exactly this is being undertaken at the moment. Probably the best thing is to join one of the Thursday open TSC calls if the time works for you, or I can dig out a link to a recording of a previous call where the work-in-progress was presented.

[stevendearborn]

Thank you @MikeRalphson yes I would be interested.

[MikeRalphson]

@stevendearborn https://zoom.us/recording/share/PBwsPKe6OprJMcAx6bWs5Y4ySGOGnOsu7-hZGAoTS2uwIumekTziMw

[lennybacon]

As I read here swagger 3 DOES support Kerberos:

OpenAPI uses the term security scheme for authentication and authorization schemes. OpenAPI
3.0 lets you describe APIs protected using the following security schemes:

• HTTP authentication schemes (they use the Authorization header):
  • Basic
  • Bearer
  • other HTTP schemes as defined by RFC 7235 and HTTP Authentication Scheme Registry