Make Secure HTTP APIs

Golem API gateway has built-in authentication support to identify users using OpenID protocol. This allows you to refer to the claims such as request.auth.email (as an example) once authenticated in your Rib expression. You can choose to pass this information into the agent method that exist in the Rib expression, and do further logic with it. Currently, this is tested with Google Identity connector.

Setup Security for your API routes in Golem

Register an app with Google Identity Provider and get a client-id and client-secret.

Here is the direct link to register your app with Google Identity Provider (opens in a new tab). Make sure your app with a redirect URL and get the client-id and client secret.

When using a locally executed Golem instance during development, the redirect URI can be http://localhost:9006/auth/callback. Otherwise it should be be https://mydomain.com/auth/callback, where mydomain.com is the domain in which you will be deploying your API definition in Golem.

The /auth/callback part is just an example and it can be anything, as far as it doesn't collide with any other existing routes.

We call these details "Api Security Scheme" in Golem API Gateway. Next step is to register this scheme in Golem.

Register API Security Scheme with your app's client-id and client-secret with Golem

Make sure you name your security scheme uniquely, and provide the client-id, client-secret and redirect-url as given below.

 
golem api security-scheme create \
  --provider-type google \
  --client-id REPLACE_WITH_GOOGLE_CLIENT_ID \
  --client-secret REPLACE_WITH_GOOGLE_CLIENT_SECRET \
  --redirect-url http://localhost:9006/auth/callback
  --scope openid,email,profile \
  my-security

By now, you are having a security scheme registered with golem which you can refer in API definitions.

Reference the security scheme name in API definition

This name (my-security in the above example) is the one to be used in the route's security field, as described in the Making Custom APIs page.

New fields available on the Rib `request` object

Attaching a security scheme to a route adds an additional auth field to the Rib request object, which contains the claims from the authenticated user's ID token. For example, to get the authenticated user's email and use it to access an agent (with agent type example-agent) associated with this user:

let email: string = request.auth.email;
let agent = example-agent(email);

Redirects and Cookies

Internally, there are a couple of redirects that's going on when you access the protected endpoint. The first redirect is to the Google Identity Provider login page as explained below, and internally this is followed by identity provider hitting the redirect URL ( which is exposed on your behalf by Golem API gateway) with all the details of the user. This is followed by another redirect to the original URL that you tried to access, and this time the session-id, tokens/secrets set in a secure Cookie, which your browser will resend. Once the browser sends the cookie, Golem API gateway will validate the cookie and allow you to access the protected endpoint.

We will be adding more support for various clients and use-cases in future releases based on the user feedback.

Unexposed CallBack Endpoint

Note that the callback endpoint is exposed automatically based on the re-direct url specified in the API security scheme. Users cannot customise or add these call back endpoints manually. This is to avoid any security issues that may arise due to misconfiguration of the callback endpoint.

Troubleshooting

Most of the errors in this use-case are originated from a wrong security scheme configuration. For example, a wrong redirect-url can result in odd errors that is difficult to spot, as this is originated from the providers and not Golem.

Make sure the scope is correct and includes email. Trying to specify request.auth.email while the scope doesn't have it in the security scheme, will result in errors such as email not found in the request object

Known Issues

Using multiple security schemes (with the names foo-security-scheme, and bar-security-scheme ) with the same redirect-url is not supported and leads to an internal error.

Selected profile: local
 
error: API Security Scheme Service - Error: 500 Internal Server Error, InternalError: Internal repository error (unique
     key violation)

Making Custom APIs Troubleshooting