openid-connectopenapigoogle-openid

How to describe in a OAS3 spec the security schema of a endpoints using Google's OpenId?


The application that I'm building is using the AuthorizationCode with PKCE of Google OpenId. After the user's authentication, the app is going to send the AccessToken to authenticate itself to the backend server and also send the IdToken in order to retrieve the user's data.

But if I'm not wrong, the server will need to also authenticate itself into Google's using ClientCredentials flow in order to retrieve the data on the user's behalf.

How should I specify that in an OAS3 spec?

Should the endpoint have both OpenID and OAuth2?


Solution

  • API DOCS

    It is usual for an an API spec such as Swagger to just focus on the calling client's view of the API and not internal implementation details:

    Your API could support multiple clients over time, with different client side flows for getting a token, eg:

    GETTING STARTED GUIDE

    If you need to summarise client side authentication flows I would put that in a separate document, since it is not the API's concern.

    It is common to provide this kind of overview in a 'Getting Started' guide, for people who need to get connected. And to cover aspects such as token expiry, error responses, environments.

    MY APPROACH

    I always provide both of the above docs. I can get across to customers what they need, without depending too much on tools such as Swagger UI, which often do not do what we want.