microsoft / microsoft/typespec

HttpLibrary / OpenAPI3 Emitter - Add support for security schema type "mutualTLS"

Open
#9,266 0 comments 0 reactions 0 assignees View on GitHub
feature lib:http needs-area triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

### Clear and concise description of the problem

### The Problem
TypeSpec does not support defining security schemas of type "mutualTLS" introduced in version 3.1.0 of OAS ([spec](https://spec.openapis.org/oas/v3.1.0.html#security-scheme-object)).

This type is not documented as an [Available Schema](https://typespec.io/docs/libraries/http/authentication/#available-security-schemes) in the Http Library.

This type does not appear in the enum `Http.AuthType` when using the VSCode Extension intellisense.
Image

After manually adding the security type "mutualTLS", the openapi3 emitter does not recognize it and logs a warning. The resulting OAS does not include the described securitySchema.

```typespec
// main.tsp
import "@typespec/http";

using Http;
@service(#{ title: "Demo" })
namespace Demo;

model MutualTLS {
type: "mutualTLS";
description: "MutualTLS Authentication";
}

@useAuth(MutualTLS)
op route(): void;
```

```sh
# Execution
$ tsp compile .
TypeSpec compiler v1.7.1

✔ Compiling
⚠ @typespec/openapi3 24ms tsp-output/schema/
Diagnostics were reported during compilation:

main.tsp:5:11 - warning @typespec/openapi3/unsupported-auth: Authentication "mutualTLS" is not a known authentication by the openapi3 emitter, it will be ignored.
> 5 | namespace Demo;
| ^^^^

Found 1 warning.
```

```yaml
# Output OAS
openapi: 3.1.0
info:
title: Demo
version: 0.0.0
tags: []
paths:
/:
get:
operationId: route
parameters: []
responses:
'204':
description: 'There is no content to send for this request, but the headers may be useful. '
security:
- MutualTLS: []
components:
schemas:
MutualTLS:
type: object
required:
- type
- description
properties:
type:
type: string
enum:
- mutualTLS
description:
type: string
enum:
- MutualTLS Authentication

```

### Feature Proposal

1. Add "mutualTLS" to the enum AuthType in the Http Library
2. Add support to the VSCode Extension for the newly updated AuthType enum value
3. Add support to the OpenAPI3 Emitter for the securitySchema type "mutualTLS"

### Checklist

- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Read the [docs](https://typespec.io/docs/).
- [x] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.