Exploring OIDC protected REST API

[daniel_biales]

I have an API that is protected by OIDC. I want developers to be able to explore this API via a REST client. Is there a common pattern or recommendation for doing this.

The ideas I had are:

1. Modifying the proxy so it can do redirects to the IDP to get a bearer token and somehow storing some session info that will use that bearer token when the user makes subsequent calls

2. Build a simple CLI/UI for the API so the application will handle the authentication and pass it onto the API

3. Use something like the passcode flow that the Apigee Management API uses to give the user either a passcode that is associated with a bearer token stored in a KVM or a passcode that they can use to get a bearer token.

[dchiesa1 · Accepted solution]

1. regarding your first idea. Redirect.

   When you say "redirect to the IDP," ... under what circumstance?

   If you are suggesting that you modify the proxy to check for a token, and then have the proxy issue a 302 when a token is not present. ... I don't like that idea. It sort of violates the REST principles. A response indicating "unauthorized" should include a 401 status code.

   Instead just design the proxy to issue a regular error when a token is not present, with an error message and maybe a URL that points people to a human-readable page that describes what they need to do to get a proper token.

   {
     "error" : "Unauthorized, missing token",
     "code" : 401,
     "information" : "https://myserver.com/missing_token.html" 
   } 
   

   Maybe you are suggesting that the proxy ought to handle the OIDC token issuance "kickoff". That is a GET to /authorize, and the OIDC endpoint is expected to issue a 302 to the user-accessible login and consent endpoint.

   That's a good idea, if your IDP itself does not support OIDC directly. In fact there are examples that do this. search the community site and you will find them. Many IDPs (Auth0, Okta, Google Signin, etc) support OIDC directly, so you wouldn't need to do this part. But if you have your own user store and database, then ... you can do this.

2. regarding your second idea - build a CLU or UI...

   My response to that: It depends.If you are in the business of providing APIs, then building a CLI or UI is probably the wrong thing. If you are building CLIs, then yes. If you're building APIs, I'd recommend just carefully documenting the steps and making sure that devs can use it first time, without much trouble. OIDC has a few steps, so it's good to provide examples that work in Bash+curl, C#, Java, Python, PHP... whatever languages you expect your devs to use.

3. regarding passcode.

   That's an interesting idea, but I suggest that the "Exploration" experience should be as close as possible to the actual experience. Don't go building a passcode flow if it is used only for understanding the API. It will confuse people if they don't have to use passcodes in production, but they do have to use them to get started.

   BTW, there is a TOTP Java callout that might be interesting for you. https://community.apigee.com/answers/62694/view.html